xnu-1504.3.12.tar.gz

[apple/xnu.git] / bsd / sys / kpi_socket.h

diff --git a/bsd/sys/kpi_socket.h b/bsd/sys/kpi_socket.h
index f65b17472c8622eaa2aa7c3ee977ca096ecfe141..28cbd28ac66c2a55f62669ddcafec8ecc8360d76 100644 (file)
--- a/bsd/sys/kpi_socket.h
+++ b/bsd/sys/kpi_socket.h
@@ -1,5 +1,5 @@
 /*
 /*

- * Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 2008 Apple Computer, Inc. All rights reserved.

  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  * 
  *
  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
  * 


@@ -39,27 +39,30 @@
 
 #include <sys/types.h>
 #include <sys/kernel_types.h>
 
 #include <sys/types.h>
 #include <sys/kernel_types.h>

+#include <sys/socket.h>
+
+__BEGIN_DECLS

 
 struct timeval;
 
 /*!
        @typedef sock_upcall
 
 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.
        @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.
                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:
                Your upcall function will be called when:

-               
+

        @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.
 */
        @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);
+typedef void (*sock_upcall)(socket_t so, void *cookie, int waitf);

 
 /*!
        @function sock_accept
 
 /*!
        @function sock_accept


@@ -82,9 +85,8 @@ typedef void (*sock_upcall)(socket_t so, void* cookie, int waitf);
                socket for tracking the connection.
        @result 0 on success otherwise the errno error.
  */
                socket for tracking the connection.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_accept(socket_t so, struct sockaddr *from, int fromlen,
-                                       int flags, sock_upcall callback, void* cookie,
-                                       socket_t *new_so);
+extern errno_t sock_accept(socket_t so, struct sockaddr *from, int fromlen,
+    int flags, sock_upcall callback, void *cookie, socket_t *new_so);

 
 /*!
        @function sock_bind
 
 /*!
        @function sock_bind


@@ -94,7 +96,7 @@ errno_t sock_accept(socket_t so, struct sockaddr *from, int fromlen,
        @param to The local address the socket should be bound to.
        @result 0 on success otherwise the errno error.
  */
        @param to The local address the socket should be bound to.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_bind(socket_t so, const struct sockaddr *to);
+extern errno_t sock_bind(socket_t so, const struct sockaddr *to);

 
 /*!
        @function sock_connect
 
 /*!
        @function sock_connect


@@ -110,18 +112,18 @@ errno_t sock_bind(socket_t so, const struct sockaddr *to);
        @result 0 on success, EINPROGRESS for a non-blocking connect that
                has not completed, otherwise the errno error.
  */
        @result 0 on success, EINPROGRESS for a non-blocking connect that
                has not completed, otherwise the errno error.
  */

-errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags);
+extern errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags);

 
 #ifdef KERNEL_PRIVATE
 
 #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.
        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.
        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.
        @function sock_connectwait
        @discussion Allows a caller to wait on a socket connect.
        @param so The socket being connected.


@@ -130,8 +132,8 @@ errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags);
                returned if the connection did not complete in the timeout
                specified.
  */
                returned if the connection did not complete in the timeout
                specified.
  */

-errno_t sock_connectwait(socket_t so, const struct timeval *tv);
-#endif KERNEL_PRIVATE
+extern errno_t sock_connectwait(socket_t so, const struct timeval *tv);
+#endif /* KERNEL_PRIVATE */

 
 /*!
        @function sock_getpeername
 
 /*!
        @function sock_getpeername


@@ -142,7 +144,8 @@ errno_t sock_connectwait(socket_t so, const struct timeval *tv);
        @param peernamelen Length of storage for the peer name.
        @result 0 on success otherwise the errno error.
  */
        @param peernamelen Length of storage for the peer name.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_getpeername(socket_t so, struct sockaddr *peername, int peernamelen);
+extern errno_t sock_getpeername(socket_t so, struct sockaddr *peername,
+    int peernamelen);

 
 /*!
        @function sock_getsockname
 
 /*!
        @function sock_getsockname


@@ -153,7 +156,8 @@ errno_t sock_getpeername(socket_t so, struct sockaddr *peername, int peernamelen
        @param socknamelen Length of storage for the socket name.
        @result 0 on success otherwise the errno error.
  */
        @param socknamelen Length of storage for the socket name.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_getsockname(socket_t so, struct sockaddr *sockname, int socknamelen);
+extern errno_t sock_getsockname(socket_t so, struct sockaddr *sockname,
+    int socknamelen);

 
 /*!
        @function sock_getsockopt
 
 /*!
        @function sock_getsockopt


@@ -165,7 +169,8 @@ errno_t sock_getsockname(socket_t so, struct sockaddr *sockname, int socknamelen
        @param optlen The length of optval, returns the actual length.
        @result 0 on success otherwise the errno error.
  */
        @param optlen The length of optval, returns the actual length.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_getsockopt(socket_t so, int level, int optname, void *optval, int *optlen);
+extern errno_t sock_getsockopt(socket_t so, int level, int optname,
+    void *optval, int *optlen);

 
 /*!
        @function sock_ioctl
 
 /*!
        @function sock_ioctl


@@ -175,7 +180,7 @@ errno_t sock_getsockopt(socket_t so, int level, int optname, void *optval, int *
        @param argp The argument.
        @result 0 on success otherwise the errno error.
  */
        @param argp The argument.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_ioctl(socket_t so, unsigned long request, void *argp);
+extern errno_t sock_ioctl(socket_t so, unsigned long request, void *argp);

 
 /*!
        @function sock_setsockopt
 
 /*!
        @function sock_setsockopt


@@ -187,7 +192,41 @@ errno_t sock_ioctl(socket_t so, unsigned long request, void *argp);
        @param optlen The length of optval.
        @result 0 on success otherwise the errno error.
  */
        @param optlen The length of optval.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_setsockopt(socket_t so, int level, int optname, const void *optval, int optlen);
+extern errno_t sock_setsockopt(socket_t so, int level, int optname,
+    const void *optval, int optlen);
+
+#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);
+#endif

 
 /*!
        @function sock_listen
 
 /*!
        @function sock_listen


@@ -197,7 +236,7 @@ errno_t sock_setsockopt(socket_t so, int level, int optname, const void *optval,
        @param backlog The maximum length of the queue of pending connections.
        @result 0 on success otherwise the errno error.
  */
        @param backlog The maximum length of the queue of pending connections.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_listen(socket_t so, int backlog);
+extern errno_t sock_listen(socket_t so, int backlog);

 
 /*!
        @function sock_receive
 
 /*!
        @function sock_receive


@@ -211,7 +250,8 @@ errno_t sock_listen(socket_t so, int backlog);
        @result 0 on success, EWOULDBLOCK if non-blocking and operation
                would cause the thread to block, otherwise the errno error.
  */
        @result 0 on success, EWOULDBLOCK if non-blocking and operation
                would cause the thread to block, otherwise the errno error.
  */

-errno_t sock_receive(socket_t so, struct msghdr *msg, int flags, size_t *recvdlen);
+extern errno_t sock_receive(socket_t so, struct msghdr *msg, int flags,
+    size_t *recvdlen);

 
 /*!
        @function sock_receivembuf
 
 /*!
        @function sock_receivembuf


@@ -231,7 +271,8 @@ errno_t sock_receive(socket_t so, struct msghdr *msg, int flags, size_t *recvdle
        @result 0 on success, EWOULDBLOCK if non-blocking and operation
                would cause the thread to block, otherwise the errno error.
  */
        @result 0 on success, EWOULDBLOCK if non-blocking and operation
                would cause the thread to block, otherwise the errno error.
  */

-errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data, int flags, size_t *recvlen);
+extern errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data,
+    int flags, size_t *recvlen);

 
 /*!
        @function sock_send
 
 /*!
        @function sock_send


@@ -245,7 +286,8 @@ errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data, int flag
        @result 0 on success, EWOULDBLOCK if non-blocking and operation
                would cause the thread to block, otherwise the errno error.
  */
        @result 0 on success, EWOULDBLOCK if non-blocking and operation
                would cause the thread to block, otherwise the errno error.
  */

-errno_t sock_send(socket_t so, const struct msghdr *msg, int flags, size_t *sentlen);
+extern errno_t sock_send(socket_t so, const struct msghdr *msg, int flags,
+    size_t *sentlen);

 
 /*!
        @function sock_sendmbuf
 
 /*!
        @function sock_sendmbuf


@@ -261,17 +303,20 @@ errno_t sock_send(socket_t so, const struct msghdr *msg, int flags, size_t *sent
                would cause the thread to block, otherwise the errno error.
                Regardless of return value, the mbuf chain 'data' will be freed.
  */
                would cause the thread to block, otherwise the errno error.
                Regardless of return value, the mbuf chain 'data' will be freed.
  */

-errno_t sock_sendmbuf(socket_t so, const struct msghdr *msg, mbuf_t data, int flags, size_t *sentlen);
+extern errno_t sock_sendmbuf(socket_t so, const struct msghdr *msg, mbuf_t data,
+    int flags, size_t *sentlen);

 
 /*!
        @function sock_shutdown
        @discussion Shutdown one or both directions of a connection. See
                'man 2 shutdown' for more information.
        @param so The socket.
 
 /*!
        @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.
+       @param how SHUT_RD - shutdown receive.
+               SHUT_WR - shutdown send.
+               SHUT_RDWR - shutdown both.

        @result 0 on success otherwise the errno error.
  */
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_shutdown(socket_t so, int how);
+extern errno_t sock_shutdown(socket_t so, int how);

 
 /*!
        @function sock_socket
 
 /*!
        @function sock_socket


@@ -287,20 +332,21 @@ errno_t sock_shutdown(socket_t so, int how);
        @param new_so Upon success, a reference to the new socket.
        @result 0 on success otherwise the errno error.
  */
        @param new_so Upon success, a reference to the new socket.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_socket(int domain, int type, int protocol, sock_upcall callback,
-                          void* cookie, socket_t *new_so);
+extern errno_t sock_socket(int domain, int type, int protocol,
+    sock_upcall callback, void *cookie, socket_t *new_so);

 
 /*!
        @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
 
 /*!
        @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.
+               using sock_close may leave a file descriptor pointing to the
+               closed socket, resulting in undefined behavior.

  */
  */

-void   sock_close(socket_t so);
+extern void sock_close(socket_t so);

 
 

-/*!
+#ifdef KERNEL_PRIVATE
+/*

        @function sock_retain
        @discussion Prevents the socket from closing
        @param so The socket to close.  Increment a retain count on the
        @function sock_retain
        @discussion Prevents the socket from closing
        @param so The socket to close.  Increment a retain count on the


@@ -310,9 +356,9 @@ void        sock_close(socket_t so);
                that socket. It is used in conjunction with
                sock_release(socket_t so).
  */
                that socket. It is used in conjunction with
                sock_release(socket_t so).
  */

-void   sock_retain(socket_t so);
+extern void sock_retain(socket_t so);

 
 

-/*!
+/*

        @function sock_release
        @discussion Decrement the retain count and close the socket if the
                retain count reaches zero.
        @function sock_release
        @discussion Decrement the retain count and close the socket if the
                retain count reaches zero.


@@ -320,7 +366,8 @@ void        sock_retain(socket_t so);
                on a socket acquired with sock_retain. When the last retain
                count is reached, this will call sock_close to close the socket.
  */
                on a socket acquired with sock_retain. When the last retain
                count is reached, this will call sock_close to close the socket.
  */

-void   sock_release(socket_t so);
+extern void sock_release(socket_t so);
+#endif /* KERNEL_PRIVATE */

 
 /*!
        @function sock_setpriv
 
 /*!
        @function sock_setpriv


@@ -330,7 +377,7 @@ void        sock_release(socket_t so);
        @param on Indicate whether or not the SS_PRIV flag should be set.
        @result 0 on success otherwise the errno error.
  */
        @param on Indicate whether or not the SS_PRIV flag should be set.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_setpriv(socket_t so, int on);
+extern errno_t sock_setpriv(socket_t so, int on);

 
 /*!
        @function sock_isconnected
 
 /*!
        @function sock_isconnected


@@ -338,20 +385,20 @@ errno_t sock_setpriv(socket_t so, int on);
        @param so The socket to check.
        @result 0 - socket is not connected. 1 - socket is connected.
  */
        @param so The socket to check.
        @result 0 - socket is not connected. 1 - socket is connected.
  */

-int sock_isconnected(socket_t so);
+extern int sock_isconnected(socket_t so);

 
 /*!
        @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.
 
 /*!
        @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.
  */
                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.
  */

-int sock_isnonblocking(socket_t so);
+extern int sock_isnonblocking(socket_t so);

 
 /*!
        @function sock_gettype
 
 /*!
        @function sock_gettype


@@ -360,15 +407,15 @@ int sock_isnonblocking(socket_t so);
                parameters following so are NULL, that information is not
                retrieved.
        @param so The socket to check.
                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, etc...). May be NULL.
-       @param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...). May be NULL.
+       @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.
  */
        @param protocol The socket protocol. May be NULL.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol);
+extern errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol);

 
 #ifdef KERNEL_PRIVATE
 
 #ifdef KERNEL_PRIVATE

-/*!
+/*

        @function sock_nointerrupt
        @discussion Disables interrupt on socket buffers (sets SB_NOINTR on
                send and receive socket buffers).
        @function sock_nointerrupt
        @discussion Disables interrupt on socket buffers (sets SB_NOINTR on
                send and receive socket buffers).


@@ -376,6 +423,52 @@ errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol);
        @param on Indicate whether or not the SB_NOINTR flag should be set.
        @result 0 on success otherwise the errno error.
  */
        @param on Indicate whether or not the SB_NOINTR flag should be set.
        @result 0 on success otherwise the errno error.
  */

-errno_t sock_nointerrupt(socket_t so, int on);
-#endif KERNEL_PRIVATE
-#endif __KPI_SOCKET__
+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);
+#endif /* KERNEL_PRIVATE */
+
+__END_DECLS
+#endif /* __KPI_SOCKET__ */