1.\" $OpenBSD: accept.2,v 1.26 2013/07/17 05:42:11 schwarze 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: July 17 2013 $ 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/socket.h> 41.Ft int 42.Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen" 43.Sh DESCRIPTION 44The argument 45.Fa s 46is a socket that has been created with 47.Xr socket 2 , 48bound to an address with 49.Xr bind 2 , 50and is listening for connections after a 51.Xr listen 2 . 52The 53.Fn accept 54call extracts the first connection request on the queue of pending 55connections, creates a new socket with the same properties of 56.Fa s , 57and allocates a new file descriptor for the socket. 58If no pending connections are present on the queue, 59and the socket is not marked as non-blocking, 60.Fn accept 61blocks the caller until a connection is present. 62If the socket is marked non-blocking and no pending 63connections are present on the queue, 64.Fn accept 65returns an error as described below. 66The accepted socket may not be used to accept more connections. 67The original socket 68.Fa s 69remains open. 70.Pp 71The argument 72.Fa addr 73is a result parameter that is filled in with the address of the connecting 74entity as known to the communications layer. 75The exact format of the 76.Fa addr 77parameter is determined by the domain in which the communication 78is occurring. 79The structure 80.Li sockaddr_storage 81exists for greater portability. 82It is large enough to hold any of the types that may be returned in the 83.Fa addr 84parameter. 85.Pp 86The 87.Fa addrlen 88is a value-result parameter; it should initially contain the 89amount of space pointed to by 90.Fa addr ; 91on return it will contain the actual length (in bytes) of the 92address returned. 93If 94.Fa addrlen 95does not point to enough space to hold the entire socket address, the 96result will be truncated to the initial value of 97.Fa addrlen 98(in bytes). 99This call is used with connection-based socket types, currently with 100.Dv SOCK_STREAM . 101.Pp 102It is possible to 103.Xr select 2 104or 105.Xr poll 2 106a socket for the purposes of doing an 107.Fn accept 108by selecting it for read. 109.Pp 110For certain protocols which require an explicit confirmation, 111.Fn accept 112can be thought of as merely dequeuing the next connection 113request and not implying confirmation. 114Confirmation can be implied by a normal read or write on the new file 115descriptor, and rejection can be implied by closing the new socket. 116.Pp 117One can obtain user connection request data without confirming 118the connection by issuing a 119.Xr recvmsg 2 120call with an 121.Fa msg_iovlen 122of 0 and a non-zero 123.Fa msg_controllen , 124or by issuing a 125.Xr getsockopt 2 126request. 127Similarly, one can provide user connection rejection information 128by issuing a 129.Xr sendmsg 2 130call providing only the control information, or by calling 131.Xr setsockopt 2 . 132.Sh RETURN VALUES 133The call returns \-1 on error. 134If it succeeds, it returns a non-negative integer that is a descriptor 135for the accepted socket. 136.Sh EXAMPLES 137The following code uses struct 138.Li sockaddr_storage 139to allocate enough space for the returned address: 140.Bd -literal -offset indent 141#include <sys/types.h> 142#include <sys/socket.h> 143 144struct sockaddr_storage addr; 145socklen_t len = sizeof(addr); 146int retcode; 147 148retcode = accept(s, (struct sockaddr *)&addr, &len); 149if (retcode == -1) 150 err(1, "accept"); 151.Ed 152.Sh ERRORS 153.Fn accept 154will fail if: 155.Bl -tag -width Er 156.It Bq Er EBADF 157The descriptor is invalid. 158.It Bq Er ENOTSOCK 159The descriptor doesn't reference a socket. 160.It Bq Er EOPNOTSUPP 161The referenced socket is not of type 162.Dv SOCK_STREAM . 163.It Bq Er EINTR 164A signal was caught before a connection arrived. 165.It Bq Er EINVAL 166The referenced socket is not listening for connections (that is, 167.Xr listen 2 168has not yet been called). 169.It Bq Er EFAULT 170The 171.Fa addr 172or 173.Fa addrlen 174parameter is not in a valid part of the process address space. 175.It Bq Er EWOULDBLOCK 176The socket is marked non-blocking and no connections 177are present to be accepted. 178.It Bq Er EMFILE 179The per-process descriptor table is full. 180.It Bq Er ENFILE 181The system file table is full. 182.It Bq Er ECONNABORTED 183A connection has been aborted. 184.El 185.Sh SEE ALSO 186.Xr bind 2 , 187.Xr connect 2 , 188.Xr listen 2 , 189.Xr poll 2 , 190.Xr select 2 , 191.Xr socket 2 192.Sh STANDARDS 193The 194.Fn accept 195function conforms to 196.St -p1003.1-2008 . 197.Sh HISTORY 198The 199.Fn accept 200system call first appeared in 201.Bx 4.1c . 202.Sh CAVEATS 203When 204.Er EMFILE 205or 206.Er ENFILE 207is returned, 208new connections are neither dequeued nor discarded. 209Thus considerable care is required in 210.Xr select 2 211and 212.Xr poll 2 213loops. 214