ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

kpi_socket.h

Includes:

Overview

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

sock_accept

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.

sock_bind

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.

sock_close

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.

sock_connect

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.

sock_getpeername

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

sock_getsockname

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

sock_getsockopt

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

sock_gettype

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.

sock_ioctl

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

sock_isconnected

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.

sock_isnonblocking

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.

sock_listen

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

sock_receive

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.

sock_receivembuf

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.

sock_send

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.

sock_sendmbuf

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.

sock_setpriv

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.

sock_setsockopt

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

sock_shutdown

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.

sock_socket

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

sock_upcall

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

Fields

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: 2008-12-19