getpeername()--Retrieve Destination Address of Socket

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

  int getpeername(int socket_descriptor,
                  struct sockaddr *destination_address,
                  int *address_length)

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

  int getpeername(int socket_descriptor,
                  struct sockaddr *destination_address,
                  socklen_t *address_length)

The getpeername() function is used to retrieve the destination address to which the socket is connected.

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 descriptor of the socket for which the destination address is to be retrieved.

destination_address

(Output) A pointer to a buffer of type struct sockaddr in which the destination address to which the socket connects is stored. 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

(I/O) This parameter is a value-result field. The caller passes a pointer to the length of the destination_address parameter. On return from the call, the address_length parameter contains the actual length of the destination address.

Authorities

No authorization is required.

Return Value

getpeername() returns an integer. Possible values are:

• -1 (unsuccessful)
  
  
• 0 (successful)

Error Conditions

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

Error Messages

Usage Notes

1. getpeername() fails if issued against a socket for which a connect() has not been done.
   
   
2. For connection oriented sockets, getpeername() fails if both the write side and the read side have been closed through the use of one or more previous shutdown() functions.
   
   
3. If the length of the address to be returned exceeds the length of the destination_address parameter, the returned address is truncated.
   
   
4. 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];
    };
   

5. When used with an address family of AF_UNIX or AF_UNIX_CCSID, getpeername() always returns the same path name that was specified on the bind() in the peer program. If the path name specified by the peer program was not a fully qualified path name, the output of getpeername() is meaningful only if your program knows what current directory was in effect for the peer program when it issued the bind(). For AF_UNIX, the path name is returned in the default coded character set identifier (CCSID) currently in effect for the job. For AF_UNIX_CCSID, the output structure sockaddr_unc defines the format and CCSID of the returned path name.
   
   
6. 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 getpeername() API is mapped to qso_getpeername98().

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• accept()--Wait for Connection Request and Make Connection
  
  
• bind()--Set Local Address for Socket
  
  
• connect()--Establish Connection or Destination Address
  
  
• getsockname()--Retrieve Local Address of Socket

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