recvmsg man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

recvmsg(2)							    recvmsg(2)

NAME
       recvmsg - Receive 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 stan‐
       dards as follows:

       recvmsg(): XNS4.0, XNS5.0

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

PARAMETERS
       Specifies  the  socket  file descriptor.	 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_options field
	      for holding options 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.  Permits the caller of this func‐
	      tion 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: Peeks  at  the  incoming  message.
	      Processes	 out-of-band  data on sockets that support out-of-band
	      data.  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  con‐
	      nection  is  terminated,	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_options 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
       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() 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
       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.

       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 pass‐
       ing 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  val‐
       ues:  Data  includes  the  end-of-record	 marker.  Out-of-band data was
       received.  Data was truncated before delivery.  Control data was	 trun‐
       cated 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 fur‐
       ther 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	struc‐
       ture pointed to by the message parameter as appropriate. If no messages
       are available and the peer has closed the connection, the recv()	 func‐
       tion  returns  a	 value	of 0. 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 follow‐
       ing  values:  The  socket  parameter  is	 not  valid.  A connection was
       forcibly closed by a peer.  The message parameter; storage  pointed  to
       by  the msg_name, msg_control, or msg_iov fields of the message parame‐
       ter; 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.  A signal interrupted this function before any data  was	avail‐
       able.  The MSG_OOB flag is set and no out-of-band data is available.

	      The  sum	of  the	 iov_len  values overflows an ssize_t.	An I/O
	      error occurred while reading from or writing to the file system.
	      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.
	      Insufficient  resources were available in the system to complete
	      the call.	 The system did not have sufficient memory to  fulfill
	      the  request.  The available STREAMS resources were insufficient
	      for the operation to complete.  A receive is attempted on a con‐
	      nection-oriented	socket	that  is  not  connected.   The socket
	      parameter refers to a file, not a socket.	 The  specified	 flags
	      are  not	supported  this socket type.  The connection timed out
	      during connection establishment, or due to a transmission	 time‐
	      out  on active connection.  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.

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

       Standards: standards(5)

       Network Programmer's Guide

								    recvmsg(2)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net