recv(2)recv(2)NAMErecv(), recvfrom(), recvmsg() - receive a message from a socket
SYNOPSIS
UNIX 03 Only (X/Open Sockets)
Obsolescent UNIX 95 Only (X/Open Sockets)
DESCRIPTION
The and system calls are used to receive messages from a socket.
s is a socket descriptor from which messages are received.
buf is a pointer to the buffer into which the messages are placed.
len is the maximum number of bytes that can fit in the buffer refer‐
enced by buf.
If the socket uses connection-based communications, such as a
SOCK_STREAM socket, these calls can only be used after the connection
has been established (see connect(2)). For connectionless sockets such
as SOCK_DGRAM, these calls can be used whether a connection has been
specified or not.
operates in the same manner as except that it is able to return the
address of the socket from which the message was sent. For connected
datagram sockets, simply returns the same address as (see getpeer‐
name(2)). For stream sockets, retrieves data in the same manner as but
does not return the socket address of the sender. If from is nonzero,
the source address of the message is placed in the socket address
structure pointed to by from. fromlen is a value-result parameter,
initialized to the size of the structure associated with from, and mod‐
ified on return to indicate the actual size of the address stored
there. If the memory pointed to by from is not large enough to contain
the entire address, only the first fromlen bytes of the address are
returned.
For message-based sockets such as SOCK_DGRAM, the entire message must
be read in a single operation. If a message is too long to fit in the
supplied buffer, the excess bytes are discarded. For stream-based
sockets such as SOCK_STREAM, there is no concept of message boundaries.
In this case, data is returned to the user as soon as it becomes avail‐
able, and no data is discarded. See the AF_CCITT Only subsection below
for a list of the exceptions to this behavior for connections in the
address family AF_CCITT.
performs the same action as but scatters the read data into the buffers
specified in the structure (see below). This structure is defined in
and has the following form
msg_name points to a structure in which the address of the sending
socket is to be stored, if the socket is connectionless; msg_name may
be a null pointer if no name is specified. msg_iov specifies the loca‐
tions of the character arrays for storing the incoming data.
msg_accrights specifies a buffer to receive any access rights sent
along with the message. Access rights are limited to file descriptors
of size int. If access rights are not being transferred, set the
msg_accrights field to NULL. Access rights are supported only for
AF_UNIX.
By default, and are blocking system calls and do not complete until
there is data to read or the end of the socket data stream is reached
(the remote side of a connection-based socket has performed an orderly
shutdown and there is no more data to read).
There are three ways to enable nonblocking mode:
· With the request
· With the flag
· With the flag
Although the use of is not recommended, if nonblocking I/O is enabled
using or the equivalent request (defined in and explained in ioctl(2),
ioctl(5) and socket(7)), the request completes in one of six ways:
· If there is enough data available to satisfy the entire request,
completes successfully, having read all of the data, and returns
the number of bytes read.
· If there is not enough data available to satisfy the entire
request, completes successfully, having read as much data as pos‐
sible, and returns the number of bytes it was able to read.
· If there is no data available, returns −1 and is set to
· If the remote side of a connection-based socket has performed an
orderly shutdown and there is no more data to read (the socket has
reached the end of its data stream), returns 0.
· If the remote side of a connection-based socket has reset the con‐
nection, returns −1 and sets to
· If an error occurs, returns −1 and sets to indicate the error.
If nonblocking I/O is disabled using always executes completely (block‐
ing as necessary) and returns the number of bytes read.
If the flag is set using (defined in and explained in fcntl(2) and
fcntl(5)), POSIX-style nonblocking I/O is enabled. In this case, the
request completes in one of six ways:
· If there is enough data available to satisfy the entire request,
completes successfully, having read all the data, and returns the
number of bytes read.
· If there is not enough data available to satisfy the entire
request, completes successfully, having read as much data as pos‐
sible, and returns the number of bytes it was able to read.
· If there is no data available, completes, having read no data, and
returns −1 and sets to
· If the remote side of a connection-based socket has performed an
orderly shutdown and there is no more data to read (the socket has
reached the end of its data stream), returns 0.
· If the remote side of a connection-based socket has reset the con‐
nection, returns −1 and sets to
· If an error occurs, returns −1 and is set to indicate the error.
If the flag is set using (defined in and explained in fcntl(2) and
fcntl(5)), nonblocking I/O is enabled. In this case, the request com‐
pletes in one of five ways:
· If there is enough data available to satisfy the entire request,
completes successfully, having read all the data, and returns the
number of bytes read.
· If there is not enough data to satisfy the entire request com‐
pletes successfully, having read as much data as possible, and
returns the number of bytes it was able to read.
· If the remote side of a connection-based socket has performed an
orderly shutdown and there is no more data to read (the socket has
reached the end of its data stream), completes and returns 0. The
call will also complete and return 0 when there is no data to
read. To distinguish this condition from the end of the data
stream, you can use a or call to check for data before calling If
the or call indicates that an event has occurred on the socket,
the subsequent but call will only return 0 if the socket has
reached the end of the data stream.
· If the remote side of a connection-based socket has reset the con‐
nection, returns −1 and sets to
· If an error occurs, returns −1 and is set to indicate the error.
If the or flag is cleared using the corresponding style of nonblocking
I/O, if previously enabled, is disabled. In this case, always executes
completely (blocking as necessary) and returns the number of bytes
read.
Since both the and flags and request are supported, some clarification
on how these features interact is necessary. If the or flag has been
set, requests behave accordingly, regardless of any requests. If nei‐
ther the flag nor the flag has been set, requests control the behavior
of
By default nonblocking I/O is disabled.
can be used to determine when more data arrives by selecting the socket
for reading.
The flags parameter can be set to both, or zero. If it is set to any
data returned to the user still is treated as if it had not been read.
The next rereads the same data. The flag is used to receive out-of-
band data. For TCP SOCK_STREAM sockets, both the and flags can be set
at the same time. The flag value is supported for TCP SOCK_STREAM
sockets only. is not supported for AF_UNIX or AF_VME_LINK sockets.
A call made to a socket behaves in exactly the same way as a with flags
set to zero.
AF_CCITT Only
Connections in the address family AF_CCITT support message-based sock‐
ets only. Although the user specifies connection-based communications
(SOCK_STREAM), the X.25 subsystem communicates via messages. This
address family does not support SOCK_DGRAM socket types.
Normally, each returns one complete X.25 message. If the socket is in
nonblocking mode, behaves as described above. Note that if the user
specifies len less than the actual X.25 message size, the excess data
is discarded and no error indication is returned. The size of the next
available message as well as the state of MDTF, D, and Q bits can be
obtained with
Connections of the address family AF_CCITT receive data in the same way
as message-based connections described above, with the following addi‐
tions and exceptions:
· is supported; however, the from and fromlen parameters are ignored
(that is, it works in the same manner as
· To receive a message in fragments of the complete X.25 message,
use The state of the MDTF bit is 1 for all except the last frag‐
ment of the message.
· The flag is supported.
· The flag is supported; the two flags can be combined.
· If a message is received that is larger than the user-controlled
maximum message size, the X.25 subsystem RESETs the circuit, dis‐
cards the data, and sends the out-of-band event to the socket.
X/Open Sockets Only
For the structure has the following form:
msg_control specifies a buffer to receive any ancillary data sent along
with the message. Ancillary data consists of a sequence of pairs, each
consisting of a structure followed by a data array. The data array
contains the ancillary data message, and the structure contains
descriptive information that allows an application to correctly parse
the data. has the following structure:
If the cmsg_level is SOL_SOCKET, and cmsg_type is SCM_RIGHTS, then it
indicates that the data array contains the access rights to be
received. Access rights are supported only for AF_UNIX. Access rights
are limited to file descriptors of size int.
If the cmsg_level is then cmsg_type must be one of the supported types:
or (See description in IPv6(7P)).
If ancillary data are not being transferred, set the msg_control field
to NULL, and set the msg_controllen field to 0.
The flags parameter accepts a new value, which requests that the func‐
tion block 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, or an error is pending for the socket.
On successful completion of the msg_flags member of the message header
is the bitwise-inclusive OR of all of the following flags that indicate
conditions detected for the received message.
End of record was received (if supported by the protocol).
Out-of-band data was received.
Normal data was truncated.
Control data was truncated.
X/Open Sockets Compilation Environment
See xopen_networking(7).
DEPENDENCIES
AF_CCITT
is supported; however, the from and fromlen parameters are ignored (it
works in the same manner as
The call is not supported over X.25 links. Use the call instead to
enable nonblocking I/0.
RETURN VALUE
and return the following values:
Successful completion.
n is the number of bytes received.
The socket is blocking
and the transport connection to the remote node failed,
or the remote side of a connection-based socket has per‐
formed an orderly shutdown and there is no more data to
read (the socket has reached the end of its data stream).
Sockets with the flag set may also return 0 at any time
when there is no data available.
Failure.
is set to indicate the error.
ERRORS
If or fails, is set to one of the following values.
Non-blocking I/O is enabled using
flag with and the receive operation would
block, or the socket has an error that was
set asynchronously. An asynchronous error
can be caused by a gateway failing to for‐
ward a datagram because the datagram exceeds
the MTU of the next-hop network and the
"Don't Fragment" (DF) bit in the datagram is
set. (See in getsockopt(2).)
The argument s is an invalid descriptor.
A connection was forcibly closed by a peer.
An invalid pointer was specified in the
buf, from, or fromlen parameter, or in the
msghdr structure.
The receive was interrupted by delivery of a signal
before any data was available for the
receive.
The len parameter or a length in the msghdr
structure is invalid; or no data is avail‐
able on receive of out of band data.
The number of file descriptors available to the calling
process has been exceeded.
A length in the msghdr structure is invalid.
Insufficient resources were available in the system
to perform the operation.
The remote system or an intermediate system in the communica‐
tions path
does not support a protocol option sent by
the local system. This option may have been
set using a or call, or set as a system
parameter.
Buffers could not be allocated for the message
that was to be created due to insufficient
STREAMS memory resources.
Receive on a SOCK_STREAM
socket that is not yet connected.
The argument s is a valid file descriptor, but it is not
a socket.
The flag was set for a UDP SOCK_DGRAM message-
based socket, or or was set for any AF_UNIX
socket. The flag is supported only for
stream-based TCP SOCK_STREAM sockets. Nei‐
ther nor is supported for AF_UNIX sockets.
AF_CCITT only: was issued on a socket.
The connection timed out during connection establishment,
or due to a transmission timeout on active
connection.
Non-blocking I/O is enabled using
request, and the requested operation would
block.
OBSOLESCENCE
Currently, the and types are the same size. This is compatible with
the UNIX 95 and UNIX 03 profiles. However, in a future release, might
be a different size. In that case, passing a pointer will evoke com‐
pile-time warnings, which must be corrected in order for the applica‐
tion to behave correctly. Also, the size of the and structures and the
relative position of their members will be different, which might
affect application behavior. Applications that use now, where appro‐
priate, will avoid such migration problems. On the other hand, appli‐
cations that need to be portable to the UNIX 95 profile should follow
the X/Open specification (see xopen_networking(7)).
WARNINGS
Linking binary objects compiled to specification and binary objects
compiled to specification to the same executable may result in unex‐
pected behavior, including application abnormal termination and unex‐
pected socket errors. See xopen_networking(7) for details and remedy.
FUTURE DIRECTION
Currently, the default behavior is the however, it might be changed to
in a future release. At that time, any behavior that is incompatible
with might be obsoleted. Applications that conform to the X/Open spec‐
ification now will avoid migration problems (see xopen_networking(7)).
AUTHOR
and were developed by HP and the University of California, Berkeley.
SEE ALSOgetsockopt(2), read(2), select(2), send(2), socket(2),
thread_safety(5), inet(7F), socket(7), IPv6(7P), sctp(7), TCP(7P),
UDP(7P), UNIX(7P), xopen_networking(7).
STANDARDS CONFORMANCErecv(2)
