1/*
2 * Copyright (c) 2008-2011 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/*!
29	@header kpi_socket.h
30	This header defines an API for creating and interacting with sockets
31	in the kernel. It is possible to create sockets in the kernel
32	without an associated file descriptor. In some cases, a reference to
33	the socket may be known while the file descriptor is not. These
34	functions can be used for interacting with sockets in the kernel.
35	The API is similar to the user space socket API.
36 */
37#ifndef __KPI_SOCKET__
38#define __KPI_SOCKET__
39
40#include <sys/types.h>
41#include <sys/kernel_types.h>
42#include <sys/socket.h>
43
44__BEGIN_DECLS
45
46struct timeval;
47
48/*!
49	@typedef sock_upcall
50
51	@discussion sock_upcall is used by a socket to notify an in kernel
52		client that data is waiting. Instead of making blocking calls in
53		the kernel, a client can specify an upcall which will be called
54		when data is available or the socket is ready for sending.
55
56		Calls to your upcall function are not serialized and may be
57		called concurrently from multiple threads in the kernel.
58
59		Your upcall function will be called:
60		    when there is data more than the low water mark for reading,
61		    or when there is space for a write,
62		    or when there is a connection to accept,
63		    or when a socket is connected,
64		    or when a socket is closed or disconnected
65
66	@param so A reference to the socket that's ready.
67	@param cookie The cookie passed in when the socket was created.
68	@param waitf Indicates whether or not it's safe to block.
69*/
70typedef void (*sock_upcall)(socket_t so, void *cookie, int waitf);
71
72/*!
73	@function sock_accept
74	@discussion Accepts an incoming connection on a socket. See 'man 2
75		accept' for more information. Allocating a socket in this manner
76		creates a socket with no associated file descriptor.
77	@param so The listening socket you'd like to accept a connection on.
78	@param from A pointer to a socket address that will be filled in
79		with the address the connection is from.
80	@param fromlen Maximum length of from.
81	@param flags Supports MSG_DONTWAIT and MSG_USEUPCALL. If
82		MSG_DONTWAIT is set, accept will return EWOULDBLOCK if there are
83		no connections ready to be accepted. If MSG_USEUPCALL is set,
84		the created socket will use the same upcall function attached to
85		the original socket.
86	@param callback A notifier function to be called when an event
87		occurs on the socket. This may be NULL.
88	@param cookie A cookie passed directly to the callback.
89	@param new_so Upon success, *new_so will be a reference to a new
90		socket for tracking the connection.
91	@result 0 on success otherwise the errno error.
92 */
93extern errno_t sock_accept(socket_t so, struct sockaddr *from, int fromlen,
94    int flags, sock_upcall callback, void *cookie, socket_t *new_so);
95
96/*!
97	@function sock_bind
98	@discussion Binds a socket to a specific address. See 'man 2 bind'
99		for more information.
100	@param so The socket to be bound.
101	@param to The local address the socket should be bound to.
102	@result 0 on success otherwise the errno error.
103 */
104extern errno_t sock_bind(socket_t so, const struct sockaddr *to);
105
106/*!
107	@function sock_connect
108	@discussion Initiates a connection on the socket. See 'man 2
109		connect' for more information.
110	@param so The socket to be connect.
111	@param to The remote address the socket should connect to.
112	@param flags Flags for connecting. The only flag supported so far is
113		MSG_DONTWAIT. MSG_DONTWAIT will perform a non-blocking connect.
114		sock_connect will return immediately with EINPROGRESS. The
115		upcall, if supplied, will be called when the connection is
116		completed.
117	@result 0 on success, EINPROGRESS for a non-blocking connect that
118		has not completed, otherwise the errno error.
119 */
120extern errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags);
121
122#ifdef KERNEL_PRIVATE
123/*
124	This function was added to support NFS. NFS does something funny,
125	setting a short timeout and checking to see if it should abort the
126	connect every two seconds. Ideally, NFS would use the upcall to be
127	notified when the connect is complete.
128
129	If you feel you need to use this function, please contact us to
130	explain why.
131
132	@function sock_connectwait
133	@discussion Allows a caller to wait on a socket connect.
134	@param so The socket being connected.
135	@param tv The amount of time to wait.
136	@result 0 on success otherwise the errno error. EINPROGRESS will be
137		returned if the connection did not complete in the timeout
138		specified.
139 */
140extern errno_t sock_connectwait(socket_t so, const struct timeval *tv);
141#endif /* KERNEL_PRIVATE */
142
143/*!
144	@function sock_getpeername
145	@discussion Retrieves the remote address of a connected socket. See
146		'man 2 getpeername'.
147	@param so The socket.
148	@param peername Storage for the peer name.
149	@param peernamelen Length of storage for the peer name.
150	@result 0 on success otherwise the errno error.
151 */
152extern errno_t sock_getpeername(socket_t so, struct sockaddr *peername,
153    int peernamelen);
154
155/*!
156	@function sock_getsockname
157	@discussion Retrieves the local address of a socket. See 'man 2
158		getsockname'.
159	@param so The socket.
160	@param sockname Storage for the local name.
161	@param socknamelen Length of storage for the socket name.
162	@result 0 on success otherwise the errno error.
163 */
164extern errno_t sock_getsockname(socket_t so, struct sockaddr *sockname,
165    int socknamelen);
166
167/*!
168	@function sock_getsockopt
169	@discussion Retrieves a socket option. See 'man 2 getsockopt'.
170	@param so The socket.
171	@param level Level of the socket option.
172	@param optname The option name.
173	@param optval The option value.
174	@param optlen The length of optval, returns the actual length.
175	@result 0 on success otherwise the errno error.
176 */
177extern errno_t sock_getsockopt(socket_t so, int level, int optname,
178    void *optval, int *optlen);
179
180/*!
181	@function sock_ioctl
182	@discussion Performs an ioctl operation on a socket. See 'man 2 ioctl'.
183	@param so The socket.
184	@param request The ioctl name.
185	@param argp The argument.
186	@result 0 on success otherwise the errno error.
187 */
188extern errno_t sock_ioctl(socket_t so, unsigned long request, void *argp);
189
190/*!
191	@function sock_setsockopt
192	@discussion Sets a socket option. See 'man 2 setsockopt'.
193	@param so The socket.
194	@param level Level of the socket option.
195	@param optname The option name.
196	@param optval The option value.
197	@param optlen The length of optval.
198	@result 0 on success otherwise the errno error.
199 */
200extern errno_t sock_setsockopt(socket_t so, int level, int optname,
201    const void *optval, int optlen);
202
203#ifdef KERNEL_PRIVATE
204/*
205	This function was added to support AFP setting the traffic class
206	for a backup stream within a wireless LAN or over link-local address.
207
208	If you feel you need to use this function, please contact us to
209	explain why.
210
211	@function sock_settclassopt
212	@discussion Allows a caller to set the traffic class.
213	@param so The socket.
214	@param optval The option value.
215	@param optlen The length of optval.
216	@result 0 on success otherwise the errno error.
217 */
218extern errno_t sock_settclassopt(socket_t so, const void* optval, size_t optlen);
219
220/*
221	This function was added to support AFP getting the traffic class
222	set on a stream.
223
224	This is also a private API, please contact us if you need to use it.
225
226	@function sockgettclassopt
227	@discussion Allows a caller to get the traffic class.
228	@param so The socket.
229	@param optval The option value.
230	@param optlen The length of optval, returns the actual length.
231	@result 0 on success otherwise the errno error.
232*/
233extern errno_t sock_gettclassopt(socket_t so, void* optval, size_t* optlen);
234
235#ifdef XNU_KERNEL_PRIVATE
236extern void socket_set_traffic_mgt_flags_locked(socket_t so, u_int32_t flags);
237extern void socket_clear_traffic_mgt_flags_locked(socket_t so, u_int32_t flags);
238#endif /* XNU_KERNEL_PRIVATE */
239#ifdef BSD_KERNEL_PRIVATE
240extern void socket_set_traffic_mgt_flags(socket_t so, u_int32_t flags);
241extern void socket_clear_traffic_mgt_flags(socket_t so, u_int32_t flags);
242extern errno_t socket_defunct(struct proc *, socket_t so, int);
243#endif /* BSD_KERNEL_PRIVATE */
244#endif /* KERNEL_PRIVATE */
245
246/*!
247	@function sock_listen
248	@discussion Indicate that the socket should start accepting incoming
249		connections. See 'man 2 listen'.
250	@param so The socket.
251	@param backlog The maximum length of the queue of pending connections.
252	@result 0 on success otherwise the errno error.
253 */
254extern errno_t sock_listen(socket_t so, int backlog);
255
256/*!
257	@function sock_receive
258	@discussion Receive data from a socket. Similar to recvmsg. See 'man
259		2 recvmsg' for more information about receiving data.
260	@param so The socket.
261	@param msg The msg describing how the data should be received.
262	@param flags See 'man 2 recvmsg'.
263	@param recvdlen Number of bytes received, same as return value of
264		userland recvmsg.
265	@result 0 on success, EWOULDBLOCK if non-blocking and operation
266		would cause the thread to block, otherwise the errno error.
267 */
268extern errno_t sock_receive(socket_t so, struct msghdr *msg, int flags,
269    size_t *recvdlen);
270
271/*!
272	@function sock_receivembuf
273	@discussion Receive data from a socket. Similar to sock_receive
274		though data is returned as a chain of mbufs. See 'man 2 recvmsg'
275		for more information about receiving data.
276	@param so The socket.
277	@param msg The msg describing how the data should be received. May
278		be NULL. The msg_iov is ignored.
279	@param data Upon return *data will be a reference to an mbuf chain
280		containing the data received. This eliminates copying the data
281		out of the mbufs. Caller is responsible for freeing the mbufs.
282	@param flags See 'man 2 recvmsg'.
283	@param recvlen Maximum number of bytes to receive in the mbuf chain.
284		Upon return, this value will be set to the number of bytes
285		received, same as return value of userland recvmsg.
286	@result 0 on success, EWOULDBLOCK if non-blocking and operation
287		would cause the thread to block, otherwise the errno error.
288 */
289extern errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data,
290    int flags, size_t *recvlen);
291
292/*!
293	@function sock_send
294	@discussion Send data on a socket. Similar to sendmsg. See 'man 2
295		sendmsg' for more information about sending data.
296	@param so The socket.
297	@param msg The msg describing how the data should be sent. Any
298		pointers must point to data in the kernel.
299	@param flags See 'man 2 sendmsg'.
300	@param sentlen The number of bytes sent.
301	@result 0 on success, EWOULDBLOCK if non-blocking and operation
302		would cause the thread to block, otherwise the errno error.
303 */
304extern errno_t sock_send(socket_t so, const struct msghdr *msg, int flags,
305    size_t *sentlen);
306
307/*!
308	@function sock_sendmbuf
309	@discussion Send data in an mbuf on a socket. Similar to sock_send
310		only the data to be sent is taken from the mbuf chain.
311	@param so The socket.
312	@param msg The msg describing how the data should be sent. The
313		msg_iov is ignored. msg may be NULL.
314	@param data The mbuf chain of data to send.
315	@param flags See 'man 2 sendmsg'.
316	@param sentlen The number of bytes sent.
317	@result 0 on success, EWOULDBLOCK if non-blocking and operation
318		would cause the thread to block, otherwise the errno error.
319		Regardless of return value, the mbuf chain 'data' will be freed.
320 */
321extern errno_t sock_sendmbuf(socket_t so, const struct msghdr *msg, mbuf_t data,
322    int flags, size_t *sentlen);
323
324/*!
325	@function sock_shutdown
326	@discussion Shutdown one or both directions of a connection. See
327		'man 2 shutdown' for more information.
328	@param so The socket.
329	@param how SHUT_RD - shutdown receive.
330		SHUT_WR - shutdown send.
331		SHUT_RDWR - shutdown both.
332	@result 0 on success otherwise the errno error.
333 */
334extern errno_t sock_shutdown(socket_t so, int how);
335
336/*!
337	@function sock_socket
338	@discussion Allocate a socket. Allocating a socket in this manner
339		creates a socket with no associated file descriptor. For more
340		information, see 'man 2 socket'.
341	@param domain The socket domain (PF_INET, etc...).
342	@param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...).
343	@param protocol The socket protocol.
344	@param callback A notifier function to be called when an event
345		occurs on the socket. This may be NULL.
346	@param cookie A cookie passed directly to the callback.
347	@param new_so Upon success, a reference to the new socket.
348	@result 0 on success otherwise the errno error.
349 */
350extern errno_t sock_socket(int domain, int type, int protocol,
351    sock_upcall callback, void *cookie, socket_t *new_so);
352
353/*!
354	@function sock_close
355	@discussion Close the socket.
356	@param so The socket to close. This should only ever be a socket
357		created with sock_socket. Closing a socket created in user space
358		using sock_close may leave a file descriptor pointing to the
359		closed socket, resulting in undefined behavior.
360 */
361extern void sock_close(socket_t so);
362
363#ifdef KERNEL_PRIVATE
364/*
365	@function sock_retain
366	@discussion Prevents the socket from closing
367	@param so The socket to close.  Increment a retain count on the
368		socket, preventing it from being closed when sock_close is
369		called. This is used when a File Descriptor is passed (and
370		closed) from userland and the kext wants to keep ownership of
371		that socket. It is used in conjunction with
372		sock_release(socket_t so).
373 */
374extern void sock_retain(socket_t so);
375
376/*
377	@function sock_release
378	@discussion Decrement the retain count and close the socket if the
379		retain count reaches zero.
380	@param so The socket to release. This is used to release ownership
381		on a socket acquired with sock_retain. When the last retain
382		count is reached, this will call sock_close to close the socket.
383 */
384extern void sock_release(socket_t so);
385#endif /* KERNEL_PRIVATE */
386
387/*!
388	@function sock_setpriv
389	@discussion Set the privileged bit in the socket. Allows for
390		operations that require root privileges.
391	@param so The socket on which to modify the SS_PRIV flag.
392	@param on Indicate whether or not the SS_PRIV flag should be set.
393	@result 0 on success otherwise the errno error.
394 */
395extern errno_t sock_setpriv(socket_t so, int on);
396
397/*!
398	@function sock_isconnected
399	@discussion Returns whether or not the socket is connected.
400	@param so The socket to check.
401	@result 0 - socket is not connected. 1 - socket is connected.
402 */
403extern int sock_isconnected(socket_t so);
404
405/*!
406	@function sock_isnonblocking
407	@discussion Returns whether or not the socket is non-blocking. In
408		the context of this KPI, non-blocking means that functions to
409		perform operations on a socket will not wait for completion.
410
411		To enable or disable blocking, use the FIONBIO ioctl. The
412		parameter is an int. If the int is zero, the socket will block.
413		If the parameter is non-zero, the socket will not block.
414	@result 0 - socket will block. 1 - socket will not block.
415 */
416extern int sock_isnonblocking(socket_t so);
417
418/*!
419	@function sock_gettype
420	@discussion Retrieves information about the socket. This is the same
421		information that was used to create the socket. If any of the
422		parameters following so are NULL, that information is not
423		retrieved.
424	@param so The socket to check.
425	@param domain The domain of the socket (PF_INET, ...). May be NULL.
426	@param type The socket type (SOCK_STREAM, SOCK_DGRAM, ...). May be NULL.
427	@param protocol The socket protocol. May be NULL.
428	@result 0 on success otherwise the errno error.
429 */
430extern errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol);
431
432#ifdef KERNEL_PRIVATE
433/*
434	@function sock_nointerrupt
435	@discussion Disables interrupt on socket buffers (sets SB_NOINTR on
436		send and receive socket buffers).
437	@param so The socket to modify.
438	@param on Indicate whether or not the SB_NOINTR flag should be set.
439	@result 0 on success otherwise the errno error.
440 */
441extern errno_t sock_nointerrupt(socket_t so, int on);
442
443/*
444	@function sock_getlistener
445	@discussion Retrieves the listening socket of a pre-accepted socket,
446		i.e. a socket which is still in the incomplete/completed list.
447		Once a socket has been accepted, the information pertaining
448		to its listener is no longer available.  Therefore, modules
449		interested in finding out the listening socket should install
450		the appropriate socket filter callback (sf_attach) which gets
451		invoked prior to the socket being fully accepted, and call
452		this routine at such a time to obtain the listener.  Callers
453		are guaranteed that the listener socket will not go away
454		during the sf_attach callback, and therefore the value is
455		safe to be used only in that callback context.  Callers should
456		therefore take note that the listening socket's lock will be
457		held throughout the duration of the callback.
458	@param so The pre-accepted socket.
459	@result Non-NULL value which indicates the listening socket; otherwise,
460		NULL if the socket is not in the incomplete/completed list
461		of a listener.
462 */
463extern socket_t sock_getlistener(socket_t so);
464
465/*
466	@function sock_getaddr
467	@discussion Retrieves the local or remote address of a socket.
468		This is a composite of sock_getpeername and sock_getsockname,
469		except that the allocated socket address is returned to the
470		caller, and that the caller is reponsible for calling
471		sock_freeaddr once finished with it.
472	@param so The socket.
473	@param psockname Pointer to the storage for the socket name.
474	@param peername 0 for local address, and non-zero for peer address.
475	@result 0 on success otherwise the errno error.
476 */
477extern errno_t sock_getaddr(socket_t so, struct sockaddr **psockname,
478    int peername);
479
480/*
481	@function sock_freeaddr
482	@discussion Frees the socket address allocated by sock_getaddr.
483	@param sockname The socket name to be freed.
484 */
485extern void sock_freeaddr(struct sockaddr *sockname);
486
487/*
488	@function sock_setupcall
489	@discussion Set the notifier function to be called when an event
490		occurs on the socket. This may be set to NULL to disable
491		further notifications. Setting the function does not
492		affect currently notifications about to be sent or being sent.
493		Note: When this function is used on a socket passed from userspace
494		it is crucial to call sock_retain() on the socket otherwise a callback
495		could be dispatched on a closed socket and cause a crash.
496	@param sock The socket.
497	@param callback The notifier function
498	@param context A cookie passed directly to the callback
499*/
500extern errno_t sock_setupcall(socket_t sock, sock_upcall callback, void* context);
501
502#endif /* KERNEL_PRIVATE */
503
504__END_DECLS
505#endif /* __KPI_SOCKET__ */
506