recv(2) — AIX PS/2 1.2.1



RECV(2,L)                   AIX Technical Reference                   RECV(2,L)



-------------------------------------------------------------------------------
recv, recvfrom, recvmsg



PURPOSE

Receives a message from a socket.

SYNTAX

#include <sys/types.h>
#include <sys/socket.h>




   int recv (s, buf, len, flagsint recvfrom (s, buf, len, flags, from, fromlen)
   int s;                      int s;
   char *buf;                  char *buf;
   int len, flags;             int len, flags;
                               struct sockaddr *from;
   int recvmsg (s, msg, flags) int *fromlen;
   int s;
   struct msghdr msg [ ];
   int flags;



DESCRIPTION

The recv system call is normally used only on a connected socket (see
"connect"), but recvfrom and recvmsg can be used to receive data on a socket
whether it is connected or not.

If the value of from is anything other than 0, the source address of the
message is filled in.  The fromlen parameter is initialized to the size of the
buffer associated with the from parameter.  On return, it is modified to
indicate the actual size of the address stored there.  These system calls
return the length of the message.  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.  For more information, see "socket."

If no messages are available at the socket, the receive system calls wait for a
message to arrive, unless the socket is nonblocking.  A socket marked
nonblocking with the O_NONBLOCK flag or the FIONBIO ioctl returns a value of -1
and sets errno to EAGAIN in the situation where it would otherwise have
blocked.  A socket marked with the O_NDELAY flag returns ZERO in the situation
where it would otherwise have blocked.

Use the select system call to determine when more data arrives.  For more
information, see "select."



Processed November 7, 1990         RECV(2,L)                                  1



RECV(2,L)                   AIX Technical Reference                   RECV(2,L)




The flags argument to a receive call is formed by logically ORing one or more
of the values shown in the following list:

MSG_PEEK    Peeks at incoming message.

MSG_OOB     Processes out-of-band data.  This flag can only be used for stream
            sockets in the INET domain.  It is not supported in the UNIX domain
            and does not work for datagrams.  In addition, only one byte of
            out-of-band data can be processed at a time.

The recvmsg system call uses a msghdr structure to minimize the number of
directly supplied parameters.  The msghdr structure is defined in the
sys/socket.h header file, and it contains the following members:

     caddr_t msg_name;          /* optional address             */
     int     msg_namelen;       /* size of address              */
     struct  iovec *msg_iov;    /* scatter/gather array         */
     int     msg_iovlen;        /* # of elements in msg_iov     */
     caddr_t msg_accrights;     /* access rights are currently  */
                                /* limited to file descriptors, */
                                /* which each occupy the size   */
                                /* of an int           */
     int     msg_accrightslen;  /* length of access rights      */

In the above structure, the fields are defined as follows:

msg_name     Defines the destination address if the socket is unconnected.  If
             no names are needed, you can use a NULL pointer for msg_name.

msg_namelen  Specifies the size of msg_name.

msg_iov      Describes the scatter gather locations.

msg_iovlen   Specifies the number of elements in the msg_iov array.

msg_accrights
             Defines the access rights sent with the message.

msg_accrightslen
             Specifies the length of the access rights.

RETURN VALUE

Upon successful completion, the length of the message in bytes is returned.  If
the recv, recvfrom, or recvmsg system call fails, a value of -1 is returned,
and errno is set to indicate the error.  A socket marked with the O_NDELAY flag
returns ZERO in the situation where it would otherwise have blocked.

ERROR CONDITIONS

The system call fails if one or more of the following are true:



Processed November 7, 1990         RECV(2,L)                                  2



RECV(2,L)                   AIX Technical Reference                   RECV(2,L)




EBADF     The s parameter is not valid.

ENOTSOCK  The s parameter refers to a file, not a socket.

EAGAIN    The socket is marked nonblocking with the O_NONBLOCK flag or the
          FIONBIO ioctl in the situation where it would otherwise have blocked.

EINTR     The receive was interrupted by delivery of a signal before any data
          was available for the receive.

EFAULT    The data was specified to be received into a nonwritable part of the
          user address space.

EINVAL    The msg_iovlen field of the msghdr structure passed into a recvmsg
          call was negative.

RELATED INFORMATION

In this book:  "send, sendto, sendmsg" and "socket."



































Processed November 7, 1990         RECV(2,L)                                  3

Museum

Related Articles