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