Previous topic |
Next topic |
Contents |
Contact z/OS |
Library |
PDF
bind() z/OS Communications Server: IP Sockets Application Programming Interface Guide and Reference SC27-3660-00 |
|
The bind() call binds a unique local name to the socket using descriptors. After calling socket(), the descriptor does not have a name associated with it. However, it does belong to a particular addressing family, as specified when socket() is called. The exact format of a name depends on the addressing family. The bind() call also allows servers to specify the network interfaces from which they want to receive UDP packets and TCP connection requests.
The s parameter is a socket descriptor of any type created by calling socket(). The name parameter points to a buffer containing the name to be bound to s. The namelen parameter is the size, in bytes, of the buffer pointed to by name. Related informationSocket descriptor created in the AF_INET domain If the socket descriptor s was created in the AF_INET domain, then the format of the name buffer
is expected to be sockaddr_in, as defined
in the header file IN.H.
The sin_family field must be set to AF_INET. The sin_port field identifies the port to which the application must bind. It must be specified in network byte order. If sin_port is set to 0, the caller expects the system to assign an available port. The application can call getsockname() to discover the port number assigned. The in_addr sin_addr field is set to the internet address and must be specified in network byte order. On hosts with more than one network interface (called multihomed hosts), a caller can select the interface to which it should bind. Subsequently, only UDP packets and TCP connection requests from this interface (the one value matching the bound name) are routed to the application. If this field is set to the constant INADDR_ANY, as defined in IN.H, the caller is requesting that the socket be bound to all network interfaces on the host. Subsequently, UDP packets and TCP connections from all interfaces matching the bound name are routed to the application. This becomes important when a server offers a service to multiple networks. By leaving the address unspecified, the server can accept all UDP packets and TCP connection requests made of its port, regardless of the network interface on which the requests arrived. The sin_zero field is not used and should be set to all zeros. Socket descriptor created in the AF_IUCV domain If the socket descriptor s is created
in the AF_IUCV domain, the format of the name buffer is expected to
be sockaddr_iucv, as defined in the header file SAIUCV.H.
Note: Internally, dynamic names are built using hexadecimal
character strings representing the internal storage address of the
socket. You should choose names that contain at least one non-hexadecimal
character to prevent potential conflict. Hexadecimal characters include
0–9, and a–f. Uppercase A–F are considered non-hexadecimal and can
be used by the user to build dynamic names.
Return valuesThe value 0 indicates success;
the value -1 indicates an error. Errno identifies the specific error.
ExampleThe following examples show the bind() call. The internet address and port must be in network byte order. To put the port into network byte order, the htons() utility routine is called to convert a short integer from host byte order to network byte order. The address field is set using another utility routine, inet_addr(), which takes a character string representing the dotted decimal address of an interface and returns the binary internet address representation in network byte order. Finally, it is a good idea to clear the structure before using it to ensure that the name requested does not set any reserved fields. See connect() for examples how a client might connect to servers.
This example illustrates the bind() call binding to interfaces
in the AF_INET domain.
This example illustrates the bind() call binding to interfaces
in the AF_IUCV domain.
The binding of a stream socket is not complete until a successful call to bind(), listen(), or connect() is made. Applications using stream sockets should check the return values of bind(), listen(), and connect() before using any function that requires a bound stream socket. Related callsgethostbyname(), getsockname(), htons(), inet_addr(), listen(), socket() |
Copyright IBM Corporation 1990, 2014
|