Format
X/Open: #define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>
ssize_t sendmsg(int socket, struct msghdr *msg, int flags);
Berkeley
sockets: #define _OE_SOCKETS
#include <sys/socket.h>
int sendmsg(int socket, struct msghdr *msg, int flags);
General description
The sendmsg() function sends messages on a socket with
a socket descriptor passed in an array of message headers. - Parameter
- Description
- socket
- The socket descriptor.
- msg
- An array of message headers from which messages are sent.
- flags
- Specifying one or more of the following flags. If more than one
flag is specified, the logical OR operator ( | ) must be used to separate
them.
- MSG_OOB
- Sends out-of-band data on the socket. Only SOCK_STREAM sockets
support out-of-band data. The out-of-band data is a single byte.
Before out-of-band data can be sent between two programs,
there must be some coordination of effort. If the data is intended
to not be read inline, the recipient of the out-of-band data must
specify the recipient of the SIGURG signal that is generated when
the out-of-band data is sent. If no recipient is set, no signal is
sent. The recipient is set by setting the action parameter
of the fcntl() function to F_SETOWN and specifying either a PID or
GID. For more information on setting a recipient for out-of-band data,
see fcntl() — Control open file descriptors.
The recipient of
the data determines whether to receive out-of-band data inline or
not inline by the setting of the SO_OOBINLINE socket option using
the setsockopt() function. For more information on receiving out-of-band
data, see setsockopt() — Set options associated with a socket, recv() — Receive data on a socket, recvfrom() — Receive messages on a socket,
and recvmsg() — Receive messages on a socket and store in an array of message headers.
- MSG_DONTROUTE
- The SO_DONTROUTE socket option is turned on for
the duration of the operation. This flag is typically used by diagnostic
or routing programs.
A message header is defined by the msghdr structure,
which can be found in the sys/socket.h header file and contains the
following elements:
- Element
- Description
- msg_iov
- An array of iovec buffers containing the message.
- msg_iovlen
- The number of elements in the msg_iov array.
- msg_name
- An optional pointer to the buffer containing the recipient's address.
- msg_namelen
- The size of the address buffer.
- caddr_t msg_accrights
- Access rights sent or received (ignored if specified by the user).
This field is ignored by z/OS® UNIX services.
- int msg_accrightslen
- Length of access rights data (ignored if specified by the user).
This field is ignored by z/OS UNIX services.
- msg_control
- Ancillary data.
- msg_controllen
- Ancillary data buffer length.
- msg_flags
- Flags on received message.
Ancillary data consists of a sequence of pairs,
each consisting of a cmsghdr structure followed by a data array. The
data array contains the ancillary data message and the cmsghdr structure
contains descriptive information that allows an application to correctly
parse the data.
The sys/socket.h header file
defines the cmsghdr structure that includes at least the following
elements: - Element
- Description
- cmsg_len
- Data byte count, including header.
- cmsg_level
- Originating protocol.
- cmsg_type
- Protocol-specific type.
The following ancillary data
are available at the IPv4 level:
- Ancillary data
- Description
- IP_PKTINFO
- (RAW and UDP) Specifies the interface packets are sent over and
the IP address used as the packet source IP. The data is passed in
an in_pktinfo structure as defined in netinet/in.h.
The following ancillary data
are available at the IPv6 level:
- Ancillary data
- Description
- IPV6_HOPLIMIT
- (RAW, TCP, and UDP) Specifies the maximum hop limit for an outgoing
packet. The data is passed in a structure as defined in netinet/in.h.
- IPV6_PATHMTU
- (RAW and UDP) Specifies the path MTU value for the destination
of a connected socket. The data is passed in a structure as defined
in netinet/in.h.
- IPV6_PKTINFO
- (RAW and UDP) Specifies the interface packets are sent over and
the IP address used as the packet source IP. The data is passed in
an in6_pktinfo structure as defined in netinet/in.h.
The following ancillary data
are available at the socket level:
- Ancillary data
- Description
- SCM_RIGHTS
- Specifies the data array that contains the access rights to be
sent or received. This ancillary data is valid only for the AF_UNIX
domain. The data is passed in a structure as defined in sys/socket.h.
The sys/socket.h header file defines the following
macros to gain access to the data arrays in the ancillary data associated
with a message header:
- CMSG_DATA(cmsg)
- If the argument is a pointer to a cmsghdr structure, this macro
returns an unsigned character pointer to the data array associated
with the cmsghdr structure.
- CMSG_NXTHDR(mhdr,cmsg)
- If the first argument is a pointer to a msghdr structure and the
second argument is a pointer to a cmsghdr structure in the ancillary
data (pointed to by the msg_control field of that msghdr structure),
this macro returns a pointer to the next cmsghdr structure or a NULL
pointer if this structure is the last cmsghdr structure in the ancillary
data.
- CMSG_FIRSTHDR(mhdr)
- If the argument is a pointer to a msghdr structure, this macro
returns a pointer to the first cmsghdr structure in the ancillary
data associated with this msghdr structure, or a NULL pointer if there
is no ancillary data associated with the msghdr structure.
The sendmsg() call applies to sockets regardless
of whether they are in the connected state.
This call returns
the length of the data sent. If there is not enough available buffer
space to hold the socket data to be transmitted, and the socket is
in blocking mode, sendmsg() blocks the caller until additional buffer
space becomes available. If the socket is in nonblocking mode, sendmsg()
returns -1 and sets the error code to EWOULDBLOCK. See fcntl() — Control open file descriptors or ioctl() — Control device for
a description of how to set nonblocking mode.
For datagram
sockets, this call sends the entire datagram, provided that the datagram
fits into the TCP/IP buffers. Stream sockets act like streams of
information with no boundaries separating data. For example, if an
application wishes to send 1000 bytes, each call to this function
can send 1 byte, or 10 bytes, or the entire 1000 bytes. Therefore,
applications using stream sockets should place this call in a loop,
calling this function until all data has been sent.
Socket
address structure for IPv6: For an AF_INET6 socket, if msg_name
is specified then the address should be in a sockaddr_in6 address
structure. The sockaddr_in6 structure is defined in the header file
netinet/in.h.
Special behavior for C++: To
use this function with C++, you
must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Note: The
sendmsg() function has a dependency on the level of the Enhanced ASCII
Extensions. See
Enhanced ASCII support for details.
Returned value
If successful, sendmsg()
returns the length of the message in bytes.
A value of 0 or
greater indicates the number of bytes sent, however, this does not
assure that data delivery was complete. A connection can be dropped
by a peer socket and a SIGPIPE signal generated at a later time if
data delivery is not complete.
If unsuccessful, sendmsg() returns
-1 and sets errno to one of the following values:
- Error Code
- Description
- EADDRNOTAVAIL
- The ipi6_addr is not available for use
on the ipi6_ifindex interface.
- EAFNOSUPPORT
- The address family is not supported (it is not AF_UNIX, AF_INET,
or AF_INET6).
- EBADF
- socket is not a valid socket descriptor.
- ECONNREFUSED
- The attempt to connect was rejected.
- ECONNRESET
- A connection was forcibly closed by a peer.
- EFAULT
- Using msg would result in an attempt
to access storage outside the caller's address space.
- EHOSTUNREACH
- No route to the destination exists over the interface specified
by ifi6_index.
- EINTR
- A signal interrupted sendmsg() before any data was transmitted.
- EINVAL
- msg_namelength is not the size of a
valid address for the specified address family.
- EIO
- There has been a network or transport failure.
- EMSGSIZE
- The message was too big to be sent as a single datagram. The default
is large-envelope-size. (Envelopes are used
to hold datagrams and fragments during TCP/IP processing. Large envelopes
hold UDP datagrams greater than 2KB while they are processed for output,
and when they are waiting for an application program to receive them
on input.)
- ENETDOWN
- The interface specified by ipi6_ifindex is
not enabled for IPv6 use.
- ENOBUFS
- Buffer space is not available to send the message.
- ENOTCONN
- The socket is not connected.
- ENOTSOCK
- The descriptor is for a file, not for a socket.
- ENXIO
- The interface specified by ipi6_ifindex does
not exist.
- EOPNOTSUPP
- The socket argument is associated with
a socket that does not support one or more of the values set in flags.
- EPIPE
- For a connected stream socket the connection to the peer socket
has been lost. A SIGPIPE signal is sent to the calling process.
- EWOULDBLOCK
- socket is in nonblocking mode and no
data buffers are available or the SO_SNDTIMEO timeout value was reached
before buffers became available.
The following are for AF_UNIX only:
- Error Code
- Description
- EACCES
- Search permission is denied for a component of the path prefix,
or write access to the named socket is denied.
- EIO
- An I/O error occurred while reading from or writing to the file
system.
- ELOOP
- Too many symbolic links were encountered in translating the pathname
in the socket address.
- ENAMETOOLONG
- A component of a pathname exceeded NAME_MAX characters,
or an entire pathname exceeded PATH_MAX characters.
- ENOENT
- A component of the pathname does not name an existing file or
the pathname is an empty string.
- ENOTDIR
- A component of the path prefix of the pathname in the socket
address is not a directory.