unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 recv(2)							     recv(2)




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

 SYNOPSIS
      #include <&lt&lt&lt;sys/socket.h>&gt&gt&gt;

      int recv(int s, void *buf, int len, int flags);

      int recvfrom(
	  int	    s,
	  void	   *buf,
	  int	    len,
	  int	    flags,
	  void	   *from,
	  int	   *fromlen
      );

      int recvmsg(int s, struct msghdr msg[], int flags);

    _XOPEN_SOURCE_EXTENDED Only (UNIX 98)
      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 sockaddr *from,
	      socklen_t	      *fromlen
      );

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

    Obsolescent _XOPEN_SOURCE_EXTENDED Only (UNIX 95)
      ssize_t recvfrom(
	      int	       s,
	      void	      *buf,
	      size_t	       len,
	      int	       flags,
	      struct sockaddr *from,
	      size_t	      *fromlen
      );

 DESCRIPTION
      The recv(), recvfrom(), and recvmsg() system calls are used to receive
      messages from a socket.

      s is a socket descriptor from which messages are received.

      buf is a pointer to the buffer into which the messages are placed.




 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




      len is the maximum number of bytes that can fit in the buffer
      referenced by buf.

      If the socket uses connection-based communications, such as a
      SOCK_STREAM socket, these calls can only be used after the connection
      has been established (see connect(2)).  For connectionless sockets
      such as SOCK_DGRAM, these calls can be used whether a connection has
      been specified or not.

      recvfrom() operates in the same manner as recv() except that it is
      able to return the address of the socket from which the message was
      sent.  For connected datagram sockets, recvfrom() simply returns the
      same address as getpeername() (see getpeername(2)).  For stream
      sockets, recvfrom() retrieves data in the same manner as recv(), but
      does not return the socket address of the sender.	 If from is nonzero,
      the source address of the message is placed in the socket address
      structure pointed to by from.  fromlen is a value-result parameter,
      initialized to the size of the structure associated with from, and
      modified on return to indicate the actual size of the address stored
      there.  If the memory pointed to by from is not large enough to
      contain the entire address, only the first fromlen bytes of the
      address are returned.

      For message-based sockets such as SOCK_DGRAM, the entire message must
      be read in a single operation.  If a message is too long to fit in the
      supplied buffer, the excess bytes are discarded.	For stream-based
      sockets such as SOCK_STREAM, there is no concept of message
      boundaries.  In this case, data is returned to the user as soon as it
      becomes available, and no data is discarded.  See the AF_CCITT Only
      subsection below for a list of the exceptions to this behavior for
      connections in the address family AF_CCITT.

      recvmsg() performs the same action as recv(), but scatters the read
      data into the buffers specified in the msghdr structure (see
      _XOPEN_SOURCE_EXTENDED Only below).  This structure is defined in
      <&lt&lt&lt;sys/socket.h>&gt&gt&gt; and has the following form (HP-UX BSD Sockets Only):

	   struct msghdr {
	       caddr_t	 msg_name;	      /* optional address */
	       int	 msg_namelen;	      /* size of address  */
	       struct	 iovec *msg_iov;      /* scatter array for data */
	       int	 msg_iovlen;	      /* # of elements in msg_iov */
	       caddr_t	 msg_accrights;	      /* access rights */
	       int	 msg_accrightslen;    /* size of msg_accrights */
	   }

      msg_name points to a sockaddr structure in which the address of the
      sending socket is to be stored, if the socket is connectionless;
      msg_name may be a null pointer if no name is specified.  msg_iov
      specifies the locations of the character arrays for storing the
      incoming data.  msg_accrights specifies a buffer to receive any access



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




      rights sent along with the message.  Access rights are limited to file
      descriptors of size int.	If access rights are not being transferred,
      set the msg_accrights field to NULL.  Access rights are supported only
      for AF_UNIX.

      If no data is available to be received, recv() waits for a message to
      arrive unless nonblocking mode is enabled.  There are three ways to
      enable nonblocking mode:

	+  With the FIOSNBIO ioctl() request
	+  With the O_NONBLOCK fcntl() flag
	+  With the O_NDELAY fcntl() flag

      Although the use of FIONBIO is not recommended, if nonblocking I/O is
      enabled using FIOSNBIO or the equivalent FIONBIO request (defined in
      <&lt&lt&lt;sys/ioctl.h>&gt&gt&gt; and explained in ioctl(2), ioctl(5) and socket(7)), the
      recv() request completes in one of three ways:

	+  If there is enough data available to satisfy the entire request,
	   recv() completes successfully, having read all of the data, and
	   returns the number of bytes read.

	+  If there is not enough data available to satisfy the entire
	   request, recv() complete successfully, having read as much data
	   as possible, and returns the number of bytes it was able to read.

	+  If there is no data available, recv() fails and errno is set to
	   [EWOULDBLOCK].

      If nonblocking I/O is disabled using FIOSNBIO, recv() always executes
      completely (blocking as necessary) and returns the number of bytes
      read.

      If the O_NONBLOCK flag is set using fcntl() (defined in <&lt&lt&lt;sys/fcntl.h>&gt&gt&gt;
      and explained in fcntl(2) and fcntl(5)), POSIX-style nonblocking I/O
      is enabled.  In this case, the recv() request completes in one of
      three ways:

	+  If there is enough data available to satisfy the entire request,
	   recv() completes successfully, having read all the data, and
	   returns the number of bytes read.

	+  If there is not enough data available to satisfy the entire
	   request, recv() completes successfully, having read as much data
	   as possible, and returns the number of bytes it was able to read.

	+  If there is no data available, recv() completes, having read no
	   data, and returns -1 with errno set to [EAGAIN].

      If the O_NDELAY flag is set using fcntl() (defined in <&lt&lt&lt;sys/fcntl.h>&gt&gt&gt;
      and explained in fcntl(2) and fcntl(5)), nonblocking I/O is enabled.



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




      In this case, the recv() request completes in one of three ways:

	+  If there is enough data available to satisfy the entire request,
	   recv() completes successfully, having read all the data, and
	   returns the number of bytes read.

	+  If there is not enough data available to satisfy the entire
	   request, recv() completes successfully, having read as much data
	   as possible, and returns the number of bytes it was able to read.

	+  If there is no data available, recv() completes successfully,
	   having read no data, and returns 0.

      If the O_NONBLOCK or O_NDELAY flag is cleared using fcntl(), the
      corresponding style of nonblocking I/O, if previously enabled, is
      disabled.	 In this case, recv() always executes completely (blocking
      as necessary) and returns the number of bytes read.

      Since both the fcntl() O_NONBLOCK and O_NDELAY flags and ioctl()
      FIOSNBIO request are supported, some clarification on how these
      features interact is necessary.  If the O_NONBLOCK or O_NDELAY flag
      has been set, recv() requests behave accordingly, regardless of any
      FIOSNBIO requests.  If neither the O_NONBLOCK flag nor the O_NDELAY
      flag has been set, FIOSNBIO requests control the the behavior of
      recv().

      By default nonblocking I/O is disabled.

      select() can be used to determine when more data arrives by selecting
      the socket for reading.

      The flags parameter can be set to MSG_PEEK, MSG_OOB, both, or zero.
      If it is set to MSG_PEEK, any data returned to the user still is
      treated as if it had not been read.  The next recv() rereads the same
      data.  The MSG_OOB flag is used to receive out-of-band data.  For TCP
      SOCK_STREAM sockets, both the MSG_PEEK and MSG_OOB flags can be set at
      the same time.  The MSG_OOB flag value is supported for TCP
      SOCK_STREAM sockets only.	 MSG_OOB is not supported for AF_UNIX or
      AF_VME_LINK sockets.

      A read() call made to a socket behaves in exactly the same way as a
      recv() with flags set to zero.

    AF_CCITT Only
      Connections in the address family AF_CCITT support message-based
      sockets only.  Although the user specifies connection-based
      communications (SOCK_STREAM), the X.25 subsystem communicates via
      messages.	 This address family does not support SOCK_DGRAM socket
      types.





 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




      Normally, each recv() returns one complete X.25 message.	If the
      socket is in nonblocking mode, recv() behaves as described above.
      Note that if the user specifies len less than the actual X.25 message
      size, the excess data is discarded and no error indication is
      returned.	 The size of the next available message as well as the state
      of MDTF, D, and Q bits can be obtained with ioctl(X25_NEXT_MSG_STAT).

      Connections of the address family AF_CCITT receive data in the same
      way as message-based connections described above, with the following
      additions and exceptions:

	+  recvfrom() is supported; however, the from and fromlen parameters
	   are ignored (that is, it works in the same manner as recv()).

	+  To receive a message in fragments of the complete X.25 message,
	   use ioctl(X25_SET_FRAGMENT_SIZE).  The state of the MDTF bit is 1
	   for all except the last fragment of the message.

	+  The MSG_OOB flag is supported.

	+  The MSG_PEEK flag is supported; the two flags can be combined.

	+  If a message is received that is larger than the user-controlled
	   maximum message size (see af_ccitt(7F)), the X.25 subsystem
	   RESETs the circuit, discards the data, and sends the out-of-band
	   event OOB_VC_MESSAGE_TOO_BIG to the socket.

    _XOPEN_SOURCE_EXTENDED Only
      For X/Open Sockets, the msghdr structure has the following form:

	   (UNIX 98)

	   struct msghdr {
	       void	  *msg_name;	       /* optional address */
	       socklen_t   msg_namelen;	       /* size of address  */
	       struct	   iovec *msg_iov;     /* scatter array for data */
	       int	   msg_iovlen;	       /* # of elements in msg_iov */
	       void	  *msg_control;	       /* ancillary data, see below */
	       socklen_t   msg_controllen;     /* ancillary data buffer len */
	       int	   msg_flags;	       /* flags on received message */
	   }

	   Obsolescent (UNIX 95)

	   struct msghdr {
	       void	  *msg_name;	       /* optional address */
	       size_t	   msg_namelen;	       /* size of address  */
	       struct	   iovec *msg_iov;     /* scatter array for data */
	       int	   msg_iovlen;	       /* # of elements in msg_iov */
	       void	  *msg_control;	       /* ancillary data, see below */
	       size_t	   msg_controllen;     /* ancillary data buffer len */



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




	       int	   msg_flags;	       /* flags on received message */
	   }

      msg_control specifies a buffer to receive any ancillary data sent
      along with the message.  Ancillary data consists of a sequence of
      pairs, each consisting of a cmsghdr structure followed by a data
      array.  The data array contains the ancillary data message, and the
      cmsghdr structure contains descriptive information that allows an
      application to correctly parse the data.	cmsghdr has the following
      structure:

	   (UNIX 98)

	   struct cmsghdr {
	       socklen_t  cmsg_len;	 /* data byte count, including hdr*/
	       int	  cmsg_level;	 /* originating protocol */
	       int	  cmsg_type;	 /* protocol-specific type */
	   }

	   Obsolescent (UNIX 95)

	   struct cmsghdr {
	       size_t	  cmsg_len;	 /* data byte count, including hdr*/
	       int	  cmsg_level;	 /* originating protocol */
	       int	  cmsg_type;	 /* protocol-specific type */
	   }

      The supported value for cmsg_level is SOL_SOCKET, and the supported
      value for cmsg_type is SCM_RIGHTS.  Together they indicate that the
      data array contains the access rights to be received. Access rights
      are supported only for AF_UNIX.  Access rights are limited to file
      descriptors of size int.	If ancillary data are not being transferred,
      set the msg_control field to NULL, and set the msg_controllen field to
      0.

      The flags parameter accepts a new value, MSG_WAITALL, which requests
      that the function block 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.

      On successful completion of recvmsg(), the msg_flags member of the
      message header is the bitwise-inclusive OR of all of the following
      flags that indicate conditions detected for the received message.

	   MSG_EOR	       End of record was received (if supported by
			       the protocol).

	   MSG_OOB	       Out-of-band data was received.





 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




	   MSG_TRUNC	       Normal data was truncated.

	   MSG_CTRUNC	       Control data was truncated.

 DEPENDENCIES
    AF_CCITT
      recvfrom() is supported; however, the from and fromlen parameters are
      ignored (i.e., it works in the same manner as recv()).

      The O_NDELAY fcntl() call is not supported over X.25 links.  Use the
      FIOSNBIO ioctl() call instead to enable nonblocking I/0.

 RETURN VALUE
      recv(), recvfrom(), and recvmsg() return the following values:

	    n	Successful completion.	n is the number of bytes received.
	    0	The socket is blocking and the transport connection to the
		remote node failed.
	   -1	Failure.  errno is set to indicate the error.

 ERRORS
      If recv(), recvfrom(), or recvmsg() fails, errno is set to one of the
      following values.

	   [EAGAIN]	       Non-blocking I/O is enabled using O_NONBLOCK
			       flag with fcntl() and the receive operation
			       would block, or the socket has an error that
			       was set asynchronously.	An asynchronous
			       error can be caused by a gateway failing to
			       forward a datagram because the datagram
			       exceeds the MTU of the next-hop network and
			       the "Don't Fragment" (DF) bit in the datagram
			       is set.	(See SO_PMTU in getsockopt(2).)

	   [EBADF]	       The argument s is an invalid descriptor.

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

	   [EFAULT]	       An invalid pointer was specified in the buf ,
			       from , or fromlen parameter, or in the msghdr
			       structure.

	   [EINTR]	       The receive was interrupted by delivery of a
			       signal before any data was available for the
			       receive.

	   [EINVAL]	       The len parameter or a length in the msghdr
			       structure is invalid; or no data is available
			       on receive of out of band data.





 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




	   [EMFILE]	       The number of file descriptors available to
			       the calling process has been exceeded.

	   [EMSGSIZE]	       A length in the msghdr structure is invalid.

	   [ENOBUFS]	       Insufficient resources were available in the
			       system to perform the operation.

	   [ENOSR]	       Buffers could not be allocated for the
			       message that was to be created due to
			       insufficient STREAMS memory resources.

	   [ENOTCONN]	       Receive on a SOCK_STREAM socket that is not
			       yet connected.

	   [ENOTSOCK]	       The argument s is a valid file descriptor,
			       but it is not a socket.

	   [EOPNOTSUPP]	       The MSG_OOB flag was set for a UDP SOCK_DGRAM
			       message-based socket, or MSG_OOB or MSG_PEEK
			       was set for any AF_UNIX socket.	The MSG_OOB
			       flag is supported only for stream-based TCP
			       SOCK_STREAM sockets.  Neither MSG_PEEK nor
			       MSG_OOB is supported for AF_UNIX sockets.

			       AF_CCITT only: recv() was issued on a
			       listen() socket.

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

	   [EWOULDBLOCK]       Non-blocking I/O is enabled using ioctl()
			       FIOSNBIO request, and the requested operation
			       would block.

 OBSOLESCENCE
      Currently, the socklen_t and size_t types are the same size.  This is
      compatible with both the UNIX 95 and UNIX 98 profiles.  However, in a
      future release, socklen_t might be a different size.  In that case,
      passing a size_t pointer will evoke compile-time warnings, which must
      be corrected in order for the application to behave correctly.  Also,
      the size of the msghdr and cmsghdr structures and the relative
      position of their members will be different, which might affect
      application behavior.  Applications that use socklen_t now, where
      appropriate, will avoid such migration problems.	On the other hand,
      applications that need to be portable to the UNIX 95 profile should
      follow the X/Open specification (see xopen_networking(7)).

 FUTURE DIRECTION
      Currently, the default behavior is the HP-UX BSD Sockets; however, it



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 recv(2)							     recv(2)




      might be changed to X/Open Sockets in a future release.  At that time,
      any HP-UX BSD Sockets behavior that is incompatible with X/Open
      Sockets might be obsoleted.  Applications that conform to the X/Open
      specification now will avoid migration problems (see
      xopen_networking(7)).

 MULTITHREAD USAGE
      The recv(), recvmsg(), and recvfrom() system calls are thread-safe.
      They each have a cancellation point; and they are async-cancel safe,
      async-signal safe, and fork-safe.

 AUTHOR
      recv(), recvmsg(), and recvfrom() were developed by HP and the
      University of California, Berkeley.

 SEE ALSO
      getsockopt(2), read(2), select(2), send(2), socket(2), af_ccitt(7F),
      af_vme_link(7F), inet(7F), socket(7), socketx25(7), tcp(7P), udp(7P),
      unix(7P), xopen_networking(7).

 STANDARDS CONFORMANCE
      recv(): XPG4
































 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000