share/man/man9/socket.9

   1 .\"-
   2 .\" Copyright (c) 2006 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  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
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd April 12, 2013
  29 .Dt SOCKET 9
  30 .Os
  31 .Sh NAME
  32 .Nm socket
  33 .Nd "kernel socket interface"
  34 .Sh SYNOPSIS
  35 .In sys/socket.h
  36 .In sys/socketvar.h
  37 .Ft int
  38 .Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td"
  39 .Ft void
  40 .Fn soclose "struct socket *so"
  41 .Ft int
  42 .Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td"
  43 .Ft int
  44 .Fo socreate
  45 .Fa "int dom" "struct socket **aso" "int type" "int proto"
  46 .Fa "struct ucred *cred" "struct thread *td"
  47 .Fc
  48 .Ft int
  49 .Fn sogetopt "struct socket *so" "struct sockopt *sopt"
  50 .Ft int
  51 .Fo soreceive
  52 .Fa "struct socket *so" "struct sockaddr **psa" "struct uio *uio"
  53 .Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp"
  54 .Fc
  55 .Ft int
  56 .Fn sosetopt "struct socket *so" "struct sockopt *sopt"
  57 .Ft int
  58 .Fo sosend
  59 .Fa "struct socket *so" "struct sockaddr *addr" "struct uio *uio"
  60 .Fa "struct mbuf *top" "struct mbuf *control" "int flags" "struct thread *td"
  61 .Fc
  62 .Ft int
  63 .Fn soshutdown "struct socket *so" "int how"
  64 .Sh DESCRIPTION
  65 The kernel
  66 .Nm
  67 programming interface permits in-kernel consumers to interact with
  68 local and network socket objects in a manner similar to that permitted using
  69 the
  70 .Xr socket 2
  71 user API.
  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
  75 operate directly on
  76 .Vt "struct socket"
  77 pointers.
  78 .Pp
  79 Except where otherwise indicated,
  80 .Nm
  81 functions may sleep, and are not appropriate for use in an
  82 .Xr ithread 9
  83 context or while holding non-sleepable kernel locks.
  84 .Ss Creating and Destroying Sockets
  85 A new socket may be created using
  86 .Fn socreate .
  87 As with
  88 .Xr socket 2 ,
  89 arguments specify the requested domain, type, and protocol via
  90 .Fa dom , type ,
  91 and
  92 .Fa proto .
  93 The socket is returned via
  94 .Fa aso
  95 on success.
  96 In addition, the credential used to authorize operations associated with the
  97 socket will be passed via
  98 .Fa cred
  99 (and will be cached for the lifetime of the socket), and the thread
 100 performing the operation via
 101 .Fa td .
 102 .Em Warning :
 103 authorization of the socket creation operation will be performed
 104 using the thread credential for some protocols (such as raw sockets).
 105 .Pp
 106 Sockets may be closed and freed using
 107 .Fn soclose ,
 108 which has similar semantics to
 109 .Xr close 2 .
 110 .Ss Connections and Addresses
 111 The
 112 .Fn sobind
 113 function is equivalent to the
 114 .Xr bind 2
 115 system call, and binds the socket
 116 .Fa so
 117 to the address
 118 .Fa nam .
 119 The operation would be authorized using the credential on thread
 120 .Fa td .
 121 .Pp
 122 The
 123 .Fn soconnect
 124 function is equivalent to the
 125 .Xr connect 2
 126 system call, and initiates a connection on the socket
 127 .Fa so
 128 to the address
 129 .Fa nam .
 130 The operation will be authorized using the credential on thread
 131 .Fa td .
 132 Unlike the user system call,
 133 .Fn soconnect
 134 returns immediately; the caller may
 135 .Xr msleep 9
 136 on
 137 .Fa so->so_timeo
 138 while holding the socket mutex and waiting for the
 139 .Dv SS_ISCONNECTING
 140 flag to clear or
 141 .Fa so->so_error
 142 to become non-zero.
 143 If
 144 .Fn soconnect
 145 fails, the caller must manually clear the
 146 .Dv SS_ISCONNECTING
 147 flag.
 148 .Pp
 149 The
 150 .Fn soshutdown
 151 function is equivalent to the
 152 .Xr shutdown 2
 153 system call, and causes part or all of a connection on a socket to be closed
 154 down.
 155 .Ss Socket Options
 156 The
 157 .Fn sogetopt
 158 function is equivalent to the
 159 .Xr getsockopt 2
 160 system call, and retrieves a socket option on socket
 161 .Fa so .
 162 The
 163 .Fn sosetopt
 164 function is equivalent to the
 165 .Xr setsockopt 2
 166 system call, and sets a socket option on socket
 167 .Fa so .
 168 .Pp
 169 The second argument in both
 170 .Fn sogetopt
 171 and
 172 .Fn sosetopt
 173 is the
 174 .Fa sopt
 175 pointer to a
 176 .Vt "struct sopt"
 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"
 181 .It Va sopt_dir
 182 Set to
 183 .Dv SOPT_SET
 184 or
 185 .Dv SOPT_GET
 186 depending on whether this is a get or set operation.
 187 .It Va sopt_level
 188 Specify the level in the network stack the operation is targeted at; for
 189 example,
 190 .Dv SOL_SOCKET .
 191 .It Va sopt_name
 192 Specify the name of the socket option to set.
 193 .It Va sopt_val
 194 Kernel space pointer to the argument value for the socket option.
 195 .It Va sopt_valsize
 196 Size of the argument value in bytes.
 197 .El
 198 .Ss Socket I/O
 199 The
 200 .Fn soreceive
 201 function is equivalent to the
 202 .Xr recvmsg 2
 203 system call, and attempts to receive bytes of data from the socket
 204 .Fa so ,
 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
 207 .Fa uio
 208 argument, or as an mbuf chain returned to the caller via
 209 .Fa mp0 ,
 210 avoiding a data copy.
 211 The
 212 .Fa uio
 213 must always be
 214 .Pf non- Dv NULL .
 215 If
 216 .Fa mp0
 217 is
 218 .Pf non- Dv NULL ,
 219 only the
 220 .Pf uio_resid
 221 of
 222 .Fa uio
 223 is used.
 224 The caller may optionally retrieve a socket address on a protocol with the
 225 .Dv PR_ADDR
 226 capability by providing storage via
 227 .Pf non- Dv NULL
 228 .Fa psa
 229 argument.
 230 The caller may optionally retrieve control data mbufs via a
 231 .Pf non- Dv NULL
 232 .Fa controlp
 233 argument.
 234 Optional flags may be passed to
 235 .Fn soreceive
 236 via a
 237 .Pf non- Dv NULL
 238 .Fa flagsp
 239 argument, and use the same flag name space as the
 240 .Xr recvmsg 2
 241 system call.
 242 .Pp
 243 The
 244 .Fn sosend
 245 function is equivalent to the
 246 .Xr sendmsg 2
 247 system call, and attempts to send bytes of data via the socket
 248 .Fa so ,
 249 optionally blocking if data cannot be immediately sent.
 250 Data may be sent directly from kernel or user memory via the
 251 .Fa uio
 252 argument, or as an mbuf chain via
 253 .Fa top ,
 254 avoiding a data copy.
 255 Only one of the
 256 .Fa uio
 257 or
 258 .Fa top
 259 pointers may be
 260 .Pf non- Dv NULL .
 261 An optional destination address may be specified via a
 262 .Pf non- Dv NULL
 263 .Fa addr
 264 argument, which may result in an implicit connect if supported by the
 265 protocol.
 266 The caller may optionally send control data mbufs via a
 267 .Pf non- Dv NULL
 268 .Fa control
 269 argument.
 270 Flags may be passed to
 271 .Fn sosend
 272 using the
 273 .Fa flags
 274 argument, and use the same flag name space as the
 275 .Xr sendmsg 2
 276 system call.
 277 .Pp
 278 Kernel callers running in
 279 .Xr ithread 9
 280 context, or with a mutex held, will wish to use non-blocking sockets and pass
 281 the
 282 .Dv MSG_DONTWAIT
 283 flag in order to prevent these functions from sleeping.
 284 .Sh SEE ALSO
 285 .Xr bind 2 ,
 286 .Xr close 2 ,
 287 .Xr connect 2 ,
 288 .Xr getsockopt 2 ,
 289 .Xr recv 2 ,
 290 .Xr send 2 ,
 291 .Xr setsockopt 2 ,
 292 .Xr shutdown 2 ,
 293 .Xr socket 2 ,
 294 .Xr ng_ksocket 4 ,
 295 .Xr ithread 9 ,
 296 .Xr msleep 9 ,
 297 .Xr ucred 9
 298 .Sh HISTORY
 299 The
 300 .Xr socket 2
 301 system call appeared in
 302 .Bx 4.2 .
 303 This manual page was introduced in
 304 .Fx 7.0 .
 305 .Sh AUTHORS
 306 This manual page was written by
 307 .An Robert Watson .
 308 .Sh BUGS
 309 The use of explicitly passed credentials, credentials hung from explicitly
 310 passed threads, the credential on
 311 .Dv curthread ,
 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
 315 .Fa td
 316 arguments should be
 317 .Fa cred
 318 arguments, or simply not be present at all.
 319 .Pp
 320 The caller may need to manually clear
 321 .Dv SS_ISCONNECTING
 322 if
 323 .Fn soconnect
 324 returns an error.
 325 .Pp
 326 The
 327 .Dv MSG_DONTWAIT
 328 flag is not implemented for
 329 .Fn sosend ,
 330 and may not always work with
 331 .Fn soreceive
 332 when zero copy sockets are enabled.
 333 .Pp
 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.
 336 .Pp
 337 The
 338 .Fn soref
 339 and
 340 .Fn sorele
 341 functions are not described, and in most cases should not be used, due to
 342 confusing and potentially incorrect interactions when
 343 .Fn sorele
 344 is last called after
 345 .Fn soclose .