# recvfrom

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           recvfrom — receive a message from a socket
    


## SYNOPSIS



           #include <sys/socket.h>
    
           ssize_t recvfrom(int _socket_ , void *restrict _buffer_ , size_t _length_ ,
               int _flags_ , struct sockaddr *restrict _address_ ,
               socklen_t *restrict _address_len_);
    


## DESCRIPTION



           The _recvfrom_() function shall receive a message from a connection-
           mode or connectionless-mode socket. It is normally used with
           connectionless-mode sockets because it permits the application to
           retrieve the source address of received data.
    
           The _recvfrom_() function takes the following arguments:
    
           _socket_      Specifies the socket file descriptor.
    
           _buffer_      Points to the buffer where the message should be
                       stored.
    
           _length_      Specifies the length in bytes of the buffer pointed to
                       by the _buffer_ argument.
    
           _flags_       Specifies the type of message reception. Values of
                       this argument are formed by logically OR'ing zero or
                       more of the following values:
    
                       MSG_PEEK    Peeks at an incoming message. The data is
                                   treated as unread and the next _recvfrom_()
                                   or similar function shall still return
                                   this data.
    
                       MSG_OOB     Requests out-of-band data. The
                                   significance and semantics of out-of-band
                                   data are protocol-specific.
    
                       MSG_WAITALL On SOCK_STREAM sockets this requests that
                                   the function block until the full amount
                                   of data can be returned. The function may
                                   return the smaller amount of data if the
                                   socket is a message-based socket, if a
                                   signal is caught, if the connection is
                                   terminated, if MSG_PEEK was specified, or
                                   if an error is pending for the socket.
    
           _address_     A null pointer, or points to a **sockaddr** structure in
                       which the sending address is to be stored. The length
                       and format of the address depend on the address family
                       of the socket.
    
           _address_len_ Either a null pointer, if _address_ is a null pointer,
                       or a pointer to a **socklen_t** object which on input
                       specifies the length of the supplied **sockaddr**
                       structure, and on output specifies the length of the
                       stored address.
    
           The _recvfrom_() function shall return the length of the message
           written to the buffer pointed to by the _buffer_ argument. For
           message-based sockets, such as SOCK_RAW, SOCK_DGRAM, and
           SOCK_SEQPACKET, the entire message shall be read in a single
           operation. If a message is too long to fit in the supplied buffer,
           and MSG_PEEK is not set in the _flags_ argument, the excess bytes
           shall be discarded. For stream-based sockets, such as SOCK_STREAM,
           message boundaries shall be ignored. In this case, data shall be
           returned to the user as soon as it becomes available, and no data
           shall be discarded.
    
           If the MSG_WAITALL flag is not set, data shall be returned only up
           to the end of the first message.
    
           Not all protocols provide the source address for messages. If the
           _address_ argument is not a null pointer and the protocol provides
           the source address of messages, the source address of the received
           message shall be stored in the **sockaddr** structure pointed to by
           the _address_ argument, and the length of this address shall be
           stored in the object pointed to by the _address_len_ argument.
    
           If the actual length of the address is greater than the length of
           the supplied **sockaddr** structure, the stored address shall be
           truncated.
    
           If the _address_ argument is not a null pointer and the protocol
           does not provide the source address of messages, the value stored
           in the object pointed to by _address_ is unspecified.
    
           If no messages are available at the socket and O_NONBLOCK is not
           set on the socket's file descriptor, _recvfrom_() shall block until
           a message arrives. If no messages are available at the socket and
           O_NONBLOCK is set on the socket's file descriptor, _recvfrom_()
           shall fail and set _errno_ to **[EAGAIN]** or **[EWOULDBLOCK]**.
    


## RETURN VALUE



           Upon successful completion, _recvfrom_() shall return the length of
           the message in bytes. If no messages are available to be received
           and the peer has performed an orderly shutdown, _recvfrom_() shall
           return 0. Otherwise, the function shall return -1 and set _errno_ to
           indicate the error.
    


## ERRORS



           The _recvfrom_() function shall fail if:
    
           **EAGAIN** or **EWOULDBLOCK**
                  The socket's file descriptor is marked O_NONBLOCK and no
                  data is waiting to be received; or MSG_OOB is set and no
                  out-of-band data is available and either the socket's file
                  descriptor is marked O_NONBLOCK or the socket does not
                  support blocking to await out-of-band data.
    
           **EBADF** The _socket_ argument is not a valid file descriptor.
    
           **ECONNRESET**
                  A connection was forcibly closed by a peer.
    
           **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.
    
           **ENOTCONN**
                  A receive is attempted on a connection-mode socket that is
                  not connected.
    
           **ENOTSOCK**
                  The _socket_ argument does not refer to a socket.
    
           **EOPNOTSUPP**
                  The specified flags are not supported for this socket type.
    
           **ETIMEDOUT**
                  The connection timed out during connection establishment,
                  or due to a transmission timeout on active connection.
    
           The _recvfrom_() function may fail if:
    
           **EIO** An I/O error occurred while reading from or writing to the
                  file system.
    
           **ENOBUFS**
                  Insufficient resources were available in the system to
                  perform the operation.
    
           **ENOMEM** Insufficient memory was available to fulfill the request.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           The _select_() and _poll_() functions can be used to determine when
           data is available to be received.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *