bsd/man/man2/accept.2

   1 .\"     $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)accept.2    8.2 (Berkeley) 12/11/93
  35 .\"
  36 .Dd December 11, 1993
  37 .Dt ACCEPT 2
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm accept
  41 .Nd accept a connection on a socket
  42 .Sh SYNOPSIS
  43 .Fd #include <sys/socket.h>
  44 .Ft int
  45 .Fo accept
  46 .Fa "int socket"
  47 .Fa "struct sockaddr *restrict address"
  48 .Fa "socklen_t *restrict address_len"
  49 .Fc
  50 .Sh DESCRIPTION
  51 The argument
  52 .Fa socket
  53 is a socket that has been created with
  54 .Xr socket 2 ,
  55 bound to an address with
  56 .Xr bind 2 ,
  57 and is listening for connections after a
  58 .Xr listen 2 .
  59 .Fn accept
  60 extracts the first connection request
  61 on the queue of pending connections, creates
  62 a new socket with the same properties of
  63 .Fa socket ,
  64 and allocates a new file descriptor
  65 for the socket.  If no pending connections are
  66 present on the queue, and the socket is not marked
  67 as non-blocking,
  68 .Fn accept
  69 blocks the caller until a connection is present.
  70 If the socket is marked non-blocking and no pending
  71 connections are present on the queue,
  72 .Fn accept
  73 returns an error as described below.
  74 The accepted socket
  75 may not be used
  76 to accept more connections.  The original socket
  77 .Fa socket,
  78 remains open.
  79 .Pp
  80 The argument
  81 .Fa address
  82 is a result parameter that is filled in with
  83 the address of the connecting entity,
  84 as known to the communications layer.
  85 The exact format of the
  86 .Fa address
  87 parameter is determined by the domain in which the communication
  88 is occurring.
  89 The
  90 .Fa address_len
  91 is a value-result parameter; it should initially contain the
  92 amount of space pointed to by
  93 .Fa address ;
  94 on return it will contain the actual length (in bytes) of the
  95 address returned.
  96 This call
  97 is used with connection-based socket types, currently with
  98 .Dv SOCK_STREAM .
  99 .Pp
 100 It is possible to
 101 .Xr select 2
 102 a socket for the purposes of doing an
 103 .Fn accept
 104 by selecting it for read.
 105 .Pp
 106 For certain protocols which require an explicit confirmation,
 107 such as
 108 .Tn ISO
 109 or
 110 .Tn DATAKIT ,
 111 .Fn accept
 112 can be thought of
 113 as merely dequeuing the next connection
 114 request and not implying confirmation.
 115 Confirmation can be implied by a normal read or write on the new
 116 file descriptor, and rejection can be implied by closing the
 117 new socket.
 118 .Pp
 119 One can obtain user connection request data without confirming
 120 the connection by issuing a
 121 .Xr recvmsg 2
 122 call with an
 123 .Fa msg_iovlen
 124 of 0 and a non-zero
 125 .Fa msg_controllen ,
 126 or by issuing a
 127 .Xr getsockopt 2
 128 request.
 129 Similarly, one can provide user connection rejection information
 130 by issuing a
 131 .Xr sendmsg 2
 132 call with providing only the control information,
 133 or by calling
 134 .Xr setsockopt 2 .
 135 .Sh RETURN VALUES
 136 The call returns \-1 on error and the global variable
 137 .Va errno
 138 is set to indicate the error.
 139 If it succeeds, it returns a non-negative integer
 140 that is a descriptor for the accepted socket.
 141 .Sh ERRORS
 142 The
 143 .Fn accept
 144 system call will fail if:
 145 .Bl -tag -width Er
 146 .\" ==========
 147 .It Bq Er EBADF
 148 .Fa socket
 149 is not a valid file descriptor.
 150 .\" ==========
 151 .It Bq Er ECONNABORTED
 152 The connection to
 153 .Fa socket
 154 has been aborted.
 155 .\" ==========
 156 .It Bq Er EFAULT
 157 The
 158 .Fa address
 159 parameter is not in a writable part of the
 160 user address space.
 161 .\" ==========
 162 .It Bq Er EINTR
 163 The
 164 .Fn accept
 165 system call was terminated by a signal.
 166 .\" ==========
 167 .It Bq Er EINVAL
 168 .Fa socket
 169 is unwilling to accept connections.
 170 .\" ==========
 171 .It Bq Er EMFILE
 172 The per-process descriptor table is full.
 173 .\" ==========
 174 .It Bq Er ENFILE
 175 The system file table is full.
 176 .\" ==========
 177 .It Bq Er ENOMEM
 178 Insufficient memory was available to complete the operation.
 179 .\" ==========
 180 .It Bq Er ENOTSOCK
 181 .Fa socket
 182 references a file type other than a socket.
 183 .\" ==========
 184 .It Bq Er EOPNOTSUPP
 185 .Fa socket
 186 is not of type
 187 .Dv SOCK_STREAM
 188 and thus does not accept connections.
 189 .\" ==========
 190 .It Bq Er EWOULDBLOCK
 191 .Fa socket
 192 is marked as non-blocking and no connections are present to be accepted.
 193 .El
 194 .Sh LEGACY SYNOPSIS
 195 .Fd #include <sys/types.h>
 196 .Fd #include <sys/socket.h>
 197 .Pp
 198 The include file
 199 .In sys/types.h
 200 is necessary.
 201 .Sh SEE ALSO
 202 .Xr bind 2 ,
 203 .Xr connect 2 ,
 204 .Xr listen 2 ,
 205 .Xr select 2 ,
 206 .Xr socket 2 ,
 207 .Xr compat 5
 208 .Sh HISTORY
 209 The
 210 .Fn accept
 211 function appeared in
 212 .Bx 4.2 .