recv() — Receive data on a socket
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>
ssize_t recv(int socket, void *buffer, size_t length, int flags);
#define _OE_SOCKETS
#include <sys/socket.h>
int recv(int socket, char *buffer, int length, int flags);
General description
- Parameter
- Description
- socket
- The socket descriptor.
- buf
- The pointer to the buffer that receives the data.
- len
- The length in bytes of the buffer pointed to by the buf parameter. If the MSG_CONNTERM flag is set, the length of the buffer must be zero.
- flags
- The flags parameter is set by specifying
one or more of the following flags. If more than one flag is specified,
the logical OR operator ( | ) must be used to separate them. The MSG_CONNTERM flag is mutually exclusive with other
flags.
- MSG_CONNTERM
- Requests that the function completes only when a TCP connection
is terminated. It is valid for TCP sockets only. Other normal receive
requests are also completed. The application must be able to deal
with the fact that a normal receive and this special connection termination
receive might be driven in parallel. AT-TLS considerations: If AT-TLS is being used to provide transparent TLS/SSL support for a TCP socket and a receive request with MSG_CONNTERM is outstanding, AT-TLS will immediately honor any TLS/SSL close notify alerts sent by the peer and initiate TLS/SSL session shutdown. For more information about AT-TLS and determining whether a TCP connection is using AT-TLS, see z/OS Communications Server: IP Programmer's Guide and Reference.
- MSG_OOB
- Reads any out-of-band data on the socket. Out-of-band data is
sent when the MSG_OOB flag is on for a send(), sendto(), or sendmsg().
The fcntl() command should be used with F_SETOWN to specify the recipient, either a pid or a gid, of a SIGURG signal that will be sent when out-of-band data is sent. If no recipient is set, no signal will be sent. For more information, see the fcntl() command. The recipient of the data determines whether to receive out-of-band data inline or not inline by the setting of the SO_OOBINLINE option of setsockopt(). If SO_OOBINLINE is set off and the MSG_OOB flag is set on, the out-of-band data byte will be read out-of-line. It is invalid for the MSG_OOB flag to be set on when SO_OOBINLINE is set on. If there is out-of-band data available, and the MSG_OOB flag is not set (SO_OOBINLINE can be on or off), then the data up to, but not including, the out-of-band data will be read. When the read cursor has reached the out-of-band data byte, then only the out-of-band data will be read on the next read. The SIOCATMARK option of ioctl() can be used to determine if the read cursor is currently at the out-of-band data byte. For more information, refer to the setsockopt() and ioctl() commands.
- MSG_PEEK
- Peeks at the data present on the socket; the data is returned but not consumed, so that a subsequent receive operation sees the same data.
- MSG_WAITALL
- Requests that the function 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, an error is pending, or SO_RCVTIMEO is set and the timer is expired for the socket.
This call returns the length of the incoming message or data. If a datagram packet is too long to fit in the supplied buffer, datagram sockets discard excess bytes. If data is not available for the socket socket, and socket is in blocking mode, the recv() call blocks the caller until data arrives. If data is not available and socket is in nonblocking mode, recv() returns a -1 and sets the error code to EWOULDBLOCK. See fcntl() — Control open file descriptors or ioctl() — Control device for a description of how to set nonblocking mode.
For datagram sockets, this call returns the entire datagram that was sent, provided that the datagram fits into the specified buffer. Stream sockets act like streams of information with no boundaries separating data. For example, if applications A and B are connected with a stream socket and application A sends 1000 bytes, each call to this function can return 1 byte, or 10 bytes, or the entire 1000 bytes. Therefore, applications using stream sockets should place this call in a loop, calling this function until all data has been received.
Special behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Returned value
If successful, recv() returns the length of the message or datagram in bytes. The value 0 indicates the connection is closed.
- Error Code
- Description
- EBADF
- socket is not a valid socket descriptor.
- ECONNRESET
- A connection was forcibly closed by a peer.
- EFAULT
- Using the buf and len parameters would result in an attempt to access storage outside the caller's address space.
- EINTR
- The recv() call was interrupted by a signal that was caught before any data was available.
- EINVAL
- The request is invalid or not supported. The MSG_OOB flag is set and no out-of-band data is available.
- EIO
- There has been a network or transport failure.
- ENOBUFS
- Insufficient system resources are available to complete the call.
- ENOTCONN
- A receive is attempted on a connection-oriented socket that is not connected.
- ENOTSOCK
- The descriptor is for a file, not for a socket.
- EOPNOTSUPP
- The specified flags are not supported for this socket type or protocol.
- ETIMEDOUT
- The connection timed out during connection establishment, or due to a transmission timeout on active connection.
- EWOULDBLOCK
- socket is in nonblocking mode and data is not available to read. or the SO_RCVTIMEO timeout value was been reached before data was available.
Related information
- sys/socket.h
- connect() — Connect a socket
- fcntl() — Control open file descriptors
- getsockopt() — Get the options associated with a socket
- ioctl() — Control device
- read() — Read from a file or socket
- readv() — Read data on a file or socket and store in a set of buffers
- recvfrom() — Receive messages on a socket
- recvmsg() — Receive messages on a socket and store in an array of message headers
- select(), pselect() — Monitor activity on files or sockets and message queues
- selectex() — Monitor activity on files or sockets and message queues
- send() — Send data on a socket
- sendmsg() — Send messages on a socket
- sendto() — Send data on a socket
- setsockopt() — Set options associated with a socket
- socket() — Create a socket
- write() — Write data on a file or socket
- writev() — Write data on a file or socket from an array