 |
Index for
Section 2 |
|
 |
Alphabetical
listing for R |
|
 |
Bottom of
page |
|
recvmsg(2)
NAME
recvmsg - Receive a message from a socket using a message structure
SYNOPSIS
#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 );
STANDARDS
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.
PARAMETERS
socket
Specifies the socket file descriptor.
message
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.
flags
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:
MSG_PEEK Peeks at the incoming message.
MSG_OOB Processes out-of-band data on sockets that support out-of-
band data.
MSG_WAITALL 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.
DESCRIPTION
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:
MSG_EOR
Data includes the end-of-record marker.
MSG_OOB
Out-of-band data was received.
MSG_TRUNC
Data was truncated before delivery.
MSG_CTRUNC
Control data was truncated before delivery.
NOTES
[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.
RETURN VALUES
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.
ERRORS
If the recvmsg() function fails, errno may be set to one of the following
values:
[EBADF]
The socket parameter is not valid.
[ECONNRESET]
A connection was forcibly closed by a peer.
[EFAULT]
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.
[EINTR]
A signal interrupted this function before any data was available.
[EINVAL]
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.
[EIO]
An I/O error occurred while reading from or writing to the file system.
[EMSGSIZE]
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.
[ENOBUFS]
Insufficient resources were available in the system to complete the
call.
[ENOMEM]
The system did not have sufficient memory to fulfill the request.
[ENOSR]
The available STREAMS resources were insufficient for the operation to
complete.
[ENOTCONN]
A receive is attempted on a connection-oriented socket that is not
connected.
[ENOTSOCK]
The socket parameter refers to a file, not a socket.
[EOPNOTSUPP]
The specified flags are not supported this socket type.
[ETIMEDOUT]
The connection timed out during connection establishment, or due to a
transmission timeout on active connection.
[EWOULDBLOCK]
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.
SEE ALSO
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
|
Index for
Section 2 |
|
|
Alphabetical
listing for R |
|
 |
Top of
page |
|