recvfrom

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

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


SYNOPSIS

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


       int recv(int s, void *buf, int len, unsigned int flags);

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

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


DESCRIPTION

       WARNING:  This  is  a  BSD man page.  As of Linux 0.99.11,
       recvmsg was not implemented.

       Recvfrom and recvmsg are used to receive messages  from  a
       socket,  and  may  be  used  to  receive  data on a socket
       whether or not it is connection-oriented.

       If from is non-nil, and the socket is not  connection-ori-
       ented,  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  recv call is normally used only on a connected socket
       (see connect(2)) and is identical to recvfrom with  a  nil
       from  parameter.   As  it is redundant, it may not be sup-
       ported in future releases.

       All three routines return the length  of  the  message  on
       successful completion.  If a message is too long to fit in
       the supplied buffer, excess bytes may be discarded depend-
       ing  on  the  type  of socket the message is received from
       (see socket(2)).

       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 the value  -1  is
       returned  and  the  external variable errno set to EWOULD-
       BLOCK.  The receive calls normally return any data  avail-
       able,  up to the requested amount, rather than waiting for
       receipt of the full amount  requested;  this  behavior  is
       affected  by  the  socket-level  options  SO_RCVLOWAT  and
       SO_RCVTIMEO described in getsockopt(2).

       The select(2) call may be used to determine when more data
       arrive.
       The  flags argument to a recv call is formed by or'ing one
       or more of the values:


       MSG_OOB process out-of-band data

       MSG_PEEK
               peek at incoming message

       MSG_WAITALL
               wait for full request or error

               The MSG_OOB flag requests receipt  of  out-of-band
               data that would not be received in the normal data
               stream.  Some protocols place  expedited  data  at
               the  head  of the normal data queue, and thus this
               flag cannot be  used  with  such  protocols.   The
               MSG_PEEK  flag  causes  the  receive  operation to
               return data from  the  beginning  of  the  receive
               queue  without  removing that data from the queue.
               Thus, a subsequent receive call  will  return  the
               same data.  The MSG_WAITALL flag requests that the
               operation block until the full request  is  satis-
               fied.   However,  the  call  may still return less
               data than requested if  a  signal  is  caught,  an
               error or disconnect occurs, or the next data to be
               received  is  of  a  different  type   than   that
               returned.

               The  recvmsg call uses a msghdr structure to mini-
               mize 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 */
                    u_int     msg_namelen;   /* size of address */
                    struct    iovec *msg_iov;     /* scatter/gather array */
                    u_int     msg_iovlen;    /* # elements in msg_iov */
                    caddr_t   msg_control;   /* ancillary data, see below */
                    u_int     msg_controllen; /* ancillary data buffer len */
                    int  msg_flags;     /* flags on received message */
               };

       Here msg_name  and  msg_namelen  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.   Msg_iov and msg_iovlen describe scatter gather
       locations, as discussed in  read(2).   Msg_control,  which
       has  length  msg_controllen,  points to a buffer for other
       protocol control related messages or  other  miscellaneous
       ancillary data.  The messages are of the form:

               struct cmsghdr {
                    u_int     cmsg_len; /* data byte count, including hdr */
                    int  cmsg_level;    /* originating protocol */
                    int  cmsg_type;     /* protocol-specific type */
               /* followed by
                    u_char    cmsg_data[]; */
               };

       As  an  example, one could use this to learn of changes in
       the data-stream in XNS/SPP, or in ISO, to obtain user-con-
       nection-request  data by requesting a recvmsg with no data
       buffer provided immediately after an accept call.

       Open file descriptors are now passed as ancillary data for
       AF_UNIX  domain sockets, with cmsg_level set to SOL_SOCKET
       and cmsg_type set to SCM_RIGHTS.

       The msg_flags field is set on return according to the mes-
       sage  received.  MSG_EOR indicates end-of-record; the data
       returned completed a record (generally used  with  sockets
       of  type  SOCK_SEQPACKET).   MSG_TRUNC  indicates that the
       trailing portion of a datagram was discarded  because  the
       datagram  was larger than the buffer supplied.  MSG_CTRUNC
       indicates that some control data  were  discarded  due  to
       lack  of  space in the buffer for ancillary data.  MSG_OOB
       is returned to indicate that expedited or out-of-band data
       were received.



RETURN VALUES

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


ERRORS

       EBADF   The argument s is an invalid descriptor.

       ENOTCONN
               The socket is associated  with  a  connection-ori-
               ented  protocol  and  has  not been connected (see
               connect(2) and accept(2)).

       ENOTSOCK
               The argument s does not refer to a socket.

       EWOULDBLOCK
               The socket is marked non-blocking, and the receive
               operation  would  block,  or a receive timeout had
               been set, and the timeout expired before data were
               received.

       EINTR   The  receive was interrupted by delivery of a sig-
               nal before any data were available.

       EFAULT  The receive buffer pointer(s)  point  outside  the
               process's address space.


HISTORY

       These function calls appeared in BSD 4.2.


SEE ALSO

       fcntl(2), read(2), select(2), getsockopt(2), socket(2)
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.