bind()

The bind() socket call binds a local name to the socket. Rbind() binds a SOCKS local name to the socket. See Socket Secure Support for information about SOCKS.

Syntax

#include <types.h>
#include <sys\socket.h>
int bind(s, name, namelen)
int s;
struct sockaddr *name;
int namelen;

Parameters

Socket descriptor returned by a previous call to socket(). name

namelen

name

Description

The bind() call binds a unique local name to the socket with descriptor s. After calling socket(), a 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() procedure also allows servers to specify from which network interfaces they wish to receive UDP packets and TCP connection requests.

If s was created in the AF_INET domain, the format of the name buffer is expected to be sockaddr_in as defined in the header file <NETINET\IN.H>:

struct in_addr{
        u_long s_addr;
};
struct sockaddr_in
{
        u_char  sin_len;
        u_char  sin_family;
        u_short sin_port;
        struct  in_addr sin_addr;
        char    sin_zero[8];
};

The sin_len field is ignored. The sin_family field must be set to AF_INET. The sin_port field is set to the port that the application must bind to. It must be specified in network byte order. If sin_port is set to 0, the caller leaves it to the system to assign an available port. The application can call getsockname() to discover the port number assigned. The 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 that the host will bind to.

Subsequently, only UDP packets or TCP connection requests which match the bound name from this interface are routed to the socket. If sin_addr is set to the constant INADDR_ANY, as defined in <NETINET\IN.H>, the caller is requesting that the socket be bound to all network interfaces on the host. After this, UDP packets or TCP connections which match the bound name from all interfaces are routed to the socket. This becomes important when a server offers a service to multiple networks. By leaving the address unspecified, the server can accept all UDP packets or TCP connection requests made for its port, regardless of the network interface on which the requests arrived. The sin_zero field is not used and must be set to all zeros.

In the NetBIOS (AF_NET) domain, set all 16 characters in snb_name in the sockaddr_nb structure to binary zeros (null). The system will generate a name for the socket.

Return Values

The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling sock_errno() or psock_errno().

Error Code

Description

SOCEADDRINUSE

getsockopt ( )

setsockopt ( )

SOCEADDRNOTAVAIL

Theaddressspecifiedisnotvalidonthishost . Forexample ,theinternetaddressdoesnotspecifyavalidnetworkinterface . SOCEAFNOSUPPORT

Theaddressfamilyisnotsupported . SOCENOTSOCK

SOCEFAULT

name

namelen

SOCEINVAL

namelen

SOCENOBUFS

Nobufferspaceisavailable .

Examples

Note the following about the bind() call examples:

For the internet examples, put the internet address and port in network-byte order. To put the port into network-byte order, use the htons() utility routine to convert a short integer from host-byte order to network-byte order.
For the internet examples, set the address field using the inet_addr() utility routine, which takes a character string representing the dotted-decimal address of an interface and returns the binary internet address representation in network-byte order.
Zero the structure before using it to ensure that the name requested does not set any reserved fields.

See connect() for examples of how a client might connect to servers.

int rc;int s;
struct sockaddr_in myname;
int bind(int s, struct sockaddr *name, int namelen); /* extracted from sys/socket.h */
/* Bind to a specific interface in the internet domain */
/* clear the structure */
memset(&myname, 0, sizeof(myname));
myname.sin_len = sizeof(myname);
myname.sin_family = AF_INET;
myname.sin_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 internet network interfaces on the system */
/* clear the structure */
memset(&myname, 0, sizeof(myname));
myname.sin_len = sizeof(myname);
myname.sin_family = AF_INET;
myname.sin_addr.s_addr = INADDR_ANY; /* all interfaces */
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                        */
/* clear the structure */
memset(&myname, 0, sizeof(myname));
myname.sin_len = sizeof(myname);
myname.sin_family = AF_INET;
myname.sin_addr = inet_addr("129.5.24.1"); /* specific interface */
myname.sin_port = 0;
...
rc = bind(s, (struct sockaddr *) &myname, sizeof(myname));

/* Bind to a unique NetBIOS name on adapter 0 */
struct sockaddr_nb nbname;
memset(&nbname, 0, sizeof(nbname));
nbname.sin_len = sizeof(nbname);
nbname.snb_family = AF_NB;
nbname.snb_type = NB_UNIQUE;
nbname.snb_adapter = 0;
strcpy(nbname.snb_name, "NBSERVER"); /* Note that a NetBIOS name is
                                        16 bytes long.  In this example,
                                        the last 8 bytes are filled
                                        with zeros.                    */

...
rc = bind(s, (struct sockaddr *) &nbname, sizeof(nbname));

[Back: addsockettolist()]
[Next: connect()]