bind2addrsel()--Set Local Address for Socket with Address Selection Preferences

  #include <netinet/in.h>

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

  #define _XOPEN_SOURCE 520
  #include <netinet/in.h>

int bind2addrsel(int socket_descriptor,
          const struct sockaddr *destination_address,
          socklen_t address_length)

The bind2addrsel() function is used to associate a local address with a connection oriented socket based on the address selection preferences and destination address.

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 that has the source address selection preferences set and is to be bound.

destination_address

(Input) A pointer to a buffer of type struct sockaddr that contains the destination address to which the socket wants to communicate. 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.

address_length

(Input) The length of the destination_address.

Authorities

• No authorization is required.
  

Return Value

bind2addrsel() returns an integer. Possible values are:

• -1 (unsuccessful)
• 0 (successful)

Error Conditions

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

Error Messages

Usage Notes

1. This API is only valid for sockets that use an address family of AF_INET6; therefore, the internet address structure must be a sockaddr_in6. The system will bind to an address based on the supplied destination address and the source address selection preferences set for the socket. A port number in which to bind to will automatically be selected.

   The BSD 4.3 structure is:

         typedef unsigned short sa_family_t;
         typedef unsigned short in_port_t;
   
         struct sockaddr_in6 {
            sa_family_t     sin6_family;
            in_port_t       sin6_port;
            uint32_t        sin6_flowinfo;
            struct in6_addr sin6_addr;
            uint32_t        sin6_scope_id;
         };
   

   The BSD 4.4/UNIX 98 compatible structure is:

         typedef uchar   sa_family_t;
         typedef unsigned short in_port_t;
   
         struct sockaddr_in6 {
            uint8_t         sin6_len;
            sa_family_t     sin6_family;
            in_port_t       sin6_port;
            uint32_t        sin6_flowinfo;
            struct in6_addr sin6_addr;
            uint32_t        sin6_scope_id;
         };
   

   The BSD 4.4 sin6_len field is the length of the address. The sin6_family is the address family (AF_INET6 in this case), sin6_port is the port number, and sin6_addr is the internet address. The sin6_flowinfo field contains two pieces of information: the traffic class and the flow label. Note: This field is currently not supported and should be set to zero for upward compatibility. The sin6_scope_id field identifies a set of interfaces as appropriate for the scope of the address carried in the sin6_addr field. Note: This field must be set if the address is link-local.

2. An implicit bind on the connect() API can be used in place of this API when setting the IPV6_ADDR_PREFERECES socket option on setsockopt().
3. 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 bind2addrsel() API is mapped to qso_bind2addrsel98().

Related Information

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

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