recvfrom()--Receive Data

  #include <sys/types.h>
  #include <sys/socket.h>

 int recvfrom(int socket_descriptor,
             char *buffer,
             int buffer_length,
             int flags,
             struct sockaddr *from_address,
             int *address_length)

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

 ssize_t recvfrom(int socket_descriptor,
             void *buffer,
             size_t buffer_length,
             int flags,
             struct sockaddr *from_address,
             socklen_t *address_length)

The recvfrom() function is used to receive data through a connected or unconnected socket.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

socket_descriptor

(Input) The socket descriptor that is to be read from.

buffer

(Input) The pointer to the buffer in which the data that is to be read is stored.

buffer_length

(Input) The length of the buffer.

int flags

(Input) A flag value that controls the reception of the data. The flags value is either zero, or is obtained by performing an OR operation on one or more of the following constants:

MSG_OOB	Receive out-of-band data. Valid only for sockets with an address family of AF_INET or AF_INET6 and type SOCK_STREAM.
MSG_PEEK	Obtain a copy of the message without removing the message from the socket.
MSG_WAITALL	Wait for a full request or an error.

from_address

(Output) A pointer to a buffer of type struct sockaddr that contains the address from which the message was received.

The structure sockaddr is defined in <sys/socket.h>.

The BSD 4.3 structure is:

      struct sockaddr {
         u_short sa_family;
         char    sa_data[14];
      };

The BSD 4.4/UNIX 98 compatible structure is:

      typedef uchar   sa_family_t;

      struct sockaddr {
         uint8_t     sa_len;
         sa_family_t sa_family;
         char        sa_data[14];
      };

The BSD 4.4 sa_len field is the length of the address. The sa_family field identifies the address family to which the address belongs, and sa_data is the address whose format is dependent on the address family.

Note: See the usage notes about using different address families with sockaddr_storage.

address_length

(Input/output) This parameter is a value-result field. The caller passes a pointer to the length of the from_address parameter. On return from the call, address_length will contain the actual length of the address.

Authorities

An errno of EACCES is returned when the socket pointed to by the socket_descriptor field is address family AF_INET and a nonblocking connect was attempted previously and was not successful. The nonblocking connect was not successful because the thread did not have authority to the associated APPC device. The thread performing the nonblocking connect must have retrieve, insert, delete, and update authority to the APPC device.

Return Value

recvfrom() returns an integer. Possible values are:

• -1 (unsuccessful)
• n (successful), where n is the number of bytes received.

Error Conditions

When recvfrom() fails, errno can be set to one of the following:

Error Messages

Usage Notes

1. For sockets that use a connection-oriented transport service (for example, sockets with a type of SOCK_STREAM), a returned value of zero indicates one of the following:
   • The partner program has issued a close() for the socket.
     
     
   • The partner program has issued a shutdown() to disable writing to the socket.
     
     
   • The connection is broken and the error was returned on a previously issued socket function.
     
     
   • A shutdown() to disable reading was previously done on the socket.
   
   
   
2. If the socket is using a connection-oriented transport service, the from_address and address_length parameters are ignored.
   
   
3. The following applies to sockets that use a connectionless transport service (for example, a socket with a type of SOCK_DGRAM):
   • If a connect() has been issued previously, then data can be received only from the address specified in the previous connect().
     
     
   • If the from_address parameter is set to NULL or address_length specifies a value of zero, the address from which data is received is discarded by the system.
     
     
   • If the length of the address to be returned exceeds the length of the from_address parameter, the returned address is truncated.
     
     
   • The structure sockaddr is a generic structure used for any address family but it is only 16 bytes long. The actual address returned for some address families may be much larger. You should declare storage for the address with the structure sockaddr_storage. This structure is large enough and aligned for any protocol-specific structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the sockaddr_storage will always align with the family field of any protocol-specific structure.

     The BSD 4.3 structure is:

      #define _SS_MAXSIZE 304
      #define _SS_ALIGNSIZE (sizeof (char*))
      #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t))
      #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+
                             _SS_PAD1SIZE + _SS_ALIGNSIZE))
     
      struct sockaddr_storage {
          sa_family_t   ss_family;
          char         _ss_pad1[_SS_PAD1SIZE];
          char*        _ss_align;
          char         _ss_pad2[_SS_PAD2SIZE];
      };
     

     The BSD 4.4/UNIX 98 compatible structure is:

      #define _SS_MAXSIZE 304
      #define _SS_ALIGNSIZE (sizeof (char*))
      #define _SS_PAD1SIZE (_SS_ALIGNSIZE - (sizeof(uint8_t) + sizeof(sa_family_t)))
      #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(uint8_t) + sizeof(sa_family_t)+
                             _SS_PAD1SIZE + _SS_ALIGNSIZE))
     
      struct sockaddr_storage {
          uint8_t       ss_len;
          sa_family_t   ss_family;
          char         _ss_pad1[_SS_PAD1SIZE];
          char*        _ss_align;
          char         _ss_pad2[_SS_PAD2SIZE];
      };
     

     
     
   • If the socket is using an address family of AF_UNIX, the address (which is a path name) is returned in the default coded character set identifier (CCSID) currently in effect for the job.
     
     
   • If the socket is using an address family of AF_UNIX_CCSID, the output structure sockaddr_unc defines the format and coded character set identifier (CCSID) of the address (which is a path name).
     
     
   • The entire message must be read in a single read operation. If the size of the message is too large to fit in the user supplied buffer, the remaining bytes of the message are discarded.
     
     
   • A returned value of zero indicates one of the following:
     • The partner program has sent a NULL message (a datagram with no user data).
       
       
     • A shutdown() to disable reading was previously done on the socket.
       
       
     • The buffer length specified was zero.
   
   
4. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the recvfrom() API is mapped to qso_recvfrom98().

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• fcntl()--Perform File Control Command
  
  
• ioctl()--Perform I/O Control Request
  
  
• recv()--Receive Data
  
  
• recvmsg()--Receive Data or Descriptors or Both

[ Back to top | UNIX-Type APIs | APIs by category ]