Index for Section 2

Alphabetical listing for R

Bottom of page

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
  compatibility (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():  XNS4.0

  The recvmsg function also supports POSIX.1g Draft 6.6.

  Refer to the standards(5) reference page for more information about
  industry 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
	    containing 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
			   terminated, or an error is pending for the socket.

DESCRIPTION
  The recvmsg() function receives messages from unconnected or connected
  sockets and returns the length of the message.  When a message is too long
  for the buffer, the message may be truncated depending on the type of
  socket from which the message is written.

  When no messages are available at the socket specified by the socket
  parameter, 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() function 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
  unconnected.	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.

  [POSIX]  In POSIX.1g Draft 6.6 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
  miscellaneous 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_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
  function 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]	 [Tru64 UNIX]  The message parameter is not in a readable or
		 writable part of user address-space.

  [EINTR]	 This function was interrupted by a signal before any data
		 was available.

  [EINVAL]	 The MSG-OOB flag is set and no out-of-band data is
		 available.

		 The value of the msg_iovlen member of the Lmsghdr structure
		 is less than or equal to zero or is greater than IOV_MAX.

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

  [ENOBUFS]	 Insufficient resources were available in the system to
		 complete 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.

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

  Standards: standards(5)

Index for Section 2

Alphabetical listing for R

Top of page