lib/libc/accept.2

   1 .\"     $OpenBSD: accept.2,v 1.28 2014/09/09 03:50:43 guenther Exp $
   2 .\"     $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft Exp $
   3 .\"
   4 .\" Copyright (c) 1983, 1990, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)accept.2    8.2 (Berkeley) 12/11/93
  32 .\"
  33 .Dd October 13, 2016
  34 .Dt ACCEPT 2
  35 .Os
  36 .Sh NAME
  37 .Nm accept ,
  38 .Nm accept4
  39 .Nd accept a connection on a socket
  40 .Sh SYNOPSIS
  41 .In sys/socket.h
  42 .Ft int
  43 .Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen"
  44 .Ft int
  45 .Fn accept4 "int s" "struct sockaddr *addr" "socklen_t *addrlen" "int flags"
  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 call extracts the first connection request on the queue of pending
  58 connections, creates a new socket with the same non-blocking I/O mode as
  59 .Fa s ,
  60 and allocates a new file descriptor for the socket with the
  61 close-on-exec flag clear.
  62 .Pp
  63 The
  64 .Fn accept4
  65 system call is similar, however the non-blocking I/O mode of the
  66 new socket is determined by the
  67 .Dv SOCK_NDELAY
  68 and
  69 .Dv SOCK_NONBLOCK
  70 flags in the
  71 .Fa flags
  72 argument and the close-on-exec flag on the new file descriptor is
  73 determined by the
  74 .Dv SOCK_CLOEXEC
  75 flag in the
  76 .Fa flags
  77 argument. See
  78 .Dv O_NDELAY ,
  79 .Dv O_NONBLOCK
  80 and
  81 .Dv FD_CLOEXEC
  82 in
  83 .Xr fcntl.h 3HEAD
  84 for more details.
  85 .Pp
  86 If no pending connections are present on the queue,
  87 and the socket is not marked as non-blocking,
  88 .Fn accept
  89 blocks the caller until a connection is present.
  90 If the socket is marked non-blocking and no pending
  91 connections are present on the queue,
  92 .Fn accept
  93 returns an error as described below.
  94 The accepted socket may not be used to accept more connections.
  95 The original socket
  96 .Fa s
  97 remains open.
  98 .Pp
  99 The argument
 100 .Fa addr
 101 is a result parameter that is filled in with the address of the connecting
 102 entity as known to the communications layer.
 103 The exact format of the
 104 .Fa addr
 105 parameter is determined by the domain in which the communication
 106 is occurring.
 107 The structure
 108 .Li sockaddr_storage
 109 exists for greater portability.
 110 It is large enough to hold any of the types that may be returned in the
 111 .Fa addr
 112 parameter.
 113 .Pp
 114 The
 115 .Fa addrlen
 116 is a value-result parameter; it should initially contain the
 117 amount of space pointed to by
 118 .Fa addr ;
 119 on return it will contain the actual length (in bytes) of the
 120 address returned.
 121 If
 122 .Fa addrlen
 123 does not point to enough space to hold the entire socket address, the
 124 result will be truncated to the initial value of
 125 .Fa addrlen
 126 (in bytes).
 127 This call is used with connection-based socket types, currently with
 128 .Dv SOCK_STREAM .
 129 .Pp
 130 It is possible to
 131 .Xr select 2
 132 or
 133 .Xr poll 2
 134 a socket for the purposes of doing an
 135 .Fn accept
 136 by selecting it for read.
 137 .Sh RETURN VALUES
 138 The call returns \-1 on error.
 139 If it succeeds, it returns a non-negative integer that is a descriptor
 140 for the accepted socket.
 141 .Sh EXAMPLES
 142 The following code uses struct
 143 .Li sockaddr_storage
 144 to allocate enough space for the returned address:
 145 .Bd -literal -offset indent
 146 #include <sys/types.h>
 147 #include <sys/socket.h>
 148
 149 struct sockaddr_storage addr;
 150 socklen_t len = sizeof(addr);
 151 int retcode;
 152
 153 retcode = accept(s, (struct sockaddr *)&addr, &len);
 154 if (retcode == -1)
 155         err(1, "accept");
 156 .Ed
 157 .Sh ERRORS
 158 .Fn accept
 159 and
 160 .Fn accept4
 161 will fail if:
 162 .Bl -tag -width Er
 163 .It Bq Er EBADF
 164 The descriptor is invalid.
 165 .It Bq Er ENOTSOCK
 166 The descriptor doesn't reference a socket.
 167 .It Bq Er EOPNOTSUPP
 168 The referenced socket is not of type
 169 .Dv SOCK_STREAM .
 170 .It Bq Er EINTR
 171 A signal was caught before a connection arrived.
 172 .It Bq Er EINVAL
 173 The referenced socket is not listening for connections (that is,
 174 .Xr listen 2
 175 has not yet been called).
 176 .It Bq Er EFAULT
 177 The
 178 .Fa addr
 179 or
 180 .Fa addrlen
 181 parameter is not in a valid part of the process address space.
 182 .It Bq Er EWOULDBLOCK
 183 The socket is marked non-blocking and no connections
 184 are present to be accepted.
 185 .It Bq Er EMFILE
 186 The per-process descriptor table is full.
 187 .It Bq Er ECONNABORTED
 188 A connection has been aborted.
 189 .It Bq Er ENOMEM
 190 There was insufficient memory available to complete the operation.
 191 .El
 192 .Pp
 193 In addition,
 194 .Fn accept4
 195 will fail if
 196 .Bl -tag -width Er
 197 .It Bq Er EINVAL
 198 .Fa flags
 199 is invalid.
 200 .El
 201 .Sh SEE ALSO
 202 .Xr bind 2 ,
 203 .Xr connect 2 ,
 204 .Xr listen 2 ,
 205 .Xr poll 2 ,
 206 .Xr select 2 ,
 207 .Xr socket 2
 208 .Sh STANDARDS
 209 The
 210 .Fn accept
 211 function conforms to
 212 .St -p1003.1-2008 .
 213 The
 214 .Fn accept4
 215 function is expected to conform to a future revision of that standard.
 216 .Sh HISTORY
 217 The
 218 .Fn accept
 219 system call first appeared in
 220 .Bx 4.1c .