]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/accept.2
xnu-2782.30.5.tar.gz
[apple/xnu.git] / bsd / man / man2 / accept.2
CommitLineData
9bccf70c
A
1.\" $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft 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. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by the University of
17.\" California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)accept.2 8.2 (Berkeley) 12/11/93
35.\"
36.Dd December 11, 1993
37.Dt ACCEPT 2
38.Os BSD 4.2
39.Sh NAME
40.Nm accept
41.Nd accept a connection on a socket
42.Sh SYNOPSIS
9bccf70c
A
43.Fd #include <sys/socket.h>
44.Ft int
2d21ac55
A
45.Fo accept
46.Fa "int socket"
47.Fa "struct sockaddr *restrict address"
48.Fa "socklen_t *restrict address_len"
49.Fc
9bccf70c
A
50.Sh DESCRIPTION
51The argument
2d21ac55 52.Fa socket
9bccf70c
A
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 .
9bccf70c 59.Fn accept
9bccf70c
A
60extracts the first connection request
61on the queue of pending connections, creates
62a new socket with the same properties of
2d21ac55 63.Fa socket ,
9bccf70c
A
64and allocates a new file descriptor
65for the socket. If no pending connections are
66present on the queue, and the socket is not marked
67as non-blocking,
68.Fn accept
69blocks the caller until a connection is present.
70If the socket is marked non-blocking and no pending
71connections are present on the queue,
72.Fn accept
73returns an error as described below.
74The accepted socket
75may not be used
76to accept more connections. The original socket
2d21ac55 77.Fa socket,
9bccf70c
A
78remains open.
79.Pp
80The argument
2d21ac55 81.Fa address
9bccf70c
A
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
2d21ac55 86.Fa address
9bccf70c
A
87parameter is determined by the domain in which the communication
88is occurring.
89The
2d21ac55 90.Fa address_len
9bccf70c
A
91is a value-result parameter; it should initially contain the
92amount of space pointed to by
2d21ac55 93.Fa address ;
9bccf70c
A
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
102a socket for the purposes of doing an
103.Fn accept
104by selecting it for read.
105.Pp
106For certain protocols which require an explicit confirmation,
107such as
108.Tn ISO
109or
110.Tn DATAKIT ,
111.Fn accept
112can be thought of
113as merely dequeuing the next connection
114request and not implying confirmation.
115Confirmation can be implied by a normal read or write on the new
116file descriptor, and rejection can be implied by closing the
117new socket.
118.Pp
119One can obtain user connection request data without confirming
120the connection by issuing a
121.Xr recvmsg 2
122call with an
123.Fa msg_iovlen
124of 0 and a non-zero
125.Fa msg_controllen ,
126or by issuing a
127.Xr getsockopt 2
128request.
129Similarly, one can provide user connection rejection information
130by issuing a
131.Xr sendmsg 2
132call with providing only the control information,
133or by calling
134.Xr setsockopt 2 .
135.Sh RETURN VALUES
2d21ac55
A
136The call returns \-1 on error and the global variable
137.Va errno
138is set to indicate the error.
139If it succeeds, it returns a non-negative integer
140that is a descriptor for the accepted socket.
9bccf70c
A
141.Sh ERRORS
142The
143.Fn accept
2d21ac55 144system call will fail if:
9bccf70c 145.Bl -tag -width Er
2d21ac55 146.\" ==========
9bccf70c 147.It Bq Er EBADF
2d21ac55
A
148.Fa socket
149is not a valid file descriptor.
150.\" ==========
151.It Bq Er ECONNABORTED
152The connection to
153.Fa socket
154has been aborted.
155.\" ==========
9bccf70c
A
156.It Bq Er EFAULT
157The
2d21ac55 158.Fa address
9bccf70c
A
159parameter is not in a writable part of the
160user address space.
2d21ac55
A
161.\" ==========
162.It Bq Er EINTR
163The
164.Fn accept
165system call was terminated by a signal.
166.\" ==========
167.It Bq Er EINVAL
168.Fa socket
169is unwilling to accept connections.
170.\" ==========
9bccf70c
A
171.It Bq Er EMFILE
172The per-process descriptor table is full.
2d21ac55 173.\" ==========
9bccf70c
A
174.It Bq Er ENFILE
175The system file table is full.
2d21ac55
A
176.\" ==========
177.It Bq Er ENOMEM
178Insufficient memory was available to complete the operation.
179.\" ==========
180.It Bq Er ENOTSOCK
181.Fa socket
182references a file type other than a socket.
183.\" ==========
184.It Bq Er EOPNOTSUPP
185.Fa socket
186is not of type
187.Dv SOCK_STREAM
188and thus does not accept connections.
189.\" ==========
190.It Bq Er EWOULDBLOCK
191.Fa socket
192is marked as non-blocking and no connections are present to be accepted.
9bccf70c 193.El
2d21ac55
A
194.Sh LEGACY SYNOPSIS
195.Fd #include <sys/types.h>
196.Fd #include <sys/socket.h>
197.Pp
198The include file
199.In sys/types.h
200is necessary.
9bccf70c
A
201.Sh SEE ALSO
202.Xr bind 2 ,
203.Xr connect 2 ,
204.Xr listen 2 ,
205.Xr select 2 ,
2d21ac55
A
206.Xr socket 2 ,
207.Xr compat 5
9bccf70c
A
208.Sh HISTORY
209The
210.Fn accept
211function appeared in
212.Bx 4.2 .