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 65The kernel 66.Nm 67programming interface permits in-kernel consumers to interact with 68local and network socket objects in a manner similar to that permitted using 69the 70.Xr socket 2 71user API. 72These interfaces are appropriate for use by distributed file systems and 73other network-aware kernel services. 74While the user API operates on file descriptors, the kernel interfaces 75operate directly on 76.Vt "struct socket" 77pointers. 78.Pp 79Except where otherwise indicated, 80.Nm 81functions may sleep, and are not appropriate for use in an 82.Xr ithread 9 83context or while holding non-sleepable kernel locks. 84.Ss Creating and Destroying Sockets 85A new socket may be created using 86.Fn socreate . 87As with 88.Xr socket 2 , 89arguments specify the requested domain, type, and protocol via 90.Fa dom , type , 91and 92.Fa proto . 93The socket is returned via 94.Fa aso 95on success. 96In addition, the credential used to authorize operations associated with the 97socket will be passed via 98.Fa cred 99(and will be cached for the lifetime of the socket), and the thread 100performing the operation via 101.Fa td . 102.Em Warning : 103authorization of the socket creation operation will be performed 104using the thread credential for some protocols (such as raw sockets). 105.Pp 106Sockets may be closed and freed using 107.Fn soclose , 108which has similar semantics to 109.Xr close 2 . 110.Ss Connections and Addresses 111The 112.Fn sobind 113function is equivalent to the 114.Xr bind 2 115system call, and binds the socket 116.Fa so 117to the address 118.Fa nam . 119The operation would be authorized using the credential on thread 120.Fa td . 121.Pp 122The 123.Fn soconnect 124function is equivalent to the 125.Xr connect 2 126system call, and initiates a connection on the socket 127.Fa so 128to the address 129.Fa nam . 130The operation will be authorized using the credential on thread 131.Fa td . 132Unlike the user system call, 133.Fn soconnect 134returns immediately; the caller may 135.Xr msleep 9 136on 137.Fa so->so_timeo 138while holding the socket mutex and waiting for the 139.Dv SS_ISCONNECTING 140flag to clear or 141.Fa so->so_error 142to become non-zero. 143If 144.Fn soconnect 145fails, the caller must manually clear the 146.Dv SS_ISCONNECTING 147flag. 148.Pp 149The 150.Fn soshutdown 151function is equivalent to the 152.Xr shutdown 2 153system call, and causes part or all of a connection on a socket to be closed 154down. 155.Ss Socket Options 156The 157.Fn sogetopt 158function is equivalent to the 159.Xr getsockopt 2 160system call, and retrieves a socket option on socket 161.Fa so . 162The 163.Fn sosetopt 164function is equivalent to the 165.Xr setsockopt 2 166system call, and sets a socket option on socket 167.Fa so . 168.Pp 169The second argument in both 170.Fn sogetopt 171and 172.Fn sosetopt 173is the 174.Fa sopt 175pointer to a 176.Vt "struct sopt" 177describing the socket option operation. 178The caller-allocated structure must be zeroed, and then have its fields 179initialized to specify socket option operation arguments: 180.Bl -tag -width ".Va sopt_valsize" 181.It Va sopt_dir 182Set to 183.Dv SOPT_SET 184or 185.Dv SOPT_GET 186depending on whether this is a get or set operation. 187.It Va sopt_level 188Specify the level in the network stack the operation is targeted at; for 189example, 190.Dv SOL_SOCKET . 191.It Va sopt_name 192Specify the name of the socket option to set. 193.It Va sopt_val 194Kernel space pointer to the argument value for the socket option. 195.It Va sopt_valsize 196Size of the argument value in bytes. 197.El 198.Ss Socket I/O 199The 200.Fn soreceive 201function is equivalent to the 202.Xr recvmsg 2 203system call, and attempts to receive bytes of data from the socket 204.Fa so , 205optionally blocking awaiting for data if none is ready to read. 206Data may be retrieved directly to kernel or user memory via the 207.Fa uio 208argument, or as an mbuf chain returned to the caller via 209.Fa mp0 , 210avoiding a data copy. 211The 212.Fa uio 213must always be 214.Pf non- Dv NULL . 215If 216.Fa mp0 217is 218.Pf non- Dv NULL , 219only the 220.Pf uio_resid 221of 222.Fa uio 223is used. 224The caller may optionally retrieve a socket address on a protocol with the 225.Dv PR_ADDR 226capability by providing storage via 227.Pf non- Dv NULL 228.Fa psa 229argument. 230The caller may optionally retrieve control data mbufs via a 231.Pf non- Dv NULL 232.Fa controlp 233argument. 234Optional flags may be passed to 235.Fn soreceive 236via a 237.Pf non- Dv NULL 238.Fa flagsp 239argument, and use the same flag name space as the 240.Xr recvmsg 2 241system call. 242.Pp 243The 244.Fn sosend 245function is equivalent to the 246.Xr sendmsg 2 247system call, and attempts to send bytes of data via the socket 248.Fa so , 249optionally blocking if data cannot be immediately sent. 250Data may be sent directly from kernel or user memory via the 251.Fa uio 252argument, or as an mbuf chain via 253.Fa top , 254avoiding a data copy. 255Only one of the 256.Fa uio 257or 258.Fa top 259pointers may be 260.Pf non- Dv NULL . 261An optional destination address may be specified via a 262.Pf non- Dv NULL 263.Fa addr 264argument, which may result in an implicit connect if supported by the 265protocol. 266The caller may optionally send control data mbufs via a 267.Pf non- Dv NULL 268.Fa control 269argument. 270Flags may be passed to 271.Fn sosend 272using the 273.Fa flags 274argument, and use the same flag name space as the 275.Xr sendmsg 2 276system call. 277.Pp 278Kernel callers running in 279.Xr ithread 9 280context, or with a mutex held, will wish to use non-blocking sockets and pass 281the 282.Dv MSG_DONTWAIT 283flag 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 299The 300.Xr socket 2 301system call appeared in 302.Bx 4.2 . 303This manual page was introduced in 304.Fx 7.0 . 305.Sh AUTHORS 306This manual page was written by 307.An Robert Watson . 308.Sh BUGS 309The use of explicitly passed credentials, credentials hung from explicitly 310passed threads, the credential on 311.Dv curthread , 312and the cached credential from 313socket creation time is inconsistent, and may lead to unexpected behaviour. 314It is possible that several of the 315.Fa td 316arguments should be 317.Fa cred 318arguments, or simply not be present at all. 319.Pp 320The caller may need to manually clear 321.Dv SS_ISCONNECTING 322if 323.Fn soconnect 324returns an error. 325.Pp 326The 327.Dv MSG_DONTWAIT 328flag is not implemented for 329.Fn sosend , 330and may not always work with 331.Fn soreceive 332when zero copy sockets are enabled. 333.Pp 334This manual page does not describe how to register socket upcalls or monitor 335a socket for readability/writability without using blocking I/O. 336.Pp 337The 338.Fn soref 339and 340.Fn sorele 341functions are not described, and in most cases should not be used, due to 342confusing and potentially incorrect interactions when 343.Fn sorele 344is last called after 345.Fn soclose . 346