bind

Table of Contents >> Programmer's Reference

#include <trsocket.h>

int bind	(
	int listenSocketDescriptor,
	const struct sockaddr * localAddressPtr,
	int localAddressLength
	);

Function Description

bind() assigns an address to an unnamed socket. When a socket is created with socket(), it exists in an address family space but has no address assigned. bind() requests that the address pointed to by addressPtr be assigned to the socket. Clients do not normally require that an address be assigned to a socket. However, servers usually require that the socket be bound to a well known address.

The port number should be less than 32768 to avoid a potential conflict with unbound sockets that are assigned random port numbers above this value. Bind to port TM_WILD_PORT (0xFFFF) to receive UDP packets or incoming TCP or SCTP connection requests on any port.

Set the IP address field of localAddressPtr to all zeros to receive UDP packets or incoming TCP or SCTP connection requests on any local IP address.

If you are using a dual-mode stack (compile time macros TM_USE_IPV4 and TM_USE_IPV6 are defined) then, by default, sockets bound to an IPv6 address will also receive UDP packets or incoming TCP or SCTP connection requests from IPv4 peers. To restrict your socket to IPv6 traffic only, enable the setsockopt() IPV6_V6ONLY option prior to calling bind().

Multiple sockets can bind to the same port with different IP addresses if you uncomment the following compile time macro in trsystem.h and you enable the setsockopt() SO_REUSEADDR option on all sockets that share the same port (technically, you don't have to use SO_REUSEADDR on the first bound socket).

#define TM_USE_REUSEADDR_LIST

Multiple sockets can bind to the same port and the same IP address on different interfaces if you uncomment the following compile time macro in trsystem.h and you enable the setsockopt() SO_REUSEPORT option on all sockets that share the same port.

#define TM_USE_REUSEPORT

Sockets that share the same port (and, perhaps, IP address) can be bound to different interfaces if you uncomment the following compile time macro in trsystem.h and you set the setsockopt() SO_BINDTODEVICE option on all sockets that share the same port. Set the device binding on a socket prior to calling bind() to avoid a possible TM_EADDRINUSE error. See Appendix C: Strong End System Model / Weak End System Model for further details.

#define TM_USE_STRONG_ESL

Parameters

• listenSocketDescriptor

  The socket descriptor to assign an IP address and port number to.

• localAddressPtr

  The pointer to the structure containing the address to assign.

• localAddressLength

  The length of the address structure.

Returns

• TM_ENOERROR

  Success

• TM_SOCKET_ERROR

  Failure

Note:

TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself. To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).

Possible socket errors

• TM_EADDRINUSE

  The specified address is already in use.

• TM_EBADF

  The socket descriptor is invalid.

• TM_EINVAL

  One of the following:

• listenSocketDescriptor is 0.
• localAddressPtr is 0.
• *localAddressLength is too small.
• The socket is already bound.

Table of Contents >> Programmer's Reference