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)

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

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

The getsockname() function is used to retrieve the local address associated with the 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 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>.

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 local_address parameter. On return from the call, the address_length parameter contains the actual length of the local address.

Authorities

No authorization is required.

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:

Error Messages

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. 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];
    };
   

3. When used with an address family of AF_UNIX or AF_UNIX_CCSID, getsockname() always returns the same path name 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 meaningful only if your program knows what current directory was in effect at the time of 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.
   
   
4. 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_INET6:
     
     
     • 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().
     
     
   • For address family of AF_UNIX or AF_UNIX_CCSID, getsockname() returns 0 if issued before a bind(). The address length is 0. This is always the case for sockets created by socketpair().
   
   
5. 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 getsockname() API is mapped to qso_getsockname98().

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• bind()--Set Local Address for Socket
  
  
• connect()--Establish Connection or Destination Address

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