BSD Socket interface

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

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.

Return values

The	number of bytes that were sent on success, or -1 on error.