recv, recvfrom, recvmsg

Purpose

     Receives a message from a socket.

Library

     Sockets Library (libsock.a)

Syntax

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

     int recv (s, buf, len, flags)        int 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 subroutine  can  be 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  zero, the
     source address of the message  is filled in.  The fromlen
     parameter is initialized to the  size of the buffer asso-
     ciated with the  from parameter.  On return,  it is modi-
     fied to  indicate the actual  size of the  address stored
     there.   These  subroutines  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
     subroutines  wait for  a  message to  arrive, unless  the
     socket is  non-blocking.  If a socket  is non-blocking, a
     "-1" is returned with the  external variable errno set to
     EWOULDBLOCK.

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

     The flags  argument to receive  a call is formed  by log-
     ically OR-ing one or more of the values shown in the fol-
     lowing list:

     MSG_PEEK   Peeks at incoming message.

     MSG_OOB    Processes out-of-band data.

     The recvmsg  subroutine uses a msghdr  structure to mini-
     mize  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  iov *msg_iov;      /* scatter/gather array         */
          int     msg_iovlen;        /* # of elements in msg_iov     */
          caddr_t msg_accrights;     /* access rights sent/received  */
          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
     routine fails,  a value of  -1 is returned, and  errno is
     set to indicate the error.

     Diagnostics

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

     EBADF             The s parameter is not valid.

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

     EWOULDBLOCK       The socket is  marked non-blocking, and
                       no  connections   are  present   to  be
                       accepted.

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

     EFAULT            The addr parameter is not in a writable
                       part of the user address space.

     Related Information

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