kpi_socket.h Reference

Declared in
kpi_socket.h

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.

Included Headers

Functions

See the Overview section above for header-level documentation.

sock_accept

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_bind

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_close

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_connect

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_getpeername

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_getsockname

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_getsockopt

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_gettype

extern 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, ...). May be NULL.

type

The socket type (SOCK_STREAM, SOCK_DGRAM, ...). 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_ioctl

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_isconnected

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_isnonblocking

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_listen

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_receive

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_receivembuf

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_send

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_sendmbuf

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_setpriv

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_setsockopt

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_shutdown

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

sock_socket

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

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h

Callbacks

See the Overview section above for header-level documentation.

sock_upcall

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 there is data more than the low water mark for reading, or when there is space for a write, or when there is a connection to accept, or when a socket is connected, or when a socket is closed or disconnected

Availability
  • Available in OS X v10.4 and later.
Declared In
kpi_socket.h