1.\" $NetBSD: accept.2,v 1.28 2011/06/27 08:21:07 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 June 2, 2011 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 -column SOCK_NONBLOCK -offset indent 146.It Dv SOCK_CLOEXEC 147Set the close on exec property. 148.It Dv SOCK_NONBLOCK 149Sets non-blocking I/O. 150.El 151.Pp 152It can also temporarily replace the signal mask of the calling thread if 153.Fa sigmask 154is a 155.Pf non- Dv NULL 156pointer, then the 157.Fn paccept 158function shall replace the signal mask of the caller by the set of 159signals pointed to by 160.Fa sigmask 161before waiting for a connection, and shall restore the signal mask 162of the calling thread before returning. 163.Sh RETURN VALUES 164The 165.Fn accept 166and 167.Fn paccept 168calls return \-1 on error. 169If they succeed, they return a non-negative 170integer that is a descriptor for the accepted socket. 171.Sh COMPATIBILITY 172The 173.Fn accept 174implementation makes the new file descriptor inherit file flags 175(like 176.Dv O_NONBLOCK ) 177from the listening socket. 178It's a traditional behaviour for BSD derivative systems. 179On the other hand, there are implementations which don't do so. 180Linux is an example of such implementations. 181Portable programs should not rely on either of the behaviours. 182.Sh ERRORS 183The 184.Fn accept 185will fail if: 186.Bl -tag -width Er 187.It Bq Er EAGAIN 188The socket is marked non-blocking and no connections 189are present to be accepted. 190.It Bq Er EBADF 191The descriptor is invalid. 192.It Bq Er ECONNABORTED 193A connection has been aborted. 194.It Bq Er EFAULT 195The 196.Fa addr 197parameter is not in a writable part of the 198user address space. 199.It Bq Er EINTR 200The 201.Fn accept 202call has been interrupted by a signal. 203.It Bq Er EINVAL 204The socket has not been set up to accept connections (using 205.Xr bind 2 206and 207.Xr listen 2 ) . 208.It Bq Er EMFILE 209The per-process descriptor table is full. 210.It Bq Er ENFILE 211The system file table is full. 212.It Bq Er ENOTSOCK 213The descriptor references a file, not a socket. 214.It Bq Er EOPNOTSUPP 215The referenced socket is not of type 216.Dv SOCK_STREAM . 217.El 218.Sh SEE ALSO 219.Xr bind 2 , 220.Xr connect 2 , 221.Xr listen 2 , 222.Xr poll 2 , 223.Xr select 2 , 224.Xr socket 2 225.Sh HISTORY 226The 227.Fn accept 228function appeared in 229.Bx 4.2 . 230The 231.Fn pselect 232function is inspired from Linux and appeared in 233.Nx 6.0 . 234