bind()--Set Local Address for Socket
BSD 4.3 Syntax
#include <sys/types.h> #include <sys/socket.h> int bind(int socket_descriptor, struct sockaddr *local_address, int address_length)
Service Program Name: QSOSRV1
Default Public Authority: *USE
Threadsafe: Yes
UNIX 98 Compatible Syntax
#define _XOPEN_SOURCE 520 #include <sys/socket.h> int bind(int socket_descriptor, const struct sockaddr *local_address, socklen_t address_length)
Service Program Name: QSOSRV1
Default Public Authority: *USE
Threadsafe: Yes
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:
[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:
|
[EADDRNOTAVAIL] | Address not available. This error code indicates
one of the following:
|
[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:
|
[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. |
[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
Message ID | Error Message Text |
---|---|
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
- 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.
- The process must have the following types of permission:
- 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.
- 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.
- 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.
- 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.
- 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
API introduced: V3R1