Open System Services System Calls Reference Manual (G06.25+, H06.03+)

recvmsg(2) OSS System Calls Reference Manual
If no messages are available at the socket and the socket’s file descriptor is blocking
(O_NONBLOCK is not set), the recvmsg() function blocks until a message arrives. If no mes-
sages are available at the socket and the socket’s file descriptor is marked nonblocking
(O_NONBLOCK is set), the recvmsg() function fails and sets errno to [EWOULDBLOCK].
In the msghdr structure, the msg_name and msg_namelen members specify the source address
if the socket is unconnected. If the socket is connected, the msg_name and msg_namelen
members are ignored. The msg_name member can be a null pointer if no names are desired or
required. The msg_iov and msg_iovlen members describe the scatter/gather locations.
Upon successful completion of the recvmsg() call, the value of the msg_flags member of the
msghdr structure is the bitwise OR of zero or more of the following values:
MSG_CTRUNC
Control data was truncated.
MSG_OOB Out-of-band data was received.
MSG_TRUNC
Normal data was truncated.
In the msghdr structure, the msg_control and msg_controllen members specify the ancillary
data buffer that can be used only by sockets in the AF_UNIX domain to receive file descriptors
passed from another process on the same node. The msg_control member can be a null pointer
if ancillary data is not desired or required. If the msg_control member is nonnull, on input the
msg_controllen member contains the size of the ancillary data buffer and on output it contains
the size of the received ancillary data. If, on output, the msg_controllen member is nonzero, the
ancillary data buffer contains a cmsghdr structure followed by one to sixteen file descriptors.
If recvmsg() is called with an ancillary data buffer and MSG_PEEK is set, the msg_controllen
member is valid, but the ancillary data is not meaningful (no file descriptors are received).
Ancillary data is not discarded but remains available for the next call to recvmsg() where
MSG_PEEK is set.
If recvmsg() is called with an ancillary data buffer that is too small to hold the available file
descriptors, MSG_CTRUNC is set, and the excess file descriptors are discarded.
If recvmsg() is called with an ancillary data buffer and one or more of the received file descrip-
tors are unusable (perhaps because of a device error), there is no error indication until the file
descriptor is used.
NOTES
When data is available, a call to the select() function indicates that the file descriptor for the
socket is ready for reading.
RETURN VALUES
Upon successful completion, the recvmsg() function returns the length of the received message
in bytes. If no data is available and the peer socket has performed an orderly shutdown, 0 (zero)
is returned.
If the recvmsg() function call fails, the value -1 is returned, and errno is set to indicate the error.
ERRORS
If any of these conditions occurs, the recvmsg() function sets errno to the corresponding value:
[EBADF] The socket parameter is not a valid file descriptor.
6−20 Hewlett-Packard Company 527186-003