bind Subroutine

Purpose

Binds a name to a socket.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>
int bind ( Socket,  Name,  NameLength)
int Socket;
const struct sockaddr *Name;
socklen_t NameLength;

Description

The bind subroutine assigns a Name parameter to an unnamed socket. Sockets created by the socket subroutine are unnamed; they are identified only by their address family. Subroutines that connect sockets either assign names or use unnamed sockets.

For a UNIX domain socket, a connect call only succeeds if the process that calls connect has read and write permissions on the socket file created by the bind call. Permissions are determined by the umask value of the process that created the file.

An application program can retrieve the assigned socket name with the getsockname subroutine.

The socket applications can be compiled with COMPAT_43 defined. This makes the sockaddr structure BSD 4.3 compatible. For more details refer to the socket.h file.

Binding a name in the UNIX domain creates a socket in the file system that must be deleted by the caller when it is no longer needed.

Note: When you enable IPv6 for an application, IPv4 addresses are also supported. You can use an AF_INET6 socket to send and receive both IPv4 and IPv6 packets because AF_INET6 sockets are capable of handling communication with both IPv4 and IPv6 hosts. However, you must convert the address format of the IPv4 addresses that were previously passed to the socket calls to the IPv4-mapped IPv6 address format. For example, you must convert 10.1.1.1 in the sockaddr_in structure to ::ffff:10.1.1.1 in the sockaddr_in6 structure.

Parameters

Item Description
Socket Specifies the socket descriptor (an integer) of the socket to be bound.
Name Points to an address structure that specifies the address to which the socket should be bound. The /usr/include/sys/socket.h file defines the sockaddr address structure. The sockaddr structure contains an identifier specific to the address format and protocol provided in the socket subroutine.
NameLength Specifies the length of the socket address structure.

Return Values

Upon successful completion, the bind subroutine returns a value of 0.

If the bind subroutine is unsuccessful, the subroutine handler performs the following actions:

  • Returns a value of -1 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable. For further explanation of the errno variable see "Error Notification Object Class" in Communications Programming Concepts.

Error Codes

The bind subroutine is unsuccessful if any of the following errors occurs:

Value Description
EACCES The requested address is protected, and the current user does not have permission to access it.
EADDRINUSE The specified address is already in use.
EADDRNOTAVAIL The specified address is not available from the local machine.
EAFNOSUPPORT The specified address is not a valid address for the address family of the specified socket.
EAGAIN The transient ports are already in use and are not available.
EBADF The Socket parameter is not valid.
EDESTADDRREQ The address argument is a null pointer.
EFAULT The Address parameter is not in a writable part of the UserAddress space.
EINVAL The socket is already bound to an address.
ENOBUF Insufficient buffer space available.
ENODEV The specified device does not exist.
ENOTSOCK The Socket parameter refers to a file, not a socket.
EOPNOTSUPP The socket referenced by Socket parameter does not support address binding.

Examples

The following program fragment illustrates the use of the bind subroutine to bind the name "/tmp/zan/" to a UNIX domain socket.

#include <sys/un.h>
.
.
.
struct sockaddr_un addr;
.
.
.
strcpy(addr.sun_path, "/tmp/zan/");
addr.sun_len = strlen(addr.sun_path);
addr.sun_family = AF_UNIX; 
bind(s,(struct sockaddr*)&addr, SUN_LEN(&addr));