BSD Sockets#

This section provides a reference to BSD Socket API functions.

The BSD socket implementation tries to emulate the standards library to the extent possible for embedded offerings from Silabs. There are substantial limitation/exceptions however, and those are mentioned in the subsequent documentation of BSD sockets.

Note

  • sl_si91x_get_saved_firmware_status() needs to be called to get to know error code returned by firmware in case when API returns -1 and errno being 0.

Modules#

sockaddr

Socket Type

Socket Option Name

Socket Option Level

Socket Address Family

Socket Protocol

Typedefs#

typedef uint32_t

Socket Length is internal type.

typedef __socklen_t

Public type for socket length.

typedef uint8_t

Internal type for sockaddr address family.

Public type for sockaddr address family.

Functions#

int
socket(int domain, int type, int protocol)

Create an endpoint for communication.

int
bind(int socket_id, const struct sockaddr *addr, socklen_t addr_len)

Bind a name to a socket.

int
listen(int socket_id, int backlog)

Listen for connections on a socket.

int
accept(int socket_id, struct sockaddr *addr, socklen_t *addr_len)

Accept a connection on a socket.

int
connect(int socket_id, const struct sockaddr *addr, socklen_t addr_len)

Initiate a connection on a socket.

ssize_t
recv(int socket_id, void *buf, size_t buf_len, int flags)

Receive a message from a socket.

ssize_t
recvfrom(int socket_id, void *buf, size_t buf_len, int flags, struct sockaddr *from_addr, socklen_t *from_addr_len)

Receive a message from a socket.

ssize_t
send(int socket_id, const void *buf, size_t buf_len, int flags)

Send a message on a socket.

ssize_t
sendto(int socket_id, const void *buf, size_t buf_len, int flags, const struct sockaddr *to_addr, socklen_t to_addr_len)

Send a message on a socket.

int
setsockopt(int socket_id, int option_level, int option_name, const void *option_value, socklen_t option_length)

Set options on a socket.

int
getsockopt(int socket_id, int option_level, int option_name, void *option_value, socklen_t *option_length)

Get options on a socket.

int
getpeername(int socket_id, struct sockaddr *name, socklen_t *name_len)

Get the name of the connected peer socket.

int
getsockname(int socket_id, struct sockaddr *name, socklen_t *name_len)

Get the current address assigned to a socket.

int
close(int socket_id)

Close a socket.

Typedef Documentation#

__socklen_t#

__socklen_t

Socket Length is internal type.

It represents the length of a socket address that is used internally within network system calls to specify the size of address structures.


Definition at line 56 of file components/service/bsd_socket/inc/netinet_in.h

socklen_t#

socklen_t

Public type for socket length.

It is a public alias for the internal __socklen_t type.You can use it to specify the length of socket addresses in the network system calls.


Definition at line 65 of file components/service/bsd_socket/inc/netinet_in.h

__sa_family_t#

__sa_family_t

Internal type for sockaddr address family.

The address family of a socket address is used internally within the system to specify the address type. (for example, IPv4 and IPv6).


Definition at line 93 of file components/service/bsd_socket/inc/netinet_in.h

sa_family_t#

sa_family_t

Public type for sockaddr address family.

It is a public alias for the internal ___sa_family_t. It specifies the address family of a socket address in user applications.


Definition at line 102 of file components/service/bsd_socket/inc/netinet_in.h

Function Documentation#

socket#

int socket (int domain, int type, int protocol)

Create an endpoint for communication.

Parameters
[in]domain

Specifies a communication domain, selecting the protocol family to be used for communication. Must be one of the values from Socket Address Family.

[in]type

Specifies the semantics of communication for the socket. Must be one of the values from BSD_SOCKET_TYPES. Currently defined types are SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, SOCK_RDM, and SOCK_SEQPACKET.

[in]protocol

Specifies a particular protocol to be used with the socket. Normally, only a single protocol exists to support a particular socket type within a given protocol family. However, if multiple protocols exist, a specific protocol must be specified. The protocol number to use is specific to the communication domain. Must be one of the values from Socket Protocol.

The socket() function creates an endpoint for communication and returns a file descriptor that refers to that endpoint. The file descriptor returned by a successful call would be the lowest-numbered file descriptor not currently open for the process.

Returns

  • Returns a descriptor referencing the socket if successful. Returns -1 if an error occurs.


Definition at line 648 of file components/service/bsd_socket/inc/socket.h

bind#

int bind (int socket_id, const struct sockaddr * addr, socklen_t addr_len)

Bind a name to a socket.

Parameters
[in]socket_id

Socket identification number.

[in]addr

Pointer to a sockaddr structure containing the address to be assigned to the socket.

[in]addr_len

The addr_len parameter specifies the size, in bytes, of the address structure pointed to by addr.

When a socket is created with socket(), it exists in a namespace (address family) but, has no address assigned to it. The bind() function assigns the address specified by addr to the socket referred to by the file descriptor socket_id.
Traditionally, this operation is called "assigning a name to a socket".

It is normally necessary to assign a local address using bind() before a SOCK_STREAM socket may receive connections.

Returns

  • Returns 0 if successful. Otherwise, returns -1 and sets the global variable errno to indicate the error.


Definition at line 674 of file components/service/bsd_socket/inc/socket.h

listen#

int listen (int socket_id, int backlog)

Listen for connections on a socket.

Parameters
[in]socket_id

Socket identification number.

[in]backlog

The backlog argument defines the maximum number of pending connections that can be queued.

The listen() function marks the socket referred to by socket_id as a passive socket, that is, as a socket that would be used to accept incoming connection requests using accept(). This function applies only to sockets of type SOCK_STREAM or SOCK_SEQPACKET.

  • To accept connections, a socket must first be created with socket(). A willingness to accept incoming connections and a queue limit for incoming connections must be specified with listen(), and then the connections can be accepted with accept().

Returns

  • Returns 0 if successful. Otherwise, returns -1 and sets the global variable errno to indicate the error.


Definition at line 700 of file components/service/bsd_socket/inc/socket.h

accept#

int accept (int socket_id, struct sockaddr * addr, socklen_t * addr_len)

Accept a connection on a socket.

Parameters
[in]socket_id

Socket identification number of the socket to accept. This socket must have been created with socket(), bound to an address with bind(), and set to listen for connections with listen().

[out]addr

Pointer to a sockaddr structure that will be filled with the address of the connecting entity, as known to the communications layer. The exact format of the addr argument is determined by the domain in which the communication is occurring. A null pointer may be specified for addr if the address information is not desired; in this case, addr_len is not used and should also be null.

[inout]addr_len

Pointer to a socklen_t variable. Initially, it should contain the amount of space pointed to by addr. On return, it will contain the actual length (in bytes) of the address returned. This call is used with connection-based socket types, currently with SOCK_STREAM.

The accept() system call is used with connection-based socket types (for example, SOCK_STREAM, SOCK_SEQPACKET). It extracts the first connection request on the queue of pending connections for the listening socket (socket_id), creates a new connected socket, and returns a new file descriptor referring to that socket. The newly created socket is not in the listening state. The original socket (socket_id) is unaffected by this call.

If no pending connections are present on the queue and the original socket is not marked as non-blocking, this function blocks the caller until a connection is present. If the original socket is marked non-blocking and no pending connections are present on the queue, accept() returns an error. The accepted socket may not be used to accept more connections. The original socket (socket_id) remains open.

Returns

  • Returns a non-negative integer that is a descriptor for the accepted socket if successful. Returns -1 on error and sets the global variable errno to indicate the error.

Note

  • The accept() system call only supports blocking mode.


Definition at line 740 of file components/service/bsd_socket/inc/socket.h

connect#

int connect (int socket_id, const struct sockaddr * addr, socklen_t addr_len)

Initiate a connection on a socket.

Parameters
[in]socket_id

The socket identification number.

[in]addr

The addr argument of type sockaddr is the address is that to which datagrams are to be sent.

[in]addr_len

The addr_len argument of type socklen_t indicates the amount of space pointed to by addr, in bytes.

The connect() system call connects the socket referred to by the file descriptor socket_id to the address specified by addr.
The addr_len argument specifies the size of addr. The format of the address in addr is determined by the address space of the socket socket_id; see socket() for further details.

If socket_id is of type SOCK_DGRAM, the connect() system call specifies the peer with which the socket is to be associated. If the socket is of type SOCK_STREAM, the connect() system call attempts to make a connection to another socket. The other socket is specified by addr, which is an address in the communications space of the socket. Each communications space interprets the addr argument in its own way. Generally, stream sockets may successfully connect() only once; datagram sockets can use connect() multiple times to change their association.

Returns

  • Returns 0 if successful. Otherwise, returns -1 and sets the global variable errno to indicate the error.

Note

  • Connecting to an invalid address, such as a null address, will result in an EFAULT error.


Definition at line 773 of file components/service/bsd_socket/inc/socket.h

recv#

ssize_t recv (int socket_id, void * buf, size_t buf_len, int flags)

Receive a message from a socket.

Parameters
[in]socket_id

Socket identification number.

[out]buf

Pointer to the buffer that receives the data.

[in]buf_len

Length of the buffer pointed to by the buf parameter.

[in]flags

Controls the reception of the data. Currently, no flags are supported and this parameter should be set to 0.

The recv() function is normally used only on a connected socket. It receives messages from a socket and returns the length of the message on successful completion. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from. By default, recv() is a blocking API. To use it in a non-blocking manner, you can set the socket to non-blocking mode using setsockopt().

Returns

  • ssize_t

Note

  • The recv() system call does not support any flags.


Definition at line 803 of file components/service/bsd_socket/inc/socket.h

recvfrom#

ssize_t recvfrom (int socket_id, void * buf, size_t buf_len, int flags, struct sockaddr * from_addr, socklen_t * from_addr_len)

Receive a message from a socket.

Parameters
[in]socket_id

The socket identification number.

[out]buf

Pointer to the buffer that receives the data.

[in]buf_len

The length of the buffer pointed to by the buf parameter, in bytes.

[in]flags

Controls the reception of the data. Currently, no flags are supported and this parameter should be set to 0.

[out]from_addr

Pointer to a socket address structure of type sockaddr that will be filled with the source address of the received message. If the source address is not required, this parameter can be NULL.

[inout]from_addr_len

A value-result argument of type socklen_t. Initially, it should contain the size of the buffer associated with from_addr. On return, it will be modified to indicate the actual size of the address stored there. If from_addr is NULL, this parameter is ignored.

The recvfrom() system call is used to receive messages from a socket and can be used to receive data on a socket whether or not it is connection-oriented. If from_addr is not a null pointer and the socket is not connection-oriented, the source address of the message is filled in.

Returns

  • Returns the length of the message on successful completion. Returns -1 on error and sets the global variable errno to indicate the error.

Note

  • The recvfrom() system call does not support any flags.


Definition at line 841 of file components/service/bsd_socket/inc/socket.h

send#

ssize_t send (int socket_id, const void * buf, size_t buf_len, int flags)

Send a message on a socket.

Parameters
[in]socket_id

The socket identification number.

[in]buf

Pointer to the buffer containing the message to transmit.

[in]buf_len

The length of the message in bytes.

[in]flags

Controls the transmission of the data. Currently, no flags are supported and this parameter should be set to 0.

The send() function is used to transmit a message on a socket. This function can only be used when the socket is in a connected state. If the socket is connection-oriented, the protocol must support implied connect or the socket must be explicitly connected before use. No indication of failure to deliver is implicit in a send(). Locally detected errors are indicated by a return value of -1. If no message space is available at the socket to hold the message to be transmitted, then send() normally blocks, unless the socket has been placed in non-blocking I/O mode.

Returns

  • Returns the number of bytes sent on success. Returns -1 on error and sets the global variable errno to indicate the error.

Note

    • The send() system call currently supports only blocking mode.

    • The send() system call does not guarantee that the packets are transmitted to the remote node; they are enqueued in the local queue.

    • The send() system call does not support any flags.

    • The send() system call can send a maximum of 1460 bytes in the case of plain TCP/UDP. For TLS, the maximum buffer length is 1370 bytes.


Definition at line 876 of file components/service/bsd_socket/inc/socket.h

sendto#

ssize_t sendto (int socket_id, const void * buf, size_t buf_len, int flags, const struct sockaddr * to_addr, socklen_t to_addr_len)

Send a message on a socket.

Parameters
[in]socket_id

The socket identification number.

[in]buf

Pointer to the buffer containing the message to transmit.

[in]buf_len

The length of the message in bytes.

[in]flags

Controls the transmission of the data. Due to firmware limitations, sendto() does not support any flags and this parameter should be set to 0.

[in]to_addr

Pointer to a sockaddr structure containing the address of the target.

[in]to_addr_len

Size of the address structure pointed to by to_addr, in bytes.

The sendto() function is used to transmit a message on a socket. This function can be used at any time if the socket is in connectionless mode. If the socket is in connection mode, the protocol must support implied connect or the socket must be in a connected state before use. The address of the target is specified by to_addr with to_addr_len indicating its size. If the socket is in a connected state, the target address passed to sendto() is ignored. If the message is too long to pass atomically through the protocol, the error EMSGSIZE is returned, and the message is not transmitted.

Returns

  • The number of octets sent. If an error occurred, a value of -1 is returned.

Note

    • The sendto() system call can only send a maximum of 1460 bytes in the case of plain TCP/UDP. For TLS, the maximum buffer length is 1370 bytes.

    • The sendto() system call does not support any flags.


Definition at line 915 of file components/service/bsd_socket/inc/socket.h

setsockopt#

int setsockopt (int socket_id, int option_level, int option_name, const void * option_value, socklen_t option_length)

Set options on a socket.

Parameters
[in]socket_id

The socket identification number.

[in]option_level

The level at which the option is being set. One of the values from Socket Option Level.

[in]option_name

The name of the option to set. One of the values from Socket Option Name. The option_name argument and any specified options are passed uninterpreted to the appropriate protocol module for interpretation.

[in]option_value

A pointer to the buffer containing the value for the option. Most socket-level options utilize an int argument for option_value. For setsockopt(), the argument should be non-zero to enable a boolean option, or zero if the option is to be disabled.

[in]option_length

The length of the option data, in bytes, pointed to by option_value.

The setsockopt() system call manipulates the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost "socket" level. When manipulating socket options, the level at which the option resides and the name of the option must be specified. To manipulate options at the socket level, option_level is specified as SOL_SOCKET. To manipulate options at any other level, the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, option_level should be set to the protocol number of TCP. The option_value and option_length arguments are used to access option values for setsockopt().

Returns

  • Returns 0 on successful completion. Returns -1 on error and sets the global variable errno to indicate the error.

Note

  • The following options are currently supported:

    • SO_RCVTIMEO: Receive timeout.

    • SO_KEEPALIVE: Keep connections alive.

    • TCP_ULP: TCP upper layer protocol.

    • SO_MAX_RETRANSMISSION_TIMEOUT_VALUE: Maximum retransmission timeout value.

    • IP_TOS: Type of service.


Definition at line 958 of file components/service/bsd_socket/inc/socket.h

getsockopt#

int getsockopt (int socket_id, int option_level, int option_name, void * option_value, socklen_t * option_length)

Get options on a socket.

Parameters
[in]socket_id

The socket identification number.

[in]option_level

The level at which the option is defined. One of the values from Socket Option Level.

[in]option_name

The name of the option to retrieve. One of the values from Socket Option Name. The option_name argument and any specified options are passed uninterpreted to the appropriate protocol module for interpretation.

[out]option_value

Pointer to a buffer where the retrieved option value will be stored.

[inout]option_length

A value-result argument of type socklen_t. Initially, it should contain the size of the buffer pointed to by option_value. On return, it will be modified to indicate the actual size of the value returned. If no option value is to be supplied or returned, option_value may be NULL.

The getsockopt() system call retrieves the options associated with a socket. Options may exist at multiple protocol levels; they are always present at the uppermost "socket" level. When retrieving socket options, the level at which the option resides and the name of the option must be specified. To retrieve options at the socket level, option_level is specified as SOL_SOCKET. To retrieve options at any other level, the protocol number of the appropriate protocol controlling the option is supplied. For example, to indicate that an option is to be interpreted by the TCP protocol, option_level should be set to the protocol number of TCP. The option_value and option_length arguments identify a buffer in which the value for the requested options are to be returned.

Returns

  • Returns 0 on successful completion. Returns -1 on error and sets the global variable errno to indicate the error.

Note

  • The following options are currently supported:

    • SO_RCVTIMEO: Receive timeout.

    • SO_KEEPALIVE: Keep connections alive.

    • TCP_ULP: TCP upper layer protocol.

    • SO_MAX_RETRANSMISSION_TIMEOUT_VALUE: Maximum retransmission timeout value.

    • IP_TOS: Type of service.


Definition at line 1002 of file components/service/bsd_socket/inc/socket.h

getpeername#

int getpeername (int socket_id, struct sockaddr * name, socklen_t * name_len)

Get the name of the connected peer socket.

Parameters
[in]socket_id

The socket identification number.

[out]name

Pointer to a sockaddr structure that will be filled with the address of the peer socket.

[inout]name_len

A value-result argument of type socklen_t. Initially, it should contain the size of the buffer pointed to by name. On return, it will be modified to indicate the actual size of the address returned (in bytes).

The getpeername() system call returns the address of the peer connected to the socket specified by socket_id. The address is returned in the buffer pointed to by name, and the actual size of the address is returned in the variable pointed to by name_len. If the buffer provided is too small, the address is truncated.

Returns

  • Returns 0 on success. Returns -1 on error and sets the global variable errno to indicate the error.


Definition at line 1027 of file components/service/bsd_socket/inc/socket.h

getsockname#

int getsockname (int socket_id, struct sockaddr * name, socklen_t * name_len)

Get the current address assigned to a socket.

Parameters
[in]socket_id

The socket identification number.

[out]name

Pointer to a sockaddr structure that will be filled with the address of the socket.

[inout]name_len

A value-result argument of type socklen_t. Initially, it should contain the size of the buffer pointed to by name. On return, it will be modified to indicate the actual size of the address returned (in bytes).

The getsockname() system call returns the current address to which the socket socket_id is bound. The address is returned in the buffer pointed to by name, and the actual size of the address is returned in the variable pointed to by name_len. If the buffer provided is too small, the address is truncated.

Returns

  • Returns 0 on success. Returns -1 on error and sets the global variable errno to indicate the error.


Definition at line 1052 of file components/service/bsd_socket/inc/socket.h

close#

int close (int socket_id)

Close a socket.

Parameters
[in]socket_id

The socket identification number.

The close() function closes a socket identified by socket_id, so that it no longer refers to any file and can be reused. This function releases the resources associated with the socket and makes the socket descriptor available for reuse.

Returns

  • Returns 0 on success. Returns -1 on error and sets the global variable errno to indicate the error.

Note

    • Calling close() on a server socket or the first client socket will close all associated sockets.

    • If close() is called on a non-existing socket, the error EBADF (Bad file descriptor) will be set in errno.


Definition at line 1073 of file components/service/bsd_socket/inc/socket.h