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/types.h>
  44 .Fd #include <sys/socket.h>
  45 .Ft int
  46 .Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen"
  47 .Sh DESCRIPTION
  48 The argument
  49 .Fa s
  50 is a socket that has been created with
  51 .Xr socket 2 ,
  52 bound to an address with
  53 .Xr bind 2 ,
  54 and is listening for connections after a
  55 .Xr listen 2 .
  56 The
  57 .Fn accept
  58 argument
  59 extracts the first connection request
  60 on the queue of pending connections, creates
  61 a new socket with the same properties of
  62 .Fa s
  63 and allocates a new file descriptor
  64 for the socket.  If no pending connections are
  65 present on the queue, and the socket is not marked
  66 as non-blocking,
  67 .Fn accept
  68 blocks the caller until a connection is present.
  69 If the socket is marked non-blocking and no pending
  70 connections are present on the queue,
  71 .Fn accept
  72 returns an error as described below.
  73 The accepted socket
  74 may not be used
  75 to accept more connections.  The original socket
  76 .Fa s
  77 remains open.
  78 .Pp
  79 The argument
  80 .Fa addr
  81 is a result parameter that is filled in with
  82 the address of the connecting entity,
  83 as known to the communications layer.
  84 The exact format of the
  85 .Fa addr
  86 parameter is determined by the domain in which the communication
  87 is occurring.
  88 The
  89 .Fa addrlen
  90 is a value-result parameter; it should initially contain the
  91 amount of space pointed to by
  92 .Fa addr ;
  93 on return it will contain the actual length (in bytes) of the
  94 address returned.
  95 This call
  96 is used with connection-based socket types, currently with
  97 .Dv SOCK_STREAM .
  98 .Pp
  99 It is possible to
 100 .Xr select 2
 101 a socket for the purposes of doing an
 102 .Fn accept
 103 by selecting it for read.
 104 .Pp
 105 For certain protocols which require an explicit confirmation,
 106 such as
 107 .Tn ISO
 108 or
 109 .Tn DATAKIT ,
 110 .Fn accept
 111 can be thought of
 112 as merely dequeuing the next connection
 113 request and not implying confirmation.
 114 Confirmation can be implied by a normal read or write on the new
 115 file descriptor, and rejection can be implied by closing the
 116 new socket.
 117 .Pp
 118 One can obtain user connection request data without confirming
 119 the connection by issuing a
 120 .Xr recvmsg 2
 121 call with an
 122 .Fa msg_iovlen
 123 of 0 and a non-zero
 124 .Fa msg_controllen ,
 125 or by issuing a
 126 .Xr getsockopt 2
 127 request.
 128 Similarly, one can provide user connection rejection information
 129 by issuing a
 130 .Xr sendmsg 2
 131 call with providing only the control information,
 132 or by calling
 133 .Xr setsockopt 2 .
 134 .Sh RETURN VALUES
 135 The call returns \-1 on error.  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 will fail if:
 141 .Bl -tag -width Er
 142 .It Bq Er EBADF
 143 The descriptor is invalid.
 144 .It Bq Er ENOTSOCK
 145 The descriptor references a file, not a socket.
 146 .It Bq Er EOPNOTSUPP
 147 The referenced socket is not of type
 148 .Dv SOCK_STREAM .
 149 .It Bq Er EFAULT
 150 The
 151 .Fa addr
 152 parameter is not in a writable part of the
 153 user address space.
 154 .It Bq Er EWOULDBLOCK
 155 The socket is marked non-blocking and no connections
 156 are present to be accepted.
 157 .It Bq Er EMFILE
 158 The per-process descriptor table is full.
 159 .It Bq Er ENFILE
 160 The system file table is full.
 161 .El
 162 .Sh SEE ALSO
 163 .Xr bind 2 ,
 164 .Xr connect 2 ,
 165 .Xr listen 2 ,
 166 .Xr select 2 ,
 167 .Xr socket 2
 168 .Sh HISTORY
 169 The
 170 .Fn accept
 171 function appeared in
 172 .Bx 4.2 .