2 .\" Copyright (c) 2006 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd "kernel socket interface"
38 .Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td"
40 .Fn soclose "struct socket *so"
42 .Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td"
45 .Fa "int dom" "struct socket **aso" "int type" "int proto"
46 .Fa "struct ucred *cred" "struct thread *td"
49 .Fn sogetopt "struct socket *so" "struct sockopt *sopt"
52 .Fa "struct socket *so" "struct sockaddr **psa" "struct uio *uio"
53 .Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp"
56 .Fn sosetopt "struct socket *so" "struct sockopt *sopt"
59 .Fa "struct socket *so" "struct sockaddr *addr" "struct uio *uio"
60 .Fa "struct mbuf *top" "struct mbuf *control" "int flags" "struct thread *td"
63 .Fn soshutdown "struct socket *so" "int how"
67 programming interface permits in-kernel consumers to interact with
68 local and network socket objects in a manner similar to that permitted using
72 These interfaces are appropriate for use by distributed file systems and
73 other network-aware kernel services.
74 While the user API operates on file descriptors, the kernel interfaces
79 Except where otherwise indicated,
81 functions may sleep, and are not appropriate for use in an
83 context or while holding non-sleepable kernel locks.
84 .Ss Creating and Destroying Sockets
85 A new socket may be created using
89 arguments specify the requested domain, type, and protocol via
93 The socket is returned via
96 In addition, the credential used to authorize operations associated with the
97 socket will be passed via
99 (and will be cached for the lifetime of the socket), and the thread
100 performing the operation via
103 authorization of the socket creation operation will be performed
104 using the thread credential for some protocols (such as raw sockets).
106 Sockets may be closed and freed using
108 which has similar semantics to
110 .Ss Connections and Addresses
113 function is equivalent to the
115 system call, and binds the socket
119 The operation would be authorized using the credential on thread
124 function is equivalent to the
126 system call, and initiates a connection on the socket
130 The operation will be authorized using the credential on thread
132 Unlike the user system call,
134 returns immediately; the caller may
138 while holding the socket mutex and waiting for the
145 fails, the caller must manually clear the
151 function is equivalent to the
153 system call, and causes part or all of a connection on a socket to be closed
158 function is equivalent to the
160 system call, and retrieves a socket option on socket
164 function is equivalent to the
166 system call, and sets a socket option on socket
169 The second argument in both
177 describing the socket option operation.
178 The caller-allocated structure must be zeroed, and then have its fields
179 initialized to specify socket option operation arguments:
180 .Bl -tag -width ".Va sopt_valsize"
186 depending on whether this is a get or set operation.
188 Specify the level in the network stack the operation is targeted at; for
192 Specify the name of the socket option to set.
194 Kernel space pointer to the argument value for the socket option.
196 Size of the argument value in bytes.
201 function is equivalent to the
203 system call, and attempts to receive bytes of data from the socket
205 optionally blocking awaiting for data if none is ready to read.
206 Data may be retrieved directly to kernel or user memory via the
208 argument, or as an mbuf chain returned to the caller via
210 avoiding a data copy.
224 The caller may optionally retrieve a socket address on a protocol with the
226 capability by providing storage via
230 The caller may optionally retrieve control data mbufs via a
234 Optional flags may be passed to
239 argument, and use the same flag name space as the
245 function is equivalent to the
247 system call, and attempts to send bytes of data via the socket
249 optionally blocking if data cannot be immediately sent.
250 Data may be sent directly from kernel or user memory via the
252 argument, or as an mbuf chain via
254 avoiding a data copy.
261 An optional destination address may be specified via a
264 argument, which may result in an implicit connect if supported by the
266 The caller may optionally send control data mbufs via a
270 Flags may be passed to
274 argument, and use the same flag name space as the
278 Kernel callers running in
280 context, or with a mutex held, will wish to use non-blocking sockets and pass
283 flag in order to prevent these functions from sleeping.
301 system call appeared in
303 This manual page was introduced in
306 This manual page was written by
309 The use of explicitly passed credentials, credentials hung from explicitly
310 passed threads, the credential on
312 and the cached credential from
313 socket creation time is inconsistent, and may lead to unexpected behaviour.
314 It is possible that several of the
318 arguments, or simply not be present at all.
320 The caller may need to manually clear
328 flag is not implemented for
330 and may not always work with
332 when zero copy sockets are enabled.
334 This manual page does not describe how to register socket upcalls or monitor
335 a socket for readability/writability without using blocking I/O.
341 functions are not described, and in most cases should not be used, due to
342 confusing and potentially incorrect interactions when