/*
* Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
*
- * @APPLE_LICENSE_HEADER_START@
+ * @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. Please obtain a copy of the License at
- * http://www.opensource.apple.com/apsl/ and read it before using this
- * file.
+ * 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
* Please see the License for the specific language governing rights and
* limitations under the License.
*
- * @APPLE_LICENSE_HEADER_END@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
/*!
@header kpi_socket.h
#include <sys/types.h>
#include <sys/kernel_types.h>
+#include <sys/socket.h>
+
+__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:
-
+
@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.
@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);
+ int flags, sock_upcall callback, void* cookie, socket_t *new_so);
/*!
@function sock_bind
errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags);
#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.
specified.
*/
errno_t sock_connectwait(socket_t so, const struct timeval *tv);
-#endif KERNEL_PRIVATE
+#endif /* KERNEL_PRIVATE */
/*!
@function sock_getpeername
@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);
+errno_t sock_getpeername(socket_t so, struct sockaddr *peername,
+ int peernamelen);
/*!
@function sock_getsockname
@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);
+errno_t sock_getsockname(socket_t so, struct sockaddr *sockname,
+ int socknamelen);
/*!
@function sock_getsockopt
@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);
+errno_t sock_getsockopt(socket_t so, int level, int optname, void *optval,
+ int *optlen);
/*!
@function sock_ioctl
@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);
+errno_t sock_setsockopt(socket_t so, int level, int optname, const void *optval,
+ int optlen);
/*!
@function sock_listen
@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);
+errno_t sock_receive(socket_t so, struct msghdr *msg, int flags,
+ size_t *recvdlen);
/*!
@function sock_receivembuf
@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);
+errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data,
+ int flags, size_t *recvlen);
/*!
@function sock_send
@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);
+errno_t sock_send(socket_t so, const struct msghdr *msg, int flags,
+ size_t *sentlen);
/*!
@function sock_sendmbuf
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);
+errno_t sock_sendmbuf(socket_t so, const struct msghdr *msg, mbuf_t data,
+ int flags, size_t *sentlen);
/*!
@function sock_shutdown
@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);
+ void* cookie, socket_t *new_so);
/*!
@function sock_close
*/
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
*/
void sock_retain(socket_t so);
-/*!
+/*
@function sock_release
@discussion Decrement the retain count and close the socket if the
retain count reaches zero.
count is reached, this will call sock_close to close the socket.
*/
void sock_release(socket_t so);
+#endif /* KERNEL_PRIVATE */
/*!
@function sock_setpriv
@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.
errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol);
#ifdef KERNEL_PRIVATE
-/*!
+/*
@function sock_nointerrupt
@discussion Disables interrupt on socket buffers (sets SB_NOINTR on
send and receive socket buffers).
@result 0 on success otherwise the errno error.
*/
errno_t sock_nointerrupt(socket_t so, int on);
-#endif KERNEL_PRIVATE
-#endif __KPI_SOCKET__
+
+/*
+ @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.
+ */
+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.
+ */
+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.
+ */
+void sock_freeaddr(struct sockaddr *sockname);
+#endif /* KERNEL_PRIVATE */
+
+__END_DECLS
+#endif /* __KPI_SOCKET__ */
projects / apple / xnu.git / blobdiff