1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright 1989 AT&T
  19 .\" Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved
  20 .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All rights reserved.
  21 .\" Copyright 2018 Nexenta Systems, Inc.
  22 .\"
  23 .Dd August 2, 2018
  24 .Dt ACCEPT 3C
  25 .Os
  26 .Sh NAME
  27 .Nm accept
  28 .Nd accept a connection on a socket
  29 .Sh LIBRARY
  30 .Lb libc
  31 .Sh SYNOPSIS
  32 .In sys/types.h
  33 .In sys/socket.h
  34 .Ft int
  35 .Fo accept
  36 .Fa "int s"
  37 .Fa "struct sockaddr *restrict addr"
  38 .Fa "socklen_t *addrlen"
  39 .Fc
  40 .Ft int
  41 .Fo accept4
  42 .Fa "int s"
  43 .Fa "struct sockaddr *restrict addr"
  44 .Fa "socklen_t *addrlen"
  45 .Fa "int flags"
  46 .Fc
  47 .Sh DESCRIPTION
  48 The argument
  49 .Fa s
  50 is a socket that has been created with
  51 .Xr socket 3C
  52 and bound to an address with
  53 .Xr bind 3C ,
  54 and that is listening for connections after a call to
  55 .Xr listen 3C .
  56 The
  57 .Fn accept
  58 function extracts the first connection on the queue of pending connections,
  59 creates a new socket with the properties of
  60 .Fa s ,
  61 and allocates a new file descriptor,
  62 .Va ns ,
  63 for the socket.
  64 If no pending connections are present on the queue and the socket is not marked
  65 as non-blocking,
  66 .Fn accept
  67 blocks the caller until a connection is present.
  68 If the socket is marked as non-blocking and no pending connections are present
  69 on the queue,
  70 .Fn accept
  71 returns an error as described below.
  72 The
  73 .Fn accept
  74 function uses the
  75 .Xr netconfig 4
  76 file to determine the STREAMS device file name associated with
  77 .Fa s .
  78 This is the device on which the connect indication will be accepted.
  79 The accepted socket,
  80 .Va ns ,
  81 is used to read and write data to and from the socket that connected to
  82 .Va ns .
  83 It is not used to accept more connections.
  84 The original socket
  85 .Pq Fa s
  86 remains open for accepting further connections.
  87 .Pp
  88 The argument
  89 .Fa addr
  90 is a result parameter that is filled in with the address of the connecting
  91 entity as it is known to the communications layer.
  92 The exact format of the
  93 .Fa addr
  94 parameter is determined by the domain in which the communication occurs.
  95 .Pp
  96 The argument
  97 .Fa addrlen
  98 is a value-result parameter.
  99 Initially, it contains the amount of space pointed to by
 100 .Fa addr ;
 101 on return it contains the length in bytes of the address returned.
 102 .Pp
 103 The
 104 .Fn accept
 105 function is used with connection-based socket types, currently with
 106 .Dv SOCK_STREAM .
 107 .Pp
 108 The
 109 .Fn accept4
 110 function allows flags that control the behavior of a successfully accepted
 111 socket.
 112 If
 113 .Fa flags
 114 is 0,
 115 .Fn accept4
 116 acts identically to
 117 .Fn accept .
 118 Values for
 119 .Fa flags
 120 are constructed by a bitwise-inclusive-OR of flags from the following list,
 121 defined in
 122 .In sys/socketvar.h :
 123 .Bl -tag -width Ds
 124 .It Dv SOCK_CLOEXEC
 125 The accepted socket will have the
 126 .Dv FD_CLOEXEC
 127 flag set as if
 128 .Xr fcntl 2
 129 was called on it.
 130 This flag is set before the socket is passed to the caller thus avoiding the
 131 race condition between
 132 .Fn accept
 133 and
 134 .Xr fcntl 2 .
 135 See
 136 .Dv O_CLOEXEC
 137 in
 138 .Xr open 2
 139 for more details.
 140 .It Dv SOCK_NDELAY
 141 The accepted socket will have the
 142 .Dv O_NDELAY
 143 flag set as if
 144 .Xr fcntl 2
 145 was called on it.
 146 This sets the socket into non-blocking mode.
 147 See
 148 .Dv O_NDELAY
 149 in
 150 .Xr fcntl.h 3HEAD
 151 for more details.
 152 .It Dv SOCK_NONBLOCK
 153 The accepted socket will have the
 154 .Dv O_NONBLOCK
 155 flag set as if
 156 .Xr fcntl 2
 157 was called on it.
 158 This sets the socket into non-blocking mode
 159 .Po POSIX; see
 160 .Xr standards 5
 161 .Pc .
 162 See
 163 .Dv O_NONBLOCK
 164 in
 165 .Xr fcntl.h 3HEAD
 166 for more details.
 167 .El
 168 .Pp
 169 It is possible to
 170 .Xr select 3C
 171 or
 172 .Xr poll 2
 173 a socket for the purpose of an
 174 .Fn accept
 175 by selecting or polling it for a read.
 176 However, this will only indicate when a connect indication is pending; it is
 177 still necessary to call
 178 .Fn accept .
 179 .Sh RETURN VALUES
 180 The
 181 .Fn accept
 182 function returns -1 on error.
 183 If it succeeds, it returns a non-negative integer that is a descriptor for the
 184 accepted socket.
 185 .Sh ERRORS
 186 .Fn accept
 187 and
 188 .Fn accept4
 189 will fail if:
 190 .Bl -tag -width Er
 191 .It Bq Er EBADF
 192 The descriptor is invalid.
 193 .It Bq Er ECONNABORTED
 194 The remote side aborted the connection before the
 195 .Fn accept
 196 operation completed.
 197 .It Bq Er EFAULT
 198 The
 199 .Fa addr
 200 parameter or the
 201 .Fa addrlen
 202 parameter is invalid.
 203 .It Bq Er EINTR
 204 The
 205 .Fn accept
 206 attempt was interrupted by the delivery of a signal.
 207 .It Bq Er EMFILE
 208 The per-process descriptor table is full.
 209 .It Bq Er ENODEV
 210 The protocol family and type corresponding to
 211 .Fa s
 212 could not be found in the
 213 .Pa netconfig
 214 file.
 215 .It Bq Er ENOMEM
 216 There was insufficient user memory available to complete the operation.
 217 .It Bq Er ENOSR
 218 There were insufficient STREAMS resources available to complete the operation.
 219 .It Bq Er ENOTSOCK
 220 The descriptor does not reference a socket.
 221 .It Bq Er EOPNOTSUPP
 222 The referenced socket is not of type
 223 .Dv SOCK_STREAM .
 224 .It Bq Er EPROTO
 225 A protocol error has occurred; for example, the STREAMS protocol stack has not
 226 been initialized or the connection has already been released.
 227 .It Bq Er EWOULDBLOCK
 228 The socket is marked as non-blocking and no connections are present to be
 229 accepted.
 230 .El
 231 .Pp
 232 Additionally,
 233 .Fn accept4
 234 will fail if:
 235 .Bl -tag -width Er
 236 .It Bq Er EINVAL
 237 The
 238 .Fa flags
 239 value is invalid.
 240 The
 241 .Fa flags
 242 argument can only be the bitwise inclusive-OR of
 243 .Dv SOCK_CLOEXEC ,
 244 .Dv SOCK_NONBLOCK ,
 245 and
 246 .Dv SOCK_NDELAY .
 247 .El
 248 .Sh MT-LEVEL
 249 .Sy Safe
 250 .Sh SEE ALSO
 251 .Xr fcntl 2 ,
 252 .Xr poll 2 ,
 253 .Xr bind 3C ,
 254 .Xr connect 3C ,
 255 .Xr listen 3C ,
 256 .Xr select 3C ,
 257 .Xr sockaddr 3C ,
 258 .Xr socket 3C ,
 259 .Xr fcntl.h 3HEAD ,
 260 .Xr socket.h 3HEAD ,
 261 .Xr netconfig 4 ,
 262 .Xr attributes 5 ,
 263 .Xr standards 5