recv(3N)                                                           recv(3N)


   NAME
         recv, recvfrom, recvmsg - receive a message from a socket

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

         int recv(s, buf, len, flags)
         int s;
         char *buf;
         int len, flags;

         int recvfrom(s, buf, len, flags, from, fromlen)
         int s;
         char *buf;
         int len, flags;
         struct sockaddr *from;
         int *fromlen;

         int recvmsg(s, msg, flags)
         int s;
         struct msghdr *msg;
         int flags;

   DESCRIPTION
         s is a socket created with socket(3N).  recv(), recvfrom(), and
         recvmsg() are used to receive messages from another socket.  recv()
         may be used only on a connected socket (see connect(3N)), 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 not a NULL pointer, the source address of the message is
         filled in.  fromlen 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.  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(3N)).

         If no messages are available at the socket, the receive call waits
         for a message to arrive, unless the socket is nonblocking (see
         fcntl(2)) in which case -1 is returned with the external variable
         errno set to EWOULDBLOCK.

         The select() call may be used to determine when more data arrives.

         The flags parameter is formed by ORing one or more of the following:

         MSGOOB   Read any out-of-band data present on the socket rather than
                   the regular in-band data.



   7/91                                                                 Page 1

   recv(3N)                                                           recv(3N)


         MSGPEEK  Peek at the data present on the socket; the data is
                   returned, but not consumed, so that a subsequent receive
                   operation will see the same data.

         The recvmsg() call uses a msghdr structure to minimize the number of
         directly supplied parameters.  This structure is defined in
         /usr/include/sys/socket.h and includes the following members:

               caddrt      msgname;         /* optional address */
               int          msgnamelen;      /* size of address */
               struct iovec *msgiov;         /* scatter/gather array */
               int          msgiovlen;       /* # elements in msgiov */
               caddrt      msgaccrights;    /* access rights sent/received */
               int          msgaccrightslen;

         Here msgname and msgnamelen specify the destination address if the
         socket is unconnected; msgname may be given as a NULL pointer if no
         names are desired or required.  The msgiov and msgiovlen describe
         the scatter-gather locations, as described in read(2).  A buffer to
         receive any access rights sent along with the message is specified in
         msgaccrights, which has length msgaccrightslen.

   RETURN VALUE
         These calls return the number of bytes received, or -1 if an error
         occurred.

   ERRORS
         The calls fail if:

         EBADF               s is an invalid descriptor.

         ENOTSOCK            s is a descriptor for a file, not a socket.

         EINTR               The operation was interrupted by delivery of a
                             signal before any data was available to be
                             received.

         EWOULDBLOCK         The socket is marked non-blocking and the
                             requested operation would block.

         ENOMEM              There was insufficient user memory available for
                             the operation to complete.

         ENOSR               There were insufficient STREAMS resouces
                             available for the operation to complete.

   SEE ALSO
         connect(3N), fcntl(2), getsockopt(3N), ioctl(2), read(2), send(3N),
         socket(3N).




   Page 2                                                                 7/91