BSD Sockets#

__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.

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.

__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).

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.

socket#

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

Create an endpoint for communication.

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 the socket ID or file descriptor that references the socket upon success. Returns -1 if an error occurs.

Note

• The type supports SOCK_STREAM and SOCK_DGRAM only.

bind#

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

Bind a name to a socket.

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.

listen#

int listen (int socket_id, int backlog)

Listen for connections on a socket.

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.

accept#

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

Accept a connection on a socket.

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.

connect#

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

Initiate a connection on a socket.

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.

recv#

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

Receive a message from a socket.

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.

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.

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.

send#

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

Send a message on a socket.

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.

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.

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.

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.

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, one of the supported values from TOS Defines (Values 0-7 are deprecated).

  • SL_SO_CERT_INDEX: Set the certificate index for the socket.

  • SL_SO_HIGH_PERFORMANCE_SOCKET: Set the high-performance socket option for the socket.

  • SL_SO_TLS_SNI: Set the server name indication for the socket.

  • SL_SO_TLS_ALPN: Set the application layer protocol negotiation for the socket. The options SL_SO_CERT_INDEX, SL_SO_HIGH_PERFORMANCE_SOCKET, SL_SO_TLS_SNI, and SL_SO_TLS_ALPN are Silicon Labs specific options. This function is used before the socket is connected.

getsockopt#

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

Get options on a socket.

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.

getpeername#

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

Get the name of the connected peer socket.

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.

getsockname#

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

Get the current address assigned to a socket.

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.

close#

int close (int socket_id)

Close a socket.

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.