1/*
2 * Copyright (c) 2008-2017 Apple 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#ifdef KERNEL_PRIVATE
73/*!
74 @typedef sock_evupcall
75
76 @discussion sock_evupcall is used by a socket to notify an in kernel
77 client when an event occurs. Instead of making blocking calls in
78 the kernel, a client can specify an upcall which will be called
79 when an event status is available.
80 @param so A reference to the socket that's ready.
81 @param cookie The cookie passed in when the socket was created.
82 @param event Indicates the event as defined by SO_FILT_HINT_*
83*/
84typedef void (*sock_evupcall)(socket_t so, void *cookie, u_int32_t event);
85#endif /* KERNEL_PRIVATE */
86
87/*!
88 @function sock_accept
89 @discussion Accepts an incoming connection on a socket. See 'man 2
90 accept' for more information. Allocating a socket in this manner
91 creates a socket with no associated file descriptor.
92 @param so The listening socket you'd like to accept a connection on.
93 @param from A pointer to a socket address that will be filled in
94 with the address the connection is from.
95 @param fromlen Maximum length of from.
96 @param flags Supports MSG_DONTWAIT and MSG_USEUPCALL. If
97 MSG_DONTWAIT is set, accept will return EWOULDBLOCK if there are
98 no connections ready to be accepted. If MSG_USEUPCALL is set,
99 the created socket will use the same upcall function attached to
100 the original socket.
101 @param callback A notifier function to be called when an event
102 occurs on the socket. This may be NULL.
103 @param cookie A cookie passed directly to the callback.
104 @param new_so Upon success, *new_so will be a reference to a new
105 socket for tracking the connection.
106 @result 0 on success otherwise the errno error.
107 */
108#ifdef KERNEL_PRIVATE
109extern errno_t sock_accept_internal(socket_t so, struct sockaddr *from, int fromlen,
110 int flags, sock_upcall callback, void *cookie, socket_t *new_so);
111
112#define sock_accept(so, from, fromlen, flags, callback, cookie, new_so) \
113 sock_accept_internal((so), (from), (fromlen), (flags), (callback), \
114 (cookie), (new_so))
115#else
116extern errno_t sock_accept(socket_t so, struct sockaddr *from, int fromlen,
117 int flags, sock_upcall callback, void *cookie, socket_t *new_so);
118#endif /* KERNEL_PRIVATE */
119
120/*!
121 @function sock_bind
122 @discussion Binds a socket to a specific address. See 'man 2 bind'
123 for more information.
124 @param so The socket to be bound.
125 @param to The local address the socket should be bound to.
126 @result 0 on success otherwise the errno error.
127 */
128extern errno_t sock_bind(socket_t so, const struct sockaddr *to);
129
130/*!
131 @function sock_connect
132 @discussion Initiates a connection on the socket. See 'man 2
133 connect' for more information.
134 @param so The socket to be connect.
135 @param to The remote address the socket should connect to.
136 @param flags Flags for connecting. The only flag supported so far is
137 MSG_DONTWAIT. MSG_DONTWAIT will perform a non-blocking connect.
138 sock_connect will return immediately with EINPROGRESS. The
139 upcall, if supplied, will be called when the connection is
140 completed.
141 @result 0 on success, EINPROGRESS for a non-blocking connect that
142 has not completed, otherwise the errno error.
143 */
144extern errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags);
145
146#ifdef KERNEL_PRIVATE
147/*
148 This function was added to support NFS. NFS does something funny,
149 setting a short timeout and checking to see if it should abort the
150 connect every two seconds. Ideally, NFS would use the upcall to be
151 notified when the connect is complete.
152
153 If you feel you need to use this function, please contact us to
154 explain why.
155
156 @function sock_connectwait
157 @discussion Allows a caller to wait on a socket connect.
158 @param so The socket being connected.
159 @param tv The amount of time to wait.
160 @result 0 on success otherwise the errno error. EINPROGRESS will be
161 returned if the connection did not complete in the timeout
162 specified.
163 */
164extern errno_t sock_connectwait(socket_t so, const struct timeval *tv);
165#endif /* KERNEL_PRIVATE */
166
167/*!
168 @function sock_getpeername
169 @discussion Retrieves the remote address of a connected socket. See
170 'man 2 getpeername'.
171 @param so The socket.
172 @param peername Storage for the peer name.
173 @param peernamelen Length of storage for the peer name.
174 @result 0 on success otherwise the errno error.
175 */
176extern errno_t sock_getpeername(socket_t so, struct sockaddr *peername,
177 int peernamelen);
178
179/*!
180 @function sock_getsockname
181 @discussion Retrieves the local address of a socket. See 'man 2
182 getsockname'.
183 @param so The socket.
184 @param sockname Storage for the local name.
185 @param socknamelen Length of storage for the socket name.
186 @result 0 on success otherwise the errno error.
187 */
188extern errno_t sock_getsockname(socket_t so, struct sockaddr *sockname,
189 int socknamelen);
190
191/*!
192 @function sock_getsockopt
193 @discussion Retrieves a socket option. See 'man 2 getsockopt'.
194 @param so The socket.
195 @param level Level of the socket option.
196 @param optname The option name.
197 @param optval The option value.
198 @param optlen The length of optval, returns the actual length.
199 @result 0 on success otherwise the errno error.
200 */
201extern errno_t sock_getsockopt(socket_t so, int level, int optname,
202 void *optval, int *optlen);
203
204/*!
205 @function sock_ioctl
206 @discussion Performs an ioctl operation on a socket. See 'man 2 ioctl'.
207 @param so The socket.
208 @param request The ioctl name.
209 @param argp The argument.
210 @result 0 on success otherwise the errno error.
211 */
212extern errno_t sock_ioctl(socket_t so, unsigned long request, void *argp);
213
214/*!
215 @function sock_setsockopt
216 @discussion Sets a socket option. See 'man 2 setsockopt'.
217 @param so The socket.
218 @param level Level of the socket option.
219 @param optname The option name.
220 @param optval The option value.
221 @param optlen The length of optval.
222 @result 0 on success otherwise the errno error.
223 */
224extern errno_t sock_setsockopt(socket_t so, int level, int optname,
225 const void *optval, int optlen);
226
227#ifdef KERNEL_PRIVATE
228/*
229 This function was added to support AFP setting the traffic class
230 for a backup stream within a wireless LAN or over link-local address.
231
232 If you feel you need to use this function, please contact us to
233 explain why.
234
235 @function sock_settclassopt
236 @discussion Allows a caller to set the traffic class.
237 @param so The socket.
238 @param optval The option value.
239 @param optlen The length of optval.
240 @result 0 on success otherwise the errno error.
241 */
242extern errno_t sock_settclassopt(socket_t so, const void* optval, size_t optlen);
243
244/*
245 This function was added to support AFP getting the traffic class
246 set on a stream.
247
248 This is also a private API, please contact us if you need to use it.
249
250 @function sockgettclassopt
251 @discussion Allows a caller to get the traffic class.
252 @param so The socket.
253 @param optval The option value.
254 @param optlen The length of optval, returns the actual length.
255 @result 0 on success otherwise the errno error.
256*/
257extern errno_t sock_gettclassopt(socket_t so, void* optval, size_t* optlen);
258
259#ifdef XNU_KERNEL_PRIVATE
260extern void socket_set_traffic_mgt_flags_locked(socket_t so, u_int8_t flags);
261extern void socket_clear_traffic_mgt_flags_locked(socket_t so, u_int8_t flags);
262#endif /* XNU_KERNEL_PRIVATE */
263#ifdef BSD_KERNEL_PRIVATE
264extern void socket_set_traffic_mgt_flags(socket_t so, u_int8_t flags);
265extern void socket_clear_traffic_mgt_flags(socket_t so, u_int8_t flags);
266extern errno_t socket_defunct(struct proc *, socket_t so, int);
267extern errno_t sock_receive_internal(socket_t, struct msghdr *, mbuf_t *,
268 int, size_t *);
269#endif /* BSD_KERNEL_PRIVATE */
270#endif /* KERNEL_PRIVATE */
271
272/*!
273 @function sock_listen
274 @discussion Indicate that the socket should start accepting incoming
275 connections. See 'man 2 listen'.
276 @param so The socket.
277 @param backlog The maximum length of the queue of pending connections.
278 @result 0 on success otherwise the errno error.
279 */
280extern errno_t sock_listen(socket_t so, int backlog);
281
282/*!
283 @function sock_receive
284 @discussion Receive data from a socket. Similar to recvmsg. See 'man
285 2 recvmsg' for more information about receiving data.
286 @param so The socket.
287 @param msg The msg describing how the data should be received.
288 @param flags See 'man 2 recvmsg'.
289 @param recvdlen Number of bytes received, same as return value of
290 userland recvmsg.
291 @result 0 on success, EWOULDBLOCK if non-blocking and operation
292 would cause the thread to block, otherwise the errno error.
293 */
294extern errno_t sock_receive(socket_t so, struct msghdr *msg, int flags,
295 size_t *recvdlen);
296
297/*!
298 @function sock_receivembuf
299 @discussion Receive data from a socket. Similar to sock_receive
300 though data is returned as a chain of mbufs. See 'man 2 recvmsg'
301 for more information about receiving data.
302 @param so The socket.
303 @param msg The msg describing how the data should be received. May
304 be NULL. The msg_iov is ignored.
305 @param data Upon return *data will be a reference to an mbuf chain
306 containing the data received. This eliminates copying the data
307 out of the mbufs. Caller is responsible for freeing the mbufs.
308 @param flags See 'man 2 recvmsg'.
309 @param recvlen Maximum number of bytes to receive in the mbuf chain.
310 Upon return, this value will be set to the number of bytes
311 received, same as return value of userland recvmsg.
312 @result 0 on success, EWOULDBLOCK if non-blocking and operation
313 would cause the thread to block, otherwise the errno error.
314 */
315extern errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data,
316 int flags, size_t *recvlen);
317
318/*!
319 @function sock_send
320 @discussion Send data on a socket. Similar to sendmsg. See 'man 2
321 sendmsg' for more information about sending data.
322 @param so The socket.
323 @param msg The msg describing how the data should be sent. Any
324 pointers must point to data in the kernel.
325 @param flags See 'man 2 sendmsg'.
326 @param sentlen The number of bytes sent.
327 @result 0 on success, EWOULDBLOCK if non-blocking and operation
328 would cause the thread to block, otherwise the errno error.
329 */
330extern errno_t sock_send(socket_t so, const struct msghdr *msg, int flags,
331 size_t *sentlen);
332
333/*!
334 @function sock_sendmbuf
335 @discussion Send data in an mbuf on a socket. Similar to sock_send
336 only the data to be sent is taken from the mbuf chain.
337 @param so The socket.
338 @param msg The msg describing how the data should be sent. The
339 msg_iov is ignored. msg may be NULL.
340 @param data The mbuf chain of data to send.
341 @param flags See 'man 2 sendmsg'.
342 @param sentlen The number of bytes sent.
343 @result 0 on success, EWOULDBLOCK if non-blocking and operation
344 would cause the thread to block, otherwise the errno error.
345 Regardless of return value, the mbuf chain 'data' will be freed.
346 */
347extern errno_t sock_sendmbuf(socket_t so, const struct msghdr *msg, mbuf_t data,
348 int flags, size_t *sentlen);
349
350/*!
351 @function sock_shutdown
352 @discussion Shutdown one or both directions of a connection. See
353 'man 2 shutdown' for more information.
354 @param so The socket.
355 @param how SHUT_RD - shutdown receive.
356 SHUT_WR - shutdown send.
357 SHUT_RDWR - shutdown both.
358 @result 0 on success otherwise the errno error.
359 */
360extern errno_t sock_shutdown(socket_t so, int how);
361
362/*!
363 @function sock_socket
364 @discussion Allocate a socket. Allocating a socket in this manner
365 creates a socket with no associated file descriptor. For more
366 information, see 'man 2 socket'.
367 @param domain The socket domain (PF_INET, etc...).
368 @param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...).
369 @param protocol The socket protocol.
370 @param callback A notifier function to be called when an event
371 occurs on the socket. This may be NULL.
372 @param cookie A cookie passed directly to the callback.
373 @param new_so Upon success, a reference to the new socket.
374 @result 0 on success otherwise the errno error.
375 */
376#ifdef KERNEL_PRIVATE
377extern errno_t sock_socket_internal(int domain, int type, int protocol,
378 sock_upcall callback, void *cookie, socket_t *new_so);
379
380#define sock_socket(domain, type, protocol, callback, cookie, new_so) \
381 sock_socket_internal((domain), (type), (protocol), \
382 (callback), (cookie), (new_so))
383#else
384extern errno_t sock_socket(int domain, int type, int protocol,
385 sock_upcall callback, void *cookie, socket_t *new_so);
386#endif /* KERNEL_PRIVATE */
387
388/*!
389 @function sock_close
390 @discussion Close the socket.
391 @param so The socket to close. This should only ever be a socket
392 created with sock_socket. Closing a socket created in user space
393 using sock_close may leave a file descriptor pointing to the
394 closed socket, resulting in undefined behavior.
395 */
396extern void sock_close(socket_t so);
397
398#ifdef KERNEL_PRIVATE
399/*
400 @function sock_retain
401 @discussion Prevents the socket from closing
402 @param so The socket to close. Increment a retain count on the
403 socket, preventing it from being closed when sock_close is
404 called. This is used when a File Descriptor is passed (and
405 closed) from userland and the kext wants to keep ownership of
406 that socket. It is used in conjunction with
407 sock_release(socket_t so).
408 */
409extern void sock_retain(socket_t so);
410
411/*
412 @function sock_release
413 @discussion Decrement the retain count and close the socket if the
414 retain count reaches zero.
415 @param so The socket to release. This is used to release ownership
416 on a socket acquired with sock_retain. When the last retain
417 count is reached, this will call sock_close to close the socket.
418 */
419extern void sock_release(socket_t so);
420#endif /* KERNEL_PRIVATE */
421
422/*!
423 @function sock_setpriv
424 @discussion Set the privileged bit in the socket. Allows for
425 operations that require root privileges.
426 @param so The socket on which to modify the SS_PRIV flag.
427 @param on Indicate whether or not the SS_PRIV flag should be set.
428 @result 0 on success otherwise the errno error.
429 */
430extern errno_t sock_setpriv(socket_t so, int on);
431
432/*!
433 @function sock_isconnected
434 @discussion Returns whether or not the socket is connected.
435 @param so The socket to check.
436 @result 0 - socket is not connected. 1 - socket is connected.
437 */
438extern int sock_isconnected(socket_t so);
439
440/*!
441 @function sock_isnonblocking
442 @discussion Returns whether or not the socket is non-blocking. In
443 the context of this KPI, non-blocking means that functions to
444 perform operations on a socket will not wait for completion.
445
446 To enable or disable blocking, use the FIONBIO ioctl. The
447 parameter is an int. If the int is zero, the socket will block.
448 If the parameter is non-zero, the socket will not block.
449 @result 0 - socket will block. 1 - socket will not block.
450 */
451extern int sock_isnonblocking(socket_t so);
452
453/*!
454 @function sock_gettype
455 @discussion Retrieves information about the socket. This is the same
456 information that was used to create the socket. If any of the
457 parameters following so are NULL, that information is not
458 retrieved.
459 @param so The socket to check.
460 @param domain The domain of the socket (PF_INET, ...). May be NULL.
461 @param type The socket type (SOCK_STREAM, SOCK_DGRAM, ...). May be NULL.
462 @param protocol The socket protocol. May be NULL.
463 @result 0 on success otherwise the errno error.
464 */
465extern errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol);
466
467#ifdef KERNEL_PRIVATE
468/*
469 @function sock_nointerrupt
470 @discussion Disables interrupt on socket buffers (sets SB_NOINTR on
471 send and receive socket buffers).
472 @param so The socket to modify.
473 @param on Indicate whether or not the SB_NOINTR flag should be set.
474 @result 0 on success otherwise the errno error.
475 */
476extern errno_t sock_nointerrupt(socket_t so, int on);
477
478/*
479 @function sock_getlistener
480 @discussion Retrieves the listening socket of a pre-accepted socket,
481 i.e. a socket which is still in the incomplete/completed list.
482 Once a socket has been accepted, the information pertaining
483 to its listener is no longer available. Therefore, modules
484 interested in finding out the listening socket should install
485 the appropriate socket filter callback (sf_attach) which gets
486 invoked prior to the socket being fully accepted, and call
487 this routine at such a time to obtain the listener. Callers
488 are guaranteed that the listener socket will not go away
489 during the sf_attach callback, and therefore the value is
490 safe to be used only in that callback context. Callers should
491 therefore take note that the listening socket's lock will be
492 held throughout the duration of the callback.
493 @param so The pre-accepted socket.
494 @result Non-NULL value which indicates the listening socket; otherwise,
495 NULL if the socket is not in the incomplete/completed list
496 of a listener.
497 */
498extern socket_t sock_getlistener(socket_t so);
499
500/*
501 @function sock_getaddr
502 @discussion Retrieves the local or remote address of a socket.
503 This is a composite of sock_getpeername and sock_getsockname,
504 except that the allocated socket address is returned to the
505 caller, and that the caller is reponsible for calling
506 sock_freeaddr once finished with it.
507 @param so The socket.
508 @param psockname Pointer to the storage for the socket name.
509 @param peername 0 for local address, and non-zero for peer address.
510 @result 0 on success otherwise the errno error.
511 */
512extern errno_t sock_getaddr(socket_t so, struct sockaddr **psockname,
513 int peername);
514
515/*
516 @function sock_freeaddr
517 @discussion Frees the socket address allocated by sock_getaddr.
518 @param sockname The socket name to be freed.
519 */
520extern void sock_freeaddr(struct sockaddr *sockname);
521
522/*
523 @function sock_setupcall
524 @discussion Set the notifier function to be called when an event
525 occurs on the socket. This may be set to NULL to disable
526 further notifications. Setting the function does not
527 affect currently notifications about to be sent or being sent.
528 Note: When this function is used on a socket passed from
529 userspace it is crucial to call sock_retain() on the socket
530 otherwise a callback could be dispatched on a closed socket
531 and cause a crash.
532 @param sock The socket.
533 @param callback The notifier function
534 @param context A cookie passed directly to the callback
535*/
536extern errno_t sock_setupcall(socket_t sock, sock_upcall callback,
537 void *context);
538
539/*
540 @function sock_setupcalls
541 @discussion Set the notifier function to be called when an event
542 occurs on the socket. This may be set to NULL to disable
543 further notifications. Setting the function does not
544 affect currently notifications about to be sent or being sent.
545 Note: When this function is used on a socket passed from
546 userspace it is crucial to call sock_retain() on the socket
547 otherwise a callback could be dispatched on a closed socket
548 and cause a crash.
549 @param sock The socket.
550 @param read_callback The read notifier function
551 @param read_context A cookie passed directly to the read callback
552 @param write_callback The write notifier function
553 @param write_context A cookie passed directly to the write callback
554*/
555extern errno_t sock_setupcalls(socket_t sock, sock_upcall read_callback,
556 void *read_context, sock_upcall write_callback, void *write_context);
557
558/*
559 @function sock_setupcalls_locked
560 @discussion The locked version of sock_setupcalls
561 @param locked: When sets, indicates that the callbacks expect to be
562 on a locked socket. Thus, no unlock is done prior to
563 calling the callback.
564 */
565extern void sock_setupcalls_locked(socket_t sock,
566 sock_upcall rcallback, void *rcontext,
567 sock_upcall wcallback, void *wcontext, int locked);
568
569/*
570 @function sock_catchevents
571 @discussion Set the notifier function to be called when an event
572 occurs on the socket. This may be set to NULL to disable
573 further notifications. Setting the function does not
574 affect currently notifications about to be sent or being sent.
575 @param sock The socket.
576 @param event_callback The event notifier function
577 @param event_context A cookie passed directly to the event callback
578 @param event_mask One or more SO_FILT_HINT_* values OR'ed together,
579 indicating the registered event(s).
580*/
581extern errno_t sock_catchevents(socket_t sock, sock_evupcall event_callback,
582 void *event_context, u_int32_t event_mask);
583
584extern void sock_catchevents_locked(socket_t sock, sock_evupcall ecallback,
585 void *econtext, u_int32_t emask);
586
587
588/*
589 @function sock_iskernel
590 @discussion Returns true if the socket was created by the kernel or
591 is owned by the kernel.
592 @param sock The socket.
593 @result True if the kernel owns the socket.
594*/
595extern int sock_iskernel(socket_t);
596#endif /* KERNEL_PRIVATE */
597
598__END_DECLS
599#endif /* __KPI_SOCKET__ */
600