]>
git.saurik.com Git - apple/xnu.git/blob - bsd/sys/kpi_socket.h
2 * Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
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.
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
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.
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
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.
37 #ifndef __KPI_SOCKET__
38 #define __KPI_SOCKET__
40 #include <sys/types.h>
41 #include <sys/kernel_types.h>
42 #include <sys/socket.h>
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.
56 Calls to your upcall function are not serialized and may be
57 called concurrently from multiple threads in the kernel.
59 Your upcall function will be called when:
61 @param so A reference to the socket that's ready.
62 @param cookie The cookie passed in when the socket was created.
63 @param waitf Indicates whether or not it's safe to block.
65 typedef void (*sock_upcall
)(socket_t so
, void* cookie
, int waitf
);
69 @discussion Accepts an incoming connection on a socket. See 'man 2
70 accept' for more information. Allocating a socket in this manner
71 creates a socket with no associated file descriptor.
72 @param so The listening socket you'd like to accept a connection on.
73 @param from A pointer to a socket address that will be filled in
74 with the address the connection is from.
75 @param fromlen Maximum length of from.
76 @param flags Supports MSG_DONTWAIT and MSG_USEUPCALL. If
77 MSG_DONTWAIT is set, accept will return EWOULDBLOCK if there are
78 no connections ready to be accepted. If MSG_USEUPCALL is set,
79 the created socket will use the same upcall function attached to
81 @param callback A notifier function to be called when an event
82 occurs on the socket. This may be NULL.
83 @param cookie A cookie passed directly to the callback.
84 @param new_so Upon success, *new_so will be a reference to a new
85 socket for tracking the connection.
86 @result 0 on success otherwise the errno error.
88 errno_t
sock_accept(socket_t so
, struct sockaddr
*from
, int fromlen
,
89 int flags
, sock_upcall callback
, void* cookie
, socket_t
*new_so
);
93 @discussion Binds a socket to a specific address. See 'man 2 bind'
95 @param so The socket to be bound.
96 @param to The local address the socket should be bound to.
97 @result 0 on success otherwise the errno error.
99 errno_t
sock_bind(socket_t so
, const struct sockaddr
*to
);
102 @function sock_connect
103 @discussion Initiates a connection on the socket. See 'man 2
104 connect' for more information.
105 @param so The socket to be connect.
106 @param to The remote address the socket should connect to.
107 @param flags Flags for connecting. The only flag supported so far is
108 MSG_DONTWAIT. MSG_DONTWAIT will perform a non-blocking connect.
109 sock_connect will return immediately with EINPROGRESS. The
110 upcall, if supplied, will be called when the connection is
112 @result 0 on success, EINPROGRESS for a non-blocking connect that
113 has not completed, otherwise the errno error.
115 errno_t
sock_connect(socket_t so
, const struct sockaddr
*to
, int flags
);
117 #ifdef KERNEL_PRIVATE
119 This function was added to support NFS. NFS does something funny,
120 setting a short timeout and checking to see if it should abort the
121 connect every two seconds. Ideally, NFS would use the upcall to be
122 notified when the connect is complete.
124 If you feel you need to use this function, please contact us to
127 @function sock_connectwait
128 @discussion Allows a caller to wait on a socket connect.
129 @param so The socket being connected.
130 @param tv The amount of time to wait.
131 @result 0 on success otherwise the errno error. EINPROGRESS will be
132 returned if the connection did not complete in the timeout
135 errno_t
sock_connectwait(socket_t so
, const struct timeval
*tv
);
136 #endif /* KERNEL_PRIVATE */
139 @function sock_getpeername
140 @discussion Retrieves the remote address of a connected socket. See
142 @param so The socket.
143 @param peername Storage for the peer name.
144 @param peernamelen Length of storage for the peer name.
145 @result 0 on success otherwise the errno error.
147 errno_t
sock_getpeername(socket_t so
, struct sockaddr
*peername
,
151 @function sock_getsockname
152 @discussion Retrieves the local address of a socket. See 'man 2
154 @param so The socket.
155 @param sockname Storage for the local name.
156 @param socknamelen Length of storage for the socket name.
157 @result 0 on success otherwise the errno error.
159 errno_t
sock_getsockname(socket_t so
, struct sockaddr
*sockname
,
163 @function sock_getsockopt
164 @discussion Retrieves a socket option. See 'man 2 getsockopt'.
165 @param so The socket.
166 @param level Level of the socket option.
167 @param optname The option name.
168 @param optval The option value.
169 @param optlen The length of optval, returns the actual length.
170 @result 0 on success otherwise the errno error.
172 errno_t
sock_getsockopt(socket_t so
, int level
, int optname
, void *optval
,
177 @discussion Performs an ioctl operation on a socket. See 'man 2 ioctl'.
178 @param so The socket.
179 @param request The ioctl name.
180 @param argp The argument.
181 @result 0 on success otherwise the errno error.
183 errno_t
sock_ioctl(socket_t so
, unsigned long request
, void *argp
);
186 @function sock_setsockopt
187 @discussion Sets a socket option. See 'man 2 setsockopt'.
188 @param so The socket.
189 @param level Level of the socket option.
190 @param optname The option name.
191 @param optval The option value.
192 @param optlen The length of optval.
193 @result 0 on success otherwise the errno error.
195 errno_t
sock_setsockopt(socket_t so
, int level
, int optname
, const void *optval
,
199 @function sock_listen
200 @discussion Indicate that the socket should start accepting incoming
201 connections. See 'man 2 listen'.
202 @param so The socket.
203 @param backlog The maximum length of the queue of pending connections.
204 @result 0 on success otherwise the errno error.
206 errno_t
sock_listen(socket_t so
, int backlog
);
209 @function sock_receive
210 @discussion Receive data from a socket. Similar to recvmsg. See 'man
211 2 recvmsg' for more information about receiving data.
212 @param so The socket.
213 @param msg The msg describing how the data should be received.
214 @param flags See 'man 2 recvmsg'.
215 @param recvdlen Number of bytes received, same as return value of
217 @result 0 on success, EWOULDBLOCK if non-blocking and operation
218 would cause the thread to block, otherwise the errno error.
220 errno_t
sock_receive(socket_t so
, struct msghdr
*msg
, int flags
,
224 @function sock_receivembuf
225 @discussion Receive data from a socket. Similar to sock_receive
226 though data is returned as a chain of mbufs. See 'man 2 recvmsg'
227 for more information about receiving data.
228 @param so The socket.
229 @param msg The msg describing how the data should be received. May
230 be NULL. The msg_iov is ignored.
231 @param data Upon return *data will be a reference to an mbuf chain
232 containing the data received. This eliminates copying the data
233 out of the mbufs. Caller is responsible for freeing the mbufs.
234 @param flags See 'man 2 recvmsg'.
235 @param recvlen Maximum number of bytes to receive in the mbuf chain.
236 Upon return, this value will be set to the number of bytes
237 received, same as return value of userland recvmsg.
238 @result 0 on success, EWOULDBLOCK if non-blocking and operation
239 would cause the thread to block, otherwise the errno error.
241 errno_t
sock_receivembuf(socket_t so
, struct msghdr
*msg
, mbuf_t
*data
,
242 int flags
, size_t *recvlen
);
246 @discussion Send data on a socket. Similar to sendmsg. See 'man 2
247 sendmsg' for more information about sending data.
248 @param so The socket.
249 @param msg The msg describing how the data should be sent. Any
250 pointers must point to data in the kernel.
251 @param flags See 'man 2 sendmsg'.
252 @param sentlen The number of bytes sent.
253 @result 0 on success, EWOULDBLOCK if non-blocking and operation
254 would cause the thread to block, otherwise the errno error.
256 errno_t
sock_send(socket_t so
, const struct msghdr
*msg
, int flags
,
260 @function sock_sendmbuf
261 @discussion Send data in an mbuf on a socket. Similar to sock_send
262 only the data to be sent is taken from the mbuf chain.
263 @param so The socket.
264 @param msg The msg describing how the data should be sent. The
265 msg_iov is ignored. msg may be NULL.
266 @param data The mbuf chain of data to send.
267 @param flags See 'man 2 sendmsg'.
268 @param sentlen The number of bytes sent.
269 @result 0 on success, EWOULDBLOCK if non-blocking and operation
270 would cause the thread to block, otherwise the errno error.
271 Regardless of return value, the mbuf chain 'data' will be freed.
273 errno_t
sock_sendmbuf(socket_t so
, const struct msghdr
*msg
, mbuf_t data
,
274 int flags
, size_t *sentlen
);
277 @function sock_shutdown
278 @discussion Shutdown one or both directions of a connection. See
279 'man 2 shutdown' for more information.
280 @param so The socket.
281 @param how SHUT_RD - shutdown receive. SHUT_WR - shutdown send. SHUT_RDWR - shutdown both.
282 @result 0 on success otherwise the errno error.
284 errno_t
sock_shutdown(socket_t so
, int how
);
287 @function sock_socket
288 @discussion Allocate a socket. Allocating a socket in this manner
289 creates a socket with no associated file descriptor. For more
290 information, see 'man 2 socket'.
291 @param domain The socket domain (PF_INET, etc...).
292 @param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...).
293 @param protocol The socket protocol.
294 @param callback A notifier function to be called when an event
295 occurs on the socket. This may be NULL.
296 @param cookie A cookie passed directly to the callback.
297 @param new_so Upon success, a reference to the new socket.
298 @result 0 on success otherwise the errno error.
300 errno_t
sock_socket(int domain
, int type
, int protocol
, sock_upcall callback
,
301 void* cookie
, socket_t
*new_so
);
305 @discussion Close the socket.
306 @param so The socket to close. This should only ever be a socket
307 created with sock_socket. Closing a socket created in user space
308 using sock_close may leave a file descriptor pointing to the closed
309 socket, resulting in undefined behavior.
311 void sock_close(socket_t so
);
313 #ifdef KERNEL_PRIVATE
315 @function sock_retain
316 @discussion Prevents the socket from closing
317 @param so The socket to close. Increment a retain count on the
318 socket, preventing it from being closed when sock_close is
319 called. This is used when a File Descriptor is passed (and
320 closed) from userland and the kext wants to keep ownership of
321 that socket. It is used in conjunction with
322 sock_release(socket_t so).
324 void sock_retain(socket_t so
);
327 @function sock_release
328 @discussion Decrement the retain count and close the socket if the
329 retain count reaches zero.
330 @param so The socket to release. This is used to release ownership
331 on a socket acquired with sock_retain. When the last retain
332 count is reached, this will call sock_close to close the socket.
334 void sock_release(socket_t so
);
335 #endif /* KERNEL_PRIVATE */
338 @function sock_setpriv
339 @discussion Set the privileged bit in the socket. Allows for
340 operations that require root privileges.
341 @param so The socket on which to modify the SS_PRIV flag.
342 @param on Indicate whether or not the SS_PRIV flag should be set.
343 @result 0 on success otherwise the errno error.
345 errno_t
sock_setpriv(socket_t so
, int on
);
348 @function sock_isconnected
349 @discussion Returns whether or not the socket is connected.
350 @param so The socket to check.
351 @result 0 - socket is not connected. 1 - socket is connected.
353 int sock_isconnected(socket_t so
);
356 @function sock_isnonblocking
357 @discussion Returns whether or not the socket is non-blocking. In
358 the context of this KPI, non-blocking means that functions to
359 perform operations on a socket will not wait for completion.
361 To enable or disable blocking, use the FIONBIO ioctl. The
362 parameter is an int. If the int is zero, the socket will block.
363 If the parameter is non-zero, the socket will not block.
364 @result 0 - socket will block. 1 - socket will not block.
366 int sock_isnonblocking(socket_t so
);
369 @function sock_gettype
370 @discussion Retrieves information about the socket. This is the same
371 information that was used to create the socket. If any of the
372 parameters following so are NULL, that information is not
374 @param so The socket to check.
375 @param domain The domain of the socket (PF_INET, etc...). May be NULL.
376 @param type The socket type (SOCK_STREAM, SOCK_DGRAM, etc...). May be NULL.
377 @param protocol The socket protocol. May be NULL.
378 @result 0 on success otherwise the errno error.
380 errno_t
sock_gettype(socket_t so
, int *domain
, int *type
, int *protocol
);
382 #ifdef KERNEL_PRIVATE
384 @function sock_nointerrupt
385 @discussion Disables interrupt on socket buffers (sets SB_NOINTR on
386 send and receive socket buffers).
387 @param so The socket to modify.
388 @param on Indicate whether or not the SB_NOINTR flag should be set.
389 @result 0 on success otherwise the errno error.
391 errno_t
sock_nointerrupt(socket_t so
, int on
);
394 @function sock_getlistener
395 @discussion Retrieves the listening socket of a pre-accepted socket,
396 i.e. a socket which is still in the incomplete/completed list.
397 Once a socket has been accepted, the information pertaining
398 to its listener is no longer available. Therefore, modules
399 interested in finding out the listening socket should install
400 the appropriate socket filter callback (sf_attach) which gets
401 invoked prior to the socket being fully accepted, and call
402 this routine at such a time to obtain the listener. Callers
403 are guaranteed that the listener socket will not go away
404 during the sf_attach callback, and therefore the value is
405 safe to be used only in that callback context. Callers should
406 therefore take note that the listening socket's lock will be
407 held throughout the duration of the callback.
408 @param so The pre-accepted socket.
409 @result Non-NULL value which indicates the listening socket; otherwise,
410 NULL if the socket is not in the incomplete/completed list
413 socket_t
sock_getlistener(socket_t so
);
416 @function sock_getaddr
417 @discussion Retrieves the local or remote address of a socket.
418 This is a composite of sock_getpeername and sock_getsockname,
419 except that the allocated socket address is returned to the
420 caller, and that the caller is reponsible for calling
421 sock_freeaddr once finished with it.
422 @param so The socket.
423 @param psockname Pointer to the storage for the socket name.
424 @param peername 0 for local address, and non-zero for peer address.
425 @result 0 on success otherwise the errno error.
427 errno_t
sock_getaddr(socket_t so
, struct sockaddr
**psockname
, int peername
);
430 @function sock_freeaddr
431 @discussion Frees the socket address allocated by sock_getaddr.
432 @param sockname The socket name to be freed.
434 void sock_freeaddr(struct sockaddr
*sockname
);
435 #endif /* KERNEL_PRIVATE */
438 #endif /* __KPI_SOCKET__ */