BSD Socket interface

nRF5 SDK v16.0.0
Modules | Data Structures | Macros | Typedefs | Functions | Variables

Nordic socket interface for IoT. More...

Modules

Values for socket_family_t
Values for socket_type_t
Values for socket_protocol_t
Socket send/recv flags
Values for socket_opt_lvl_t
Medium socket option level types
fcntl commands
fcntl flags
API for file descriptor set

Data Structures

struct timeval
Structure specifying time interval. More...
struct sockaddr
Generic socket address. More...
struct in6_addr
IPv6 address. More...
struct in_addr
IPv4 address structure. More...
struct sockaddr_in6
Address record for IPv6 addresses. More...
struct sockaddr_in
Address record for IPv4 addresses. More...

Macros

#define htons (x) HTONS (x)
#define htonl (x) HTONL (x)
#define ntohs (x) NTOHS (x)
#define ntohl (x) NTOHL (x)

Typedefs

typedef int32_t ssize_t
typedef uint32_t socklen_t
Socket module size type.
typedef uint16_t in_port_t
Socket port type.
typedef int socket_family_t
Socket families. More...
typedef socket_family_t sa_family_t
typedef int socket_type_t
Socket types. More...
typedef int socket_protocol_t
Socket protocols. More...
typedef int socket_opt_lvl_t
Socket option levels. More...
typedef uint32_t in_addr_t
IPv4 address.
typedef struct sockaddr sockaddr_t
typedef struct sockaddr_in6 sockaddr_in6_t
typedef struct in6_addr in6_addr_t
typedef struct sockaddr_in sockaddr_in_t

Functions

int socket ( socket_family_t family, socket_type_t type, socket_protocol_t protocol)
Function for creating a socket. More...
int close (int sock)
Function for closing a socket and freeing any resources held by it. More...
int fcntl (int fd, int cmd, int flags)
Function for controlling file descriptor options. More...
int connect (int sock, const void *p_servaddr, socklen_t addrlen)
Function for connecting to an endpoint with a given address. More...
ssize_t send (int sock, const void *p_buff, size_t nbytes, int flags)
Function for sending data through a socket. More...
ssize_t sendto (int sock, const void *p_buff, size_t nbytes, int flags, const void *p_servaddr, socklen_t addrlen)
Function for sending datagram through a socket. More...
ssize_t write (int sock, const void *p_buff, size_t nbytes)
Function for writing data to a socket. See send() for details. More...
ssize_t recv (int sock, void *p_buff, size_t nbytes, int flags)
Function for receiving data on a socket. More...
ssize_t recvfrom (int sock, void *p_buff, size_t nbytes, int flags, void *p_cliaddr, socklen_t *p_addrlen)
Function for receiving datagram on a socket. More...
ssize_t read (int sock, void *p_buff, size_t nbytes)
Function for reading data from a socket. See recv() for details. More...
int select (int nfds, fd_set *p_readset, fd_set *p_writeset, fd_set *p_exceptset, const struct timeval *p_timeout)
Function for waiting for read, write, or exception events on a socket. More...
int setsockopt (int sock, socket_opt_lvl_t level, int optname, const void *p_optval, socklen_t optlen)
Function for setting socket options for a given socket. More...
int getsockopt (int sock, socket_opt_lvl_t level, int optname, void *p_optval, socklen_t *p_optlen)
Function for getting socket options for a given socket. More...
int bind (int sock, const void *p_myaddr, socklen_t addrlen)
Function for binding a socket to an address and port. More...
int listen (int sock, int backlog)
Function for marking a socket as listenable. More...
int accept (int sock, void *p_cliaddr, socklen_t *p_addrlen)
Function for waiting for the next client to connect. More...
int inet_pton ( socket_family_t af, const char *p_src, void *p_dst)
Function for converting a human-readable IP address to a form usable by the socket API. More...

Variables

struct in6_addr in6addr_any
Global IPv6 any-address.
struct in_addr inaddr_any
Global IPv4 any-address.

Detailed Description

Nordic socket interface for IoT.

This module provides the socket interface for writing IoT applications. The API is designed to be compatible with the POSIX/BSD socket interface for the purpose of making porting easy. The socket options API has been extended to support configuring Nordic BLE stack, tuning of RF parameters as well as security options.

Macro Definition Documentation

#define htonl ( x ) HTONL (x)

Convert byte order from host to network (long).

#define htons ( x ) HTONS (x)

Convert byte order from host to network (short).

#define ntohl ( x ) NTOHL (x)

Convert byte order from network to host (long).

#define ntohs ( x ) NTOHS (x)

Convert byte order from network to host (short).

Typedef Documentation

typedef int socket_family_t

Socket families.

For a list of valid values, refer to Values for socket_family_t .

typedef int socket_opt_lvl_t

Socket option levels.

For a list of valid values, refer to Values for socket_opt_lvl_t .

typedef int socket_protocol_t

Socket protocols.

Use 0 if you do not want do specify socket protocol, which should be sufficient for most users. Other values are only provided for socket API compatibility, see Values for socket_protocol_t .

typedef int socket_type_t

Socket types.

For a list of valid values refer to Values for socket_type_t .

Function Documentation

int accept ( int sock ,
void * p_cliaddr ,
socklen_t * p_addrlen
)

Function for waiting for the next client to connect.

This function will block if there are no clients attempting to connect.

Parameters
[in] sock The socket descriptor to use for waiting on client connections.
[out] p_cliaddr Socket address that will be set to the client's address.
[out] p_addrlen The size of the p_cliaddr passed. Might be modified by the function.
Returns
A non-negative client descriptor on success, or -1 on error.
int bind ( int sock ,
const void * p_myaddr ,
socklen_t addrlen
)

Function for binding a socket to an address and port.

The provided address must be supported by the socket protocol family.

Parameters
[in] sock The socket descriptor to bind.
[in] p_myaddr The address to bind this socket to.
[in] addrlen The size of p_myaddr.
Returns
0 on success, or -1 on error.
int close ( int sock )

Function for closing a socket and freeing any resources held by it.

If the socket is already closed, this function is a noop.

Parameters
[in] sock The socket to close.
Returns
0 on success, or -1 on error.
int connect ( int sock ,
const void * p_servaddr ,
socklen_t addrlen
)

Function for connecting to an endpoint with a given address.

The socket handle must be a valid handle that has not yet been connected. Running connect on a connected handle will return an error.

Parameters
[in] sock The socket to use for connection.
[in] p_servaddr The address of the server to connect to. Currently, sockaddr_in6 is the only supported type.
[in] addrlen The size of the p_servaddr argument.
Returns
0 on success, or -1 on error.
int fcntl ( int fd ,
int cmd ,
int flags
)

Function for controlling file descriptor options.

Set or get file descriptor options or flags. For a list of supported commands, refer to fcntl commands . For a list of supported flags, refer to fcntl flags .

Parameters
[in] fd The descriptor to set options on.
[in] cmd The command class for options.
[in] flags The flags to set.
int getsockopt ( int sock ,
socket_opt_lvl_t level ,
int optname ,
void * p_optval ,
socklen_t * p_optlen
)

Function for getting socket options for a given socket.

The options are grouped by level, and the option value is the value described by the option name.

Parameters
[in] sock The socket for which to set the option.
[in] level The level or group to which the option belongs.
[in] optname The name of the socket option.
[out] p_optval Pointer to the storage for the option value.
[in,out] p_optlen The size of p_optval. Can be modified to the actual size of p_optval.
Returns
0 on success, or -1 on error.
int inet_pton ( socket_family_t af ,
const char * p_src ,
void * p_dst
)

Function for converting a human-readable IP address to a form usable by the socket API.

This function will convert a string form of addresses and encode it into a byte array.

Parameters
[in] af Address family. Only AF_INET6 supported.
[in] p_src Null-terminated string containing the address to convert.
[out] p_dst Pointer to a struct in6_addr where the address will be stored.
Returns
1 on success, 0 if src does not contain a valid address, -1 if af is not a valid address family.
int listen ( int sock ,
int backlog
)

Function for marking a socket as listenable.

Once a socket is marked as listenable, it cannot be unmarked. It is important to consider the backlog parameter, as it will affect how much memory your application will use in the worst case.

Parameters
[in] sock The socket descriptor on which to set the listening options.
[in] backlog The max length of the queue of pending connections. A value of 0 means infinite.
Returns
0 on success, or -1 on error.
ssize_t read ( int sock ,
void * p_buff ,
size_t nbytes
)

Function for reading data from a socket. See recv() for details.

Parameters
[in] sock The socket to receive data from.
[out] p_buff Buffer to hold the data to be read.
[in] nbytes Number of bytes to read. Should not be larger than the size of p_buff.
Returns
The number of bytes that were read, or -1 on error.
ssize_t recv ( int sock ,
void * p_buff ,
size_t nbytes ,
int flags
)

Function for receiving data on a socket.

API for receiving data from a socket. By default, this function will block, unless the O_NONBLOCK socket option has been set, or MSG_DONTWAIT is passed as a flag.

Parameters
[in] sock The socket to receive data from.
[out] p_buff Buffer to hold the data to be read.
[in] nbytes Number of bytes to read. Should not be larger than the size of p_buff.
[in] flags Flags to control receive behavior.
Returns
The number of bytes that were read, or -1 on error.
ssize_t recvfrom ( int sock ,
void * p_buff ,
size_t nbytes ,
int flags ,
void * p_cliaddr ,
socklen_t * p_addrlen
)

Function for receiving datagram on a socket.

API for receiving data from a socket. By default, this function will block, unless the O_NONBLOCK socket option has been set, or MSG_DONTWAIT is passed as a flag.

Parameters
[in] sock The socket to receive data from.
[out] p_buff Buffer to hold the data to be read.
[in] nbytes Number of bytes to read. Should not be larger than the size of p_buff.
[in] flags Flags to control receive behavior.
[out] p_cliaddr Socket address that will be set to the client's address.
[in,out] p_addrlen The size of the p_cliaddr passed. Might be modified by the function.
Returns
The number of bytes that were read, or -1 on error.
int select ( int nfds ,
fd_set * p_readset ,
fd_set * p_writeset ,
fd_set * p_exceptset ,
const struct timeval * p_timeout
)

Function for waiting for read, write, or exception events on a socket.

Wait for a set of socket descriptors to be ready for reading, writing, or having exceptions. The set of socket descriptors is configured before calling this function. This function will block until any of the descriptors in the set has any of the required events. This function is mostly useful when using O_NONBLOCK or MSG_DONTWAIT options to enable async operation.

Parameters
[in] nfds The highest socket descriptor value contained in the sets.
[in,out] p_readset The set of descriptors for which to wait for read events. Set to NULL if not used.
[in,out] p_writeset The set of descriptors for which to wait for write events. Set to NULL if not used.
[in,out] p_exceptset The set of descriptors for which to wait for exception events. Set to NULL if not used.
[in] p_timeout The timeout to use for select call. Set to NULL if waiting forever.
Returns
The number of ready descriptors contained in the descriptor sets on success, or -1 on error.
ssize_t send ( int sock ,
const void * p_buff ,
size_t nbytes ,
int flags
)

Function for sending data through a socket.

By default, this function will block unless the O_NONBLOCK socket option has been set, OR MSG_DONTWAIT is passed as a flag. In that case, the method will return immediately.

Parameters
[in] sock The socket to write data to.
[in] p_buff Buffer containing the data to send.
[in] nbytes Size of data contained on p_buff.
[in] flags Flags to control send behavior.
Returns
The number of bytes that were sent on success, or -1 on error.
ssize_t sendto ( int sock ,
const void * p_buff ,
size_t nbytes ,
int flags ,
const void * p_servaddr ,
socklen_t addrlen
)

Function for sending datagram through a socket.

By default, this function will block if the lower layers are not able to process the packet, unless the O_NONBLOCK socket option has been set, OR MSG_DONTWAIT is passed as a flag. In that case, the method will return immediately.

Parameters
[in] sock The socket to write data to.
[in] p_buff Buffer containing the data to send.
[in] nbytes Size of data contained in p_buff.
[in] flags Flags to control send behavior.
[in] p_servaddr The address of the server to send to. Currently, sockaddr_in6 is the only supported type.
[in] addrlen The size of the p_servaddr argument.
Returns
The number of bytes that were sent on success, or -1 on error.
int setsockopt ( int sock ,
socket_opt_lvl_t level ,
int optname ,
const void * p_optval ,
socklen_t optlen
)

Function for setting socket options for a given socket.

The options are grouped by level, and the option value should be the expected for the given option, and the lifetime must be longer than that of the socket.

Parameters
[in] sock The socket for which to set the option.
[in] level The level or group to which the option belongs.
[in] optname The name of the socket option.
[in] p_optval The value to be stored for this option.
[in] optlen The size of p_optval.
Returns
0 on success, or -1 on error.
int socket ( socket_family_t family ,
socket_type_t type ,
socket_protocol_t protocol
)

Function for creating a socket.

API to create a socket that can be used for network communication independently of lower protocol layers.

Parameters
[in] family The protocol family of the network protocol to use. Currently, only AF_INET6 is supported.
[in] type The protocol type to use for this socket.
[in] protocol The transport protocol to use for this socket.
Returns
A non-negative socket descriptor on success, or -1 on error.
ssize_t write ( int sock ,
const void * p_buff ,
size_t nbytes
)

Function for writing data to a socket. See send() for details.

Parameters
[in] sock The socket to write data to.
[in] p_buff Buffer containing the data to send.
[in] nbytes Size of data contained in p_buff.
Returns
The number of bytes that were sent on success, or -1 on error.