recv(2) CLIX recv(2)
NAME
recv, recvfrom, recvmsg - Receives a message from a socket
LIBRARY
Berkeley Software Distribution Library (libbsd.a)
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
int recv(
int s ,
char *buf ,
int len ,
int flags );
int recvfrom(
int s ,
char *buf ,
int len ,
int flags ,
struct sockaddr *from ,
int *fromlen );
int recvmsg(
int s ,
struct msghdr msg[] ,
int flags );
PARAMETERS
s Represents a socket descriptor.
buf Contains upon return the data that was read from the socket.
len Specifies the amount of space pointed to by buf.
flags Defines what type of data should be read.
from Contains the address of the socket that data is to be received
from.
fromlen Specifies the amount of space pointed to by from.
msg Specifies a scatter gather array to store the data in.
DESCRIPTION
2/94 - Intergraph Corporation 1
recv(2) CLIX recv(2)
The recv(), recvfrom(), and recvmsg() functions are used to receive
messages from a socket.
The recv() function is normally used only on a connected socket (see the
connect() function), while recvfrom() and recvmsg() may be used to receive
data on a socket whether it is in a connected state or not.
If from is nonzero, the source address of the message is filled in. The
fromlen parameter is a value-result parameter initialized to the size of
the buffer associated with from and modified on return to indicate the
actual size of the address stored there. The length of the message is
returned by the function. If a message is too long to fit in the supplied
buffer, excess bytes may be discarded depending on the type of socket the
message is received from. (See socket().)
If no messages are available at the socket, the receive function waits for
a message to arrive unless the socket is marked nonblocking. (See the
fcntl() function.) The select() function may be used to determine when
more data is available to read.
The flags parameter to a recv() function may have the following value:
#define MSG_OOB 0x1 /* process out-of-band data */
The recvmsg() function uses a msghdr structure to minimize the number of
directly supplied parameters. This structure has the following form,
defined in <sys/socket.h>:
struct msghdr {
caddr_t msg_name; /* optional address */
int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_accrights; /* access rights sent/received */
int msg_accrightslen;
};
The msg_name and msg_namelen members specify the destination address if
the socket is unconnected; msg_name may be given as a null pointer if no
names are desired or required. The msg_iov and msg_iovlen members
describe the scatter gather locations, as described in readv(). A buffer
to receive any access rights sent with the message is specified in
msg_accrights, which has length msg_accrightslen. Access rights are
currently limited to file descriptors, which each occupy the size of an
integer.
EXAMPLES
To read 20 bytes of normal data:
if (recv(sd, buf, 20, 0) == -1)
2 Intergraph Corporation - 2/94
recv(2) CLIX recv(2)
perror("Recv failed");
RETURN VALUES
Upon successful completion, the number of bytes received is returned.
Otherwise, a value of -1 is returned and errno is set to indicate the
error.
ERRORS
Each of these functions fails if one or more of the following is true:
[EBADF]
The descriptor is not valid.
[ENOTSOCK]
The descriptor references a file, not a socket.
[EWOULDBLOCK]
The socket is marked nonblocking, and the requested operation would
block.
[EINTR]
A signal was caught during the recv(), recvfrom(), or recvmsg()
function.
[EFAULT]
The data was specified to be received into a nonexistent or
protected part of the user address space.
[ECONNRESET]
The connection has been broken and there is no more data to read.
[EINVAL]
The maximum number of scatter gather locations has been exceeded.
RELATED INFORMATION
Functions: fcntl(2), readv(2), send(2), select(2), getsockopt(2),
socket(2)
2/94 - Intergraph Corporation 3