bind() — Bind a Name to a Socket

X/Open

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>

int bind(int socket, const struct sockaddr *address, size_t address_len);

Berkeley Sockets

#define _OE_SOCKETS
#include <sys/types.h>
#include <sys/socket.h>

int bind(int socket, struct sockaddr *address, int *address_len);

Binds a unique local name to the socket with descriptor socket. After calling socket(), a descriptor does not have a name associated with it. However, it does belong to a particular address family as specified when socket() is called. The exact format of a name depends on the address family.

socket

The socket descriptor returned by a previous socket() call.

address

The pointer to a sockaddr structure containing the name that is to be bound to socket.

address_len

The size of address in bytes.

If the socket descriptor socket was created in the AF_INET domain, the format of the name buffer is expected to be sockaddr_in, as defined in the netinet/in.h header file.

struct in_addr
{
        in_addr_t s_addr;
};

 struct sockaddr_in {
     unsigned char  sin_len;      /* length of sockaddr struct */
     unsigned char  sin_family;   /* addressing family */
     unsigned short sin_port;     /* port number */
     struct in_addr sin_addr;     /* IP address */
     unsigned char  sin_zero[8];  /* unassigned */

};

If the socket descriptor socket was created in the AF_INET6 domain, the format of the name buffer is expected to be sockaddr_in6, as defined in netinet/in.h:

 struct sockaddr_in6 {
     uint8_t         sin6_len;       /* length of sockaddr structure */
     sa_family_t     sin6_family;    /* addressing family */
     in_port_t       sin6_port;      /* port number */
     uint32_t        sin6_flowinfo;  /* ignored */
     struct in6_addr sin6_addr;      /* IP address */
     uint32_t        sin6_scope_id;  /* scope ID */
};

If the socket descriptor socket was created in the AF_IUCV domain, the format of the name buffer is expected to be sockaddr_iucv, as defined in the saiucv.h header file.

struct sockaddr_iucv {
    unsigned char  siucv_len;       /* length of sockaddr struct */
    unsigned char  siucv_family;    /* addressing family */
    unsigned short siucv_port;      /* port number */
    unsigned long  siucv_addr;      /* address */
    unsigned char  siucv_nodeid[8]; /* nodeid to connect to */
    unsigned char  siucv_userid[8]; /* userid to connect to */
    unsigned char  siucv_name[8];   /* iucvname for connect */
};

The siucv_name field is set to the application name by which the socket is to be known. It must be unique within the virtual machine because only one socket can be bound to a given name. The recommended form of the name contains 8 characters, padded with blanks to the right. The 8 characters for a connect() call executed by a client must exactly match the 8 characters passed in the bind() call executed by the server. This name is passed, by the sockets library, as the NAME parameter on invocations of the CMS HNDIUCV and CMSIUCV macros. It must be unique, therefore, among all the names used for these macros by any programs running in the virtual machine.

If the socket descriptor socket is created in the AF_UNIX domain, the format of the name buffer is expected to be sockaddr_un, as defined in the sys/un.h header file.

struct sockaddr_un {
    unsigned char  sun_len;        /* length of sockaddr struc */
    unsigned char  sun_family;     /* addressing family */
             char  sun_path[108];  /* pathname */
};

• For AF_UNIX, when a bind() is issued, a file is created with a mode of 660. In order to allow other users to access this file, you should issue a chmod() to modify this mode.
• For AF_UNIX, when closing sockets that were bound, you should also use unlink() to delete the file created at bind() time.
• The path name the client uses on the bind() must be unique.
• The sendto() call must specify the path name associated with the server.
• For AF_INET and AF_INET6, the user must have appropriate privileges to bind to a port in the range from 1 to 1023.

If unsuccessful, bind() returns a value of -1 and sets errno to one of the following values under the conditions described:

EACCES

Permission is denied.

For AF_INET and AF_INET6 only, permission is denied. A user that is not in the obeylist attempted to bind to a port between 0-1023 when RESTRICTLOWPORTS has been specified on the ASSORTEDPARMS statement. Or, a user attempted to bind to a port that has previously been reserved using a PORT statement in the TCP/IP cofiguration file or through obeyfile processing.

EADDRINUSE

For AF_INET AF_INET6, and AF_IUCV only, the address is already in use. For information about the AF_INET domain, see the SO_REUSEADDR option described under getsockopt() — Get Options Associated with a Socket and the SO_REUSEADDR option described under setsockopt() — Set Options Associated with a Socket.

EADDRNOTAVAIL

The address specified is not valid on this host. For example, the internet address does not specify a valid network interface.

EAFNOSUPPORT

The address family is not supported (it is not AF_INET, AF_INET6, AF_IUCV, or AF_UNIX), or the family field in the sockaddr structure does not match the family value specified on the socket() function.

EBADF

The socket parameter is not a valid file descriptor.

EFAULT

The address and address_len parameters result in an attempt to copy the address into a nonwritable portion of the caller's virtual storage.

EINVAL

The socket is already bound to an address—for example, trying to bind a name to a socket that is already connected—or the socket was shut down. This error also occurs for the AF_IUCV domain if the siucv_nodeid field in address is not all blanks or if the siucv_addr or siucv_port fields are nonzero.

EIO

A network or transport failure has occurred.

ENOBUFS

The bind() function is unable to obtain a buffer due to insufficient storage.

ENOTSOCK

The descriptor is a valid file descriptor, but it is not a socket.

EOPNOTSUPP

The socket type of the specified socket does not support binding to an address.

EPERM

The user is not authorized to bind to the port specified.

The following are for AF_UNIX only:

EACCES

The process does not have search permission on a component of the path prefix, or it does not have write access to the directory of the requested name.

EDESTADDRREQ

The address argument is a null pointer.

EEXIST

The file name already exists. You should issue unlink() before issuing bind().

EIO

An I/O error occurred.

ELOOP

Too many symbolic links were encountered in translating the path name in address.

ENAMETOOLONG

A component of a path name exceeded NAME_MAX characters, or an entire path name exceeded PATH_MAX characters.

ENOENT

A component of the path name does not name an existing file or the path name is an empty string.

ENOTDIR

A component of the path prefix of the path name in address is not a directory.

EROFS

The name would reside on a read-only file system.

The following example illustrates the bind() call binding to interfaces in the AF_INET domain. 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.

int rc;
int s;
struct sockaddr_in myname;
/* Bind to a specific interface in the internet domain */
/* make sure the sin_zero field is cleared */
memset(&myname, 0, sizeof(myname));
myname.sin_family = AF_INET;
myname.sin_addr.s_addr = inet_addr("129.5.24.1"); /* specific interface */
myname.sin_port = htons(1024);
⋮
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname));

/* Bind to all network interfaces in the internet domain */
/* make sure the sin_zero field is cleared */
memset(&myname, 0, sizeof(myname));
myname.sin_family = AF_INET;
myname.sin_addr.s_addr = INADDR_ANY; /* specific interface */
myname.sin_port = htons(1024);
⋮
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname));

/* Bind to a specific interface in the internet domain.
   Let the system choose a port                        */
/* make sure the sin_zero field is cleared */
memset(&myname, 0, sizeof(myname));
myname.sin_family = AF_INET;
myname.sin_addr.s_addr = inet_addr("129.5.24.1"); 
/* specific interface */
myname.sin_port = 0;
⋮
rc = bind(s, (struct sockaddr *) &myname, 
sizeof(myname));

The following example illustrates the bind() call binding to interfaces in the AF_INET6 domain. Note that inet_pton() is used instead of inet_addr(), and that inet_pton() fills in all of the sin6_addr field.

int                  s;  /* Socket descriptor. */
int                  rc;       
char                 v6addr[16] = "C2C1::129:5:24:1";  /* IPv6 IP address. */
struct sockaddr_in6  myname;     
struct in6_addr      IN6ADDR_ANY = IN6ADDR_ANY_INIT;  /* Init required by VM. */          

/* Bind to a specific interface in the AF_INET6 domain. */
/* (Not specifying flow info and scope ID.)             */
memset(&myname,0,sizeof(myname)); 
myname.sin6_len = sizeof(myname); 
myname.sin6_family = AF_INET6;
myname.sin6_addr = inet_pton(AF_INET6,(char *)&v6addr,&(myname.sin6_addr));
myname.sin6_port = htons(1024);
rc = bind(s,struct sockaddr *)&myname,sizeof(myname));

/* Bind to all network interfaces in the AF_INET6 domain. */
memset(&myname,0,sizeof(myname)); 
myname.sin6_len = sizeof(myname); 
myname.sin6_family = AF_INET6;
myname.sin6_addr = IN6ADDR_ANY;
myname.sin6_port = htons(1024);
rc = bind(s,struct sockaddr *)&myname,sizeof(myname));

The following example illustrates the bind() call binding to interfaces in the AF_IUCV domain.

int rc;
int s;
struct sockaddr_iucv myname;
#define SERVER_NAME "APPL1"
/* Bind to a name in the IUCV domain */
/* make sure the siucv_addr, siucv_port fields are zeroed and the
   siucv_nodeid field is set to blanks */
memset(&myname, 0, sizeof myname);
myname.siucv_family = AF_IUCV;
memset(myname.siucv_nodeid, ' ', sizeof myname.siucv_nodeid);
memset(myname.siucv_name, ' ', sizeof myname.siucv_name);
memcpy(myname.siucv_name, SERVER_NAME, sizeof SERVER_NAME -1);
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname));

The following example illustrates the bind() call binding to interfaces in the AF_UNIX domain.

int rc;
int s;
/* Bind to a name in the UNIX domain */
struct sockaddr_un myname;
char socket_name[]="/tmp/socket.for._";
⋮
memset(&myname, 0, sizeof(myname));
myname.sun_family = AF_UNIX;
strcpy(myname.sun_path,socket_name);
myname.sun_len = sizeof(myname.sun_path);
⋮
rc = bind(s, (struct sockaddr *) &myname, SUN_LEN(&myname));