Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
recv(3SOCKET)		   Sockets Library Functions		 recv(3SOCKET)

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

       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 sock-
       addr *from, int *fromlen);

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

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

       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.

       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

       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 re-
		       turned,	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  re-
		       quested	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  re-
		       turned.	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  to	 minimize  the
       number  of  directly  supplied parameters. This structure is defined in
       <sys/socket.h> and includes the following members:

       caddr_t	       msg_name;	  /* optional address */
       int	       msg_namelen;	  /* size of address */
       struct iovec    *msg_iov;	  /* scatter/gather array */
       int	       msg_iovlen;	  /* # elements	in msg_iov */
       caddr_t	       msg_accrights;	  /* access rights sent/received */
       int	       msg_accrightslen;

       The msg_name and	msg_namelen parameters specify the destination address
       when  the socket	is unconnected The msg_name can	be specified as	a NULL
       pointer if no names are desired or required. The	msg_iov	and msg_iovlen
       parameters  describe  the  scatter-gather  locations,  as  described in
       read(2).	The msg_accrights parameter specifies the buffer in which  ac-
       cess rights sent	along with the message are received. The msg_accright-
       slen specifies the length of the	buffer.

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

       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

       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-

       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 op-
		       eration 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-

       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.

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Stable			   |
       |MT-Level		     |Safe			   |

       fcntl(2), ioctl(2), read(2), connect(3SOCKET), getsockopt(3SOCKET), se-
       lect(3C),    send(3SOCKET),   socket(3SOCKET),	socket.h(3HEAD),   at-

SunOS 5.10			  05 Feb 2004			 recv(3SOCKET)


Want to link to this manual page? Use this URL:

home | help