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 BSD 4.2
  38 .Sh NAME
  39 .Nm accept
  40 .Nd accept a connection on a socket
  41 .Sh SYNOPSIS
  42 .Fd #include <sys/types.h>
  43 .Fd #include <sys/socket.h>
  44 .Ft int
  45 .Fn accept "int s" "struct sockaddr *addr" "int *addrlen"
  46 .Sh DESCRIPTION
  47 The argument
  48 .Fa s
  49 is a socket that has been created with
  50 .Xr socket 2 ,
  51 bound to an address with
  52 .Xr bind 2 ,
  53 and is listening for connections after a
  54 .Xr listen 2 .
  55 The
  56 .Fn accept
  57 argument
  58 extracts the first connection request
  59 on the queue of pending connections, creates
  60 a new socket with the same properties of
  61 .Fa s
  62 and allocates a new file descriptor
  63 for the socket.  If no pending connections are
  64 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 non-blocking and no pending
  69 connections are present on the queue,
  70 .Fn accept
  71 returns an error as described below.
  72 The accepted socket
  73 may not be used
  74 to accept more connections.  The original socket
  75 .Fa s
  76 remains open.
  77 .Pp
  78 The argument
  79 .Fa addr
  80 is a result parameter that is filled in with
  81 the address of the connecting entity,
  82 as known to the communications layer.
  83 The exact format of the
  84 .Fa addr
  85 parameter is determined by the domain in which the communication
  86 is occurring.
  87 The
  88 .Fa addrlen
  89 is a value-result parameter; it should initially contain the
  90 amount of space pointed to by
  91 .Fa addr ;
  92 on return it will contain the actual length (in bytes) of the
  93 address returned.
  94 This call
  95 is used with connection-based socket types, currently with
  96 .Dv SOCK_STREAM .
  97 .Pp
  98 It is possible to
  99 .Xr select 2
 100 a socket for the purposes of doing an
 101 .Fn accept
 102 by selecting it for read.
 103 .Pp
 104 For certain protocols which require an explicit confirmation,
 105 such as
 106 .Tn ISO
 107 or
 108 .Tn DATAKIT ,
 109 .Fn accept
 110 can be thought of
 111 as merely dequeueing the next connection
 112 request and not implying confirmation.
 113 Confirmation can be implied by a normal read or write on the new
 114 file descriptor, and rejection can be implied by closing the
 115 new socket.
 116 .Pp
 117 One can obtain user connection request data without confirming
 118 the connection by issuing a
 119 .Xr recvmsg 2
 120 call with an
 121 .Fa msg_iovlen
 122 of 0 and a non-zero
 123 .Fa msg_controllen ,
 124 or by issuing a
 125 .Xr getsockopt 2
 126 request.
 127 Similarly, one can provide user connection rejection information
 128 by issuing a
 129 .Xr sendmsg 2
 130 call with providing only the control information,
 131 or by calling
 132 .Xr setsockopt 2 .
 133 .Sh IMPLEMENTATION NOTES
 134 .Pp
 135 In the non-threaded library
 136 .Fn accept
 137 is implemented as the
 138 .Va accept
 139 syscall.
 140 .Pp
 141 In the threaded library, the
 142 .Va accept
 143 syscall is assembled to
 144 .Fn _thread_sys_accept
 145 and
 146 .Fn accept
 147 is implemented as a function which locks
 148 .Va s
 149 for read and write, then calls
 150 .Fn _thread_sys_accept .
 151 If the call to
 152 .Fn _thread_sys_accept
 153 would block, a context switch is performed. Before returning,
 154 .Fn accept
 155 unlocks
 156 .Va s .
 157 .Pp
 158 .Sh RETURN VALUES
 159 The call returns \-1 on error.  If it succeeds, it returns a non-negative
 160 integer that is a descriptor for the accepted socket.
 161 .Sh ERRORS
 162 The
 163 .Fn accept
 164 will fail if:
 165 .Bl -tag -width EWOULDBLOCK
 166 .It Bq Er EBADF
 167 The descriptor is invalid.
 168 .It Bq Er EINTR
 169 The
 170 .Fn accept
 171 operation was interrupted.
 172 .It Bq Er EMFILE
 173 The per-process descriptor table is full.
 174 .It Bq Er ENFILE
 175 The system file table is full.
 176 .It Bq Er ENOTSOCK
 177 The descriptor references a file, not a socket.
 178 .It Bq Er EINVAL
 179 .Xr listen 2
 180 has not been called on the socket descriptor.
 181 .It Bq Er EFAULT
 182 The
 183 .Fa addr
 184 parameter is not in a writable part of the
 185 user address space.
 186 .It Bq Er EWOULDBLOCK
 187 The socket is marked non-blocking and no connections
 188 are present to be accepted.
 189 .El
 190 .Sh SEE ALSO
 191 .Xr bind 2 ,
 192 .Xr connect 2 ,
 193 .Xr getpeername 2 ,
 194 .Xr listen 2 ,
 195 .Xr select 2 ,
 196 .Xr socket 2
 197 .Sh HISTORY
 198 The
 199 .Fn accept
 200 function appeared in
 201 .Bx 4.2 .