recvmsg - Receive a message from a socket using a message
structure
#include <sys/socket.h>
ssize_t recvmsg(
int socket,
struct msghdr *message,
int flags );
[Tru64 UNIX] The following definition of the recvmsg()
function does not conform to current standards and is supported
only for backward compatibility (see standards(5)):
int recvmsg(
int socket,
struct msghdr *message,
int flags );
Interfaces documented on this reference page conform to
industry standards as follows:
recvmsg(): XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the socket file descriptor. Points to a msghdr
structure, containing pointers to both the destination
address for the incoming message and to buffers containing
ancillary data. The format of the address is determined by
the behavior requested for the socket.
[Tru64 UNIX] If the compile-time option _SOCKADDR_LEN
is defined before the <sys/socket.h>
header file is included, the msghdr structure takes
4.4BSD behavior. Otherwise, the default 4.3BSD
msghdr structure is used.
In 4.4BSD, the msghdr structure has a separate
msg_options field for holding options from the
received message. In addition, the msg_accrights
field is generalized into a msg_control field. See
DESCRIPTION for more information.
If _SOCKADDR_LEN is defined, the 4.3BSD msghdr
structure is defined with the name omsghdr. Permits
the caller of this function to exercise control
over the reception of messages. The value for
this parameter is formed by a logical OR of one or
more of the following values: Peeks at the incoming
message. Processes out-of-band data on sockets
that support out-of-band data. Requests that the
function block wait until the full amount of data
requested can be returned. The function may return
a smaller amount of data if a signal is caught, the
connection is terminated, MSG_PEEK was specified,
or an error is pending for the socket.
The recvmsg() function receives messages from unconnected
or connected sockets and returns the total length of the
message.
For message-based sockets (for example, SOCK_DGRAM), you
must read the entire message in a single operation. When a
message is too long for the buffer and MSG_PEEK is not
specified, the message is truncated and MSG_TRUNC set in
the msg_options member or the msghdr structure. For
stream-based sockets (SOCK_STREAM), message boundaries are
ignored, and data is returned as soon as it is available.
If the MSG_WAITALL flag is not set, the function returns
data up to the end of the first message.
When no messages are available at the socket specified by
the socket parameter, the recvmsg() function waits for a
message to arrive. When the socket is nonblocking and no
message is available, the recvmsg() function fails and
sets errno to [EWOULDBLOCK].
Use the select() and poll() functions to determine when
more data arrives.
The recvmsg() function uses a msghdr structure to minimize
the number of directly supplied parameters. In the msghdr
structure, the msg_name and msg_namelen fields specify the
destination address if the socket is unconnected. The
msg_name field may be given as a null pointer if no names
are desired or required. The msg_iov and msg_iovlen fields
describe the scatter gather locations.
The msghdr structure uses a socklen_t data type for the
msg_iovlen field instead of a size_t data type as specified
in XNS4.0.
[Tru64 UNIX] In 4.3BSD, the msg_accrights field is a
buffer for passing access rights. In 4.4BSD, the
msg_accrights field has been expanded into a msg_control
field, to include other protocol control messages or other
miscellaneous ancillary data.
In the 4.4BSD msghdr structure, the msg_flags field holds
flags from the received message. In addition to MSG_PEEK
and MSG_OOB, the incoming flags reported in the msg_flags
field can be any of the following values: Data includes
the end-of-record marker. Out-of-band data was received.
Data was truncated before delivery. Control data was
truncated before delivery.
[Tru64 UNIX] When compiled in the X/Open UNIX environment,
calls to the recvmsg() function are internally
renamed by prepending _E to the function name. When you
are debugging a module that includes the recvmsg() function
and for which _XOPEN_SOURCE_EXTENDED has been
defined, use _Erecvmsg to refer to the recvmsg() call. See
standards(5) for further information.
[Tru64 UNIX] When compiled in the POSIX.1g socket environment,
calls to the recvmsg() function are internally
renamed by prepending _P to the function name. When you
are debugging a module that includes the recvmsg() function
and for which _POSIX_PII_SOCKET has been defined, use
_Precvmsg to refer to the recvmsg() call. See standards(5)
for further information.
Upon successful completion, the recvmsg() function returns
the length of the message in bytes, and fills in the
fields of the msghdr structure pointed to by the message
parameter as appropriate. If no messages are available and
the peer has closed the connection, the recv() function
returns a value of 0. Otherwise, a value of -1 is returned
and errno is set to indicate the error.
If the recvmsg() function fails, errno may be set to one
of the following values: The socket parameter is not
valid. A connection was forcibly closed by a peer. The
message parameter; storage pointed to by the msg_name,
msg_control, or msg_iov fields of the message parameter;
or storage pointed to by the iovec structures pointed to
by the msg_iov field are not in a readable or writable
part of user address-space. A signal interrupted this
function before any data was available. The MSG_OOB flag
is set and no out-of-band data is available.
The sum of the iov_len values overflows an ssize_t.
An I/O error occurred while reading from or writing
to the file system. The value of the msg_iovlen
member of the msghdr structure is less than or
equal to zero (0) or is greater than IOV_MAX.
Insufficient resources were available in the system
to complete the call. The system did not have sufficient
memory to fulfill the request. The available
STREAMS resources were insufficient for the
operation to complete. A receive is attempted on a
connection-oriented socket that is not connected.
The socket parameter refers to a file, not a
socket. The specified flags are not supported this
socket type. The connection timed out during connection
establishment, or due to a transmission
timeout on active connection. The socket is marked
nonblocking and no data is ready to be received.
The MSG-OOB flag is set, no out-of-band data is
available, and either the socket is marked nonblocking
or the socket does not support blocking to
wait for out-of-band data.
Functions: poll(2), recv(2), recvfrom(2), select(2),
send(2), sendmsg(2), sendto(2), shutdown(2), socket(2)
Standards: standards(5)
Network Programmer's Guide
recvmsg(2)
[ Back ] |
