recv(3SOCKET)		   Sockets Library Functions		 recv(3SOCKET)

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

SYNOPSIS
       cc [ flag... ] file... -lsocket	-lnsl  [ library... ]
       #include <sys/types.h>
       #include <sys/socket.h>
       #include <sys/uio.h>

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

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

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

DESCRIPTION
       The  recv(),  recvfrom(),  and  recvmsg() functions are used to receive
       messages  from  another	socket.  The  s   socket   is	created   with
       socket(3SOCKET).

       If  from  is  a	non-NULL pointer, the source address of the message is
       filled in. The value-result parameter fromlen  is  initialized  to  the
       size of the buffer associated with from and modified on return to indi-
       cate the actual size of the address stored in the buffer. The length of
       the  message  is  returned. If a message is too long to fit in the sup-
       plied buffer, excess bytes may be discarded depending on  the  type  of
       socket from which the message is received. See socket(3SOCKET).

       If  no messages are available at the socket, the receive call waits for
       a message to arrive. If the socket is non-blocking, -1 is returned with
       the external variable errno set to EWOULDBLOCK. See fcntl(2).

       For processes on the same host, recvmsg() can be used to receive a file
       descriptor from another process, but it cannot receive ancillary  data.
       See libxnet(3LIB).

       If  a  zero-length  buffer is specified for a message, an EOF condition
       results that is indistinguishable from the  successful  transfer  of  a
       file  descriptor.  For that reason, one or more bytes of data should be
       provided when recvmsg() passes a file descriptor.

       The select(3C) call can be used to determine when more data arrives.

       The flags parameter is formed by an OR operation on one or more of  the
       following:

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

       MSG_PEEK        Peek at the data present on the	socket.  The  data  is
		       returned,  but  not  consumed  to  allow  a  subsequent
		       receive operation to see the same data.

       MSG_WAITALL     Messages are blocked until  the	full  amount  of  data
		       requested is returned. The recv() function can return a
		       smaller amount of data if a signal is caught, the  con-
		       nection	is terminated, MSG_PEEK is specified, or if an
		       error is pending for the socket.

       MSG_DONTWAIT    Pending	messages  received  on	the   connection   are
		       returned. If data is unavailable, the function does not
		       block. This behavior is the  equivalent	to  specifying
		       O_NONBLOCK  on  the file descriptor of a socket, except
		       that write requests are unaffected.

       The  recvmsg()  function  call  uses  a	msghdr	structure  defined  in
       <sys/socket.h> to minimize the number of directly supplied parameters.

RETURN VALUES
       Upon  successful completion, these functions return the number of bytes
       received. Otherwise, they return -1  and  set  errno  to  indicate  the
       error.

ERRORS
       The recv(), recvfrom(), and recvmsg() functions return errors under the
       following conditions:

       EBADF	       The s file descriptor is invalid.

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

       EINTR	       The  operation is interrupted by the delivery of a sig-
		       nal before any data is available to be received.

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

       ENOMEM	       Insufficient user memory is available to complete oper-
		       ation.

       ENOSR	       Insufficient STREAMS resources are  available  for  the
		       operation to complete.

       ENOTSOCK        s is not a socket.

       ESTALE	       A stale NFS file handle exists.

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

       ECONNREFUSED    The requested connection was refused by the  peer.  For
		       connected  IPv4	and  IPv6 datagram sockets, this indi-
		       cates that the system received an ICMP Destination Port
		       Unreachable message from the peer.

       The  recv()  and  recvfrom()  functions fail under the following condi-
       tions:

       EINVAL	 The len argument overflows a ssize_t.

       The recvmsg() function returns errors under the following conditions:

       EINVAL	 The msg_iovlen member of the msghdr structure pointed	to  by
		 msg  is  less	than or equal to 0, or greater than [IOV_MAX}.
		 See Intro(2) for a definition of [IOV_MAX}.

       EINVAL	 One of the iov_len values in the msg_iov array member of  the
		 msghdr structure pointed to by msg is negative, or the sum of
		 the iov_len values in the msg_iov array overflows a ssize_t.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       fcntl(2),  ioctl(2),  read(2),  connect(3SOCKET),  getsockopt(3SOCKET),
       libxnet(3LIB),	   select(3C),	   send(3SOCKET),     socket(3SOCKET),
       socket.h(3HEAD), attributes(5)

SunOS 5.11			  20 Aug 2007			 recv(3SOCKET)