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);

       recv(), recvfrom(), and recvmsg() are used to receive messages from an-
       other  socket.  recv() may be used only on a connected socket (see con-
       nect(3SOCKET)), while recvfrom()	and recvmsg() may be used  to  receive
       data  on	 a  socket  whether  it	is in a	connected state	or not.	s is a
       socket created with socket(3SOCKET).

       If from is not a	NULL pointer, 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 length	of the message
       is returned. If a message is too	long to	fit in	the  supplied  buffer,
       excess  bytes may be discarded depending	on the type of socket the mes-
       sage is received	from. See socket(3SOCKET).

       If no messages are available at the socket, the receive call waits  for
       a message to arrive, unless the socket is nonblocking, in which case -1
       is returned with	the external variable errno set	 to  EWOULDBLOCK.  See

       The select() call may be	used to	determine when more data arrives.

       The flags parameter is formed by	ORing one or more of the following:

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

	     "Peek" at the data	present	on the socket; the data	 is  returned,
	     but not consumed, so that a subsequent receive operation will see
	     the same data.

       The recvmsg() 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;

       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. The msg_iov and msg_iovlen describe  the
       scatter-gather  locations, as described in read(2). A buffer to receive
       any access rights sent along with the message is	specified  in  msg_ac-
       crights,	which has length msg_accrightslen.

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

       The recv(), recvfrom(), and recvmsg() functions will fail if:

       EBADF s is an invalid file descriptor.

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

       EINTR The operation was interrupted by delivery of a signal before  any
	     data was available	to be received.

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

	     There was insufficient user memory	available for the operation to

       ENOSR There were	insufficient STREAMS resources available for the oper-
	     ation to complete.

	     s is not a	socket.

	     A stale NFS file handle exists.

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

       The recv() and recvfrom() functions will	fail if:

	     The len argument overflowed a ssize_t.

       The recvmsg() function will fail	if:

	     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  In-
	     tro(2) for	a definition of	[IOV_MAX}.

	     Either  one  of the iov_len values	in the msg_iov array member of
	     the msghdr	structure pointed to by	msg was	negative, or  the  sum
	     of	the iov_len values in the msg_iov array	overflowed a ssize_t.

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |Safe			   |

       fcntl(2),  ioctl(2),  read(2),  connect(3SOCKET),  getsockopt(3SOCKET),
       send(3SOCKET), socket(3HEAD), socket(3SOCKET), attributes(5)

SunOS 5.9			  24 Jan 2002			 recv(3SOCKET)


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

home | help