lib/libcr/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: src/lib/libc/sys/accept.2,v 1.10.2.11 2002/05/09 02:24:40 silby Exp $
  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 *addr" "socklen_t *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 call
  60 extracts the first connection request
  61 on the queue of pending connections, creates
  62 a new socket with the same properties as
  63 .Fa s ,
  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 s
  78 remains open.
  79 .Pp
  80 The argument
  81 .Fa addr
  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 addr
  87 parameter is determined by the domain in which the communication
  88 is occurring.
  89 The
  90 .Fa addrlen
  91 is a value-result parameter; it should initially contain the
  92 amount of space pointed to by
  93 .Fa addr ;
  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 dequeueing 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 For some applications, performance may be enhanced by using an
 120 .Xr accept_filter 9
 121 to pre-process incoming connections.
 122 .Sh RETURN VALUES
 123 The call returns \-1 on error.  If it succeeds, it returns a non-negative
 124 integer that is a descriptor for the accepted socket.
 125 .Sh ERRORS
 126 The
 127 .Fn accept
 128 will fail if:
 129 .Bl -tag -width Er
 130 .It Bq Er EBADF
 131 The descriptor is invalid.
 132 .It Bq Er EINTR
 133 The
 134 .Fn accept
 135 operation was interrupted.
 136 .It Bq Er EMFILE
 137 The per-process descriptor table is full.
 138 .It Bq Er ENFILE
 139 The system file table is full.
 140 .It Bq Er ENOTSOCK
 141 The descriptor references a file, not a socket.
 142 .It Bq Er EINVAL
 143 .Xr listen 2
 144 has not been called on the socket descriptor.
 145 .It Bq Er EFAULT
 146 The
 147 .Fa addr
 148 parameter is not in a writable part of the
 149 user address space.
 150 .It Bq Er EWOULDBLOCK
 151 The socket is marked non-blocking and no connections
 152 are present to be accepted.
 153 .It Bq Er ECONNABORTED
 154 A connection arrived, but it was closed while waiting
 155 on the listen queue.
 156 .El
 157 .Sh SEE ALSO
 158 .Xr accept_filter 9 ,
 159 .Xr bind 2 ,
 160 .Xr connect 2 ,
 161 .Xr getpeername 2 ,
 162 .Xr listen 2 ,
 163 .Xr select 2 ,
 164 .Xr socket 2
 165 .Sh HISTORY
 166 The
 167 .Fn accept
 168 function appeared in
 169 .Bx 4.2 .