lib/libc/sys/accept.2

   1 .\" Copyright (c) 1983, 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)accept.2    8.2 (Berkeley) 12/11/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd October 9, 2014
  32 .Dt ACCEPT 2
  33 .Os
  34 .Sh NAME
  35 .Nm accept ,
  36 .Nm accept4
  37 .Nd accept a connection on a socket
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  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 accept4 "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "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 system call extracts the first connection request on the
  59 queue of pending connections, creates a new socket,
  60 and allocates a new file descriptor for the socket which
  61 inherits the state of the
  62 .Dv O_NONBLOCK
  63 and
  64 .Dv O_ASYNC
  65 properties and the destination of
  66 .Dv SIGIO
  67 and
  68 .Dv SIGURG
  69 signals from the original socket
  70 .Fa s .
  71 .Pp
  72 The
  73 .Fn accept4
  74 system call is similar,
  75 but the
  76 .Dv O_NONBLOCK
  77 property of the new socket is instead determined by the
  78 .Dv SOCK_NONBLOCK
  79 flag in the
  80 .Fa flags
  81 argument,
  82 the
  83 .Dv O_ASYNC
  84 property is cleared,
  85 the signal destination is cleared
  86 and the close-on-exec flag on the new file descriptor can be set via the
  87 .Dv SOCK_CLOEXEC
  88 flag in the
  89 .Fa flags
  90 argument.
  91 .Pp
  92 If no pending connections are
  93 present on the queue, and the original socket
  94 is not marked as non-blocking,
  95 .Fn accept
  96 blocks the caller until a connection is present.
  97 If the original socket
  98 is marked non-blocking and no pending
  99 connections are present on the queue,
 100 .Fn accept
 101 returns an error as described below.
 102 The accepted socket
 103 may not be used
 104 to accept more connections.
 105 The original socket
 106 .Fa s
 107 remains open.
 108 .Pp
 109 The argument
 110 .Fa addr
 111 is a result argument that is filled-in with
 112 the address of the connecting entity,
 113 as known to the communications layer.
 114 The exact format of the
 115 .Fa addr
 116 argument is determined by the domain in which the communication
 117 is occurring.
 118 A null pointer may be specified for
 119 .Fa addr
 120 if the address information is not desired;
 121 in this case,
 122 .Fa addrlen
 123 is not used and should also be null.
 124 Otherwise, the
 125 .Fa addrlen
 126 argument
 127 is a value-result argument; it should initially contain the
 128 amount of space pointed to by
 129 .Fa addr ;
 130 on return it will contain the actual length (in bytes) of the
 131 address returned.
 132 This call
 133 is used with connection-based socket types, currently with
 134 .Dv SOCK_STREAM .
 135 .Pp
 136 It is possible to
 137 .Xr select 2
 138 a socket for the purposes of doing an
 139 .Fn accept
 140 by selecting it for read.
 141 .Pp
 142 For certain protocols which require an explicit confirmation,
 143 such as
 144 .Tn ISO
 145 or
 146 .Tn DATAKIT ,
 147 .Fn accept
 148 can be thought of
 149 as merely dequeueing the next connection
 150 request and not implying confirmation.
 151 Confirmation can be implied by a normal read or write on the new
 152 file descriptor, and rejection can be implied by closing the
 153 new socket.
 154 .Pp
 155 For some applications, performance may be enhanced by using an
 156 .Xr accept_filter 9
 157 to pre-process incoming connections.
 158 .Pp
 159 When using
 160 .Fn accept ,
 161 portable programs should not rely on the
 162 .Dv O_NONBLOCK
 163 and
 164 .Dv O_ASYNC
 165 properties and the signal destination being inherited,
 166 but should set them explicitly using
 167 .Xr fcntl 2 ;
 168 .Fn accept4
 169 sets these properties consistently,
 170 but may not be fully portable across
 171 .Ux
 172 platforms.
 173 .Sh RETURN VALUES
 174 These calls return \-1 on error.
 175 If they succeed, they return a non-negative
 176 integer that is a descriptor for the accepted socket.
 177 .Sh ERRORS
 178 The
 179 .Fn accept
 180 and
 181 .Fn accept4
 182 system calls will fail if:
 183 .Bl -tag -width Er
 184 .It Bq Er EBADF
 185 The descriptor is invalid.
 186 .It Bq Er EINTR
 187 The
 188 .Fn accept
 189 operation was interrupted.
 190 .It Bq Er EMFILE
 191 The per-process descriptor table is full.
 192 .It Bq Er ENFILE
 193 The system file table is full.
 194 .It Bq Er ENOTSOCK
 195 The descriptor references a file, not a socket.
 196 .It Bq Er EINVAL
 197 .Xr listen 2
 198 has not been called on the socket descriptor.
 199 .It Bq Er EFAULT
 200 The
 201 .Fa addr
 202 argument is not in a writable part of the
 203 user address space.
 204 .It Bo Er EWOULDBLOCK Bc or Bq Er EAGAIN
 205 The socket is marked non-blocking and no connections
 206 are present to be accepted.
 207 .It Bq Er ECONNABORTED
 208 A connection arrived, but it was closed while waiting
 209 on the listen queue.
 210 .El
 211 .Pp
 212 The
 213 .Fn accept4
 214 system call will also fail if:
 215 .Bl -tag -width Er
 216 .It Bq Er EINVAL
 217 The
 218 .Fa flags
 219 argument is invalid.
 220 .El
 221 .Sh SEE ALSO
 222 .Xr bind 2 ,
 223 .Xr connect 2 ,
 224 .Xr getpeername 2 ,
 225 .Xr getsockname 2 ,
 226 .Xr listen 2 ,
 227 .Xr select 2 ,
 228 .Xr socket 2 ,
 229 .Xr accept_filter 9
 230 .Sh HISTORY
 231 The
 232 .Fn accept
 233 system call appeared in
 234 .Bx 4.2 .
 235 .Pp
 236 The
 237 .Fn accept4
 238 system call appeared in
 239 .Fx 10.0 .