getsockname()--Retrieve Local Address of Socket

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

int getsockname(int socket_descriptor,
                struct sockaddr *local_address,
                int *address_length)

The getsockname() function is used to retrieve the local address associated with the socket.

Parameters

socket_descriptor

(Input) The descriptor of the socket for which the local address is to be retrieved.

local_address

(Output) A pointer to a buffer of type struct sockaddr in which the local address of the socket 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 local_address parameter. On return from the call, the address_length parameter contains the actual length of the local address.

Return Value

getsockname() returns an integer. Possible values are:

• -1 (unsuccessful)

• 0 (successful)

Error Conditions

When getsockname() 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 local_address or address_length parameters.

[EINVAL]

Parameter not valid. This error code indicates one of the following:

• The address_length parameter specifies a negative value.

• The socket specified by the socket_descriptor parameter is using a connection-oriented transport service and either the write-side has been shut down (with a shutdown()) or the connection has been reset.

[EIO]

Input/output error.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[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. If the length of the address to be returned exceeds the length of the local_address parameter, the returned address will be truncated.

2. When used with an address family of AF_UNIX, getsockname() always returns the exact sockaddr_un structure that was specified on a bind(). If the path name that was specified is not a fully qualified path name, the output of getsockname() is only meaningful if your program knows what current directory was in effect at the time of the bind(). In addition, the path name is returned in the default coded character set identifier (CCSID) currently in effect for the job.

3. getsockname() produces different results, depending on the address family or type of the socket:

   • For address family of AF_INET:

     • If the type is SOCK_STREAM or SOCK_DGRAM, getsockname() will return 0 if issued before the bind(). The socket address that is returned has the IP address and port number fields set to zeros.

     • If the type is SOCK_RAW, getsockname() returns a -1 if issued before a bind().

     • If the type is SOCK_STREAM, and an Rbind() has successfully completed, then the address returned is the SOCKS server address. See Rbind() for more information.

   • For address family of AF_UNIX, getsockname() returns 0 if issued before a bind(). The address length is 0. This is always the case for sockets created by socketpair().

   • For address family of AF_NS, getsockname() returns 0 if it is issued before a bind(). The socket address that is returned is set to zeros for the network, host, port, and reserved portions of the address.

4. For address family of AF_TELEPHONY:

   • If issued before the bind(), getsockname() will return 0.

   • If issued after a successful bind(), getsockname() will return the bound address.

   • If issued after a connection has been established, the address returned depends on which end of the connection is being queried. For the active (connecting) end, getsockname() will return the bound address. For the passive (accepting) end, getsockname() will return the called address, if available. Otherwise, it will return the bound address.

Related Information

• bind()--Set Local Address for Socket

• connect()--Establish Connection or Destination Address