bind()--Set Local Address for Socket

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

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

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

 int bind(int socket_descriptor,
          const struct sockaddr *local_address,
          socklen_t address_length)

The bind() function is used to associate a local address with a 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 that is to be bound.

local_address

(Input) A pointer to a buffer of type struct sockaddr that contains the local address to which the socket is to be bound. 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 local_address.

Authorities

• When the address type of the socket identified by the socket_descriptor is AF_INET, the thread must have retrieve, insert, delete, and update authority to the port specified by the local_address field. When the thread does not have this level of authority, an errno of EACCES is returned.
  
  
• When the address type of the socket identified by the socket_descriptor is AF_INET and is running IP over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. When the thread does not have this level of authority, an errno of EACCES is returned.

Return Value

bind() returns an integer. Possible values are:

• -1 (unsuccessful)
• 0 (successful)

Error Conditions

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

Error Messages

Usage Notes

1. For sockets that use an address family of AF_UNIX or AF_UNIX_CCSID, the following is applicable:
   
   
   • The process must have the following types of permission:
     • Create permission to the directory in which the entry is to be created.
     • Search permission along all the components of the path.

     Also, processes trying to establish a connection with the connect() must have write access to the entry that is created.

   • For AF_UNIX, the path name is assumed to be in the default coded character set identifier (CCSID) currently in effect for the job. For AF_UNIX_CCSID, the path name is assumed to be in the format and CCSID specified in the sockaddr_unc (pointed to by local_address).
     
     
   • When the socket is no longer needed, the caller should remove the file system entry that was created by the bind() using the unlink() or Qp0lunlink() system function.
   
   
   
2. For sockets that use an address family of AF_INET, the following is applicable:
   
   
   • The internet address structure sockaddr_in requires a 2-byte port number and a 32-bit IP address. You can have the system automatically select a port number by setting the port number to 0.

     The BSD 4.3 structure is:

           struct sockaddr_in {
              short   sin_family;
              u_short sin_port;
              struct  in_addr sin_addr;
              char    sin_zero[8];
           };
     

     The BSD 4.4/UNIX 98 compatible structure is:

           typedef uchar   sa_family_t;
     
           struct sockaddr_in {
              uint8_t        sin_len;
              sa_family_t    sin_family;
              u_short        sin_port;
              struct in_addr sin_addr;
              char           sin_zero[8];
           };
     

     The BSD 4.4 sin_len field is the length of the address. The sin_family is the address family (always AF_INET for TCP and UDP), sin_port is the port number, and sin_addr is the internet address. The sin_zero field is reserved and must be hex zeros.

   • A wildcard address is provided (INADDR_ANY defined in <netinet/in.h>) that allows an application to receive messages directed to a specified port independent of the IP address that was specified. If a local IP address is specified, only data received on that IP address is made available. INADDR_ANY must be used to receive data from multiple local interface definitions.
   
   
   
3. For sockets that use an address family of AF_INET6, the following is applicable:
   
   
   • The internet address structure sockaddr_in6 requires a 2-byte port number and a 128-bit IP address. You can have the system automatically select a port number by setting the port number to 0.

     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.

   • A wildcard address is provided that allows an application to receive messages directed to a specified port independent of the IP address that was specified. Since the IPv6 address type is a structure (struct in6_addr), a symbolic constant can be used to initialize an IPv6 address variable, but cannot be used in an assignment. Therfore, the IPv6 wildcard address is provided in two forms as defined in <netinet/in.h>. The first version is a global variable named in6addr_any. This version is used similarly to the way applications use the INADDR_ANY in IPv4 as defined above and must be used for structure assignment. The other version is a symbolic constant named IN6ADDR_ANY_INIT. This version may be used to initialize an in6_addr structure. If a local IP address is specified, only data received on that IP address is made available. The wildcard address must be used to receive data from multiple local interface definitions.
   
   
   
4. 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 bind() API is mapped to qso_bind98().

Related Information

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

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