unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



recvfrom(2)							  recvfrom(2)



NAME
  recvfrom - Receives messages from sockets

SYNOPSIS

  #include <sys/socket.h>
  ssize_t recvfrom(
	  int socket,
	  void *buffer,
	  size_t length,
	  int flags,
	  struct sockaddr *address,
	  socklen_t *address_len) ;

  [XNS4.0]  The	definition of the recvfrom() function in XNS4.0	uses a size_t
  data type for	the address_len	parameter instead of a socklen_t data type as
  specified in XNS5.0 (the previous definition).

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

  int recvfrom(
	  int socket,
	  char *buffer,
	  int length,
	  int flags,
	  struct sockaddr *address,
	  int *address_len) ;

STANDARDS

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

  recvfrom():  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.

  buffer    Specifies a	pointer	to the buffer to which the message should be
	    written.

  length    Specifies the length (in bytes) of the buffer pointed to by	the
	    buffer parameter.

  flags	    Points to a	value that controls message reception. The parameter
	    to control message reception is formed by the logical OR of	one
	    or more of the following values:

	    MSG_PEEK  Peeks at the incoming message.

	    MSG_OOB   Processes	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, MSG_PEEK was
		      specified, or an error is	pending	for the	socket.

  address   Points to a	sockaddr structure, the	format of which	is determined
	    by the domain and by the behavior requested	for the	socket.	 The
	    sockaddr structure is an overlay for a sockaddr_in,	sockaddr_un,
	    sockaddr_in6, or sockaddr_storage structure, depending on which
	    of the supported address families is active.

	    [Tru64 UNIX]   If the compile-time option _SOCKADDR_LEN is
	    defined before the sys/socket.h header file	is included, the
	    sockaddr structure takes 4.4BSD behavior, with a field for speci-
	    fying the length of	the socket address.  Otherwise,	the default
	    4.3BSD sockaddr structure is used, with the	length of the socket
	    address assumed to be 14 bytes or less.

	    If _SOCKADDR_LEN is	defined, the 4.3BSD sockaddr structure is
	    defined with the name osockaddr.

  address_len
	    Specifies the length of the	sockaddr structure pointed to by the
	    address parameter.

DESCRIPTION

  The recvfrom() function permits an application program to receive messages
  from unconnected sockets.  It	is normally applied to unconnected sockets
  because it includes parameters that permit a calling program to retrieve
  the source endpoint of received data.

  To obtain the	source address of the message, specify a nonzero value for
  the address parameter.  The recvfrom() function is called with the
  address_len parameter	set to the size	of the buffer specified	by the
  address parameter.  On return, this function modifies	the address_len
  parameter to the actual size in bytes	of the address specified by the
  address parameter.  The recvfrom() function returns the length of the	mes-
  sage written to the buffer pointed to	by the buffer parameter.  When a mes-
  sage is too long for the specified buffer, excess bytes may be truncated
  depending on the type	of socket that issued the message, and depending on
  which	flags are set with the flags parameter.

  When no message is available at the socket specified by the socket parame-
  ter, the recvfrom() function waits for a message to arrive, unless the
  socket is nonblocking. When the socket is nonblocking, errno is set to
  [EWOULDBLOCK].

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

NOTES

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

RETURN VALUES

  Upon successful completion, the byte length of the written message is
  returned.  If	no messages are	available and the peer has closed the connec-
  tion,	the recv() function returns a value of 0.  Otherwise, the function
  returns a value of -1	and sets errno to indicate the error.

ERRORS

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

  [EBADF]   The	socket parameter is not	a valid	file descriptor.

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

  [EFAULT]  Nonexistent	or protected address space is specified	for the	mes-
	    sage buffer, sending address, or address length.

	    [Tru64 UNIX]  A valid message buffer was not specified.

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

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

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

  [ENOBUFS] Insufficient resources are 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 opera-
	    tion 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 nonblocking; 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 nonblocking or	does not support blocking to
	    await out-of-band data.

RELATED	INFORMATION

  Functions: read(2), recv(2), recvmsg(2), select(2), send(2), sendmsg(2),
  sendto(2), shutdown(2), socket(2), write(2).

  Standards: standards(5).