zmq_msg_send(3)

SYNOPSIS

int zmq_msg_send (zmq_msg_t *msg, void *socket, int flags);

DESCRIPTION

The zmq_msg_send() function is identical to zmq_sendmsg(3), which +shall be deprecated in future versions. zmq_msg_send() is more consistent +with other message manipulation functions.

The zmq_msg_send() function shall queue the message referenced by the msg +argument to be sent to the socket referenced by the socket argument. The +flags argument is a combination of the flags defined below:

+ZMQ_DONTWAIT +: +
+For socket types (DEALER, PUSH) that block when there are no available peers +(or all peers have full high-water mark), specifies that the operation should +be performed in non-blocking mode. If the message cannot be queued on the +socket, the zmq_msg_send() function shall fail with errno set to EAGAIN. +
+
+ZMQ_SNDMORE +: +
+Specifies that the message being sent is a multi-part message, and that further +message parts are to follow. Refer to the section regarding multi-part messages +below for a detailed description. +
+

The zmq_msg_t structure passed to zmq_msg_send() is nullified during the +call. If you want to send the same message to multiple sockets you have to copy +it using (e.g. using zmq_msg_copy()).

+ + + +

Note

A successful invocation of zmq_msg_send() does not indicate that the +message has been transmitted to the network, only that it has been queued on +the socket and ØMQ has assumed responsibility for the message. You do not need +to call zmq_msg_close() after a successful zmq_msg_send().

Multi-part messages

A ØMQ message is composed of 1 or more message parts. Each message +part is an independent zmq_msg_t in its own right. ØMQ ensures atomic +delivery of messages: peers shall receive either all message parts of a +message or none at all. The total number of message parts is unlimited except +by available memory.

An application that sends multi-part messages must use the ZMQ_SNDMORE flag +when sending each message part except the final one.

RETURN VALUE

The zmq_msg_send() function shall return number of bytes in the message +if successful. Otherwise it shall return -1 and set errno to one of the +values defined below.

ERRORS

+EAGAIN +: +
+Non-blocking mode was requested and the message cannot be sent at the moment. +
+
+ENOTSUP +: +
+The zmq_msg_send() operation is not supported by this socket type. +
+
+EFSM +: +
+The zmq_msg_send() operation cannot be performed on this socket at the moment +due to the socket not being in the appropriate state. This error may occur with +socket types that switch between several states, such as ZMQ_REP. See the +messaging patterns section of zmq_socket(3) for more information. +
+
+ETERM +: +
+The ØMQ context associated with the specified socket was terminated. +
+
+ENOTSOCK +: +
+The provided socket was invalid. +
+
+EINTR +: +
+The operation was interrupted by delivery of a signal before the message was +sent. +
+
+EFAULT +: +
+Invalid message. +
+
+EHOSTUNREACH +: +
+The message cannot be routed. +
+

EXAMPLE

Filling in a message and sending it to a socket

/* Create a new message, allocating 6 bytes for message content */
+zmq_msg_t msg;
+int rc = zmq_msg_init_size (&msg, 6);
+assert (rc == 0);
+/* Fill in message content with 'AAAAAA' */
+memset (zmq_msg_data (&msg), 'A', 6);
+/* Send the message to the socket */
+rc = zmq_msg_send (&msg, socket, 0);
+assert (rc == 6);

Sending a multi-part message

/* Send a multi-part message consisting of three parts to socket */
+rc = zmq_msg_send (&part1, socket, ZMQ_SNDMORE);
+rc = zmq_msg_send (&part2, socket, ZMQ_SNDMORE);
+/* Final part; no more parts to follow */
+rc = zmq_msg_send (&part3, socket, 0);

AUTHORS

This page was written by the ØMQ community. To make a change please +read the ØMQ Contribution Policy at http://www.zeromq.org/docs:contributing.

+zmq_msg_send(3) Manual Page +

NAME