bind (Windows Sockets)

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function associates a local address with a socket.

Syntax

int bind(
  SOCKET s,
  const struct sockaddr FAR* name,
  int namelen
);

Parameters

s
[in] Descriptor identifying an unbound socket.

name
[in] Address to assign to the socket from the sockaddr structure.

namelen
[in] Length of the value in the name parameter.

Return Value

If no error occurs, this function returns zero. If an error occurs, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

Remarks

This function is used on an unconnected socket before subsequent calls to the connect (Windows Sockets) or listen function. The bind function is used to bind to either connection-oriented (stream) or connectionless (datagram) sockets. When a socket is created with a call to the socket (Windows Sockets) function, it exists in a name space (address family) but has no name assigned to it. Use the bind function to establish the local association of the socket by assigning a local name to an unnamed socket.

A name consists of the three parts when using the Internet address family. The following list shows these parts:

The address family
A host address
A port number

In Winsock 2.2, the name parameter is not strictly interpreted as a pointer to a sockaddr structure. It is cast this way for Winsock 1.1 compatibility. Service providers are free to regard it as a pointer to a block of memory of size namelen. The first 2 bytes in this block (corresponding to the sa_family member of the sockaddr structure) must contain the address family that was used to create the socket. Otherwise, an error WSAEFAULT occurs.

If an application does not care what local address is assigned, specify the manifest constant value ADDR_ANY for the sa_data member of the name parameter. This allows the underlying service provider to use any appropriate network address, potentially simplifying application programming in the presence of multihomed hosts (that is, hosts that have more than one network interface and address).

For TCP/IP, if the port is specified as 0, the service provider assigns a unique port to the application with a value between 49152 and 65535. The application can use getsockname (Windows Sockets) after calling bind to learn the address and the port that has been assigned to it. If the Internet address is equal to INADDR_ANY, getsockname cannot necessarily supply the address until the socket is connected because several addresses can be valid if the host is multihomed. Binding to a specific port number other than port 0 is discouraged for client applications because there is a danger of conflicting with another socket already using that port number.

Notes for IrDA Sockets

The SOCKADDR_IRDAstructure is used in the addr parameter.
There is no wildcard address equivalent to INADDR_ANY.
The Af_irda.h header file must be explicitly included.
Local names are not exposed in IrDA. IrDA client sockets therefore must never call the bind function before the connect (Windows Sockets) function. If the IrDA socket was previously bound to a service name using bind, the connect function will fail with SOCKET_ERROR.

For more inforamtion about IrDA support in Windows Embedded CE, see Infrared Communications.

The following table shows a list of possible error codes.

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEACCES	An attempt was made to access a socket in a way forbidden by its access permissions. An example is using a broadcast address for sendto without broadcast permission being set using setsockopt (Windows Sockets).
WSAEADDRINUSE	A process on the machine is already bound to the same fully qualified address and the socket has not been marked to allow address reuse with SO_REUSEADDR. For example, the IP address and port are bound in the af_inet case. (See the SO_REUSEADDR socket option under setsockopt (Windows Sockets).)
WSAEADDRNOTAVAIL	The specified address is not a valid address for this machine.
WSAEFAULT	The name or namelen parameter is not a valid part of the user address space, the namelen parameter is too small, the name parameter contains an incorrect address format for the associated address family, or the first two bytes of the memory block specified by name do not match the address family associated with the socket descriptor s.
WSAEINPROGRESS	A blocking Winsock call is in progress, or the service provider is still processing a callback function.
WSAEINVAL	The socket is already bound to an address.
WSAENOBUFS	Not enough buffers available; too many connections.
WSAENOTSOCK	The descriptor is not a socket.

Notes for Bluetooth Sockets

The ws2bth.h header file must be explicitly included.
If the port is set to 0, the server channel identifier is automatically allocated. Use getsockname (Windows Sockets) to retrieve it.
The bind function does not register service in the SDP database. The application program is responsible for doing that.

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later