1.\" $NetBSD: accept.2,v 1.34 2019/10/27 12:28:13 pgoyette 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 October 27, 2019 33.Dt ACCEPT 2 34.Os 35.Sh NAME 36.Nm accept , 37.Nm accept4 , 38.Nm paccept 39.Nd accept a connection on a socket 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/socket.h 44.Ft int 45.Fn accept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" 46.Ft int 47.Fn accept4 "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "int flags" 48.Ft int 49.Fn paccept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "const sigset_t * restrict sigmask" "int flags" 50.Sh DESCRIPTION 51The argument 52.Fa s 53is a socket that has been created with 54.Xr socket 2 , 55bound to an address with 56.Xr bind 2 , 57and is listening for connections after a 58.Xr listen 2 . 59The 60.Fn accept 61function 62extracts the first connection request on the queue of pending 63connections, creates a new socket with the same properties of 64.Fa s 65and allocates a new file descriptor 66for the socket. 67If no pending connections are 68present on the queue, and the socket is not marked 69as non-blocking, 70.Fn accept 71blocks the caller until a connection is present. 72If the socket is marked non-blocking and no pending 73connections are present on the queue, 74.Fn accept 75returns an error as described below. 76The accepted socket 77may not be used 78to accept more connections. 79The original socket 80.Fa s 81remains open. 82.Pp 83The argument 84.Fa addr 85is a result parameter that is filled in with 86the address of the connecting entity, 87as known to the communications layer. 88The exact format of the 89.Fa addr 90parameter is determined by the domain in which the communication 91is occurring. 92The 93.Fa addrlen 94is a value-result parameter; it should initially contain the 95amount of space pointed to by 96.Fa addr ; 97on return it will contain the actual length (in bytes) of the 98address returned. 99This call 100is used with connection-based socket types, currently with 101.Dv SOCK_STREAM . 102.Pp 103It is possible to 104.Xr select 2 105or 106.Xr poll 2 107a socket for the purposes of doing an 108.Fn accept 109by selecting or polling it for read. 110.Pp 111For certain protocols which require an explicit confirmation, 112such as 113.Tn ISO 114or 115.Tn DATAKIT , 116.Fn accept 117can be thought of 118as merely dequeuing the next connection 119request and not implying confirmation. 120Confirmation can be implied by a normal read or write on the new 121file descriptor, and rejection can be implied by closing the 122new socket. 123.Pp 124One can obtain user connection request data without confirming 125the connection by issuing a 126.Xr recvmsg 2 127call with an 128.Fa msg_iovlen 129of 0 and a non-zero 130.Fa msg_controllen , 131or by issuing a 132.Xr getsockopt 2 133request. 134Similarly, one can provide user connection rejection information 135by issuing a 136.Xr sendmsg 2 137call with providing only the control information, 138or by calling 139.Xr setsockopt 2 . 140.Pp 141The 142.Fn accept4 143function is equivalent to paccept with sigmask 144.Dv NULL . 145.Pp 146The 147.Fn paccept 148function behaves exactly like 149.Fn accept , 150but it also allows to set the following 151.Fa flags 152on the returned file descriptor: 153.Bl -tag -width SOCK_NOSIGPIPEXX -offset indent 154.It Dv SOCK_CLOEXEC 155Set the close on exec property. 156.It Dv SOCK_NONBLOCK 157Sets non-blocking I/O. 158.It Dv SOCK_NOSIGPIPE 159Return 160.Er EPIPE 161instead of raising 162.Dv SIGPIPE . 163.El 164.Pp 165It can also temporarily replace the signal mask of the calling thread if 166.Fa sigmask 167is a 168.Pf non- Dv NULL 169pointer, then the 170.Fn paccept 171function shall replace the signal mask of the caller by the set of 172signals pointed to by 173.Fa sigmask 174before waiting for a connection, and shall restore the signal mask 175of the calling thread before returning. 176.Sh RETURN VALUES 177The 178.Fn accept 179and 180.Fn paccept 181calls return \-1 on error. 182If they succeed, they return a non-negative 183integer that is a descriptor for the accepted socket. 184.Sh COMPATIBILITY 185The 186.Fn accept 187implementation makes the new file descriptor inherit file flags 188(like 189.Dv O_NONBLOCK ) 190from the listening socket. 191It's a traditional behaviour for BSD derivative systems. 192On the other hand, there are implementations which don't do so. 193Linux is an example of such implementations. 194Portable programs should not rely on either of the behaviours. 195The 196.Pp 197.Fn accept4 198function is compatible with the Linux implementation. 199.Sh ERRORS 200The 201.Fn accept 202function will fail if: 203.Bl -tag -width Er 204.It Bq Er EAGAIN 205The socket is marked non-blocking and no connections 206are present to be accepted. 207.It Bq Er EBADF 208The descriptor is invalid. 209.It Bq Er ECONNABORTED 210A connection has been aborted. 211.It Bq Er EFAULT 212The 213.Fa addr 214parameter is not in a writable part of the 215user address space. 216.It Bq Er EINTR 217The 218.Fn accept 219call has been interrupted by a signal. 220.It Bq Er EINVAL 221The socket has not been set up to accept connections (using 222.Xr bind 2 223and 224.Xr listen 2 ) . 225.It Bq Er EMFILE 226The per-process descriptor table is full. 227.It Bq Er ENFILE 228The system file table is full. 229.It Bq Er ENOTSOCK 230The descriptor references a file, not a socket. 231.It Bq Er EOPNOTSUPP 232The referenced socket is not of type 233.Dv SOCK_STREAM . 234.El 235.Sh SEE ALSO 236.Xr bind 2 , 237.Xr connect 2 , 238.Xr listen 2 , 239.Xr poll 2 , 240.Xr select 2 , 241.Xr socket 2 242.Sh HISTORY 243The 244.Fn accept 245function appeared in 246.Bx 4.2 . 247The 248.Fn accept4 249function matches Linux semantics and appeared in 250.Nx 8.0 . 251The 252.Fn paccept 253function is inspired from Linux and appeared in 254.Nx 6.0 . 255