NetSock_Bind

Assign network addresses to sockets. Typically, server sockets bind to addresses but client sockets do not. Servers may bind to one of the local host’s addresses but usually bind to the wildcard address (e.g. NET_SOCK_ADDR_IP_V4_WILDCARD/INADDR_ANY) on a specific, well-known port number. Whereas client sockets usually bind to one of the local host’s addresses but with a random port number (by configuring the socket address structure’s port number field with a value of 0).

Files

net_sock.h/net_sock.c
net_bsd.h/net_bsd.c

Prototypes

          NET_SOCK_RTN_CODE NetSock_Bind(NET_SOCK_ID        sock_id,
                                         NET_SOCK_ADDR     *p_addr_local,
                                         NET_SOCK_ADDR_LEN  addr_len,
                                         NET_ERR           *p_err);
           
          int               bind        (       int         sock_id,
                                         struct sockaddr   *p_addr_local,
                                                socklen_t   addr_len);

Arguments

sock_id

This is the socket ID returned by NetSock_Open()/socket() when the socket was created.

p_addr_local

Pointer to a socket address structure (see section Network Sockets Concepts) which contains the local host address to bind the socket to.

addr_len

Size of the socket address structure which must be passed the size of the socket address structure [for example, sizeof(NET_SOCK_ADDR_IPv4)].

p_err

Pointer to variable that will receive the return error code from this function:

NET_SOCK_ERR_NONE
NET_SOCK_ERR_NOT_USED
NET_SOCK_ERR_CLOSED
NET_SOCK_ERR_INVALID_SOCK
NET_SOCK_ERR_INVALID_FAMILY
NET_SOCK_ERR_INVALID_PROTOCOL
NET_SOCK_ERR_INVALID_TYPE
NET_SOCK_ERR_INVALID_STATE
NET_SOCK_ERR_INVALID_OP
NET_SOCK_ERR_INVALID_ADDR
NET_SOCK_ERR_ADDR_IN_USE
NET_SOCK_ERR_PORT_NBR_NONE_AVAIL
NET_SOCK_ERR_CONN_FAIL
NET_IF_ERR_INVALID_IF
NET_IPv4_ERR_ADDR_NONE_AVAIL
NET_IPv4_ERR_ADDR_CFG_IN_PROGRESS
NET_IPv6_ERR_ADDR_NONE_AVAIL
NET_IPv6_ERR_ADDR_TBL_SIZE
NET_CONN_ERR_NOT_USED
NET_CONN_ERR_NONE_AVAIL
NET_CONN_ERR_INVALID_CONN
NET_CONN_ERR_INVALID_FAMILY
NET_CONN_ERR_INVALID_TYPE
NET_CONN_ERR_INVALID_PROTOCOL_IX
NET_CONN_ERR_INVALID_ADDR_LEN
NET_CONN_ERR_ADDR_NOT_USED
NET_CONN_ERR_ADDR_IN_USE
NET_INIT_ERR_NOT_COMPLETED
NET_ERR_FAULT_NULL_FNCT
NET_ERR_FAULT_LOCK_ACQUIRE

Returned Value

NET_SOCK_BSD_ERR_NONE/0

if successful;

NET_SOCK_BSD_ERR_BIND/-1

otherwise.

Required Configuration

None.

Notes / Warnings

See section Network Sockets Concepts for socket address structure formats.

Sockets may bind to any of the host’s configured addresses, any localhost address (loopback), any link-local address, as well as the wildcard address.

Sockets may bind to specific port numbers or request a random, ephemeral port number by configuring the socket address structure’s port number field with a value of 0. Sockets may not bind to a port number that is within the configured range of random port numbers. By default the base number for random port is 65000:

NET_SOCK_CFG_PORT_NBR_RANDOM_BASE <= RandomPortNbrs <=
(NET_SOCK_CFG_PORT_NBR_RANDOM_BASE + NET_SOCK_CFG_NBR_SOCK + 10)