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)

The bind() function is used to associate a local address with a socket.

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>.

      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

(Input) The length of the local_address.

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_UNIX, and the address specified in the sockaddr_un 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_NS, and the port specified in the sockaddr_ns 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_NS, and the network number or the node address specified in the sockaddr_ns structure (pointed to by local_address) is not valid for the local machine.

  Note: For sockets with an address family of AF_NS, it is recommended that you specify 0 for the network number and the node address.

[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.

[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.

[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 address family.

[ENAMETOOLONG]

File name too long.

This error code is only returned on sockets that use the AF_UNIX 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 address family.

[ENOSYS]

Function not implemented.

This error code is only returned on sockets that use the AF_UNIX address family.

[ENOTDIR]

Not a directory.

This error code is only returned on sockets that use the AF_UNIX 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

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. For sockets that use an address family of AF_UNIX, 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.

   • The path name is assumed to be in the default coded character set identifier (CCSID) currently in effect for the job.

   • When the socket is no longer needed, the caller should remove the file system entry that was created by the bind() using the unlink() 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.

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

     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_NS, the following is applicable:

   • The network services address structure sockaddr_ns requires a 4-byte network number, a 6-byte node address (referred to as a host address in the actual structure) and a 2-byte port number. The network number and the node address should be set to 0. You can have the system automatically select a port number by setting the port number to 0.

   • The sockaddr_ns structure also has a reserved field, which must be specified as hexadecimal zeros.

4. For sockets that use an address family of AF_TELEPHONY, the following is applicable:

   • A telephony address tel_addr consists of a 2-byte length followed by a telephone number up to 40 digits long.

   • The telephony sockets address structure sockaddr_tel consists of the address family, the telephony address, and a reserved field.

          struct tel_addr {
             unsigned short  t_len;
             char            t_addrÕ40þ;
           };
     
           struct sockaddr_tel {
              short           stel_family;
              struct tel_addr stel_addr;
              char            stel_zeroÕ4þ;
           };
     

     The stel_family is the address family (always AF_TELEPHONY), the stel_addr is the telephone number length and the telephone number itself. The stel_zero field is reserved.

   • A wildcard telephone number is provided (TELADDR_ANY defined in <nettel/tel.h>) that allows an application to answer calls directed to any of the local numbers specified in the connection list(s) associated with the device(s) that are being used by a socket.

Related Information

• connect()--Establish Connection or Destination Address