Receive a message from a socket
Synopsis:
#include <sys/types.h>
#include <sys/socket.h>
ssize_t recv( int s,
void * buf,
size_t len,
int flags );
Arguments:
- s
- The descriptor for the socket; see
socket().
- buf
- A pointer to a buffer where the function can store the message.
- len
- The size of the buffer. If len is greater than SSIZE_MAX
(see <limits.h>), the function fails and sets errno
to EOVERFLOW.
- flags
- A combination formed by ORing one or more of the values:
- MSG_DONTWAIT — if no data is available, then instead of blocking,
return immediately with the error EAGAIN.
- MSG_NOTIFICATION — if the flag is not set, then the function returns data.
If a notification has arrived, then the flag is set and it returns a notification in the msg_iov field.
- MSG_OOB — process out-of-band data.
This flag requests receipt of out-of-band data that wouldn't be
received in the normal data stream.
You can't use this flag with protocols that place expedited data at the
head of the normal data queue.
- MSG_PEEK — peek at the incoming message.
This flag causes the receive operation to return data from the
beginning of the receive queue without removing that data from the queue.
Thus, a subsequent receive call will return the same data.
- MSG_WAITALL — wait for full request or error. This
flag requests that the operation block until the full
request is satisfied. But the call may still return less
data than requested if a signal is caught, if an error or
disconnect occurs, or if the next data to be received is of
a different type than that returned.
- MSG_WAITFORONE — wait for one packet or an error. This flag causes the
operation to block until at least one packet is available. With this setting, you can receive
as many as vlen packets, but if only one is available, then the function
returns one. However, the call may return less data than available under the following scenarios:
- a signal is caught
- an error or disconnect occurs
- the incoming packet is a different data type from the one previously received
This flag turns on MSG_DONTWAIT after the first message has been received.
Library:
libsocket
Use the -l socket option to
qcc
to link against this library.
Description:
The recv() function receives a message from a socket.
It's normally used only on a connected socket—see
connect()—and is identical to
recvfrom()
with a zero from parameter.
This routine returns the length of the message on
successful completion. If a message is too long for the
supplied buffer, buf, then excess bytes might be discarded,
depending on the type of socket that the message is received from; see
socket().
If no messages are available at the socket, the receive call
waits for a message to arrive, unless the socket is
nonblocking—see ioctl()—in which case
-1 is returned and the external variable
errno is set to EWOULDBLOCK. Normally, the
receive calls return any data available, up to the requested
amount, rather than wait for the full amount requested; this
behavior is affected by the socket-level options SO_RCVLOWAT
and SO_RCVTIMEO described in
getsockopt().
You can use
poll()
to determine when more data is to arrive.
Returns:
The number of bytes received, 0 if there are no messages available and the peer has disconnected,
or -1 if an error occurs (errno is set).
Errors:
- EBADF
- Invalid descriptor s.
- EFAULT
- The receive buffer is outside the process's address space.
- EINTR
- The receive was interrupted by delivery of a signal
before any data was available.
- ENOTCONN
- The socket is associated with a connection-oriented
protocol and hasn't been connected; see
connect()
and
accept().
- EOVERFLOW
- An attempt was made to receive an amount of data that exceeds the allowable limit.
- EWOULDBLOCK
- Either the socket is marked nonblocking and the receive
operation would block, or a receive timeout had been set and
the timeout expired before data was received.
The errno variable can also be set to any of the errors indicated by
MsgSendv().
Classification:
POSIX 1003.1
Safety: |
|
Cancellation point |
Yes |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |