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 .\" 3. 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: src/lib/libc/sys/accept.2,v 1.10.2.11 2002/05/09 02:24:40 silby Exp $
  30 .\" $DragonFly: src/lib/libc/sys/accept.2,v 1.4 2006/06/25 10:55:51 corecode Exp $
  31 .\"
  32 .Dd October 29, 2015
  33 .Dt ACCEPT 2
  34 .Os
  35 .Sh NAME
  36 .Nm accept ,
  37 .Nm accept4
  38 .Nd accept a connection on a socket
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/types.h
  43 .In sys/socket.h
  44 .Ft int
  45 .Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen"
  46 .Ft int
  47 .Fn accept4 "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen" "int flags"
  48 .Sh DESCRIPTION
  49 The argument
  50 .Fa s
  51 is a socket that has been created with
  52 .Xr socket 2 ,
  53 bound to an address with
  54 .Xr bind 2 ,
  55 and is listening for connections after a
  56 .Xr listen 2 .
  57 The
  58 .Fn accept
  59 system call extracts the first connection request
  60 on the queue of pending connections,
  61 creates a new socket,
  62 and allocates a new file descriptor
  63 for the socket
  64 which inherits the state of the
  65 .Dv O_NONBLOCK
  66 and
  67 .Dv O_ASYNC
  68 properties,
  69 socket buffer settings,
  70 socket options,
  71 and the destination of
  72 .Dv SIGIO
  73 and
  74 .Dv SIGURG
  75 signals from the original socket
  76 .Fa s .
  77 .Pp
  78 The
  79 .Fn accept4
  80 system call is similar,
  81 but the
  82 .Dv O_NONBLOCK
  83 property of the new socket is instead determined by the
  84 .Dv SOCK_NONBLOCK
  85 flag in the
  86 .Fa flags
  87 argument,
  88 the
  89 .Dv O_ASYNC
  90 property is cleared,
  91 the signal destination is cleared
  92 and the close-on-exec flag on the new file descriptor can be set via the
  93 .Dv SOCK_CLOEXEC
  94 flag in the
  95 .Fa flags
  96 argument.
  97 .Pp
  98 If no pending connections are
  99 present on the queue, and the socket is not marked
 100 as non-blocking,
 101 .Fn accept
 102 blocks the caller until a connection is present.
 103 If the socket is marked non-blocking and no pending
 104 connections are present on the queue,
 105 .Fn accept
 106 returns an error as described below.
 107 The accepted socket
 108 may not be used
 109 to accept more connections.  The original socket
 110 .Fa s
 111 remains open.
 112 .Pp
 113 The argument
 114 .Fa addr
 115 is a result parameter that is filled-in with
 116 the address of the connecting entity,
 117 as known to the communications layer.
 118 The exact format of the
 119 .Fa addr
 120 parameter is determined by the domain in which the communication
 121 is occurring.
 122 To ensure that the returned address fits,
 123 .Fa *addr
 124 should have a size of at least
 125 .Ft sizeof(struct sockaddr_storage) .
 126 The
 127 .Fa addrlen
 128 is a value-result parameter; it should initially contain the
 129 amount of space pointed to by
 130 .Fa addr ;
 131 on return it will contain the actual length (in bytes) of the
 132 address returned.
 133 These system calls
 134 are used with connection-based socket types, currently with
 135 .Dv SOCK_STREAM
 136 and
 137 .Dv SOCK_SEQPACKET .
 138 .Pp
 139 It is possible to
 140 .Xr select 2
 141 a socket for the purposes of doing an
 142 .Fn accept
 143 by selecting it for read.
 144 .Pp
 145 For certain protocols which require an explicit confirmation,
 146 such as
 147 .Tn ISO
 148 or
 149 .Tn DATAKIT ,
 150 .Fn accept
 151 can be thought of
 152 as merely dequeueing the next connection
 153 request and not implying confirmation.
 154 Confirmation can be implied by a normal read or write on the new
 155 file descriptor, and rejection can be implied by closing the
 156 new socket.
 157 .Pp
 158 For some applications, performance may be enhanced by using an
 159 .Xr accept_filter 9
 160 to pre-process incoming connections.
 161 .Sh RETURN VALUES
 162 These calls returns \-1 on error.
 163 If they succeed,
 164 they return a non-negative integer
 165 that is a descriptor for the accepted socket.
 166 .Sh ERRORS
 167 The
 168 .Fn accept
 169 and
 170 .Fn accept4
 171 system calls will fail if:
 172 .Bl -tag -width Er
 173 .It Bq Er EBADF
 174 The descriptor is invalid.
 175 .It Bq Er EINTR
 176 The
 177 .Fn accept
 178 operation was interrupted.
 179 .It Bq Er EMFILE
 180 The per-process descriptor table is full.
 181 .It Bq Er ENFILE
 182 The system file table is full.
 183 .It Bq Er ENOTSOCK
 184 The descriptor references a file, not a socket.
 185 .It Bq Er EINVAL
 186 .Xr listen 2
 187 has not been called on the socket descriptor.
 188 .It Bq Er EFAULT
 189 The
 190 .Fa addr
 191 parameter is not in a writable part of the
 192 user address space.
 193 .It Bq Er EWOULDBLOCK
 194 The socket is marked non-blocking and no connections
 195 are present to be accepted.
 196 .It Bq Er ECONNABORTED
 197 A connection arrived, but it was closed while waiting
 198 on the listen queue.
 199 .El
 200 .Pp
 201 The
 202 .Fn accept4
 203 system call will also fail if:
 204 .Bl -tag -width Er
 205 .It Bq Er EINVAL
 206 The
 207 .Fa flags
 208 argument is invalid.
 209 .El
 210 .Sh SEE ALSO
 211 .Xr bind 2 ,
 212 .Xr connect 2 ,
 213 .Xr getpeername 2 ,
 214 .Xr listen 2 ,
 215 .Xr select 2 ,
 216 .Xr socket 2 ,
 217 .Xr accept_filter 9
 218 .Sh HISTORY
 219 The
 220 .Fn accept
 221 system call appeared in
 222 .Bx 4.2 .
 223 .Pp
 224 The
 225 .Fn accept4
 226 system call appeared in
 227 .Dx 4.3 .