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.
217 The caller may optionally retrieve a socket address on a protocol with the
219 capability by providing storage via
223 The caller may optionally retrieve control data mbufs via a
227 Optional flags may be passed to
232 argument, and use the same flag name space as the
238 function is equivalent to the
240 system call, and attempts to send bytes of data via the socket
242 optionally blocking if data cannot be immediately sent.
243 Data may be sent directly from kernel or user memory via the
245 argument, or as an mbuf chain via
247 avoiding a data copy.
254 An optional destination address may be specified via a
257 argument, which may result in an implicit connect if supported by the
259 The caller may optionally send control data mbufs via a
263 Flags may be passed to
267 argument, and use the same flag name space as the
271 Kernel callers running in
273 context, or with a mutex held, will wish to use non-blocking sockets and pass
276 flag in order to prevent these functions from sleeping.
294 system call appeared in
296 This manual page was introduced in
299 This manual page was written by
302 The use of explicitly passed credentials, credentials hung from explicitly
303 passed threads, the credential on
305 and the cached credential from
306 socket creation time is inconsistent, and may lead to unexpected behaviour.
307 It is possible that several of the
311 arguments, or simply not be present at all.
313 The caller may need to manually clear
321 flag is not implemented for
323 and may not always work with
325 when zero copy sockets are enabled.
327 This manual page does not describe how to register socket upcalls or monitor
328 a socket for readability/writability without using blocking I/O.
334 functions are not described, and in most cases should not be used, due to
335 confusing and potentially incorrect interactions when