ADC Home > Reference Library > Reference > Darwin > KPI Reference

 


kpi_socket.h

Includes:
<sys/types.h>
<sys/kernel_types.h>
<sys/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

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);  
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