xref: /xnu-10002.81.5/bsd/sys/kpi_socket.h (revision 5e3eaea39dcf651e66cb99ba7d70e32cc4a99587)

/*
 * Copyright (c) 2008-2017 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/*!
 *       @header kpi_socket.h
 *       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.
 */
#ifndef __KPI_SOCKET__
#define __KPI_SOCKET__

#include <sys/types.h>
#include <sys/kernel_types.h>
#include <sys/socket.h>

#ifndef PRIVATE
#include <Availability.h>
#define __NKE_API_DEPRECATED __API_DEPRECATED("Network Kernel Extension KPI is deprecated", macos(10.4, 10.15))
#else
#define __NKE_API_DEPRECATED
#endif /* PRIVATE */

__BEGIN_DECLS

struct timeval;

/*!
 *       @typedef sock_upcall
 *
 *       @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
 *
 *       @param so A reference to the socket that's ready.
 *       @param cookie The cookie passed in when the socket was created.
 *       @param waitf Indicates whether or not it's safe to block.
 */
typedef void (*sock_upcall)(socket_t so, void *cookie, int waitf);

#ifdef KERNEL_PRIVATE
/*!
 *       @typedef sock_evupcall
 *
 *       @discussion sock_evupcall is used by a socket to notify an in kernel
 *               client when an event occurs. Instead of making blocking calls in
 *               the kernel, a client can specify an upcall which will be called
 *               when an event status is available.
 *       @param so A reference to the socket that's ready.
 *       @param cookie The cookie passed in when the socket was created.
 *       @param event Indicates the event as defined by SO_FILT_HINT_*
 */
typedef void (*sock_evupcall)(socket_t so, void *cookie, uint32_t event);
#endif /* KERNEL_PRIVATE */

/*!
 *       @function sock_accept
 *       @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.
 *       @param so The listening socket you'd like to accept a connection on.
 *       @param from A pointer to a socket address that will be filled in
 *               with the address the connection is from.
 *       @param fromlen Maximum length of from.
 *       @param 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.
 *       @param callback A notifier function to be called when an event
 *               occurs on the socket. This may be NULL.
 *       @param cookie A cookie passed directly to the callback.
 *       @param new_so Upon success, *new_so will be a reference to a new
 *               socket for tracking the connection.
 *       @result 0 on success otherwise the errno error.
 */
#ifdef KERNEL_PRIVATE
extern errno_t sock_accept_internal(socket_t so, struct sockaddr *from, int fromlen,
    int flags, sock_upcall callback, void *cookie, socket_t *new_so);

#define sock_accept(so, from, fromlen, flags, callback, cookie, new_so) \
	sock_accept_internal((so), (from), (fromlen), (flags), (callback), \
	(cookie), (new_so))
#else
extern errno_t sock_accept(socket_t so, struct sockaddr *from, int fromlen,
    int flags, sock_upcall callback, void *cookie, socket_t *new_so)
__NKE_API_DEPRECATED;
#endif /* KERNEL_PRIVATE */

/*!
 *       @function sock_bind
 *       @discussion Binds a socket to a specific address. See 'man 2 bind'
 *               for more information.
 *       @param so The socket to be bound.
 *       @param to The local address the socket should be bound to.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_bind(socket_t so, const struct sockaddr *to)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_connect
 *       @discussion Initiates a connection on the socket. See 'man 2
 *               connect' for more information.
 *       @param so The socket to be connect.
 *       @param to The remote address the socket should connect to.
 *       @param 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.
 *       @result 0 on success, EINPROGRESS for a non-blocking connect that
 *               has not completed, otherwise the errno error.
 */
extern errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags)
__NKE_API_DEPRECATED;

#ifdef KERNEL_PRIVATE
/*
 *       This function was added to support NFS. NFS does something funny,
 *       setting a short timeout and checking to see if it should abort the
 *       connect every two seconds. Ideally, NFS would use the upcall to be
 *       notified when the connect is complete.
 *
 *       If you feel you need to use this function, please contact us to
 *       explain why.
 *
 *       @function sock_connectwait
 *       @discussion Allows a caller to wait on a socket connect.
 *       @param so The socket being connected.
 *       @param tv The amount of time to wait.
 *       @result 0 on success otherwise the errno error. EINPROGRESS will be
 *               returned if the connection did not complete in the timeout
 *               specified.
 */
extern errno_t sock_connectwait(socket_t so, const struct timeval *tv);
#endif /* KERNEL_PRIVATE */

/*!
 *       @function sock_getpeername
 *       @discussion Retrieves the remote address of a connected socket. See
 *               'man 2 getpeername'.
 *       @param so The socket.
 *       @param peername Storage for the peer name.
 *       @param peernamelen Length of storage for the peer name.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_getpeername(socket_t so, struct sockaddr *peername,
    int peernamelen)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_getsockname
 *       @discussion Retrieves the local address of a socket. See 'man 2
 *               getsockname'.
 *       @param so The socket.
 *       @param sockname Storage for the local name.
 *       @param socknamelen Length of storage for the socket name.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_getsockname(socket_t so, struct sockaddr *sockname,
    int socknamelen)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_getsockopt
 *       @discussion Retrieves a socket option. See 'man 2 getsockopt'.
 *       @param so The socket.
 *       @param level Level of the socket option.
 *       @param optname The option name.
 *       @param optval The option value.
 *       @param optlen The length of optval, returns the actual length.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_getsockopt(socket_t so, int level, int optname,
    void *optval, int *optlen)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_ioctl
 *       @discussion Performs an ioctl operation on a socket. See 'man 2 ioctl'.
 *       @param so The socket.
 *       @param request The ioctl name.
 *       @param argp The argument.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_ioctl(socket_t so, unsigned long request, void *argp)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_setsockopt
 *       @discussion Sets a socket option. See 'man 2 setsockopt'.
 *       @param so The socket.
 *       @param level Level of the socket option.
 *       @param optname The option name.
 *       @param optval The option value.
 *       @param optlen The length of optval.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_setsockopt(socket_t so, int level, int optname,
    const void *optval, int optlen)
__NKE_API_DEPRECATED;

#ifdef KERNEL_PRIVATE
/*
 *       This function was added to support AFP setting the traffic class
 *       for a backup stream within a wireless LAN or over link-local address.
 *
 *       If you feel you need to use this function, please contact us to
 *       explain why.
 *
 *       @function sock_settclassopt
 *       @discussion Allows a caller to set the traffic class.
 *       @param so The socket.
 *       @param optval The option value.
 *       @param optlen The length of optval.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_settclassopt(socket_t so, const void* optval, size_t optlen);

/*
 *       This function was added to support AFP getting the traffic class
 *       set on a stream.
 *
 *       This is also a private API, please contact us if you need to use it.
 *
 *       @function sockgettclassopt
 *       @discussion Allows a caller to get the traffic class.
 *       @param so The socket.
 *       @param optval The option value.
 *       @param optlen The length of optval, returns the actual length.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_gettclassopt(socket_t so, void* optval, size_t* optlen);

#ifdef XNU_KERNEL_PRIVATE
extern void socket_set_traffic_mgt_flags_locked(socket_t so, u_int8_t flags);
extern void socket_clear_traffic_mgt_flags_locked(socket_t so, u_int8_t flags);
#endif /* XNU_KERNEL_PRIVATE */
#ifdef BSD_KERNEL_PRIVATE
extern void socket_set_traffic_mgt_flags(socket_t so, u_int8_t flags);
extern void socket_clear_traffic_mgt_flags(socket_t so, u_int8_t flags);
extern errno_t socket_defunct(struct proc *, socket_t so, int);
extern errno_t sock_receive_internal(socket_t, struct msghdr *, mbuf_t *,
    int, size_t *);
#endif /* BSD_KERNEL_PRIVATE */
#endif /* KERNEL_PRIVATE */

/*!
 *       @function sock_listen
 *       @discussion Indicate that the socket should start accepting incoming
 *               connections. See 'man 2 listen'.
 *       @param so The socket.
 *       @param backlog The maximum length of the queue of pending connections.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_listen(socket_t so, int backlog)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_receive
 *       @discussion Receive data from a socket. Similar to recvmsg. See 'man
 *               2 recvmsg' for more information about receiving data.
 *       @param so The socket.
 *       @param msg The msg describing how the data should be received.
 *       @param flags See 'man 2 recvmsg'.
 *       @param recvdlen Number of bytes received, same as return value of
 *               userland recvmsg.
 *       @result 0 on success, EWOULDBLOCK if non-blocking and operation
 *               would cause the thread to block, otherwise the errno error.
 */
extern errno_t sock_receive(socket_t so, struct msghdr *msg, int flags,
    size_t *recvdlen)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_receivembuf
 *       @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.
 *       @param so The socket.
 *       @param msg The msg describing how the data should be received. May
 *               be NULL. The msg_iov is ignored.
 *       @param 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.
 *       @param flags See 'man 2 recvmsg'.
 *       @param 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.
 *       @result 0 on success, EWOULDBLOCK if non-blocking and operation
 *               would cause the thread to block, otherwise the errno error.
 */
extern errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data,
    int flags, size_t *recvlen)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_send
 *       @discussion Send data on a socket. Similar to sendmsg. See 'man 2
 *               sendmsg' for more information about sending data.
 *       @param so The socket.
 *       @param msg The msg describing how the data should be sent. Any
 *               pointers must point to data in the kernel.
 *       @param flags See 'man 2 sendmsg'.
 *       @param sentlen The number of bytes sent.
 *       @result 0 on success, EWOULDBLOCK if non-blocking and operation
 *               would cause the thread to block, otherwise the errno error.
 */
extern errno_t sock_send(socket_t so, const struct msghdr *msg, int flags,
    size_t *sentlen)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_sendmbuf
 *       @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.
 *       @param so The socket.
 *       @param msg The msg describing how the data should be sent. The
 *               msg_iov is ignored. msg may be NULL.
 *       @param data The mbuf chain of data to send.
 *       @param flags See 'man 2 sendmsg'.
 *       @param sentlen The number of bytes sent.
 *       @result 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.
 */
extern errno_t sock_sendmbuf(socket_t so, const struct msghdr *msg, mbuf_t data,
    int flags, size_t *sentlen)
__NKE_API_DEPRECATED;

#ifdef KERNEL_PRIVATE
/*!
 *       @function sock_sendmbuf_can_wait
 *       @discussion Variation of sock_sendmbuf that can wait for the send socket
 *               buffer to drain when it is full instead of returning EMSGSIZE.
 *       @param so The socket.
 *       @param msg The msg describing how the data should be sent. The
 *               msg_iov is ignored. msg may be NULL.
 *       @param data The mbuf chain of data to send.
 *       @param flags See 'man 2 sendmsg'.
 *       @param sentlen The number of bytes sent.
 *       @result 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.
 */
extern errno_t sock_sendmbuf_can_wait(socket_t so, const struct msghdr *msg, mbuf_t data,
    int flags, size_t *sentlen);
#define HAS_SOCK_SENDMBUF_CAN_WAIT 1

#endif /* KERNEL_PRIVATE */

/*!
 *       @function sock_shutdown
 *       @discussion Shutdown one or both directions of a connection. See
 *               'man 2 shutdown' for more information.
 *       @param so The socket.
 *       @param how SHUT_RD - shutdown receive.
 *               SHUT_WR - shutdown send.
 *               SHUT_RDWR - shutdown both.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_shutdown(socket_t so, int how)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_socket
 *       @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'.
 *       @param domain The socket domain (PF_INET, etc...).
 *       @param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...).
 *       @param protocol The socket protocol.
 *       @param callback A notifier function to be called when an event
 *               occurs on the socket. This may be NULL.
 *       @param cookie A cookie passed directly to the callback.
 *       @param new_so Upon success, a reference to the new socket.
 *       @result 0 on success otherwise the errno error.
 */
#ifdef KERNEL_PRIVATE
extern errno_t sock_socket_internal(int domain, int type, int protocol,
    sock_upcall callback, void *cookie, socket_t *new_so);

#define sock_socket(domain, type, protocol, callback, cookie, new_so) \
	sock_socket_internal((domain), (type), (protocol), \
	(callback), (cookie), (new_so))
#else
extern errno_t sock_socket(int domain, int type, int protocol,
    sock_upcall callback, void *cookie, socket_t *new_so)
__NKE_API_DEPRECATED;
#endif /* KERNEL_PRIVATE */

/*!
 *       @function sock_close
 *       @discussion Close the socket.
 *       @param 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.
 */
extern void sock_close(socket_t so)
__NKE_API_DEPRECATED;

/*
 *       @function sock_retain
 *       @discussion Prevents the socket from closing
 *       @param so The socket to close.  Increment a retain count on the
 *               socket, preventing it from being closed when sock_close is
 *               called. This is used when a File Descriptor is passed (and
 *               closed) from userland and the kext wants to keep ownership of
 *               that socket. It is used in conjunction with
 *               sock_release(socket_t so).
 */
extern void sock_retain(socket_t so)
__NKE_API_DEPRECATED;

/*
 *       @function sock_release
 *       @discussion Decrement the retain count and close the socket if the
 *               retain count reaches zero.
 *       @param so The socket to release. This is used to release ownership
 *               on a socket acquired with sock_retain. When the last retain
 *               count is reached, this will call sock_close to close the socket.
 */
extern void sock_release(socket_t so)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_setpriv
 *       @discussion Set the privileged bit in the socket. Allows for
 *               operations that require root privileges.
 *       @param so The socket on which to modify the SS_PRIV flag.
 *       @param on Indicate whether or not the SS_PRIV flag should be set.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_setpriv(socket_t so, int on)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_isconnected
 *       @discussion Returns whether or not the socket is connected.
 *       @param so The socket to check.
 *       @result 0 - socket is not connected. 1 - socket is connected.
 */
extern int sock_isconnected(socket_t so)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_isnonblocking
 *       @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.
 *       @result 0 - socket will block. 1 - socket will not block.
 */
extern int sock_isnonblocking(socket_t so)
__NKE_API_DEPRECATED;

/*!
 *       @function sock_gettype
 *       @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.
 *       @param so The socket to check.
 *       @param domain The domain of the socket (PF_INET, ...). May be NULL.
 *       @param type The socket type (SOCK_STREAM, SOCK_DGRAM, ...). May be NULL.
 *       @param protocol The socket protocol. May be NULL.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol)
__NKE_API_DEPRECATED;

#ifdef KERNEL_PRIVATE
/*
 *       @function sock_nointerrupt
 *       @discussion Disables interrupt on socket buffers (sets SB_NOINTR on
 *               send and receive socket buffers).
 *       @param so The socket to modify.
 *       @param on Indicate whether or not the SB_NOINTR flag should be set.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_nointerrupt(socket_t so, int on);

/*
 *       @function sock_getlistener
 *       @discussion Retrieves the listening socket of a pre-accepted socket,
 *               i.e. a socket which is still in the incomplete/completed list.
 *               Once a socket has been accepted, the information pertaining
 *               to its listener is no longer available.  Therefore, modules
 *               interested in finding out the listening socket should install
 *               the appropriate socket filter callback (sf_attach) which gets
 *               invoked prior to the socket being fully accepted, and call
 *               this routine at such a time to obtain the listener.  Callers
 *               are guaranteed that the listener socket will not go away
 *               during the sf_attach callback, and therefore the value is
 *               safe to be used only in that callback context.  Callers should
 *               therefore take note that the listening socket's lock will be
 *               held throughout the duration of the callback.
 *       @param so The pre-accepted socket.
 *       @result Non-NULL value which indicates the listening socket; otherwise,
 *               NULL if the socket is not in the incomplete/completed list
 *               of a listener.
 */
extern socket_t sock_getlistener(socket_t so);

/*
 *       @function sock_getaddr
 *       @discussion Retrieves the local or remote address of a socket.
 *               This is a composite of sock_getpeername and sock_getsockname,
 *               except that the allocated socket address is returned to the
 *               caller, and that the caller is reponsible for calling
 *               sock_freeaddr once finished with it.
 *       @param so The socket.
 *       @param psockname Pointer to the storage for the socket name.
 *       @param peername 0 for local address, and non-zero for peer address.
 *       @result 0 on success otherwise the errno error.
 */
extern errno_t sock_getaddr(socket_t so, struct sockaddr **psockname,
    int peername);

/*
 *       @function sock_freeaddr
 *       @discussion Frees the socket address allocated by sock_getaddr.
 *       @param sockname The socket name to be freed.
 */
extern void sock_freeaddr(struct sockaddr *sockname);

/*
 *       @function sock_setupcall
 *       @discussion Set the notifier function to be called when an event
 *               occurs on the socket. This may be set to NULL to disable
 *               further notifications. Setting the function does not
 *               affect currently notifications about to be sent or being sent.
 *               Note: When this function is used on a socket passed from
 *               userspace it is crucial to call sock_retain() on the socket
 *               otherwise a callback could be dispatched on a closed socket
 *               and cause a crash.
 *       @param sock The socket.
 *       @param callback The notifier function
 *       @param context A cookie passed directly to the callback
 */
extern errno_t sock_setupcall(socket_t sock, sock_upcall callback,
    void *context);

/*
 *       @function sock_setupcalls
 *       @discussion Set the notifier function to be called when an event
 *               occurs on the socket. This may be set to NULL to disable
 *               further notifications. Setting the function does not
 *               affect currently notifications about to be sent or being sent.
 *               Note: When this function is used on a socket passed from
 *               userspace it is crucial to call sock_retain() on the socket
 *               otherwise a callback could be dispatched on a closed socket
 *               and cause a crash.
 *       @param sock The socket.
 *       @param read_callback The read notifier function
 *       @param read_context A cookie passed directly to the read callback
 *       @param write_callback The write notifier function
 *       @param write_context A cookie passed directly to the write callback
 */
extern errno_t sock_setupcalls(socket_t sock, sock_upcall read_callback,
    void *read_context, sock_upcall write_callback, void *write_context);

/*
 *       @function sock_setupcalls_locked
 *       @discussion The locked version of sock_setupcalls
 *       @param locked: When sets, indicates that the callbacks expect to be
 *                      on a locked socket. Thus, no unlock is done prior to
 *                      calling the callback.
 */
extern void sock_setupcalls_locked(socket_t sock,
    sock_upcall rcallback, void *rcontext,
    sock_upcall wcallback, void *wcontext, int locked);

/*
 *       @function sock_catchevents
 *       @discussion Set the notifier function to be called when an event
 *               occurs on the socket. This may be set to NULL to disable
 *               further notifications. Setting the function does not
 *               affect currently notifications about to be sent or being sent.
 *       @param sock The socket.
 *       @param event_callback The event notifier function
 *       @param event_context A cookie passed directly to the event callback
 *       @param event_mask One or more SO_FILT_HINT_* values OR'ed together,
 *               indicating the registered event(s).
 */
extern errno_t sock_catchevents(socket_t sock, sock_evupcall event_callback,
    void *event_context, uint32_t event_mask);

extern void sock_catchevents_locked(socket_t sock, sock_evupcall ecallback,
    void *econtext, uint32_t emask);


/*
 *       @function sock_iskernel
 *       @discussion Returns true if the socket was created by the kernel or
 *               is owned by the kernel.
 *       @param sock The socket.
 *       @result True if the kernel owns the socket.
 */
extern int sock_iskernel(socket_t);
#endif /* KERNEL_PRIVATE */

__END_DECLS
#undef __NKE_API_DEPRECATED
#endif /* __KPI_SOCKET__ */