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