RECV

C Interface

        #include <sys/types.h>

        #include <sys/socket.h>



        recv(s, buf, len, flags)

        int s;

        char *buf;

        int len, flags;



        recvmsg(s, msg, flags)

        int s;

        struct msghdr msg[];

        int flags;



   AF_UNIX only:



        #include <sys/types.h>

        #include <sys/socket.h>

        #include <sys/un.h>



        recvfrom(s, buf, len, flags, from, fromlen)

        int s;

        char *buf;

        int len, flags;

        struct sockaddr_un *from;

        int *fromlen;



   AF_INET only:



        #include <sys/types.h>

        #include <sys/socket.h>

        #include <netinet/in.h>



        recvfrom(s, buf, len, flags, from, fromlen)

        int s;

        char *buf;

        int len, flags;

        struct sockaddr_in *from;

        int *fromlen;

Description

The recv, recvfrom, and recvmsg calls are used to receive messages from a socket.

The argument s is a socket descriptor from which the message is received. The buf parameter is a pointer to the buffer into which the messages are placed. The len parameter is the maximum number of bytes that will fit into the buffer referenced by buf.

If the socket uses connection-based communications (for example, a SOCK_STREAM socket), then these calls can be used only after the connection has been established. (Refer to connect) For connection-less sockets (for example, a SOCK_DGRAM socket), these calls can be used whether a connection has been established or not.

The recvfrom call operates the same as the recv call does, except that it is able to return the address of the socket from which the message was sent. If from is non-zero, the source address of the message is placed into the socket address structure pointed to by from. The fromlen parameter is a value-result parameter, initialized to the size of the structure associated with from, and modified 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.

The length of the message is the functional return.

For message-based sockets like SOCK_DGRAM, the entire message must be read in one operation. If a message is too long to fit in the supplied buffer, the excess bytes are discarded. For stream-based sockets like SOCK_STREAM, there is no concept of message boundaries. In this case, data is returned to the user as soon as it becomes available, and no data is discarded.

If no data is available to be received, recv waits for a message to arrive unless non-blocking mode is enabled. There are two ways to enable non-blocking mode: with the O_NONBLOCK fcntl flag, and with the O_NDELAY fcntl flag.

If O_NONBLOCK is set using sfcntl (defined in <fcntl.h.sys> and explained in the fcntl section), POSIX-style non-blocking I/O is enabled. In this case, the recv request completes in one of three ways:

If there is enough data available to satisfy the entire request, recv 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, recv completes successfully, having read as much data as possible, and returns the number of bytes that it was able to read.
If there is no data available, recv completes successfully, having read no data, and returns a -1 with errno set to EAGAIN.

If O_NDELAY is set using sfcntl (defined in <fcntl.h.sys> and explained in the fcntl section), non-blocking I/O is enabled. In this case, the recv request completes in one of three ways:

If there is enough data available to satisfy the entire request, recv 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, recv completes successfully, having read as much data as possible, and returns the number of bytes that it was able to read.
If there is no data available, recv completes successfully, having read no data, and returns a 0.

If O_NONBLOCK or O_NDELAY is cleared using sfcntl, the corresponding style of non-blocking I/O, if previously enabled, is disabled. In this case, recv always executes completely (blocking as necessary) and returns the number of bytes read.

To summarize, both behave the same if there is enough data available to satisfy the entire request or even part of the request. They differ only in the third case, where there is no data available.

The select call can be used to determine when more data arrives by selecting the socket for reading.

The flags parameter can be set to MSG_PEEK or zero. If it is set to MSG_PEEK, any data returned to the user is treated as if it had not been read. The next recv rereads the same data. The value is as follows:

#define  MSG_PEEK  0x2   /* peek at incoming message */

A read call behaves the same way as a recv call with flags set to zero.

The recv|msg call uses a msghdr structure to minimize the number of directly supplied parameters. This structure has the following form, as defined in <sys/socket.h>:

   struct msghdr {

          caddr_t msg_name;         /* optional address            */

          int     msg_namelen;      /* size of address             */

          struct  iov *msg_iov;     /* scatter/gather array        */

          int     msg_iovlen;       /* # elements in msg_iov       */

          caddr_t msg_accrights;    /* access rights sent/received */

          int     msg_accrightslen;};

Here, msg_name and msg_namelen specify the destination address if the socket is unconnected, and msg_name can be given as a null pointer if no names are desired or required. The msg_iov and msg_iovlen describe the scatter gather locations, as described in read. Access rights to be sent with the message are specified in msg_accrights, which has msg_accrightslen.

Return Value

If the call is successful, it returns the number of bytes received. If the call fails, a -1 is returned, and an error code is stored in errno. A zero is returned if the socket is blocking and the transport connection to the remote node fails.

Errors

The following errors are returned by recv, recvfrom, or recvmsg:

[EBADF]: The argument s is an invalid descriptor.
[ENOTSOCK]: The argument s is not a socket.
[EWOULDBLOCK]: The socket is marked non-blocking, and the receive operation would block.
[EFAULT]: The buf, from, or fromlen parameters are not valid pointers.
[ETIMEDOUT]: The connection timed out during connection establishment, or due to a transmission timeout on an active connection.
[ENOTCONN]: Receive on a SOCK_STREAM socket that is not yet connected.
[EINVAL]: The len parameter is bad or there is no data available on a receive of out-of-band data.
[EINTR]: The call was interrupted by a signal before a valid connection arrived.
[EOPNOTSUPP]: A receive was attempted on a SOCK_DGRAM socket that has not been bound. A bind should be done before the receive.
[ENOBUFS]: Insufficient buffer memory is available.

MPE/iX Specific

For AF_UNIX, recvfrom() is supported; however, the from and fromlen parameters are ignored (that is, it works just like recv()).

The recv call can only be done on SOCK_STREAM sockets.

The recvfrom call can only be done on SOCK_DGRAM sockets.

The MSG_OOB flag, used for processing out-of-band data, is not supported on MPE/iX.

Author

UCB (University of California at Berkeley)