|
Description
The recv(), recvfrom() and recvmsg() functions receive messages from a socket.
recv() can only receive messages from a socket over which a connection is set up (see "connect() - initiate a connection over a socket ").
recvfrom() and recvmsg() can receive messages from a socket with or without a connection.
The s parameter designates the socket from which the message is received.
If the from parameter is not the null pointer, the address of the message sender is stored in the address area referenced by from.
fromlen is a result parameter. The size_t variable, to which fromlen points, initially holds the size of the buffer referenced by from. After the function returns, *fromlen contains the current length of the address stored in *from. The function returns the length of the message.
The complete message must be read in a single operation for a datagram socket. If the specified message buffer is too small and MSG_PEEK is not set in the flags parameter, data exceeding the buffer size is deleted.
Message limits are ignored with a stream socket. A soon as data is available it is returned to the caller and no data is deleted.
If no messages are available on the socket, the receive call waits for an incoming message, unless the socket is non-blocking (see "ioctl() - control sockets"). In this case, -1 is returned and the errno variable is set to the value EWOULDBLOCK.
The poll() or select() functions can be used to determine when further data arrives.
If the process which calls recv(), recvfrom() or recvmsg() receives a signal before any data is available, the function concerned is called again in a standard case. The function is not called again if the calling process has specified with sigaction() to interrupt these function calls (see also the manual "C Library Functions for POSIX Applications").
The flags parameter indicates the type of message reception.
MSG_PEEK
Receives an incoming message. However, the data is handled as unread and the next receive function again returns this data.
MSG_WAITALL
The function blocks until the entire data that was requested can be returned.
A smaller amount of data can be returned in the following cases:
A signal arrives.
The connection is closed.
An error condition occurs.
The recvmsg() function uses the msghdr structure to reduce the number of directly specified parameters. The msghdr structure is declared as follows in the <sys/socket.h> header file:
struct msghdr {
void *msg_name; /* Optional address */
size_t msg_namelen; /* Length of address */
struct iovec *msg_iov; /* Scatter/gather fields */
int msg_iovlen; /* Number of members in msg-iov */
caddr_t msg_accrights; /* Send/receive access rights */
int msg_accrightslen;
void *msg_control; /* Auxiliary data */
size_t msg_controllen; /* Length of auxiliary data buffer */
int msg_flags; /* Flag for received message */
};
The members msg_name and msg_namelen contain the sending address and the address length of the partner if the socket has no connection set up. The partner address is a sockaddr structure. The actual format of the sockaddr structure depends on the address family involved and is described in the section "Socket addressing". If the socket has a connection set up, msg_name can be passed as a null pointer.
The members msg_iov and msg_iovlen describe the scatter and gather fields.
The elements msg_accrights and msg_accrightslen as well as msg_control and msg_controllen are ignored by default (see inline documentation in <sys/socket.h> if necessary).
Return value
>0:
If successful. The value indicates the number of received bytes.
=0:
If successful. No more data can be received. The partner has closed his connection correctly (only with type SOCK_STREAM sockets).
-1:
If errors occur. errno is set to indicate the error.
Errors
EBADF
The s parameter is not a valid descriptor.
ECONNRESET
The connection to the partner was interrupted (only with type SOCK_STREAM sockets).
EFAULT
The data is to be received in a non-existent or protected part of the process address range.
EINTR
The calling process has received a signal before any data could be received. The setting to interrupt the function call and not repeat it is active.
EINVAL
More than MSG_MAXIOVLEN scatter/gather fields were specified.
EIO
User data has been lost.
ENETDOWN
The connection to the network is down.
ENOTCONN
No connection exists for the socket.
ENOTSOCK
Descriptor s references a file and not a socket.
EOPNOTSUPP
The flags parameter contains an illegal value or msg_accrights was specified.
EWOULDBLOCK
The socket is marked as non-blocking and the requested operation would block.
See also
connect(), getsockopt(), send(), socket(), fcntl(), ioctl(), read(), select()