lib/libc/sys/accept.2

   1 .\"     $NetBSD: accept.2,v 1.31 2013/08/02 20:13:09 wiz 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 March 19, 2012
  33 .Dt ACCEPT 2
  34 .Os
  35 .Sh NAME
  36 .Nm accept ,
  37 .Nm paccept
  38 .Nd accept a connection on a socket
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/socket.h
  43 .Ft int
  44 .Fn accept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen"
  45 .Ft int
  46 .Fn paccept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "const sigset_t * restrict sigmask" "int flags"
  47 .Sh DESCRIPTION
  48 The argument
  49 .Fa s
  50 is a socket that has been created with
  51 .Xr socket 2 ,
  52 bound to an address with
  53 .Xr bind 2 ,
  54 and is listening for connections after a
  55 .Xr listen 2 .
  56 The
  57 .Fn accept
  58 argument
  59 extracts the first connection request on the queue of pending
  60 connections, creates a new socket with the same properties of
  61 .Fa s
  62 and allocates a new file descriptor
  63 for the socket.
  64 If no pending connections are
  65 present on the queue, and the socket is not marked
  66 as non-blocking,
  67 .Fn accept
  68 blocks the caller until a connection is present.
  69 If the socket is marked non-blocking and no pending
  70 connections are present on the queue,
  71 .Fn accept
  72 returns an error as described below.
  73 The accepted socket
  74 may not be used
  75 to accept more connections.
  76 The original socket
  77 .Fa s
  78 remains open.
  79 .Pp
  80 The argument
  81 .Fa addr
  82 is a result parameter that is filled in with
  83 the address of the connecting entity,
  84 as known to the communications layer.
  85 The exact format of the
  86 .Fa addr
  87 parameter is determined by the domain in which the communication
  88 is occurring.
  89 The
  90 .Fa addrlen
  91 is a value-result parameter; it should initially contain the
  92 amount of space pointed to by
  93 .Fa addr ;
  94 on return it will contain the actual length (in bytes) of the
  95 address returned.
  96 This call
  97 is used with connection-based socket types, currently with
  98 .Dv SOCK_STREAM .
  99 .Pp
 100 It is possible to
 101 .Xr select 2
 102 or
 103 .Xr poll 2
 104 a socket for the purposes of doing an
 105 .Fn accept
 106 by selecting or polling it for read.
 107 .Pp
 108 For certain protocols which require an explicit confirmation,
 109 such as
 110 .Tn ISO
 111 or
 112 .Tn DATAKIT ,
 113 .Fn accept
 114 can be thought of
 115 as merely dequeuing the next connection
 116 request and not implying confirmation.
 117 Confirmation can be implied by a normal read or write on the new
 118 file descriptor, and rejection can be implied by closing the
 119 new socket.
 120 .Pp
 121 One can obtain user connection request data without confirming
 122 the connection by issuing a
 123 .Xr recvmsg 2
 124 call with an
 125 .Fa msg_iovlen
 126 of 0 and a non-zero
 127 .Fa msg_controllen ,
 128 or by issuing a
 129 .Xr getsockopt 2
 130 request.
 131 Similarly, one can provide user connection rejection information
 132 by issuing a
 133 .Xr sendmsg 2
 134 call with providing only the control information,
 135 or by calling
 136 .Xr setsockopt 2 .
 137 .Pp
 138 The
 139 .Fn paccept
 140 function behaves exactly like
 141 .Fn accept ,
 142 but it also allows to set the following
 143 .Fa flags
 144 on the returned file descriptor:
 145 .Bl -tag -width SOCK_NOSIGPIPEXX -offset indent
 146 .It Dv SOCK_CLOEXEC
 147 Set the close on exec property.
 148 .It Dv SOCK_NONBLOCK
 149 Sets non-blocking I/O.
 150 .It Dv SOCK_NOSIGPIPE
 151 Return
 152 .Er EPIPE
 153 instead of raising
 154 .Dv SIGPIPE .
 155 .El
 156 .Pp
 157 It can also temporarily replace the signal mask of the calling thread if
 158 .Fa sigmask
 159 is a
 160 .Pf non- Dv NULL
 161 pointer, then the
 162 .Fn paccept
 163 function shall replace the signal mask of the caller by the set of
 164 signals pointed to by
 165 .Fa sigmask
 166 before waiting for a connection, and shall restore the signal mask
 167 of the calling thread before returning.
 168 .Sh RETURN VALUES
 169 The
 170 .Fn accept
 171 and
 172 .Fn paccept
 173 calls return \-1 on error.
 174 If they succeed, they return a non-negative
 175 integer that is a descriptor for the accepted socket.
 176 .Sh COMPATIBILITY
 177 The
 178 .Fn accept
 179 implementation makes the new file descriptor inherit file flags
 180 (like
 181 .Dv O_NONBLOCK )
 182 from the listening socket.
 183 It's a traditional behaviour for BSD derivative systems.
 184 On the other hand, there are implementations which don't do so.
 185 Linux is an example of such implementations.
 186 Portable programs should not rely on either of the behaviours.
 187 .Sh ERRORS
 188 The
 189 .Fn accept
 190 will fail if:
 191 .Bl -tag -width Er
 192 .It Bq Er EAGAIN
 193 The socket is marked non-blocking and no connections
 194 are present to be accepted.
 195 .It Bq Er EBADF
 196 The descriptor is invalid.
 197 .It Bq Er ECONNABORTED
 198 A connection has been aborted.
 199 .It Bq Er EFAULT
 200 The
 201 .Fa addr
 202 parameter is not in a writable part of the
 203 user address space.
 204 .It Bq Er EINTR
 205 The
 206 .Fn accept
 207 call has been interrupted by a signal.
 208 .It Bq Er EINVAL
 209 The socket has not been set up to accept connections (using
 210 .Xr bind 2
 211 and
 212 .Xr listen 2 ) .
 213 .It Bq Er EMFILE
 214 The per-process descriptor table is full.
 215 .It Bq Er ENFILE
 216 The system file table is full.
 217 .It Bq Er ENOTSOCK
 218 The descriptor references a file, not a socket.
 219 .It Bq Er EOPNOTSUPP
 220 The referenced socket is not of type
 221 .Dv SOCK_STREAM .
 222 .El
 223 .Sh SEE ALSO
 224 .Xr bind 2 ,
 225 .Xr connect 2 ,
 226 .Xr listen 2 ,
 227 .Xr poll 2 ,
 228 .Xr select 2 ,
 229 .Xr socket 2
 230 .Sh HISTORY
 231 The
 232 .Fn accept
 233 function appeared in
 234 .Bx 4.2 .
 235 The
 236 .Fn paccept
 237 function is inspired from Linux and appeared in
 238 .Nx 6.0 .