Content-type: text/html Man page of recvfrom

recvfrom

Section: System Calls (2)
Index Return to Main Contents
 

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,
       size_t *address_len) ;

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

[DIGITAL]  The following definition of the recvfrom() function does not conform to current standards and is supported only for backward compatibility (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(): XNS4.0

The recvfrom 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

Specifies the socket file descriptor. Specifies a pointer to the buffer to which the message should be written. Specifies the length (in bytes) of the buffer pointed to by the buffer parameter. 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: Peeks at the incoming message. Processes 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 connection is terminated, or an error is pending for the socket. 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 or sockaddr_un structure, depending on which of the supported address families is active.

[DIGITAL]   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 specifying 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. 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 message written to the buffer pointed to by the buffer parameter. When a message 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 parameter, the recvfrom() function waits for a message to arrive, unless the socket is nonblocking. When the socket is nonblocking, errno is set to [EWOULDBLOCK].  

NOTES

[DIGITAL]  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. Otherwise, a value of -1 is returned and errno is set to indicate the error.  

ERRORS

If the recvfrom() function fails, errno may be set to one of the following values: The socket parameter is not a valid file descriptor. A connection was forcibly closed by a peer. A valid message buffer was not specified. Nonexistent or protected address space is specified for the message buffer. A signal interrupted recvfrom before any data was available. The MSG-OOB flag is set and no out-of-band data is available. [POSIX]  Insufficient resources are available in the system to complete the call. A receive is attempted on a connection-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 timeout on active connection. The socket is nonblocking; no data is ready to be received.  

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). delim off


 

Index

NAME
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:18 GMT, October 02, 2010