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 December 14, 2006
  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 Only one of the
 212 .Fa uio
 213 or
 214 .Fa mp0
 215 pointers may be
 216 .Pf non- Dv NULL .
 217 The caller may optionally retrieve a socket address on a protocol with the
 218 .Dv PR_ADDR
 219 capability by providing storage via
 220 .Pf non- Dv NULL
 221 .Fa psa
 222 argument.
 223 The caller may optionally retrieve control data mbufs via a
 224 .Pf non- Dv NULL
 225 .Fa controlp
 226 argument.
 227 Optional flags may be passed to
 228 .Fn soreceive
 229 via a
 230 .Pf non- Dv NULL
 231 .Fa flagsp
 232 argument, and use the same flag name space as the
 233 .Xr recvmsg 2
 234 system call.
 235 .Pp
 236 The
 237 .Fn sosend
 238 function is equivalent to the
 239 .Xr sendmsg 2
 240 system call, and attempts to send bytes of data via the socket
 241 .Fa so ,
 242 optionally blocking if data cannot be immediately sent.
 243 Data may be sent directly from kernel or user memory via the
 244 .Fa uio
 245 argument, or as an mbuf chain via
 246 .Fa top ,
 247 avoiding a data copy.
 248 Only one of the
 249 .Fa uio
 250 or
 251 .Fa top
 252 pointers may be
 253 .Pf non- Dv NULL .
 254 An optional destination address may be specified via a
 255 .Pf non- Dv NULL
 256 .Fa addr
 257 argument, which may result in an implicit connect if supported by the
 258 protocol.
 259 The caller may optionally send control data mbufs via a
 260 .Pf non- Dv NULL
 261 .Fa control
 262 argument.
 263 Flags may be passed to
 264 .Fn sosend
 265 using the
 266 .Fa flags
 267 argument, and use the same flag name space as the
 268 .Xr sendmsg 2
 269 system call.
 270 .Pp
 271 Kernel callers running in
 272 .Xr ithread 9
 273 context, or with a mutex held, will wish to use non-blocking sockets and pass
 274 the
 275 .Dv MSG_DONTWAIT
 276 flag in order to prevent these functions from sleeping.
 277 .Sh SEE ALSO
 278 .Xr bind 2 ,
 279 .Xr close 2 ,
 280 .Xr connect 2 ,
 281 .Xr getsockopt 2 ,
 282 .Xr recv 2 ,
 283 .Xr send 2 ,
 284 .Xr setsockopt 2 ,
 285 .Xr shutdown 2 ,
 286 .Xr socket 2 ,
 287 .Xr ng_ksocket 4 ,
 288 .Xr ithread 9 ,
 289 .Xr msleep 9 ,
 290 .Xr ucred 9
 291 .Sh HISTORY
 292 The
 293 .Xr socket 2
 294 system call appeared in
 295 .Bx 4.2 .
 296 This manual page was introduced in
 297 .Fx 7.0 .
 298 .Sh AUTHORS
 299 This manual page was written by
 300 .An Robert Watson .
 301 .Sh BUGS
 302 The use of explicitly passed credentials, credentials hung from explicitly
 303 passed threads, the credential on
 304 .Dv curthread ,
 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
 308 .Fa td
 309 arguments should be
 310 .Fa cred
 311 arguments, or simply not be present at all.
 312 .Pp
 313 The caller may need to manually clear
 314 .Dv SS_ISCONNECTING
 315 if
 316 .Fn soconnect
 317 returns an error.
 318 .Pp
 319 The
 320 .Dv MSG_DONTWAIT
 321 flag is not implemented for
 322 .Fn sosend ,
 323 and may not always work with
 324 .Fn soreceive
 325 when zero copy sockets are enabled.
 326 .Pp
 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.
 329 .Pp
 330 The
 331 .Fn soref
 332 and
 333 .Fn sorele
 334 functions are not described, and in most cases should not be used, due to
 335 confusing and potentially incorrect interactions when
 336 .Fn sorele
 337 is last called after
 338 .Fn soclose .