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 i5/OS 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:

[EACCES]	Permission denied. The process does not have the appropriate privileges to bind local_address to the socket pointed to by socket_descriptor (for example, if socket_descriptor is a socket with an address family of AF_INET, and the sockaddr_in structure (pointed to by local_address) specified a port that was restricted for use).
[EADDRINUSE]	Address already in use. This error code indicates one of the following: The socket_descriptor points to a socket with an address family of AF_INET, and the address specified in the sockaddr_in structure (pointed to by local_address) has already been assigned to another socket. The socket_descriptor points to a socket with an address family of AF_INET6, and the address specified in the sockaddr_in6 structure (pointed to by local_address) has already been assigned to another socket. The socket_descriptor points to a socket with an address family of AF_UNIX or AF_UNIX_CCSID, and the address specified in the sockaddr_un or sockaddr_unc structure (pointed to by local_address) has already been assigned to another socket.
[EADDRNOTAVAIL]	Address not available. This error code indicates one of the following: The socket_descriptor points to a socket with an address family of AF_INET, and the IP address specified in the sockaddr_in structure (pointed to by local_address) is not one defined by the local interfaces. The socket_descriptor points to a socket with an address family of AF_INET6, and the IP address specified in the sockaddr_in6 structure (pointed to by local_address) is not one defined by the local interfaces.
[EAFNOSUPPORT]	The type of socket is not supported in this protocol family. The address family specified in the address structure pointed to by local_address parameter cannot be used with the socket pointed to by the socket_descriptor parameter.
[EBADF]	Descriptor not valid.
[EDESTADDRREQ]	The local_address parameter is a null pointer. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family.
[EFAULT]	Bad address. The system detected an address which was not valid while attempting to access the local_address parameter.
[EINVAL]	Parameter not valid. This error code indicates one of the following: The address_length parameter specifies a length that is negative or is not valid for the address family. The socket referenced by socket_descriptor is not a socket of type SOCK_RAW and is already bound to an address. The local address pointed to by the local_address parameter specified an address that was not valid. The socket_descriptor points to a socket with an address family of AF_UNIX_CCSID, and the CCSID specified in sunc_qlg in the sockaddr_unc structure (pointed to by local_address) cannot be converted to the current default CCSID for integrated file system path names. The socket_descriptor points to a socket with an address family of AF_UNIX_CCSID, and there was an incomplete character or shift state sequence at the end of sunc_path in the sockaddr_unc structure (pointed to by local_address). The socket_descriptor points to a socket with an address family of AF_UNIX_CCSID, and the sockaddr_unc structure (pointed to by local_address) was not valid: The sunc_format was not set to SO_UNC_DEFAULT or SO_UNC_USE_QLG. The sunc_zero was not initialized to zeros. The sunc_format field was set to SO_UNC_USE_QLG and the sunc_qlg structure was not valid: The path type was less than 0 or greater than 3. The path length was less than 0 or out of bounds. For example, a single-byte path name was greater than 126 bytes or a double-byte path name was greater than 252 bytes. A reserved field was not initialized to zeros.
[EIO]	Input/output error.
[ELOOP]	A loop exists in symbolic links encountered during pathname resolution. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family.
[ENAMETOOLONG]	File name too long. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family.
[ENOBUFS]	There is not enough buffer space for the requested operation.
[ENOENT]	No such file or directory. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family.
[ENOSYS]	Function not implemented. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID or AF_UNIX_CCSID address family.
[ENOTDIR]	Not a directory. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family.
[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

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. Note: This field is currently not supported and should be set to zero for upward compatibility.

   • 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