bsd/sys/kpi_socket.h

   1 /*
   2  * Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*!
  23         @header kpi_socket.h
  24         This header defines an API for creating and interacting with sockets
  25         in the kernel. It is possible to create sockets in the kernel
  26         without an associated file descriptor. In some cases, a reference to
  27         the socket may be known while the file descriptor is not. These
  28         functions can be used for interacting with sockets in the kernel.
  29         The API is similar to the user space socket API.
  30  */
  31 #ifndef __KPI_SOCKET__
  32 #define __KPI_SOCKET__
  33
  34 #include <sys/types.h>
  35 #include <sys/kernel_types.h>
  36 #include <sys/socket.h>
  37
  38 struct timeval;
  39
  40 /*!
  41         @typedef sock_upcall
  42
  43         @discussion sock_upcall is used by a socket to notify an in kernel
  44                 client that data is waiting. Instead of making blocking calls in
  45                 the kernel, a client can specify an upcall which will be called
  46                 when data is available or the socket is ready for sending.
  47
  48                 Calls to your upcall function are not serialized and may be
  49                 called concurrently from multiple threads in the kernel.
  50
  51                 Your upcall function will be called when:
  52
  53         @param so A reference to the socket that's ready.
  54         @param cookie The cookie passed in when the socket was created.
  55         @param waitf Indicates whether or not it's safe to block.
  56 */
  57 typedef void (*sock_upcall)(socket_t so, void* cookie, int waitf);
  58
  59 /*!
  60         @function sock_accept
  61         @discussion Accepts an incoming connection on a socket. See 'man 2
  62                 accept' for more information. Allocating a socket in this manner
  63                 creates a socket with no associated file descriptor.
  64         @param so The listening socket you'd like to accept a connection on.
  65         @param from A pointer to a socket address that will be filled in
  66                 with the address the connection is from.
  67         @param fromlen Maximum length of from.
  68         @param flags Supports MSG_DONTWAIT and MSG_USEUPCALL. If
  69                 MSG_DONTWAIT is set, accept will return EWOULDBLOCK if there are
  70                 no connections ready to be accepted. If MSG_USEUPCALL is set,
  71                 the created socket will use the same upcall function attached to
  72                 the original socket.
  73         @param callback A notifier function to be called when an event
  74                 occurs on the socket. This may be NULL.
  75         @param cookie A cookie passed directly to the callback.
  76         @param new_so Upon success, *new_so will be a reference to a new
  77                 socket for tracking the connection.
  78         @result 0 on success otherwise the errno error.
  79  */
  80 errno_t sock_accept(socket_t so, struct sockaddr *from, int fromlen,
  81                                         int flags, sock_upcall callback, void* cookie,
  82                                         socket_t *new_so);
  83
  84 /*!
  85         @function sock_bind
  86         @discussion Binds a socket to a specific address. See 'man 2 bind'
  87                 for more information.
  88         @param so The socket to be bound.
  89         @param to The local address the socket should be bound to.
  90         @result 0 on success otherwise the errno error.
  91  */
  92 errno_t sock_bind(socket_t so, const struct sockaddr *to);
  93
  94 /*!
  95         @function sock_connect
  96         @discussion Initiates a connection on the socket. See 'man 2
  97                 connect' for more information.
  98         @param so The socket to be connect.
  99         @param to The remote address the socket should connect to.
 100         @param flags Flags for connecting. The only flag supported so far is
 101                 MSG_DONTWAIT. MSG_DONTWAIT will perform a non-blocking connect.
 102                 sock_connect will return immediately with EINPROGRESS. The
 103                 upcall, if supplied, will be called when the connection is
 104                 completed.
 105         @result 0 on success, EINPROGRESS for a non-blocking connect that
 106                 has not completed, otherwise the errno error.
 107  */
 108 errno_t sock_connect(socket_t so, const struct sockaddr *to, int flags);
 109
 110 #ifdef KERNEL_PRIVATE
 111 /*!
 112         This function was added to support NFS. NFS does something funny,
 113         setting a short timeout and checking to see if it should abort the
 114         connect every two seconds. Ideally, NFS would use the upcall to be
 115         notified when the connect is complete.
 116
 117         If you feel you need to use this function, please contact us to
 118         explain why.
 119
 120         @function sock_connectwait
 121         @discussion Allows a caller to wait on a socket connect.
 122         @param so The socket being connected.
 123         @param tv The amount of time to wait.
 124         @result 0 on success otherwise the errno error. EINPROGRESS will be
 125                 returned if the connection did not complete in the timeout
 126                 specified.
 127  */
 128 errno_t sock_connectwait(socket_t so, const struct timeval *tv);
 129 #endif KERNEL_PRIVATE
 130
 131 /*!
 132         @function sock_getpeername
 133         @discussion Retrieves the remote address of a connected socket. See
 134                 'man 2 getpeername'.
 135         @param so The socket.
 136         @param peername Storage for the peer name.
 137         @param peernamelen Length of storage for the peer name.
 138         @result 0 on success otherwise the errno error.
 139  */
 140 errno_t sock_getpeername(socket_t so, struct sockaddr *peername, int peernamelen);
 141
 142 /*!
 143         @function sock_getsockname
 144         @discussion Retrieves the local address of a socket. See 'man 2
 145                 getsockname'.
 146         @param so The socket.
 147         @param sockname Storage for the local name.
 148         @param socknamelen Length of storage for the socket name.
 149         @result 0 on success otherwise the errno error.
 150  */
 151 errno_t sock_getsockname(socket_t so, struct sockaddr *sockname, int socknamelen);
 152
 153 /*!
 154         @function sock_getsockopt
 155         @discussion Retrieves a socket option. See 'man 2 getsockopt'.
 156         @param so The socket.
 157         @param level Level of the socket option.
 158         @param optname The option name.
 159         @param optval The option value.
 160         @param optlen The length of optval, returns the actual length.
 161         @result 0 on success otherwise the errno error.
 162  */
 163 errno_t sock_getsockopt(socket_t so, int level, int optname, void *optval, int *optlen);
 164
 165 /*!
 166         @function sock_ioctl
 167         @discussion Performs an ioctl operation on a socket. See 'man 2 ioctl'.
 168         @param so The socket.
 169         @param request The ioctl name.
 170         @param argp The argument.
 171         @result 0 on success otherwise the errno error.
 172  */
 173 errno_t sock_ioctl(socket_t so, unsigned long request, void *argp);
 174
 175 /*!
 176         @function sock_setsockopt
 177         @discussion Sets a socket option. See 'man 2 setsockopt'.
 178         @param so The socket.
 179         @param level Level of the socket option.
 180         @param optname The option name.
 181         @param optval The option value.
 182         @param optlen The length of optval.
 183         @result 0 on success otherwise the errno error.
 184  */
 185 errno_t sock_setsockopt(socket_t so, int level, int optname, const void *optval, int optlen);
 186
 187 /*!
 188         @function sock_listen
 189         @discussion Indicate that the socket should start accepting incoming
 190                 connections. See 'man 2 listen'.
 191         @param so The socket.
 192         @param backlog The maximum length of the queue of pending connections.
 193         @result 0 on success otherwise the errno error.
 194  */
 195 errno_t sock_listen(socket_t so, int backlog);
 196
 197 /*!
 198         @function sock_receive
 199         @discussion Receive data from a socket. Similar to recvmsg. See 'man
 200                 2 recvmsg' for more information about receiving data.
 201         @param so The socket.
 202         @param msg The msg describing how the data should be received.
 203         @param flags See 'man 2 recvmsg'.
 204         @param recvdlen Number of bytes received, same as return value of
 205                 userland recvmsg.
 206         @result 0 on success, EWOULDBLOCK if non-blocking and operation
 207                 would cause the thread to block, otherwise the errno error.
 208  */
 209 errno_t sock_receive(socket_t so, struct msghdr *msg, int flags, size_t *recvdlen);
 210
 211 /*!
 212         @function sock_receivembuf
 213         @discussion Receive data from a socket. Similar to sock_receive
 214                 though data is returned as a chain of mbufs. See 'man 2 recvmsg'
 215                 for more information about receiving data.
 216         @param so The socket.
 217         @param msg The msg describing how the data should be received. May
 218                 be NULL. The msg_iov is ignored.
 219         @param data Upon return *data will be a reference to an mbuf chain
 220                 containing the data received. This eliminates copying the data
 221                 out of the mbufs. Caller is responsible for freeing the mbufs.
 222         @param flags See 'man 2 recvmsg'.
 223         @param recvlen Maximum number of bytes to receive in the mbuf chain.
 224                 Upon return, this value will be set to the number of bytes
 225                 received, same as return value of userland recvmsg.
 226         @result 0 on success, EWOULDBLOCK if non-blocking and operation
 227                 would cause the thread to block, otherwise the errno error.
 228  */
 229 errno_t sock_receivembuf(socket_t so, struct msghdr *msg, mbuf_t *data, int flags, size_t *recvlen);
 230
 231 /*!
 232         @function sock_send
 233         @discussion Send data on a socket. Similar to sendmsg. See 'man 2
 234                 sendmsg' for more information about sending data.
 235         @param so The socket.
 236         @param msg The msg describing how the data should be sent. Any
 237                 pointers must point to data in the kernel.
 238         @param flags See 'man 2 sendmsg'.
 239         @param sentlen The number of bytes sent.
 240         @result 0 on success, EWOULDBLOCK if non-blocking and operation
 241                 would cause the thread to block, otherwise the errno error.
 242  */
 243 errno_t sock_send(socket_t so, const struct msghdr *msg, int flags, size_t *sentlen);
 244
 245 /*!
 246         @function sock_sendmbuf
 247         @discussion Send data in an mbuf on a socket. Similar to sock_send
 248                 only the data to be sent is taken from the mbuf chain.
 249         @param so The socket.
 250         @param msg The msg describing how the data should be sent. The
 251                 msg_iov is ignored. msg may be NULL.
 252         @param data The mbuf chain of data to send.
 253         @param flags See 'man 2 sendmsg'.
 254         @param sentlen The number of bytes sent.
 255         @result 0 on success, EWOULDBLOCK if non-blocking and operation
 256                 would cause the thread to block, otherwise the errno error.
 257                 Regardless of return value, the mbuf chain 'data' will be freed.
 258  */
 259 errno_t sock_sendmbuf(socket_t so, const struct msghdr *msg, mbuf_t data, int flags, size_t *sentlen);
 260
 261 /*!
 262         @function sock_shutdown
 263         @discussion Shutdown one or both directions of a connection. See
 264                 'man 2 shutdown' for more information.
 265         @param so The socket.
 266         @param how SHUT_RD - shutdown receive. SHUT_WR - shutdown send. SHUT_RDWR - shutdown both.
 267         @result 0 on success otherwise the errno error.
 268  */
 269 errno_t sock_shutdown(socket_t so, int how);
 270
 271 /*!
 272         @function sock_socket
 273         @discussion Allocate a socket. Allocating a socket in this manner
 274                 creates a socket with no associated file descriptor. For more
 275                 information, see 'man 2 socket'.
 276         @param domain The socket domain (PF_INET, etc...).
 277         @param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...).
 278         @param protocol The socket protocol.
 279         @param callback A notifier function to be called when an event
 280                 occurs on the socket. This may be NULL.
 281         @param cookie A cookie passed directly to the callback.
 282         @param new_so Upon success, a reference to the new socket.
 283         @result 0 on success otherwise the errno error.
 284  */
 285 errno_t sock_socket(int domain, int type, int protocol, sock_upcall callback,
 286                            void* cookie, socket_t *new_so);
 287
 288 /*!
 289         @function sock_close
 290         @discussion Close the socket.
 291         @param so The socket to close. This should only ever be a socket
 292                 created with sock_socket. Closing a socket created in user space
 293                 using sock_close may leave a file descriptor pointing to the closed
 294                 socket, resulting in undefined behavior.
 295  */
 296 void    sock_close(socket_t so);
 297
 298 /*!
 299         @function sock_retain
 300         @discussion Prevents the socket from closing
 301         @param so The socket to close.  Increment a retain count on the
 302                 socket, preventing it from being closed when sock_close is
 303                 called. This is used when a File Descriptor is passed (and
 304                 closed) from userland and the kext wants to keep ownership of
 305                 that socket. It is used in conjunction with
 306                 sock_release(socket_t so).
 307  */
 308 void    sock_retain(socket_t so);
 309
 310 /*!
 311         @function sock_release
 312         @discussion Decrement the retain count and close the socket if the
 313                 retain count reaches zero.
 314         @param so The socket to release. This is used to release ownership
 315                 on a socket acquired with sock_retain. When the last retain
 316                 count is reached, this will call sock_close to close the socket.
 317  */
 318 void    sock_release(socket_t so);
 319
 320 /*!
 321         @function sock_setpriv
 322         @discussion Set the privileged bit in the socket. Allows for
 323                 operations that require root privileges.
 324         @param so The socket on which to modify the SS_PRIV flag.
 325         @param on Indicate whether or not the SS_PRIV flag should be set.
 326         @result 0 on success otherwise the errno error.
 327  */
 328 errno_t sock_setpriv(socket_t so, int on);
 329
 330 /*!
 331         @function sock_isconnected
 332         @discussion Returns whether or not the socket is connected.
 333         @param so The socket to check.
 334         @result 0 - socket is not connected. 1 - socket is connected.
 335  */
 336 int sock_isconnected(socket_t so);
 337
 338 /*!
 339         @function sock_isnonblocking
 340         @discussion Returns whether or not the socket is non-blocking. In
 341                 the context of this KPI, non-blocking means that functions to
 342                 perform operations on a socket will not wait for completion.
 343
 344                 To enable or disable blocking, use the FIONBIO ioctl. The
 345                 parameter is an int. If the int is zero, the socket will block.
 346                 If the parameter is non-zero, the socket will not block.
 347         @result 0 - socket will block. 1 - socket will not block.
 348  */
 349 int sock_isnonblocking(socket_t so);
 350
 351 /*!
 352         @function sock_gettype
 353         @discussion Retrieves information about the socket. This is the same
 354                 information that was used to create the socket. If any of the
 355                 parameters following so are NULL, that information is not
 356                 retrieved.
 357         @param so The socket to check.
 358         @param domain The domain of the socket (PF_INET, etc...). May be NULL.
 359         @param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...). May be NULL.
 360         @param protocol The socket protocol. May be NULL.
 361         @result 0 on success otherwise the errno error.
 362  */
 363 errno_t sock_gettype(socket_t so, int *domain, int *type, int *protocol);
 364
 365 #ifdef KERNEL_PRIVATE
 366 /*!
 367         @function sock_nointerrupt
 368         @discussion Disables interrupt on socket buffers (sets SB_NOINTR on
 369                 send and receive socket buffers).
 370         @param so The socket to modify.
 371         @param on Indicate whether or not the SB_NOINTR flag should be set.
 372         @result 0 on success otherwise the errno error.
 373  */
 374 errno_t sock_nointerrupt(socket_t so, int on);
 375 #endif KERNEL_PRIVATE
 376 #endif __KPI_SOCKET__