1.\" $OpenBSD: accept.2,v 1.23 2012/04/24 12:20:59 jmc Exp $ 2.\" $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft Exp $ 3.\" 4.\" Copyright (c) 1983, 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)accept.2 8.2 (Berkeley) 12/11/93 32.\" 33.Dd $Mdocdate: April 24 2012 $ 34.Dt ACCEPT 2 35.Os 36.Sh NAME 37.Nm accept 38.Nd accept a connection on a socket 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <sys/socket.h> 42.Ft int 43.Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen" 44.Sh DESCRIPTION 45The argument 46.Fa s 47is a socket that has been created with 48.Xr socket 2 , 49bound to an address with 50.Xr bind 2 , 51and is listening for connections after a 52.Xr listen 2 . 53The 54.Fn accept 55call extracts the first connection request on the queue of pending 56connections, creates a new socket with the same properties of 57.Fa s , 58and allocates a new file descriptor for the socket. 59If no pending connections are present on the queue, 60and the socket is not marked as non-blocking, 61.Fn accept 62blocks the caller until a connection is present. 63If the socket is marked non-blocking and no pending 64connections are present on the queue, 65.Fn accept 66returns an error as described below. 67The accepted socket may not be used to accept more connections. 68The original socket 69.Fa s 70remains open. 71.Pp 72The argument 73.Fa addr 74is a result parameter that is filled in with the address of the connecting 75entity as known to the communications layer. 76The exact format of the 77.Fa addr 78parameter is determined by the domain in which the communication 79is occurring. 80The structure 81.Li sockaddr_storage 82exists for greater portability. 83It is large enough to hold any of the types that may be returned in the 84.Fa addr 85parameter. 86.Pp 87The 88.Fa addrlen 89is a value-result parameter; it should initially contain the 90amount of space pointed to by 91.Fa addr ; 92on return it will contain the actual length (in bytes) of the 93address returned. 94If 95.Fa addrlen 96does not point to enough space to hold the entire socket address, the 97result will be truncated to the initial value of 98.Fa addrlen 99(in bytes). 100This call is 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 it for read. 110.Pp 111For certain protocols which require an explicit confirmation, 112.Fn accept 113can be thought of as merely dequeuing the next connection 114request and not implying confirmation. 115Confirmation can be implied by a normal read or write on the new file 116descriptor, and rejection can be implied by closing the new socket. 117.Pp 118One can obtain user connection request data without confirming 119the connection by issuing a 120.Xr recvmsg 2 121call with an 122.Fa msg_iovlen 123of 0 and a non-zero 124.Fa msg_controllen , 125or by issuing a 126.Xr getsockopt 2 127request. 128Similarly, one can provide user connection rejection information 129by issuing a 130.Xr sendmsg 2 131call providing only the control information, or by calling 132.Xr setsockopt 2 . 133.Sh RETURN VALUES 134The call returns \-1 on error. 135If it succeeds, it returns a non-negative integer that is a descriptor 136for the accepted socket. 137.Sh EXAMPLES 138The following code uses struct 139.Li sockaddr_storage 140to allocate enough space for the returned address: 141.Bd -literal -offset indent 142#include <sys/types.h> 143#include <sys/socket.h> 144 145struct sockaddr_storage addr; 146socklen_t len = sizeof(addr); 147int retcode; 148 149retcode = accept(s, (struct sockaddr *)&addr, &len); 150if (retcode == -1) 151 err(1, "accept"); 152.Ed 153.Sh ERRORS 154The 155.Fn accept 156will fail if: 157.Bl -tag -width Er 158.It Bq Er EBADF 159The descriptor is invalid. 160.It Bq Er ENOTSOCK 161The descriptor references a file, not a socket. 162.It Bq Er EOPNOTSUPP 163The referenced socket is not of type 164.Dv SOCK_STREAM . 165.It Bq Er EINTR 166A signal was caught before a connection arrived. 167.It Bq Er EINVAL 168The referenced socket is not listening for connections (that is, 169.Xr listen 2 170has not yet been called). 171.It Bq Er EFAULT 172The 173.Fa addr 174or 175.Fa addrlen 176parameter is not in a valid part of the process address space. 177.It Bq Er EWOULDBLOCK 178The socket is marked non-blocking and no connections 179are present to be accepted. 180.It Bq Er EMFILE 181The per-process descriptor table is full. 182.It Bq Er ENFILE 183The system file table is full. 184.It Bq Er ECONNABORTED 185A connection has been aborted. 186.El 187.Sh SEE ALSO 188.Xr bind 2 , 189.Xr connect 2 , 190.Xr listen 2 , 191.Xr poll 2 , 192.Xr select 2 , 193.Xr socket 2 194.Sh HISTORY 195The 196.Fn accept 197function appeared in 198.Bx 4.2 . 199.Sh CAVEATS 200When 201.Er EMFILE 202or 203.Er ENFILE 204is returned, 205new connections are neither dequeued nor discarded. 206Thus considerable care is required in 207.Xr select 2 208and 209.Xr poll 2 210loops. 211