sendmsg() — Send messages on a socket
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>
ssize_t sendmsg(int socket, struct msghdr *msg, int flags);
#define _OE_SOCKETS
#include <sys/socket.h>
int sendmsg(int socket, struct msghdr *msg, int flags);
General description
- 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.
- 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.
- Element
- Description
- cmsg_len
- Data byte count, including header.
- cmsg_level
- Originating protocol.
- cmsg_type
- Protocol-specific type.
- 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.
- 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.
- 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.
- 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.
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.
- 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.
- 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.
Related information
- sys/socket.h
- connect() — Connect a socket
- fcntl() — Control open file descriptors
- getsockopt() — Get the options associated with a socket
- ioctl() — Control device
- read() — Read from a file or socket
- readv() — Read data on a file or socket and store in a set of buffers
- recv() — Receive data on a socket
- recvfrom() — Receive messages on a socket
- recvmsg() — Receive messages on a socket and store in an array of message headers
- select(), pselect() — Monitor activity on files or sockets and message queues
- selectex() — Monitor activity on files or sockets and message queues
- sendto() — Send data on a socket
- setsockopt() — Set options associated with a socket
- socket() — Create a socket
- write() — Write data on a file or socket
- writev() — Write data on a file or socket from an array