xref: /csrg-svn/lib/libc/sys/accept.2 (revision 65100)
161181Sbostic.\" Copyright (c) 1983, 1990, 1991, 1993
261181Sbostic.\"	The Regents of the University of California.  All rights reserved.
320205Smckusick.\"
448835Scael.\" %sccs.include.redist.roff%
520205Smckusick.\"
6*65100Smckusick.\"     @(#)accept.2	8.2 (Berkeley) 12/11/93
736759Sbostic.\"
848835Scael.Dd
948835Scael.Dt ACCEPT 2
1048835Scael.Os BSD 4.2
1148835Scael.Sh NAME
1248835Scael.Nm accept
1348835Scael.Nd accept a connection on a socket
1448835Scael.Sh SYNOPSIS
1548835Scael.Fd #include <sys/types.h>
1648835Scael.Fd #include <sys/socket.h>
1748835Scael.Ft int
1848835Scael.Fn accept "int s" "struct sockaddr *addr" "int *addrlen"
1948835Scael.Sh DESCRIPTION
2020205SmckusickThe argument
2148835Scael.Fa s
2223790Ssechrestis a socket that has been created with
2348835Scael.Xr socket 2 ,
2420205Smckusickbound to an address with
2548835Scael.Xr bind 2 ,
2620205Smckusickand is listening for connections after a
2748835Scael.Xr listen 2 .
2848835ScaelThe
2948835Scael.Fn accept
3048835Scaelargument
3142476Ssklowerextracts the first connection request
3220205Smckusickon the queue of pending connections, creates
3320205Smckusicka new socket with the same properties of
3448835Scael.Fa s
3548835Scaeland allocates a new file descriptor
3620205Smckusickfor the socket.  If no pending connections are
3720205Smckusickpresent on the queue, and the socket is not marked
3820205Smckusickas non-blocking,
3948835Scael.Fn accept
4020205Smckusickblocks the caller until a connection is present.
4120205SmckusickIf the socket is marked non-blocking and no pending
4220205Smckusickconnections are present on the queue,
4348835Scael.Fn accept
4420205Smckusickreturns an error as described below.
4548835ScaelThe accepted socket
4620205Smckusickmay not be used
4720205Smckusickto accept more connections.  The original socket
4848835Scael.Fa s
4920205Smckusickremains open.
5048835Scael.Pp
5120205SmckusickThe argument
5248835Scael.Fa addr
5323790Ssechrestis a result parameter that is filled in with
5420205Smckusickthe address of the connecting entity,
5520205Smckusickas known to the communications layer.
5620205SmckusickThe exact format of the
5748835Scael.Fa addr
5820205Smckusickparameter is determined by the domain in which the communication
5920205Smckusickis occurring.
6020205SmckusickThe
6148835Scael.Fa addrlen
6220205Smckusickis a value-result parameter; it should initially contain the
6320205Smckusickamount of space pointed to by
6448835Scael.Fa addr ;
6520205Smckusickon return it will contain the actual length (in bytes) of the
6620205Smckusickaddress returned.
6720205SmckusickThis call
6848835Scaelis used with connection-based socket types, currently with
6948835Scael.Dv SOCK_STREAM .
7048835Scael.Pp
7120205SmckusickIt is possible to
7248835Scael.Xr select 2
7320205Smckusicka socket for the purposes of doing an
7448835Scael.Fn accept
7520205Smckusickby selecting it for read.
7648835Scael.Pp
7742476SsklowerFor certain protocols which require an explicit confirmation,
7848835Scaelsuch as
7948835Scael.Tn ISO
8048835Scaelor
8148835Scael.Tn DATAKIT ,
8248835Scael.Fn accept
8348835Scaelcan be thought of
8448835Scaelas merely dequeueing the next connection
8548835Scaelrequest and not implying confirmation.
8642476SsklowerConfirmation can be implied by a normal read or write on the new
87*65100Smckusickfile descriptor, and rejection can be implied by closing the
8842476Ssklowernew socket.
8948835Scael.Pp
9042476SsklowerOne can obtain user connection request data without confirming
9142476Ssklowerthe connection by issuing a
9248835Scael.Xr recvmsg 2
9348835Scaelcall with an
9448835Scael.Fa msg_iovlen
9548835Scaelof 0 and a non-zero
9648835Scael.Fa msg_controllen ,
9748835Scaelor by issuing a
9848835Scael.Xr getsockopt 2
9942476Ssklowerrequest.
10042476SsklowerSimilarly, one can provide user connection rejection information
10148835Scaelby issuing a
10248835Scael.Xr sendmsg 2
10348835Scaelcall with providing only the control information,
10442476Sskloweror by calling
10548835Scael.Xr setsockopt 2 .
10648835Scael.Sh RETURN VALUES
10728355SanneThe call returns \-1 on error.  If it succeeds, it returns a non-negative
10823790Ssechrestinteger that is a descriptor for the accepted socket.
10948835Scael.Sh ERRORS
11048835ScaelThe
11148835Scael.Fn accept
11248835Scaelwill fail if:
11348835Scael.Bl -tag -width EWOULDBLOCK
11448835Scael.It Bq Er EBADF
11520205SmckusickThe descriptor is invalid.
11648835Scael.It Bq Er ENOTSOCK
11720205SmckusickThe descriptor references a file, not a socket.
11848835Scael.It Bq Er EOPNOTSUPP
11948835ScaelThe referenced socket is not of type
12048835Scael.Dv SOCK_STREAM .
12148835Scael.It Bq Er EFAULT
12248835ScaelThe
12348835Scael.Fa addr
12448835Scaelparameter is not in a writable part of the
12520205Smckusickuser address space.
12648835Scael.It Bq Er EWOULDBLOCK
12720205SmckusickThe socket is marked non-blocking and no connections
12820205Smckusickare present to be accepted.
12948835Scael.El
13048835Scael.Sh SEE ALSO
13148835Scael.Xr bind 2 ,
13248835Scael.Xr connect 2 ,
13348835Scael.Xr listen 2 ,
13448835Scael.Xr select 2 ,
13548835Scael.Xr socket 2
13648835Scael.Sh HISTORY
13748835ScaelThe
13848835Scael.Nm
13948835Scaelfunction appeared in
14048835Scael.Bx 4.2 .
141