bind: Bind a local name to the socket

The bind socket function binds a unique local name to the socket with the s descriptor.

Last updated

  • Changed for PUT13.
  • Added for PUT00.

Format

#include <sys/socket.h>
int      bind(int s,
              struct sockaddr *name,
              int namelen);
s
The socket descriptor.
name
Pointer to a sockaddr structure (buffer) containing the name that is to be bound to the s parameter.
namelen
Size of the buffer that the name parameter points to in bytes.

Normal return

Return code 0 indicates that the function was successful.

Error return

The return code -1 indicates an error. You can get the specific error code by calling sock_errno. See z/TPF Transmission Control Protocol/Internet Protocol for more information about socket errors.
SOCADDRINUSE
The address is already in use. See setsockopt: Set options associated with a socket for more information on the SO_REUSEADDR option.
SOCADDRNOTAVAIL
The address specified is not valid on this host.
SOCAFNOSUPPORT
The address family is not supported.
SOCINVAL
The socket is already bound to an address. For example, you cannot bind a name to a socket that is in the connected state. This value is also returned if the value of the namelen parameter is not the expected length.
SOCNOTSOCK
The s parameter is not a valid socket descriptor.
E1052STATE
The socket was closed because the system was in or cycling down to 1052 state.

Programming considerations

  • The bind function binds a unique local name to the socket with descriptor s. After calling socket, a descriptor does not have a name associated with it. The bind procedure also allows servers to specify from which network interfaces they want to receive UDP packets and TCP connection requests.
  • The binding of a stream socket is not complete until a successful call to bind, listen, or connect is made. Applications using stream sockets must check the return values of bind, listen, and connect before using any function that requires a bound stream socket.
  • When binding a socket to all local IP addresses (that is, INADDR_ANY is specified), the socket is bound to all IP interfaces that are currently active, as well as to any IP interfaces that are subsequently activated.
  • If the file path already exists, the SOCADDRINUSE error is issued.
  • If the socket is a UNIX domain socket, a file is created on the file system that corresponds to the file path specified in the sockaddr_un structure that is passed to the bind function.
  • Applications must delete the files that are created on the file system for UNIX domain sockets.
  • You must provide a path that appends to the current working directory, and the absolute path must not exceed 108 characters. If the absolute path exceeds 108 characters, the bind is rejected.

Examples

  1. Bind to a specific interface in the internet domain and make sure the sin_zero field is cleared: 
    #include <sys/socket.h>
⋮
int rc;
int s;
struct sockaddr_in myname;
⋮
memset(&myname, 0, sizeof(myname));
myname.sin_family      = AF_INET;
myname.sin_port        = 5001;
myname.sin_addr.s_addr = inetaddr("129.5.24.1"); /*specific interface*/
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname));
  2. Bind to all network interfaces in the internet domain. 
    memset(&myname, 0, sizeof(myname));
myname.sin_family      = AF_INET;
myname.sin_port        = 5001;
myname.sin_addr.s_addr = INADDR_ANY; /* all interfaces */
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname));
  3. Bind to a specific interface in the internet domain and let the system choose a port. 
    memset(&myname, 0, sizeof(myname));
myname.sin_family      = AF_INET;
myname.sin_port        = INADDR_ANY;
myname.sin_addr.s_addr = inetaddr("129.5.24.1"); /*specific interface*/
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname));
  4. Bind to a specific file name in the UNIX domain.
    #include <sys/socket.h>
⋮
int rc;
int s;
struct sockaddr_un myname;
⋮
memset(&myname, 0, sizeof(myname));
myname.sun_family      = AF_UNIX;
myname.sun_path        = /tmp/myUNIXsock;
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname)); 
if (rc == -1){     
        printf("BIND ERROR = %d\n", sock_errno());
}
⋮