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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)accept.2    8.2 (Berkeley) 12/11/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd December 11, 1993
  36 .Dt ACCEPT 2
  37 .Os
  38 .Sh NAME
  39 .Nm accept
  40 .Nd accept a connection on a socket
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In sys/socket.h
  46 .Ft int
  47 .Fn accept "int s" "struct sockaddr * restrict addr" "socklen_t * restrict addrlen"
  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 on the
  60 queue of pending connections, creates a new socket,
  61 and allocates a new file descriptor for the socket which
  62 inherits the state of the
  63 .Dv O_NONBLOCK
  64 property from the original socket
  65 .Fa s .
  66 .Pp
  67 If no pending connections are
  68 present on the queue, and the original socket
  69 is not marked as non-blocking,
  70 .Fn accept
  71 blocks the caller until a connection is present.
  72 If the original socket
  73 is marked non-blocking and no pending
  74 connections are present on the queue,
  75 .Fn accept
  76 returns an error as described below.
  77 The accepted socket
  78 may not be used
  79 to accept more connections.
  80 The original socket
  81 .Fa s
  82 remains open.
  83 .Pp
  84 The argument
  85 .Fa addr
  86 is a result argument that is filled-in with
  87 the address of the connecting entity,
  88 as known to the communications layer.
  89 The exact format of the
  90 .Fa addr
  91 argument is determined by the domain in which the communication
  92 is occurring.
  93 A null pointer may be specified for
  94 .Fa addr
  95 if the address information is not desired;
  96 in this case,
  97 .Fa addrlen
  98 is not used and should also be null.
  99 Otherwise, the
 100 .Fa addrlen
 101 argument
 102 is a value-result argument; it should initially contain the
 103 amount of space pointed to by
 104 .Fa addr ;
 105 on return it will contain the actual length (in bytes) of the
 106 address returned.
 107 This call
 108 is used with connection-based socket types, currently with
 109 .Dv SOCK_STREAM .
 110 .Pp
 111 It is possible to
 112 .Xr select 2
 113 a socket for the purposes of doing an
 114 .Fn accept
 115 by selecting it for read.
 116 .Pp
 117 For certain protocols which require an explicit confirmation,
 118 such as
 119 .Tn ISO
 120 or
 121 .Tn DATAKIT ,
 122 .Fn accept
 123 can be thought of
 124 as merely dequeueing the next connection
 125 request and not implying confirmation.
 126 Confirmation can be implied by a normal read or write on the new
 127 file descriptor, and rejection can be implied by closing the
 128 new socket.
 129 .Pp
 130 For some applications, performance may be enhanced by using an
 131 .Xr accept_filter 9
 132 to pre-process incoming connections.
 133 .Sh RETURN VALUES
 134 The call returns \-1 on error.
 135 If it succeeds, it returns a non-negative
 136 integer that is a descriptor for the accepted socket.
 137 .Sh ERRORS
 138 The
 139 .Fn accept
 140 system call will fail if:
 141 .Bl -tag -width Er
 142 .It Bq Er EBADF
 143 The descriptor is invalid.
 144 .It Bq Er EINTR
 145 The
 146 .Fn accept
 147 operation was interrupted.
 148 .It Bq Er EMFILE
 149 The per-process descriptor table is full.
 150 .It Bq Er ENFILE
 151 The system file table is full.
 152 .It Bq Er ENOTSOCK
 153 The descriptor references a file, not a socket.
 154 .It Bq Er EINVAL
 155 .Xr listen 2
 156 has not been called on the socket descriptor.
 157 .It Bq Er EINVAL
 158 The
 159 .Fa addrlen
 160 argument is negative.
 161 .It Bq Er EFAULT
 162 The
 163 .Fa addr
 164 argument is not in a writable part of the
 165 user address space.
 166 .It Bq Er EWOULDBLOCK
 167 The socket is marked non-blocking and no connections
 168 are present to be accepted.
 169 .It Bq Er ECONNABORTED
 170 A connection arrived, but it was closed while waiting
 171 on the listen queue.
 172 .El
 173 .Sh SEE ALSO
 174 .Xr bind 2 ,
 175 .Xr connect 2 ,
 176 .Xr getpeername 2 ,
 177 .Xr listen 2 ,
 178 .Xr select 2 ,
 179 .Xr socket 2 ,
 180 .Xr accept_filter 9
 181 .Sh HISTORY
 182 The
 183 .Fn accept
 184 system call appeared in
 185 .Bx 4.2 .