kpi_socket.h

Introduction

This header defines an API for creating and interacting with sockets in the kernel. It is possible to create sockets in the kernel without an associated file descriptor. In some cases, a reference to the socket may be known while the file descriptor is not. These functions can be used for interacting with sockets in the kernel. The API is similar to the user space socket API.

Functions

sock_accept

sock_bind

sock_close

sock_connect

sock_getpeername

sock_getsockname

sock_getsockopt

sock_gettype

sock_ioctl

sock_isconnected

sock_isnonblocking

sock_listen

sock_receive

sock_receivembuf

sock_send

sock_sendmbuf

sock_setpriv

sock_setsockopt

sock_shutdown

sock_socket

errno_t sock_accept(
    socket_t so,
    struct sockaddr *from,
    int fromlen, 
    int flags,
    sock_upcall callback,
    void*cookie, 
    socket_t *new_so);  

Parameters

so

The listening socket you'd like to accept a connection on.

from

A pointer to a socket address that will be filled in with the address the connection is from.

fromlen

Maximum length of from.

flags

Supports MSG_DONTWAIT and MSG_USEUPCALL. If MSG_DONTWAIT is set, accept will return EWOULDBLOCK if there are no connections ready to be accepted. If MSG_USEUPCALL is set, the created socket will use the same upcall function attached to the original socket.

callback

A notifier function to be called when an event occurs on the socket. This may be NULL.

cookie

A cookie passed directly to the callback.

new_so

Upon success, *new_so will be a reference to a new socket for tracking the connection.

Return Value

0 on success otherwise the errno error.

Discussion

Accepts an incoming connection on a socket. See 'man 2 accept' for more information. Allocating a socket in this manner creates a socket with no associated file descriptor.

errno_t sock_bind(
    socket_t so,
    const struct sockaddr *to);  

Parameters

so

The socket to be bound.

to

The local address the socket should be bound to.

Return Value

0 on success otherwise the errno error.

Discussion

Binds a socket to a specific address. See 'man 2 bind' for more information.

void sock_close(
    socket_t so);  

Parameters

so

The socket to close. This should only ever be a socket created with sock_socket. Closing a socket created in user space using sock_close may leave a file descriptor pointing to the closed socket, resulting in undefined behavior.

Discussion

Close the socket.

errno_t sock_connect(
    socket_t so,
    const struct sockaddr *to,
    int flags);  

Parameters

so

The socket to be connect.

to

The remote address the socket should connect to.

flags

Flags for connecting. The only flag supported so far is MSG_DONTWAIT. MSG_DONTWAIT will perform a non-blocking connect. sock_connect will return immediately with EINPROGRESS. The upcall, if supplied, will be called when the connection is completed.

Return Value

0 on success, EINPROGRESS for a non-blocking connect that has not completed, otherwise the errno error.

Discussion

Initiates a connection on the socket. See 'man 2 connect' for more information.

errno_t sock_getpeername(
    socket_t so,
    struct sockaddr *peername,
    int peernamelen);  

Parameters

so

The socket.

peername

Storage for the peer name.

peernamelen

Length of storage for the peer name.

Return Value

0 on success otherwise the errno error.

Discussion

Retrieves the remote address of a connected socket. See 'man 2 getpeername'.

errno_t sock_getsockname(
    socket_t so,
    struct sockaddr *sockname,
    int socknamelen);  

Parameters

so

The socket.

sockname

Storage for the local name.

socknamelen

Length of storage for the socket name.

Return Value

0 on success otherwise the errno error.

Discussion

Retrieves the local address of a socket. See 'man 2 getsockname'.

errno_t sock_getsockopt(
    socket_t so,
    int level,
    int optname,
    void *optval,
    int *optlen);  

Parameters

so

The socket.

level

Level of the socket option.

optname

The option name.

optval

The option value.

optlen

The length of optval, returns the actual length.

Return Value

0 on success otherwise the errno error.

Discussion

Retrieves a socket option. See 'man 2 getsockopt'.

errno_t sock_gettype(
    socket_t so,
    int *domain,
    int *type,
    int *protocol);  

Parameters

so

The socket to check.

domain

The domain of the socket (PF_INET, etc...). May be NULL.

type

The socket type (SOCK_STREAM, SOCK_DGRAM, etc...). May be NULL.

protocol

The socket protocol. May be NULL.

Return Value

0 on success otherwise the errno error.

Discussion

Retrieves information about the socket. This is the same information that was used to create the socket. If any of the parameters following so are NULL, that information is not retrieved.

errno_t sock_ioctl(
    socket_t so,
    unsigned long request,
    void *argp);  

Parameters

so

The socket.

request

The ioctl name.

argp

The argument.

Return Value

0 on success otherwise the errno error.

Discussion

Performs an ioctl operation on a socket. See 'man 2 ioctl'.

int sock_isconnected(
    socket_t so);  

Parameters

so

The socket to check.

Return Value

0 - socket is not connected. 1 - socket is connected.

Discussion

Returns whether or not the socket is connected.

int sock_isnonblocking(
    socket_t so);  

Return Value

0 - socket will block. 1 - socket will not block.

Discussion

Returns whether or not the socket is non-blocking. In the context of this KPI, non-blocking means that functions to perform operations on a socket will not wait for completion.

To enable or disable blocking, use the FIONBIO ioctl. The parameter is an int. If the int is zero, the socket will block. If the parameter is non-zero, the socket will not block.

errno_t sock_listen(
    socket_t so,
    int backlog);  

Parameters

so

The socket.

backlog

The maximum length of the queue of pending connections.

Return Value

0 on success otherwise the errno error.

Discussion

Indicate that the socket should start accepting incoming connections. See 'man 2 listen'.

errno_t sock_receive(
    socket_t so,
    struct msghdr *msg,
    int flags,
    size_t *recvdlen);  

Parameters

so

The socket.

msg

The msg describing how the data should be received.

flags

See 'man 2 recvmsg'.

recvdlen

Number of bytes received, same as return value of userland recvmsg.

Return Value

0 on success, EWOULDBLOCK if non-blocking and operation would cause the thread to block, otherwise the errno error.

Discussion

Receive data from a socket. Similar to recvmsg. See 'man 2 recvmsg' for more information about receiving data.

errno_t sock_receivembuf(
    socket_t so,
    struct msghdr *msg,
    mbuf_t *data,
    int flags,
    size_t *recvlen);  

Parameters

so

The socket.

msg

The msg describing how the data should be received. May be NULL. The msg_iov is ignored.

data

Upon return *data will be a reference to an mbuf chain containing the data received. This eliminates copying the data out of the mbufs. Caller is responsible for freeing the mbufs.

flags

See 'man 2 recvmsg'.

recvlen

Maximum number of bytes to receive in the mbuf chain. Upon return, this value will be set to the number of bytes received, same as return value of userland recvmsg.

Return Value

0 on success, EWOULDBLOCK if non-blocking and operation would cause the thread to block, otherwise the errno error.

Discussion

Receive data from a socket. Similar to sock_receive though data is returned as a chain of mbufs. See 'man 2 recvmsg' for more information about receiving data.

errno_t sock_send(
    socket_t so,
    const struct msghdr *msg,
    int flags,
    size_t *sentlen);  

Parameters

so

The socket.

msg

The msg describing how the data should be sent. Any pointers must point to data in the kernel.

flags

See 'man 2 sendmsg'.

sentlen

The number of bytes sent.

Return Value

0 on success, EWOULDBLOCK if non-blocking and operation would cause the thread to block, otherwise the errno error.

Discussion

Send data on a socket. Similar to sendmsg. See 'man 2 sendmsg' for more information about sending data.

errno_t sock_sendmbuf(
    socket_t so,
    const struct msghdr *msg,
    mbuf_t data,
    int flags,
    size_t *sentlen);  

Parameters

so

The socket.

msg

The msg describing how the data should be sent. The msg_iov is ignored. msg may be NULL.

data

The mbuf chain of data to send.

flags

See 'man 2 sendmsg'.

sentlen

The number of bytes sent.

Return Value

0 on success, EWOULDBLOCK if non-blocking and operation would cause the thread to block, otherwise the errno error. Regardless of return value, the mbuf chain 'data' will be freed.

Discussion

Send data in an mbuf on a socket. Similar to sock_send only the data to be sent is taken from the mbuf chain.

errno_t sock_setpriv(
    socket_t so,
    int on);  

Parameters

so

The socket on which to modify the SS_PRIV flag.

on

Indicate whether or not the SS_PRIV flag should be set.

Return Value

0 on success otherwise the errno error.

Discussion

Set the privileged bit in the socket. Allows for operations that require root privileges.

errno_t sock_setsockopt(
    socket_t so,
    int level,
    int optname,
    const void *optval,
    int optlen);  

Parameters

so

The socket.

level

Level of the socket option.

optname

The option name.

optval

The option value.

optlen

The length of optval.

Return Value

0 on success otherwise the errno error.

Discussion

Sets a socket option. See 'man 2 setsockopt'.

errno_t sock_shutdown(
    socket_t so,
    int how);  

Parameters

so

The socket.

how

SHUT_RD - shutdown receive. SHUT_WR - shutdown send. SHUT_RDWR - shutdown both.

Return Value

0 on success otherwise the errno error.

Discussion

Shutdown one or both directions of a connection. See 'man 2 shutdown' for more information.

errno_t sock_socket(
    int domain,
    int type,
    int protocol,
    sock_upcall callback, 
    void*cookie,
    socket_t *new_so);  

Parameters

domain

The socket domain (PF_INET, etc...).

type

The socket type (SOCK_STREAM, SOCK_DGRAM, etc...).

protocol

The socket protocol.

callback

A notifier function to be called when an event occurs on the socket. This may be NULL.

cookie

A cookie passed directly to the callback.

new_so

Upon success, a reference to the new socket.

Return Value

0 on success otherwise the errno error.

Discussion

Allocate a socket. Allocating a socket in this manner creates a socket with no associated file descriptor. For more information, see 'man 2 socket'.

Typedefs

typedef void (*sock_upcall)(
    socket_t so,
    void*cookie,
    int waitf);  

Parameters

so

A reference to the socket that's ready.

cookie

The cookie passed in when the socket was created.

waitf

Indicates whether or not it's safe to block.

Discussion

sock_upcall is used by a socket to notify an in kernel client that data is waiting. Instead of making blocking calls in the kernel, a client can specify an upcall which will be called when data is available or the socket is ready for sending.

Calls to your upcall function are not serialized and may be called concurrently from multiple threads in the kernel.

Your upcall function will be called when:

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2006-07-17