unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



recvmsg(2)							   recvmsg(2)



NAME

  recvmsg - Receives a message from a socket using a message structure

SYNOPSIS

  #include <sys/socket.h>
  ssize_t recvmsg (
	  int socket,
	  struct msghdr	*message,
	  int flags) ;

  [Tru64 UNIX]	The following definition of the	recvmsg() function does	not
  conform to current standards and is supported	only for backward compatibil-
  ity (see standards(5)):

  int recvmsg (
	  int socket,
	  struct msghdr	*message,
	  int flags) ;

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  recvmsg():  XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  socket    Specifies the socket file descriptor.

  message   Points to a	msghdr structure, containing pointers to both the
	    destination	address	for the	incoming message and to	buffers	con-
	    taining ancillary data. The	format of the address is determined
	    by the behavior requested for the socket.

	    [Tru64 UNIX]   If the compile-time option _SOCKADDR_LEN is
	    defined before the <sys/socket.h> header file is included, the
	    msghdr structure takes 4.4BSD behavior.  Otherwise,	the default
	    4.3BSD msghdr structure is used.

	    In 4.4BSD, the msghdr structure has	a separate msg_flags field
	    for	holding	flags from the received	message.  In addition, the
	    msg_accrights field	is generalized into a msg_control field.  See
	    DESCRIPTION	for more information.

	    If _SOCKADDR_LEN is	defined, the 4.3BSD msghdr structure is
	    defined with the name omsghdr.

  flags	    Permits the	caller of this function	to exercise control over the
	    reception of messages.  The	value for this parameter is formed by
	    a logical OR of one	or more	of the following values:

	    MSG_PEEK	   Peeks at the	incoming message.

	    MSG_OOB	   Processes out-of-band data on sockets that support
			   out-of-band data.

	    MSG_WAITALL	   Requests that the function block wait until the
			   full	amount of data requested can be	returned.
			   The function	may return a smaller amount of data
			   if a	signal is caught, the connection is ter-
			   minated, MSG_PEEK was specified, or an error	is
			   pending for the socket.

DESCRIPTION

  The recvmsg()	function receives messages from	unconnected or connected
  sockets and returns the total	length of the message.

  For message-based sockets (for example, SOCK_DGRAM), you must	read the
  entire message in a single operation.	 When a	message	is too long for	the
  buffer and MSG_PEEK is not specified,	the message is truncated and
  MSG_TRUNC set	in the msg_flags member	or the msghdr structure.  For
  stream-based sockets (SOCK_STREAM), message boundaries are ignored, and
  data is returned as soon as it is available.

  If the MSG_WAITALL flag is not set, the function returns data	up to the end
  of the first message.

  When no messages are available at the	socket specified by the	socket param-
  eter,	the recvmsg() function waits for a message to arrive. When the socket
  is nonblocking and no	message	is available, the recvmsg() function fails
  and sets errno to [EWOULDBLOCK].

  Use the select() and poll() functions	to determine when more data arrives.

  The recvmsg()	function uses a	msghdr structure to minimize the number	of
  directly supplied parameters.	In the msghdr structure, the msg_name and
  msg_namelen fields specify the destination address if	the socket is uncon-
  nected.  The msg_name	field may be given as a	null pointer if	no names are
  desired or required.	The msg_iov and	msg_iovlen fields describe the
  scatter gather locations.

  The msghdr structure uses a socklen_t	data type for the msg_iovlen field
  instead of a size_t data type	as specified in	XNS4.0.

  [Tru64 UNIX]	 In 4.3BSD, the	msg_accrights field is a buffer	for passing
  access rights.  In 4.4BSD, the msg_accrights field has been expanded into a
  msg_control field, to	include	other protocol control messages	or other mis-
  cellaneous ancillary data.

  In the 4.4BSD	msghdr structure, the msg_flags	field holds flags from the
  received message.  In	addition to MSG_PEEK and MSG_OOB, the incoming flags
  reported in the msg_flags field can be any of	the following values:

  MSG_EOR	      Data includes the	end-of-record marker.

  MSG_OOB	      Out-of-band data was received.

  MSG_TRUNC	      Data was truncated before	delivery.

  MSG_CTRUNC	      Control data was truncated before	delivery.


NOTES

  [Tru64 UNIX]	When compiled in the X/Open UNIX environment, calls to the
  recvmsg() function are internally renamed by prepending _E to	the function
  name.	When you are debugging a module	that includes the recvmsg() function
  and for which	_XOPEN_SOURCE_EXTENDED has been	defined, use _Erecvmsg to
  refer	to the recvmsg() call.	See standards(5) for further information.

  [Tru64 UNIX]	When compiled in the POSIX.1g socket environment, calls	to
  the recvmsg()	function are internally	renamed	by prepending _P to the	func-
  tion name.  When you are debugging a module that includes the	recvmsg()
  function and for which _POSIX_PII_SOCKET has been defined, use _Precvmsg to
  refer	to the recvmsg() call.	See standards(5) for further information.

RETURN VALUES

  Upon successful completion, the recvmsg() function returns the length	of
  the message in bytes,	and fills in the fields	of the msghdr structure
  pointed to by	the message parameter as appropriate.  Otherwise, a value of
  -1 is	returned and errno is set to indicate the error.

ERRORS

  If the recvmsg() function fails, errno may be	set to one of the following
  values:

  [EBADF]	 The socket parameter is not valid.

  [ECONNRESET]	 A connection was forcibly closed by a peer.

  [EFAULT]	 The message parameter;	storage	pointed	to by the msg_name,
		 msg_control, or msg_iov fields	of the message parameter; or
		 storage pointed to by the iovec structures pointed to by the
		 msg_iov field are not in a readable or	writable part of user
		 address-space.

  [EINTR]	 A signal interrupted this function before any data was
		 available.

  [EINVAL]	 The MSG_OOB flag is set and no	out-of-band data is avail-
		 able.

		 The sum of the	iov_len	values overflows an ssize_t.

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

  [EMSGSIZE]	 The value of the msg_iovlen member of the msghdr structure
		 is less than or equal to zero (0) or is greater than
		 IOV_MAX.

  [ENOBUFS]	 Insufficient resources	were available in the system to	com-
		 plete the call.

  [ENOMEM]	 The system did	not have sufficient memory to fulfill the
		 request.

  [ENOSR]	 The available STREAMS resources were insufficient for the
		 operation to complete.

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

  [ENOTSOCK]	 The socket parameter refers to	a file,	not a socket.

  [EOPNOTSUPP]	 The specified flags are not supported this socket type.

  [ETIMEDOUT]	 The connection	timed out during connection establishment, or
		 due to	a transmission timeout on active connection.

  [EWOULDBLOCK]	 The socket is marked nonblocking and no data is ready to be
		 received.

		 The MSG-OOB flag is set, no out-of-band data is available,
		 and either the	socket is marked nonblocking or	the socket
		 does not support blocking to wait for out-of-band data.

RELATED	INFORMATION

  Functions: poll(2), recv(2), recvfrom(2), select(2), send(2),	sendmsg(2),
  sendto(2), shutdown(2), socket(2)

  Standards: standards(5)