sendmsg()

Send a message and its header to a socket

Synopsis:

#include <sys/types.h>
#include <sys/socket.h>

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

Arguments:

s

The descriptor for the socket; see socket().

msg

A pointer to the message that you want to send. For a description of the msghdr structure, see recvmsg().

flags

A bitwise OR of zero or more of the following:

MSG_OOB — process out-of-band data. Use this bit when you send “out-of-band” data on sockets that support this notion (e.g. SOCK_STREAM). The underlying protocol must also support out-of-band data.
MSG_DONTROUTE — bypass routing; create a direct interface. You normally use this bit only in diagnostic or routing programs.
MSG_NOSIGNAL — don't raise a SIGPIPE signal when the other end breaks the connection.

Library:

libsocket

Use the -l socket option to qcc to link against this library.

Description:

The sendmsg() function is used to transmit a message to another socket. You can use send() only when the socket is in a connected state; you can use sendmsg() at any time.

No indication of failure to deliver is implicit in a sendmsg(). Locally detected errors are indicated by a return value of -1.

If no message space is available at the socket to hold the message to be transmitted, then sendmsg() normally blocks, unless the socket has been placed in nonblocking I/O mode. You can use select() to determine when it's possible to send more data. This behavior applies if the socket was opened as SOCK_STREAM.

You typically use this function on datagram (SOCK_DGRAM) sockets, which use the send buffer only as a length check and place the message in the interface transmit queue. If the interface transmit queue is full, this fails, causing sendmsg() to return -1 and set errno to ENOBUFS.

Returns:

The number of bytes sent, or -1 if an error occurs (errno is set).

Errors:

EACCES: Search permission is denied for a component of the path prefix, or write access to the named socket is denied.
EAGAIN: The socket's file descriptor is marked O_NONBLOCK, and the requested operation would block.
EAFNOSUPPORT: Addresses in the specified address family cannot be used with this socket.
EBADF: An invalid descriptor was specified.
ECONNRESET: A connection was forcibly closed by a peer.
EDESTADDRREQ: The socket isn't connection-mode and doesn't have its peer address set, and no destination address was specified.
EFAULT: An invalid user space address was specified for a parameter.
EHOSTUNREACH: The destination host can't be reached (probably because the host is down, or a remote router can't reach it).
EINTR: A signal interrupted sendmsg() before any data was transmitted.
EINVAL: The sum of the iov_len values overflows an ssize_t.
EIO: An I/O error occurred while reading from or writing to the filesystem.
EISCONN: A destination address was specified and the socket is already connected.
EMSGSIZE: The message is too large to be sent all at once (as the socket requires), or the msg_iovlen member of the msghdr structure pointed to by message is less than or equal to 0 or is greater than IOV_MAX.
ENETDOWN: The local network interface used to reach the destination is down.
ENETUNREACH: No route to the network is present.
ENOBUFS: The system couldn't allocate an internal buffer. The operation may succeed when buffers become available.
ENOMEM: Insufficient memory was available to fulfill the request.
ENOTCONN: The socket is connection-mode but isn't connected.
ENOTSOCK: The argument s isn't a socket.
EOPNOTSUPP: The s argument is associated with a socket that doesn't support one or more of the values set in flags.
EOVERFLOW: An attempt was made to send an amount of data that when added to the sizes of the socket send message and socket address length structures exceeds the allowable limit.
EPIPE: The socket is shut down for writing, or the socket is connection-mode and is no longer connected. In the latter case, and if the socket is of type SOCK_STREAM, a SIGPIPE signal is generated to the calling thread.
EWOULDBLOCK: The socket is marked nonblocking and the requested operation would block.

If the address family of the socket is AF_UNIX, sendmsg() fails if:

EIO: An I/O error occurred while reading from or writing to the filesystem.
ELOOP: A loop exists in symbolic links encountered during resolution of the pathname in the socket address, or more than SYMLOOP_MAX symbolic links were encountered during the resolution of the pathname in the socket address.
ENAMETOOLONG: A component of a pathname exceeded NAME_MAX characters, or an entire pathname exceeded PATH_MAX characters, or pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.
ENOENT: A component of the pathname doesn't name an existing file, or the path name is an empty string.
ENOTDIR: A component of the path prefix of the pathname in the socket address isn't a directory.

Classification:

POSIX 1003.1

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes