recv(3N-xs)                   (X/OPEN SOCKETS)                  recv(3N-xs)

NAME
     recv - receive a message from a connected socket

SYNOPSIS
     cc [flag ...] file ... -lxnet [library ...]

     #include <sys/socket.h>

     ssizet recv(int socket, void *buffer,
                  sizet length, int flags);

DESCRIPTION
     The recv function receives messages from a connected socket. The func-
     tion takes the following arguments:

     socket       Specifies the socket file descriptor.

     buffer       Points to a buffer where the message should be stored.

     length       Specifies the length in bytes of the buffer pointed to by
                  the buffer argument.

     flags        Specifies the type of message reception. Values of this
                  argument are formed by logically ORing zero or more of
                  the following values:

                  MSGPEEK
                       Peeks at an incoming message. The data is treated as
                       unread and the next recv or similar function will
                       still return this data.

                  MSGOOB
                       Requests out-of-band data. The significance and
                       semantics of out-of-band data are protocol-specific.

                  MSGWAITALL
                       Requests that the function block until the full
                       amount of data requested can be returned. The func-
                       tion may return a smaller amount of data if a signal
                       is caught, the connection is terminated, or an error
                       is pending for the socket.

     The recv function returns the length of the message written to the
     buffer pointed to by the buffer argument. For message-based sockets
     such as SOCKDGRAM and SOCKSEQPACKET, the entire message must be read
     in a single operation. If a message is too long to fit in the supplied
     buffer, and MSGPEEK is not set in the flags argument, the excess
     bytes are discarded. For stream-based sockets such as SOCKSTREAM,
     message boundaries are ignored. In this case, data is returned to the
     user as soon as it becomes available, and no data is discarded.





Page 1                       Reliant UNIX 5.44                Printed 11/98

recv(3N-xs)                   (X/OPEN SOCKETS)                  recv(3N-xs)

     If the MSGWAITALL flag is not set, data will be returned only up to
     the end of the first message.

     If no messages are available at the socket and ONONBLOCK is not set
     on the socket's file descriptor, recv blocks until a message arrives.
     If no messages are available at the socket and ONONBLOCK is set on
     the socket's file descriptor, recv fails and sets errno to EWOULDBLOCK
     or EAGAIN.

RETURN VALUE
     Upon successful completion, recv returns the length of the message in
     bytes. If no messages are available to be received and the peer has
     performed an orderly shutdown, recv returns 0. Otherwise, -1 is
     returned and errno is set to indicate the error.

ERRORS
     The recv function will fail if:

     EBADF           The socket argument is not a valid file descriptor.

     ECONNRESET      A connection was forcibly closed by a peer.

     EINTR           The recv function was interrupted by a signal that was
                     caught, before any data was available.

     EINVAL          The MSGOOB flag is set and no out-of-band data is
                     available.

     ENOTCONN        A receive is attempted on a connection-oriented socket
                     that is not connected.

     ENOTSOCK        The socket argument does not refer to a socket.

     EOPNOTSUPP      The specified flags are not supported for this socket
                     type or protocol.

     ETIMEDOUT       The connection timed out during connection establish-
                     ment, or due to a transmission timeout on active con-
                     nection.

     EWOULDBLOCK or EAGAIN
                     The socket's file descriptor is marked ONONBLOCK and
                     no data is waiting to be received; or MSGOOB is set
                     and no out-of-band data is available and either the
                     socket's file descriptor is marked ONONBLOCK or the
                     socket does not support blocking to await out-of-band
                     data.

     The recv function may fail if:

     EIO             An I/O error occurred while reading from or writing to
                     the file system.


Page 2                       Reliant UNIX 5.44                Printed 11/98

recv(3N-xs)                   (X/OPEN SOCKETS)                  recv(3N-xs)

     ENOBUFS         Insufficient resources were available in the system to
                     perform the operation.

     ENOMEM          Insufficient memory was available to fulfill the
                     request.

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

APPLICATION USAGE
     The recv function is identical to recvfrom with a zero addresslen
     argument, and to read if no flags are used.

     The select and poll functions can be used to determine when data is
     available to be received.

SEE ALSO
     poll(2), read(2), write(2), select(3C), recvmsg(3N-xs),
     recvfrom(3N-xs), send(3N-xs), sendmsg(3N-xs), sendto(3N-xs),
     shutdown(3N-xs), socket(3N-xs).


































Page 3                       Reliant UNIX 5.44                Printed 11/98