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)

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

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>.

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

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.

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.

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:

[EBADF]

Descriptor not valid.

[EFAULT]

Bad address.

The system detected an address which was not valid while attempting to access the destination_address or address_length parameters.

[EINVAL]

Parameter not valid.

The address_length parameter specifies a negative value.

[EIO]

Input/output error.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOTCONN]

Requested operation requires a connection.

[ENOTSOCK]

The specified descriptor does not reference a socket.

[EUNKNOWN]

Unknown system state.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Error Messages

CPE3418 E

Possible APAR condition or hardware failure.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFA081 E

Unable to set return value or error code.

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. When used with an address family of AF_UNIX, getpeername() always returns the exact sockaddr_un structure 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 only meaningful if your program knows what current directory was in effect for the peer program when it issued the bind(). In addition, the path name is returned in the default coded character set identifier (CCSID) currently in effect for the job.

5. For sockets with an address family of AF_TELEPHONY, the following is applicable:

   • For the active (connecting) end of a connection, getpeername() will return the number dialed.

   • For the passive (accepting) end of a connection, getpeername() will return the number of the caller, if available. Otherwise, it will return TELADDR_ANY.

Related Information

• 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