1.\" $NetBSD: accept.2,v 1.31 2013/08/02 20:13:09 wiz Exp $ 2.\" 3.\" Copyright (c) 1983, 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)accept.2 8.2 (Berkeley) 12/11/93 31.\" 32.Dd March 19, 2012 33.Dt ACCEPT 2 34.Os 35.Sh NAME 36.Nm accept , 37.Nm paccept 38.Nd accept a connection on a socket 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/socket.h 43.Ft int 44.Fn accept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" 45.Ft int 46.Fn paccept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "const sigset_t * restrict sigmask" "int flags" 47.Sh DESCRIPTION 48The argument 49.Fa s 50is a socket that has been created with 51.Xr socket 2 , 52bound to an address with 53.Xr bind 2 , 54and is listening for connections after a 55.Xr listen 2 . 56The 57.Fn accept 58argument 59extracts the first connection request on the queue of pending 60connections, creates a new socket with the same properties of 61.Fa s 62and allocates a new file descriptor 63for the socket. 64If no pending connections are 65present on the queue, and the socket is not marked 66as non-blocking, 67.Fn accept 68blocks the caller until a connection is present. 69If the socket is marked non-blocking and no pending 70connections are present on the queue, 71.Fn accept 72returns an error as described below. 73The accepted socket 74may not be used 75to accept more connections. 76The original socket 77.Fa s 78remains open. 79.Pp 80The argument 81.Fa addr 82is a result parameter that is filled in with 83the address of the connecting entity, 84as known to the communications layer. 85The exact format of the 86.Fa addr 87parameter is determined by the domain in which the communication 88is occurring. 89The 90.Fa addrlen 91is a value-result parameter; it should initially contain the 92amount of space pointed to by 93.Fa addr ; 94on return it will contain the actual length (in bytes) of the 95address returned. 96This call 97is used with connection-based socket types, currently with 98.Dv SOCK_STREAM . 99.Pp 100It is possible to 101.Xr select 2 102or 103.Xr poll 2 104a socket for the purposes of doing an 105.Fn accept 106by selecting or polling it for read. 107.Pp 108For certain protocols which require an explicit confirmation, 109such as 110.Tn ISO 111or 112.Tn DATAKIT , 113.Fn accept 114can be thought of 115as merely dequeuing the next connection 116request and not implying confirmation. 117Confirmation can be implied by a normal read or write on the new 118file descriptor, and rejection can be implied by closing the 119new socket. 120.Pp 121One can obtain user connection request data without confirming 122the connection by issuing a 123.Xr recvmsg 2 124call with an 125.Fa msg_iovlen 126of 0 and a non-zero 127.Fa msg_controllen , 128or by issuing a 129.Xr getsockopt 2 130request. 131Similarly, one can provide user connection rejection information 132by issuing a 133.Xr sendmsg 2 134call with providing only the control information, 135or by calling 136.Xr setsockopt 2 . 137.Pp 138The 139.Fn paccept 140function behaves exactly like 141.Fn accept , 142but it also allows to set the following 143.Fa flags 144on the returned file descriptor: 145.Bl -tag -width SOCK_NOSIGPIPEXX -offset indent 146.It Dv SOCK_CLOEXEC 147Set the close on exec property. 148.It Dv SOCK_NONBLOCK 149Sets non-blocking I/O. 150.It Dv SOCK_NOSIGPIPE 151Return 152.Er EPIPE 153instead of raising 154.Dv SIGPIPE . 155.El 156.Pp 157It can also temporarily replace the signal mask of the calling thread if 158.Fa sigmask 159is a 160.Pf non- Dv NULL 161pointer, then the 162.Fn paccept 163function shall replace the signal mask of the caller by the set of 164signals pointed to by 165.Fa sigmask 166before waiting for a connection, and shall restore the signal mask 167of the calling thread before returning. 168.Sh RETURN VALUES 169The 170.Fn accept 171and 172.Fn paccept 173calls return \-1 on error. 174If they succeed, they return a non-negative 175integer that is a descriptor for the accepted socket. 176.Sh COMPATIBILITY 177The 178.Fn accept 179implementation makes the new file descriptor inherit file flags 180(like 181.Dv O_NONBLOCK ) 182from the listening socket. 183It's a traditional behaviour for BSD derivative systems. 184On the other hand, there are implementations which don't do so. 185Linux is an example of such implementations. 186Portable programs should not rely on either of the behaviours. 187.Sh ERRORS 188The 189.Fn accept 190will fail if: 191.Bl -tag -width Er 192.It Bq Er EAGAIN 193The socket is marked non-blocking and no connections 194are present to be accepted. 195.It Bq Er EBADF 196The descriptor is invalid. 197.It Bq Er ECONNABORTED 198A connection has been aborted. 199.It Bq Er EFAULT 200The 201.Fa addr 202parameter is not in a writable part of the 203user address space. 204.It Bq Er EINTR 205The 206.Fn accept 207call has been interrupted by a signal. 208.It Bq Er EINVAL 209The socket has not been set up to accept connections (using 210.Xr bind 2 211and 212.Xr listen 2 ) . 213.It Bq Er EMFILE 214The per-process descriptor table is full. 215.It Bq Er ENFILE 216The system file table is full. 217.It Bq Er ENOTSOCK 218The descriptor references a file, not a socket. 219.It Bq Er EOPNOTSUPP 220The referenced socket is not of type 221.Dv SOCK_STREAM . 222.El 223.Sh SEE ALSO 224.Xr bind 2 , 225.Xr connect 2 , 226.Xr listen 2 , 227.Xr poll 2 , 228.Xr select 2 , 229.Xr socket 2 230.Sh HISTORY 231The 232.Fn accept 233function appeared in 234.Bx 4.2 . 235The 236.Fn paccept 237function is inspired from Linux and appeared in 238.Nx 6.0 . 239