| blob | 61f25cb944697060c3d9220e0fb324583eba5a81 |
1 .\" $NetBSD: accept.2,v 1.25 2006/11/17 23:59:33 rillig 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 November 18, 2006
33 .Dt ACCEPT 2
34 .Os
35 .Sh NAME
36 .Nm accept
37 .Nd accept a connection on a socket
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/socket.h
42 .Ft int
43 .Fn accept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen"
44 .Sh DESCRIPTION
45 The argument
46 .Fa s
47 is a socket that has been created with
48 .Xr socket 2 ,
49 bound to an address with
50 .Xr bind 2 ,
51 and is listening for connections after a
52 .Xr listen 2 .
53 The
54 .Fn accept
55 argument
56 extracts the first connection request on the queue of pending
57 connections, creates a new socket with the same properties of
58 .Fa s
59 and allocates a new file descriptor
60 for the socket.
61 If no pending connections are
62 present on the queue, and the socket is not marked
63 as non-blocking,
64 .Fn accept
65 blocks the caller until a connection is present.
66 If the socket is marked non-blocking and no pending
67 connections are present on the queue,
68 .Fn accept
69 returns an error as described below.
70 The accepted socket
71 may not be used
72 to accept more connections.
73 The original socket
74 .Fa s
75 remains open.
76 .Pp
77 The argument
78 .Fa addr
79 is a result parameter that is filled in with
80 the address of the connecting entity,
81 as known to the communications layer.
82 The exact format of the
83 .Fa addr
84 parameter is determined by the domain in which the communication
85 is occurring.
86 The
87 .Fa addrlen
88 is a value-result parameter; it should initially contain the
89 amount of space pointed to by
90 .Fa addr ;
91 on return it will contain the actual length (in bytes) of the
92 address returned.
93 This call
94 is used with connection-based socket types, currently with
95 .Dv SOCK_STREAM .
96 .Pp
97 It is possible to
98 .Xr select 2
99 or
100 .Xr poll 2
101 a socket for the purposes of doing an
102 .Fn accept
103 by selecting or polling it for read.
104 .Pp
105 For certain protocols which require an explicit confirmation,
106 such as
107 .Tn ISO
108 or
109 .Tn DATAKIT ,
110 .Fn accept
111 can be thought of
112 as merely dequeuing the next connection
113 request and not implying confirmation.
114 Confirmation can be implied by a normal read or write on the new
115 file descriptor, and rejection can be implied by closing the
116 new socket.
117 .Pp
118 One can obtain user connection request data without confirming
119 the connection by issuing a
120 .Xr recvmsg 2
121 call with an
122 .Fa msg_iovlen
123 of 0 and a non-zero
124 .Fa msg_controllen ,
125 or by issuing a
126 .Xr getsockopt 2
127 request.
128 Similarly, one can provide user connection rejection information
129 by issuing a
130 .Xr sendmsg 2
131 call with providing only the control information,
132 or by calling
133 .Xr setsockopt 2 .
134 .Sh RETURN VALUES
135 The call returns \-1 on error.
136 If it succeeds, it returns a non-negative
137 integer that is a descriptor for the accepted socket.
138 .Sh ERRORS
139 The
140 .Fn accept
141 will fail if:
142 .Bl -tag -width Er
143 .It Bq Er EAGAIN
144 The socket is marked non-blocking and no connections
145 are present to be accepted.
146 .It Bq Er EBADF
147 The descriptor is invalid.
148 .It Bq Er ECONNABORTED
149 A connection has been aborted.
150 .It Bq Er EFAULT
151 The
152 .Fa addr
153 parameter is not in a writable part of the
154 user address space.
155 .It Bq Er EINTR
156 The
157 .Fn accept
158 call has been interrupted by a signal.
159 .It Bq Er EINVAL
160 The socket has not been set up to accept connections (using
161 .Xr bind 2
162 and
163 .Xr listen 2 ) .
164 .It Bq Er EMFILE
165 The per-process descriptor table is full.
166 .It Bq Er ENFILE
167 The system file table is full.
168 .It Bq Er ENOTSOCK
169 The descriptor references a file, not a socket.
170 .It Bq Er EOPNOTSUPP
171 The referenced socket is not of type
172 .Dv SOCK_STREAM .
173 .El
174 .Sh SEE ALSO
175 .Xr bind 2 ,
176 .Xr connect 2 ,
177 .Xr listen 2 ,
178 .Xr poll 2 ,
179 .Xr select 2 ,
180 .Xr socket 2
181 .Sh HISTORY
182 The
183 .Fn accept
184 function appeared in
185 .Bx 4.2 .