Mac Developer Library

Developer

kpi_socket.h Reference

Options
Deployment Target:

On This Page

kpi_socket.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

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

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.

Callbacks

  • Declaration

    Objective-C

    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

    Import Statement

    Objective-C

    #include <kpi_socket.h>;

    Availability

    Available in OS X v10.4 and later.