sendmsg(3)

NAME
sendmsg - send a message from a socket

SYNOPSIS
#include <sys/socket.h>

int sendmsg(int s, const struct msghdr *msg, int flags);

DESCRIPTION
sendmsg is used to transmit a message to another socket. s is a socket descriptor that specifies the socket on which the message will be sent. msg points to an object of type struct msghdr that describes the message to be sent. struct msghdr is explained below.

sendmsg operates the same way as sendto, except that it is able to gather the data given in the msg_iov member of struct msghdr. Note that sending of access rights is not implemented. sendmsg returns an error as described below if you try to send access rights. Do not rely on this behavior, because it might change in the future.

struct msghdr is defined in <sys/socket.h>, and has the following form :

    struct msghdr {
    	void	*msg_name;	/* optional address */
    	size_t	msg_namelen;	/* size of address  */
    	struct iovec *msg_iov;	/* gather array for data */
    	size_t	msg_iovlen;	/* # of elements in msg_iov */
    	void    *msg_accrights;	/* access rights */
    	size_t	msg_accrightslen; /* size of msg_accrights */
    }

msg_name is the destination address if the socket is unconnected; msg_name may be a null pointer if no name is specified. msg_iov is the location of the gather data. msg_accrights specifies a buffer to send any access rights along with the message. Transfer of access rights is not implemented, so you should set the msg_acccrights field to NULL indicating that access rights are not being transferred.

See sendto(3) to learn more about the behavior of sendmsg.

RETURN VALUE
If the sendmsg call is successful, it returns the number of bytes sent. If the call fails, -1 is returned and an error code is stored in errno.

DIAGNOSTICS
The call to sendmsg fails if:

    [EBADF]
        An invalid descriptor was specified.

    [EMSGSIZE]
        The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible.

    [EINTR]
        The operation was interrupted by a signal before any data were sent. (If some data was sent, sendmsg returns the number of bytes sent before the signal, and EINTR is not given.)

    [EINVAL]
        A member of the msg parameter is invalid or the specified destination address is not valid. The argument s is not a socket. Transfer of access rights is not implemented.

    [EDESTADDRREQ]
        The to parameter needs to specify a destination address for the message.

    [ENOMEM]
        There is insufficient buffer space to send the message.

    [ENOTCONN]
        A send on a socket that is not connected, or a send on a socket that has not completed the connect sequence with its peer, or is no longer connected to its peer.

    [EISCONN]
        An address was specified by to for a SOCK_DGRAM socket which is already connected.

    [EAFNOSUPPORT]
        Requested address does not match the address family of this socket.

    [EPIPE] and SIGPIPE signal
        An attempt was made to send on a socket that was connected, but the connection has been shut down, either by the remote peer or by this side of the connection. Note that the default action for SIGPIPE, unless the process has established a signal handler for this signal, is to terminate the process.

    [EOPNOTSUPP]
        The MSG_OOB flag was specified; it is not supported for AF_UNIX sockets.

SEE ALSO
getsockopt(3), select(3), send(3), sendto(3), socket(3).