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, socklen_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);

The bind() function 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.

Parameter

Description

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 include file netinet/in.h:

struct in_addr
{
        ip_addr_t s_addr;
};

 struct sockaddr_in {
     unsigned char  sin_len;
     unsigned char  sin_family;
     unsigned short sin_port;
     struct in_addr sin_addr;
     unsigned char  sin_zero[8];

};

Socket Descriptor Created in the AF_INET6 Domain 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 the include file netinet/in.h. The structure is defined as follows:

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;
};

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 include file un.h.

 struct sockaddr_un {
    unsigned char  sun_len;
    unsigned char  sun_family;
             char  sun_path[108];        /* pathname */
};

The sun_path field contains the NULL-terminated pathname, and sun_len contains the length of the pathname.

If unsuccessful, bind() returns -1 and sets errno to one of the following values:

Error Code

Description

EACCES

Permission denied.

EADDRINUSE

The address is already in use. See the SO_REUSEADDR option described under getsockopt() — Get the options associated with a socket and the SO_REUSEADDR described under the setsockopt() — Set options associated with a socket for more information.

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_UNIX, AF_INET, or AF_INET6).

EBADF

The socket parameter is not a valid socket descriptor.

EINVAL

One of three conditions may apply:

• The socket is already bound to an address—for example, trying to bind a name to a socket that is already connected.
• The socket was shut down.
• An incorrect parameter was passed on the bind() invocation.

Check the parameter values passed and ensure they are specified as described above.

EIO

There has been a network or transport failure.

ENOBUFS

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

ENOTSOCK

The descriptor is for a file, not for 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:

Error Code

Description

EACCES

A component of the path prefix denies search permission, or the requested name requires writing in a directory with a mode that denies write permission.

EDESTADDRREQ

The address argument is a NULL pointer.

EIO

An I/O error occurred.

ELOOP

Too many symbolic links were encountered in translating the pathname in address.

ENAMETOOLONG

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

ENOENT

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

ENOTDIR

A component of the path prefix of the pathname 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_UNIX domain.

/* 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));