TCP socket abstraction layer. More...

Data Structures
struct	spdk_sock_request
	Anywhere this struct is used, an iovec array is assumed to immediately follow the last member in memory, without any padding. More...

struct	spdk_sock_request::__sock_request_internal
	These fields are used by the socket layer and should not be modified. More...

struct	spdk_sock_impl_opts
	SPDK socket implementation options. More...

struct	spdk_sock_opts
	Spdk socket initialization options. More...

Macros
#define	SPDK_SOCK_REQUEST_IOV(req, i) ((struct iovec )(((uint8_t )req + sizeof(struct spdk_sock_request)) + (sizeof(struct iovec) * i)))

#define	SPDK_TLS_VERSION_1_1 11

#define	SPDK_TLS_VERSION_1_2 12

#define	SPDK_TLS_VERSION_1_3 13

#define	SPDK_SOCK_GROUP_REGISTER_INTERRUPT(sock, events, fn, arg) spdk_sock_group_register_interrupt(sock, events, fn, arg, #fn)

Typedefs
typedef void(*	spdk_sock_cb) (void arg, struct spdk_sock_group group, struct spdk_sock *sock)
	Callback function for spdk_sock_group_add_sock().

Enumerations
enum	spdk_placement_mode { PLACEMENT_NONE , PLACEMENT_NAPI , PLACEMENT_CPU , PLACEMENT_MARK }

Functions
	SPDK_STATIC_ASSERT (sizeof(struct spdk_sock_opts)==56, "Incorrect size")

void	spdk_sock_get_default_opts (struct spdk_sock_opts *opts)
	Initialize the default value of opts.

int	spdk_sock_getaddr (struct spdk_sock sock, char saddr, int slen, uint16_t sport, char caddr, int clen, uint16_t *cport)
	Get client and server addresses of the given socket.

const char *	spdk_sock_get_impl_name (struct spdk_sock *sock)
	Get socket implementation name.

struct spdk_sock *	spdk_sock_connect (const char ip, int port, const char impl_name)
	Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.

struct spdk_sock *	spdk_sock_connect_ext (const char ip, int port, const char impl_name, struct spdk_sock_opts *opts)
	Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.

struct spdk_sock *	spdk_sock_listen (const char ip, int port, const char impl_name)
	Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.

struct spdk_sock *	spdk_sock_listen_ext (const char ip, int port, const char impl_name, struct spdk_sock_opts *opts)
	Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.

struct spdk_sock *	spdk_sock_accept (struct spdk_sock *sock)
	Accept a new connection from a client on the specified socket and return a socket structure which holds the connection.

const char *	spdk_sock_get_interface_name (struct spdk_sock *sock)
	Gets the name of the network interface of the local port for the socket.

int32_t	spdk_sock_get_numa_id (struct spdk_sock *sock)
	Gets the NUMA node ID for the network interface of the local port for the TCP socket.

int	spdk_sock_close (struct spdk_sock **sock)
	Close a socket.

int	spdk_sock_flush (struct spdk_sock *sock)
	Flush a socket from data gathered in previous writev_async calls.

ssize_t	spdk_sock_recv (struct spdk_sock sock, void buf, size_t len)
	Receive a message from the given socket.

ssize_t	spdk_sock_writev (struct spdk_sock sock, struct iovec iov, int iovcnt)
	Write message to the given socket from the I/O vector array.

void	spdk_sock_writev_async (struct spdk_sock sock, struct spdk_sock_request req)
	Write data to the given socket asynchronously, calling the provided callback when the data has been written.

ssize_t	spdk_sock_readv (struct spdk_sock sock, struct iovec iov, int iovcnt)
	Read message from the given socket to the I/O vector array.

int	spdk_sock_recv_next (struct spdk_sock sock, void buf, void *ctx)
	Receive the next portion of the stream from the socket.

int	spdk_sock_set_recvlowat (struct spdk_sock *sock, int nbytes)
	Set the value used to specify the low water mark (in bytes) for this socket.

int	spdk_sock_set_recvbuf (struct spdk_sock *sock, int sz)
	Set receive buffer size for the given socket.

int	spdk_sock_set_sendbuf (struct spdk_sock *sock, int sz)
	Set send buffer size for the given socket.

bool	spdk_sock_is_ipv6 (struct spdk_sock *sock)
	Check whether the address of socket is ipv6.

bool	spdk_sock_is_ipv4 (struct spdk_sock *sock)
	Check whether the address of socket is ipv4.

bool	spdk_sock_is_connected (struct spdk_sock *sock)
	Check whether the socket is currently connected.

struct spdk_sock_group *	spdk_sock_group_create (void *ctx)
	Create a new socket group with user provided pointer.

void *	spdk_sock_group_get_ctx (struct spdk_sock_group *sock_group)
	Get the ctx of the sock group.

int	spdk_sock_group_add_sock (struct spdk_sock_group group, struct spdk_sock sock, spdk_sock_cb cb_fn, void *cb_arg)
	Add a socket to the group.

int	spdk_sock_group_remove_sock (struct spdk_sock_group group, struct spdk_sock sock)
	Remove a socket from the group.

int	spdk_sock_group_provide_buf (struct spdk_sock_group group, void buf, size_t len, void *ctx)
	Provides a buffer to the group to be used in its receive pool.

int	spdk_sock_group_poll (struct spdk_sock_group *group)
	Poll incoming events for each registered socket.

int	spdk_sock_group_poll_count (struct spdk_sock_group *group, int max_events)
	Poll incoming events up to max_events for each registered socket.

int	spdk_sock_group_close (struct spdk_sock_group **group)
	Close all registered sockets of the group and then remove the group.

int	spdk_sock_get_optimal_sock_group (struct spdk_sock sock, struct spdk_sock_group group, struct spdk_sock_group hint)
	Get the optimal sock group for this sock.

int	spdk_sock_impl_get_opts (const char impl_name, struct spdk_sock_impl_opts opts, size_t *len)
	Get current socket implementation options.

int	spdk_sock_impl_set_opts (const char impl_name, const struct spdk_sock_impl_opts opts, size_t len)
	Set socket implementation options.

int	spdk_sock_set_default_impl (const char *impl_name)
	Set the given sock implementation to be used as the default one.

const char *	spdk_sock_get_default_impl (void)
	Get the name of the current default implementation.

void	spdk_sock_write_config_json (struct spdk_json_write_ctx *w)
	Write socket subsystem configuration into provided JSON context.

int	spdk_sock_group_register_interrupt (struct spdk_sock_group group, uint32_t events, spdk_interrupt_fn fn, void arg, const char *name)
	Register an spdk_interrupt with specific event types on the current thread for the given socket group.

void	spdk_sock_group_unregister_interrupt (struct spdk_sock_group *group)
	Unregister an spdk_interrupt for the given socket group from the current thread.

Detailed Description

TCP socket abstraction layer.

Typedef Documentation

◆ spdk_sock_cb

typedef void(* spdk_sock_cb) (void *arg, struct spdk_sock_group *group, struct spdk_sock *sock)

Callback function for spdk_sock_group_add_sock().

Parameters

arg	Argument for the callback function.
group	Socket group.
sock	Socket.

Function Documentation

◆ spdk_sock_accept()

struct spdk_sock * spdk_sock_accept ( struct spdk_sock * sock )

Accept a new connection from a client on the specified socket and return a socket structure which holds the connection.

Parameters

sock	Listening socket.

Returns: a pointer to the accepted socket on success, or NULL on failure.

◆ spdk_sock_close()

int spdk_sock_close ( struct spdk_sock ** sock )

Close a socket.

Parameters

sock	Socket to close.

Returns: 0 on success, -1 on failure.

◆ spdk_sock_connect()

struct spdk_sock * spdk_sock_connect	(	const char *	ip,
		int	port,
		const char *	impl_name )

Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.

This function is used by client.

Parameters

ip	IP address of the server.
port	Port number of the server.
impl_name	The sock_implementation to use, such as "posix". If impl_name is specified, it will only try to connect on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can connect.

Returns: a pointer to the connected socket on success, or NULL on failure.

◆ spdk_sock_connect_ext()

struct spdk_sock * spdk_sock_connect_ext	(	const char *	ip,
		int	port,
		const char *	impl_name,
		struct spdk_sock_opts *	opts )

Create a socket using the specific sock implementation, connect the socket to the specified address and port (of the server), and then return the socket.

This function is used by client.

Parameters

ip	IP address of the server.
port	Port number of the server.
impl_name	The sock_implementation to use, such as "posix". If impl_name is specified, it will only try to connect on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can connect.
opts	The sock option pointer provided by the user which should not be NULL pointer.

Returns: a pointer to the connected socket on success, or NULL on failure.

◆ spdk_sock_flush()

int spdk_sock_flush ( struct spdk_sock * sock )

Flush a socket from data gathered in previous writev_async calls.

Parameters

sock	Socket to flush.

Returns: number of bytes sent on success, -1 (with errno set) on failure

◆ spdk_sock_get_default_impl()

const char * spdk_sock_get_default_impl ( void )

Get the name of the current default implementation.

Returns: The name of the default implementation

◆ spdk_sock_get_default_opts()

void spdk_sock_get_default_opts ( struct spdk_sock_opts * opts )

Initialize the default value of opts.

Parameters

opts Data structure where SPDK will initialize the default sock options. Users must set opts_size to sizeof(struct spdk_sock_opts). This will ensure that the libraryonly tries to fill as many fields as allocated by the caller. This allows ABI compatibility with future versions of this library that may extend the spdk_sock_opts structure.

◆ spdk_sock_get_impl_name()

const char * spdk_sock_get_impl_name ( struct spdk_sock * sock )

Get socket implementation name.

Parameters

sock	Pointer to SPDK socket.

Returns: Implementation name of given socket.

◆ spdk_sock_get_interface_name()

const char * spdk_sock_get_interface_name ( struct spdk_sock * sock )

Gets the name of the network interface of the local port for the socket.

Parameters

sock	socket to find the interface name for

Returns: null-terminated string containing interface name if found, NULL interface name could not be found

◆ spdk_sock_get_numa_id()

int32_t spdk_sock_get_numa_id ( struct spdk_sock * sock )

Gets the NUMA node ID for the network interface of the local port for the TCP socket.

Parameters

sock	TCP socket to find the NUMA socket ID for

Returns: NUMA ID, or SPDK_ENV_NUMA_ID_ANY if the NUMA ID is unknown

◆ spdk_sock_get_optimal_sock_group()

int spdk_sock_get_optimal_sock_group	(	struct spdk_sock *	sock,
		struct spdk_sock_group **	group,
		struct spdk_sock_group *	hint )

Get the optimal sock group for this sock.

Parameters

sock	The socket
group	Returns the optimal sock group. If there is no optimal sock group, returns NULL.
hint	When return is 0 and group is set to NULL, hint is used to set optimal sock group for the socket.

Returns: 0 on success. Negated errno on failure.

◆ spdk_sock_getaddr()

int spdk_sock_getaddr	(	struct spdk_sock *	sock,
		char *	saddr,
		int	slen,
		uint16_t *	sport,
		char *	caddr,
		int	clen,
		uint16_t *	cport )

Get client and server addresses of the given socket.

Parameters

sock	Socket to get address.
saddr	A pointer to the buffer to hold the address of server.
slen	Length of the buffer 'saddr'.
sport	A pointer(May be NULL) to the buffer to hold the port info of server.
caddr	A pointer to the buffer to hold the address of client.
clen	Length of the buffer 'caddr'.
cport	A pointer(May be NULL) to the buffer to hold the port info of server.

Returns: 0 on success, -1 on failure.

◆ spdk_sock_group_add_sock()

int spdk_sock_group_add_sock	(	struct spdk_sock_group *	group,
		struct spdk_sock *	sock,
		spdk_sock_cb	cb_fn,
		void *	cb_arg )

Add a socket to the group.

Parameters

group	Socket group.
sock	Socket to add.
cb_fn	Called when the operation completes.
cb_arg	Argument passed to the callback function.

Returns: 0 on success, -1 on failure with errno set.

◆ spdk_sock_group_close()

int spdk_sock_group_close ( struct spdk_sock_group ** group )

Close all registered sockets of the group and then remove the group.

Parameters

group Group to close.

Returns: 0 on success, -1 on failure.

◆ spdk_sock_group_create()

struct spdk_sock_group * spdk_sock_group_create ( void * ctx )

Create a new socket group with user provided pointer.

Parameters

ctx	the context provided by user.

Returns: a pointer to the created group on success, or NULL on failure.

◆ spdk_sock_group_get_ctx()

void * spdk_sock_group_get_ctx ( struct spdk_sock_group * sock_group )

Get the ctx of the sock group.

Parameters

sock_group Socket group.

Returns: a pointer which is ctx of the sock_group.

◆ spdk_sock_group_poll()

int spdk_sock_group_poll ( struct spdk_sock_group * group )

Poll incoming events for each registered socket.

Parameters

group Group to poll.

Returns: the number of events on success, -1 on failure.

◆ spdk_sock_group_poll_count()

int spdk_sock_group_poll_count	(	struct spdk_sock_group *	group,
		int	max_events )

Poll incoming events up to max_events for each registered socket.

Parameters

group	Group to poll.
max_events	Number of maximum events to poll for each socket.

Returns: the number of events on success, -1 on failure.

◆ spdk_sock_group_provide_buf()

int spdk_sock_group_provide_buf	(	struct spdk_sock_group *	group,
		void *	buf,
		size_t	len,
		void *	ctx )

Provides a buffer to the group to be used in its receive pool.

See spdk_sock_recv_next() for more details.

Parameters

group	Socket group.
buf	Pointer the buffer provided.
len	Length of the buffer.
ctx	Pointer that will be returned in spdk_sock_recv_next()

Returns: 0 on success, -1 on failure.

◆ spdk_sock_group_register_interrupt()

int spdk_sock_group_register_interrupt	(	struct spdk_sock_group *	group,
		uint32_t	events,
		spdk_interrupt_fn	fn,
		void *	arg,
		const char *	name )

Register an spdk_interrupt with specific event types on the current thread for the given socket group.

The provided function will be called any time one of specified event types triggers on the associated file descriptor. Event types argument is a bit mask composed by ORing together enum spdk_interrupt_event_types values.

Parameters

group	Socket group.
events	Event notification types.
fn	Called each time there are events in spdk_interrupt.
arg	Function argument for fn.
name	Human readable name for the spdk_interrupt.

Returns: 0 on success or non-zero on failure.

◆ spdk_sock_group_remove_sock()

int spdk_sock_group_remove_sock	(	struct spdk_sock_group *	group,
		struct spdk_sock *	sock )

Remove a socket from the group.

Parameters

group	Socket group.
sock	Socket to remove.

Returns: 0 on success, -1 on failure with errno set.

◆ spdk_sock_group_unregister_interrupt()

void spdk_sock_group_unregister_interrupt ( struct spdk_sock_group * group )

Unregister an spdk_interrupt for the given socket group from the current thread.

Parameters

group Socket group.

◆ spdk_sock_impl_get_opts()

int spdk_sock_impl_get_opts	(	const char *	impl_name,
		struct spdk_sock_impl_opts *	opts,
		size_t *	len )

Get current socket implementation options.

Parameters

impl_name	The socket implementation to use, such as "posix".
opts	Pointer to allocated spdk_sock_impl_opts structure that will be filled with actual values.
len	On input specifies size of passed opts structure. On return it is set to actual size that was filled with values.

Returns: 0 on success, -1 on failure. errno is set to indicate the reason of failure.

◆ spdk_sock_impl_set_opts()

int spdk_sock_impl_set_opts	(	const char *	impl_name,
		const struct spdk_sock_impl_opts *	opts,
		size_t	len )

Set socket implementation options.

Parameters

impl_name	The socket implementation to use, such as "posix".
opts	Pointer to allocated spdk_sock_impl_opts structure with new options values.
len	Size of passed opts structure.

Returns: 0 on success, -1 on failure. errno is set to indicate the reason of failure.

◆ spdk_sock_is_connected()

bool spdk_sock_is_connected ( struct spdk_sock * sock )

Check whether the socket is currently connected.

Parameters

sock	Socket to check

Returns: true if the socket is connected or false otherwise.

◆ spdk_sock_is_ipv4()

bool spdk_sock_is_ipv4 ( struct spdk_sock * sock )

Check whether the address of socket is ipv4.

Parameters

sock	Socket to check.

Returns: true if the address of socket is ipv4, or false otherwise.

◆ spdk_sock_is_ipv6()

bool spdk_sock_is_ipv6 ( struct spdk_sock * sock )

Check whether the address of socket is ipv6.

Parameters

sock	Socket to check.

Returns: true if the address of socket is ipv6, or false otherwise.

◆ spdk_sock_listen()

struct spdk_sock * spdk_sock_listen	(	const char *	ip,
		int	port,
		const char *	impl_name )

Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.

This function is used by server.

Parameters

ip	IP address to listen on.
port	Port number.
impl_name	The sock_implementation to use, such as "posix". If impl_name is specified, it will only try to listen on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can listen.

Returns: a pointer to the listened socket on success, or NULL on failure.

◆ spdk_sock_listen_ext()

struct spdk_sock * spdk_sock_listen_ext	(	const char *	ip,
		int	port,
		const char *	impl_name,
		struct spdk_sock_opts *	opts )

Create a socket using the specific sock implementation, bind the socket to the specified address and port and listen on the socket, and then return the socket.

This function is used by server.

Parameters

ip	IP address to listen on.
port	Port number.
impl_name	The sock_implementation to use, such as "posix". If impl_name is specified, it will only try to listen on that impl. If it is NULL, it will try all the sock implementations in order and uses the first sock implementation which can listen.
opts	The sock option pointer provided by the user, which should not be NULL pointer.

Returns: a pointer to the listened socket on success, or NULL on failure.

◆ spdk_sock_readv()

ssize_t spdk_sock_readv	(	struct spdk_sock *	sock,
		struct iovec *	iov,
		int	iovcnt )

Read message from the given socket to the I/O vector array.

Parameters

sock	Socket to receive message.
iov	I/O vector.
iovcnt	Number of I/O vectors in the array.

Returns: the length of the received message on success, -1 on failure.

◆ spdk_sock_recv()

ssize_t spdk_sock_recv	(	struct spdk_sock *	sock,
		void *	buf,
		size_t	len )

Receive a message from the given socket.

Parameters

sock	Socket to receive message.
buf	Pointer to a buffer to hold the data.
len	Length of the buffer.

Returns: the length of the received message on success, -1 on failure.

◆ spdk_sock_recv_next()

int spdk_sock_recv_next	(	struct spdk_sock *	sock,
		void **	buf,
		void **	ctx )

Receive the next portion of the stream from the socket.

A buffer provided to this socket's group's pool using spdk_sock_group_provide_buf() will contain the data and be returned in *buf.

Note that the amount of data in buf is determined entirely by the sock layer. You cannot request to receive only a limited amount here. You simply get whatever the next portion of the stream is, as determined by the sock module. You can place an upper limit on the size of the buffer since these buffers are originally provided to the group through spdk_sock_group_provide_buf().

This code path will only work if the recvbuf is disabled. To disable the recvbuf, call spdk_sock_set_recvbuf with a size of 0.

Parameters

sock	Socket to receive from.
buf	Populated with the next portion of the stream
ctx	Returned context pointer from when the buffer was provided.

Returns: On success, the length of the buffer placed into buf, On failure, -1 with errno set.

◆ spdk_sock_set_default_impl()

int spdk_sock_set_default_impl ( const char * impl_name )

Set the given sock implementation to be used as the default one.

Note: passing a specific sock implementation name in some sock API functions (such as spdk_sock_connect, spdk_sock_listen and etc) ignores the default value set by this function.

Parameters

impl_name The socket implementation to use, such as "posix".

Returns: 0 on success, -1 on failure. errno is set to indicate the reason of failure.

◆ spdk_sock_set_recvbuf()

int spdk_sock_set_recvbuf	(	struct spdk_sock *	sock,
		int	sz )

Set receive buffer size for the given socket.

Parameters

sock	Socket to set buffer size for.
sz	Buffer size in bytes.

Returns: 0 on success, -1 on failure.

◆ spdk_sock_set_recvlowat()

int spdk_sock_set_recvlowat	(	struct spdk_sock *	sock,
		int	nbytes )

Set the value used to specify the low water mark (in bytes) for this socket.

Parameters

sock	Socket to set for.
nbytes	Value for recvlowat.

Returns: 0 on success, -1 on failure.

◆ spdk_sock_set_sendbuf()

int spdk_sock_set_sendbuf	(	struct spdk_sock *	sock,
		int	sz )

Set send buffer size for the given socket.

Parameters

sock	Socket to set buffer size for.
sz	Buffer size in bytes.

Returns: 0 on success, -1 on failure.

◆ spdk_sock_write_config_json()

void spdk_sock_write_config_json ( struct spdk_json_write_ctx * w )

Write socket subsystem configuration into provided JSON context.

Parameters

w	JSON write context

◆ spdk_sock_writev()

ssize_t spdk_sock_writev	(	struct spdk_sock *	sock,
		struct iovec *	iov,
		int	iovcnt )

Write message to the given socket from the I/O vector array.

Parameters

sock	Socket to write to.
iov	I/O vector.
iovcnt	Number of I/O vectors in the array.

Returns: the length of written message on success, -1 on failure.

◆ spdk_sock_writev_async()

void spdk_sock_writev_async	(	struct spdk_sock *	sock,
		struct spdk_sock_request *	req )

Write data to the given socket asynchronously, calling the provided callback when the data has been written.

Parameters

sock	Socket to write to.
req	The write request to submit.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ spdk_sock_cb

Function Documentation

◆ spdk_sock_accept()

◆ spdk_sock_close()

◆ spdk_sock_connect()

◆ spdk_sock_connect_ext()

◆ spdk_sock_flush()

◆ spdk_sock_get_default_impl()

◆ spdk_sock_get_default_opts()

◆ spdk_sock_get_impl_name()

◆ spdk_sock_get_interface_name()

◆ spdk_sock_get_numa_id()

◆ spdk_sock_get_optimal_sock_group()

◆ spdk_sock_getaddr()

◆ spdk_sock_group_add_sock()

◆ spdk_sock_group_close()

◆ spdk_sock_group_create()

◆ spdk_sock_group_get_ctx()

◆ spdk_sock_group_poll()

◆ spdk_sock_group_poll_count()

◆ spdk_sock_group_provide_buf()

◆ spdk_sock_group_register_interrupt()

◆ spdk_sock_group_remove_sock()

◆ spdk_sock_group_unregister_interrupt()

◆ spdk_sock_impl_get_opts()

◆ spdk_sock_impl_set_opts()

◆ spdk_sock_is_connected()

◆ spdk_sock_is_ipv4()

◆ spdk_sock_is_ipv6()

◆ spdk_sock_listen()

◆ spdk_sock_listen_ext()

◆ spdk_sock_readv()

◆ spdk_sock_recv()

◆ spdk_sock_recv_next()

◆ spdk_sock_set_default_impl()

◆ spdk_sock_set_recvbuf()

◆ spdk_sock_set_recvlowat()

◆ spdk_sock_set_sendbuf()

◆ spdk_sock_write_config_json()

◆ spdk_sock_writev()

◆ spdk_sock_writev_async()