usr/src/man/man3xnet/accept.3xnet

   1 '\" te
   2 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved  Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4 .\" http://www.opengroup.org/bookstore/.
   5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   6 .\"  This notice shall appear on any product containing this material.
   7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  10 .TH ACCEPT 3XNET "Nov 1, 2003"
  11 .SH NAME
  12 accept \- accept a new connection on a socket
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lxnet\fR [ \fIlibrary\fR ... ]
  17 #include <sys/socket.h>
  18
  19
  20 \fBint\fR \fBaccept\fR(\fBint\fR \fIsocket\fR, \fBstruct sockaddr *restrict\fR \fIaddress\fR,
  21      \fBsocklen_t *restrict\fR \fIaddress_len\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .LP
  26 The \fBaccept()\fR function extracts the first connection on the queue of
  27 pending connections, creates a new socket with the same socket type protocol
  28 and address family as the specified socket, and allocates a new file descriptor
  29 for that socket.
  30 .sp
  31 .LP
  32 The function takes the following arguments:
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIsocket\fR\fR
  37 .ad
  38 .RS 15n
  39 Specifies a socket that was created with \fBsocket\fR(3XNET), has been bound to
  40 an address with \fBbind\fR(3XNET), and has issued a successful call to
  41 \fBlisten\fR(3XNET).
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIaddress\fR\fR
  48 .ad
  49 .RS 15n
  50 Either a null pointer, or a pointer to a \fBsockaddr\fR structure where the
  51 address of the connecting socket will be returned.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIaddress_len\fR\fR
  58 .ad
  59 .RS 15n
  60 Points to a \fBsocklen_t\fR which on input specifies the length of the supplied
  61 \fBsockaddr\fR structure, and on output specifies the length of the stored
  62 address.
  63 .RE
  64
  65 .sp
  66 .LP
  67 If \fIaddress\fR is not a null pointer, the address of the peer for the
  68 accepted connection is stored in the \fBsockaddr\fR structure pointed to by
  69 \fIaddress\fR, and the length of this address is stored in the object pointed
  70 to by \fIaddress_len\fR.
  71 .sp
  72 .LP
  73 If the actual length of the address is greater than the length of the supplied
  74 \fBsockaddr\fR structure, the stored address will be truncated.
  75 .sp
  76 .LP
  77 If the protocol permits connections by unbound clients, and the peer is not
  78 bound, then the value stored in the object pointed to by \fIaddress\fR is
  79 unspecified.
  80 .sp
  81 .LP
  82 If the listen queue is empty of connection requests and O_NONBLOCK is not set
  83 on the file descriptor for the socket, \fBaccept()\fR will block until a
  84 connection is present. If the \fBlisten\fR(3XNET) queue is empty of connection
  85 requests and O_NONBLOCK is set on the file descriptor for the socket,
  86 \fBaccept()\fR will fail and set \fBerrno\fR to \fBEAGAIN\fR or
  87 \fBEWOULDBLOCK\fR.
  88 .sp
  89 .LP
  90 The accepted socket cannot itself accept more connections.  The original socket
  91 remains open and can accept more connections.
  92 .SH USAGE
  93 .LP
  94 When a connection is available, \fBselect\fR(3C) will indicate that the file
  95 descriptor for the socket is ready for reading.
  96 .SH RETURN VALUES
  97 .LP
  98 Upon successful completion, \fBaccept()\fR returns the nonnegative file
  99 descriptor of the accepted socket.  Otherwise, \(mi1 is returned and
 100 \fBerrno\fR is set to indicate the error.
 101 .SH ERRORS
 102 .LP
 103 The \fBaccept()\fR function will fail if:
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBEAGAIN\fR\fR
 108 .ad
 109 .br
 110 .na
 111 \fB\fBEWOULDBLOCK\fR\fR
 112 .ad
 113 .RS 16n
 114 O_NONBLOCK is set for the socket file descriptor and no connections are present
 115 to be accepted.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBEBADF\fR\fR
 122 .ad
 123 .RS 16n
 124 The \fIsocket\fR argument is not a valid file descriptor.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBECONNABORTED\fR\fR
 131 .ad
 132 .RS 16n
 133 A connection has been aborted.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBEFAULT\fR\fR
 140 .ad
 141 .RS 16n
 142 The  \fIaddress\fR or  \fIaddress_len\fR parameter can not be accessed or
 143 written.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBEINTR\fR\fR
 150 .ad
 151 .RS 16n
 152 The \fBaccept()\fR function was interrupted by a signal that was caught before
 153 a valid connection arrived.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBEINVAL\fR\fR
 160 .ad
 161 .RS 16n
 162 The \fIsocket\fR is not accepting connections.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBEMFILE\fR\fR
 169 .ad
 170 .RS 16n
 171 \fBOPEN_MAX\fR file descriptors are currently open in the calling process.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBENFILE\fR\fR
 178 .ad
 179 .RS 16n
 180 The maximum number of file descriptors in the system are already open.
 181 .RE
 182
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fBENOTSOCK\fR\fR
 187 .ad
 188 .RS 16n
 189 The \fIsocket\fR argument does not refer to a socket.
 190 .RE
 191
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fBEOPNOTSUPP\fR\fR
 196 .ad
 197 .RS 16n
 198 The socket type of the specified socket does not support accepting connections.
 199 .RE
 200
 201 .sp
 202 .LP
 203 The \fBaccept()\fR function may fail if:
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBENOBUFS\fR\fR
 208 .ad
 209 .RS 11n
 210 No buffer space is available.
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fBENOMEM\fR\fR
 217 .ad
 218 .RS 11n
 219 There was insufficient memory available to complete the operation.
 220 .RE
 221
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBENOSR\fR\fR
 226 .ad
 227 .RS 11n
 228 There was insufficient STREAMS resources available to complete the operation.
 229 .RE
 230
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBEPROTO\fR\fR
 235 .ad
 236 .RS 11n
 237 A protocol error has occurred; for example, the STREAMS protocol stack has not
 238 been initialized.
 239 .RE
 240
 241 .SH ATTRIBUTES
 242 .LP
 243 See \fBattributes\fR(5) for descriptions of the following attributes:
 244 .sp
 245
 246 .sp
 247 .TS
 248 box;
 249 c | c
 250 l | l .
 251 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 252 _
 253 Interface Stability     Standard
 254 _
 255 MT-Level        MT-Safe
 256 .TE
 257
 258 .SH SEE ALSO
 259 .LP
 260 \fBsockaddr\fR(3SOCKET),
 261 \fBbind\fR(3XNET), \fBconnect\fR(3XNET), \fBlisten\fR(3XNET),
 262 \fBsocket\fR(3XNET), \fBattributes\fR(5), \fBstandards\fR(5)