Print this page
3769 Implement SOCK_NONBLOCK flag to socket()
Reviewed-by: Robert Mustacchi <rm@joyent.com>
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3socket/socket.3socket
+++ new/usr/src/man/man3socket/socket.3socket
1 1 '\" te
2 2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" Copyright 1989 AT&T
4 4 .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All Rights Reserved.
5 5 .\" 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.
6 6 .\" 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.
7 7 .\" 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]
8 8 .TH SOCKET 3SOCKET "Jan 28, 2009"
9 9 .SH NAME
10 10 socket \- create an endpoint for communication
11 11 .SH SYNOPSIS
12 12 .LP
13 13 .nf
14 14 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
15 15 #include <sys/types.h>
16 16 #include <sys/socket.h>
17 17
18 18 \fBint\fR \fBsocket\fR(\fBint\fR \fIdomain\fR, \fBint\fR \fItype\fR, \fBint\fR \fIprotocol\fR);
19 19 .fi
20 20
21 21 .SH DESCRIPTION
22 22 .sp
23 23 .LP
24 24 The \fBsocket()\fR function creates an endpoint for communication and returns a
25 25 descriptor.
26 26 .sp
27 27 .LP
28 28 The \fIdomain\fR argument specifies the protocol family within which
29 29 communication takes place. The protocol family is generally the same as the
30 30 address family for the addresses supplied in later operations on the socket.
31 31 These families are defined in \fB<sys/socket.h>\fR.
32 32 .sp
33 33 .LP
34 34 The currently supported protocol families are:
35 35 .sp
36 36 .ne 2
37 37 .na
38 38 \fB\fBPF_UNIX\fR\fR
39 39 .ad
40 40 .RS 12n
41 41 \fBUNIX\fR system internal protocols
42 42 .RE
43 43
44 44 .sp
45 45 .ne 2
46 46 .na
47 47 \fB\fBPF_INET\fR\fR
48 48 .ad
49 49 .RS 12n
50 50 Internet Protocol Version 4 (IPv4)
51 51 .RE
52 52
53 53 .sp
54 54 .ne 2
55 55 .na
56 56 \fB\fBPF_INET6\fR\fR
57 57 .ad
58 58 .RS 12n
59 59 Internet Protocol Version 6 (IPv6)
60 60 .RE
61 61
62 62 .sp
63 63 .ne 2
64 64 .na
65 65 \fB\fBPF_NCA\fR\fR
66 66 .ad
67 67 .RS 12n
68 68 Network Cache and Accelerator (NCA) protocols
69 69 .RE
70 70
71 71 .sp
72 72 .LP
73 73 The socket has the indicated \fItype\fR, which specifies the communication
74 74 semantics. Currently defined types are:
75 75 .sp
76 76 .in +2
77 77 .nf
78 78 SOCK_STREAM
79 79 SOCK_DGRAM
80 80 SOCK_RAW
81 81 SOCK_SEQPACKET
82 82 SOCK_RDM
83 83 .fi
84 84 .in -2
85 85
86 86 .sp
87 87 .LP
88 88 The \fItype\fR may be augmented by a bitwise-inclusive-OR of flags from the
89 89 following list, defined in <sys/socket.h>.
90 90
91 91 .sp
92 92 .ne 2
|
↓ open down ↓ |
92 lines elided |
↑ open up ↑ |
93 93 .na
94 94 \fB\fBSOCK_CLOEXEC\fR\fR
95 95 .ad
96 96 .RS 12n
97 97 Creates the socket with the \fBFD_CLOEXEC\fR flag set, causing the underlying
98 98 file descriptor to be closed prior to any future calls to \fBexec\fR(2). This
99 99 is similar in purpose to the \fBO_CLOEXEC\fR flag to \fBopen\fR(2).
100 100 .RE
101 101
102 102 .sp
103 +.ne 2
104 +.na
105 +\fB\fBSOCK_NDELAY\fR\fR
106 +.ad
107 +.RS 12n
108 +Creates the socket with the \fBO_NDELAY\fR flag set, causing the socket to
109 +provide nonblocking semantics as described for \fBO_NDELAY\fR in \fBopen\fR(2).
110 +\fBSOCK_NONBLOCK\fR should normally be used in preference to \fBSOCK_NDELAY\fR,
111 +and takes precedence if both are set. See \fBopen\fR(2) for further details.
112 +.RE
113 +
114 +.sp
115 +.ne 2
116 +.na
117 +\fB\fBSOCK_NONBLOCK\fR\fR
118 +.ad
119 +.RS 12n
120 +Creates the socket with the \fBO_NONBLOCK\fR flag set, causing the socket to
121 +provide nonblocking semantics as described for \fBO_NONBLOCK\fR in \fBopen\fR(2).
122 +.RE
123 +
124 +.sp
103 125 .LP
104 126 There must be an entry in the \fBnetconfig\fR(4) file for at least each
105 127 protocol family and type required. If a non-zero protocol has been specified
106 128 but no exact match for the protocol family, type, and protocol is found, then
107 129 the first entry containing the specified family and type with a \fIprotocol\fR
108 130 value of zero will be used.
109 131 .sp
110 132 .LP
111 133 A \fBSOCK_STREAM\fR type provides sequenced, reliable, two-way connection-based
112 134 byte streams. An out-of-band data transmission mechanism may be supported. A
113 135 \fBSOCK_DGRAM\fR socket supports datagrams (connectionless, unreliable messages
114 136 of a fixed (typically small) maximum length). A \fBSOCK_SEQPACKET\fR socket may
115 137 provide a sequenced, reliable, two-way connection-based data transmission path
116 138 for datagrams of fixed maximum length; a consumer may be required to read an
117 139 entire packet with each read system call. This facility is protocol specific,
118 140 and presently not implemented for any protocol family. \fBSOCK_RAW\fR sockets
119 141 provide access to internal network interfaces. The types \fBSOCK_RAW\fR, which
120 142 is available only to a user with the \fBnet_rawaccess\fR privilege, and
121 143 \fBSOCK_RDM\fR, for which no implementation currently exists, are not described
122 144 here.
123 145 .sp
124 146 .LP
125 147 The \fIprotocol\fR parameter is a protocol-family-specific value which
126 148 specifies a particular protocol to be used with the socket. Normally this
127 149 value is zero, as commonly only a single protocol exists to support a
128 150 particular socket type within a given protocol family. However, multiple
129 151 protocols may exist, in which case a particular protocol may be specified in
130 152 this manner.
131 153 .sp
132 154 .LP
133 155 Sockets of type \fBSOCK_STREAM\fR are full-duplex byte streams, similar to
134 156 pipes. A stream socket must be in a \fIconnected\fR state before any data may
135 157 be sent or received on it. A connection to another socket is created with a
136 158 \fBconnect\fR(3SOCKET) call. Once connected, data may be transferred using
137 159 \fBread\fR(2) and \fBwrite\fR(2) calls or some variant of the
138 160 \fBsend\fR(3SOCKET) and \fBrecv\fR(3SOCKET) calls. When a session has been
139 161 completed, a \fBclose\fR(2) may be performed. Out-of-band data may also be
140 162 transmitted as described on the \fBsend\fR(3SOCKET) manual page and received as
141 163 described on the \fBrecv\fR(3SOCKET) manual page.
142 164 .sp
143 165 .LP
144 166 The communications protocols used to implement a \fBSOCK_STREAM\fR insure that
145 167 data is not lost or duplicated. If a piece of data for which the peer protocol
146 168 has buffer space cannot be successfully transmitted within a reasonable length
147 169 of time, then the connection is considered broken and calls will indicate an
148 170 error with \(mi1 returns and with \fBETIMEDOUT\fR as the specific code in the
149 171 global variable \fBerrno\fR. The protocols optionally keep sockets "warm" by
150 172 forcing transmissions roughly every minute in the absence of other activity. An
151 173 error is then indicated if no response can be elicited on an otherwise idle
152 174 connection for a extended period (for instance 5 minutes). A \fBSIGPIPE\fR
153 175 signal is raised if a thread sends on a broken stream; this causes naive
154 176 processes, which do not handle the signal, to exit.
155 177 .sp
156 178 .LP
157 179 \fBSOCK_SEQPACKET\fR sockets employ the same system calls as \fBSOCK_STREAM\fR
158 180 sockets. The only difference is that \fBread\fR(2) calls will return only the
159 181 amount of data requested, and any remaining in the arriving packet will be
160 182 discarded.
161 183 .sp
162 184 .LP
163 185 \fBSOCK_DGRAM\fR and \fBSOCK_RAW\fR sockets allow datagrams to be sent to
164 186 correspondents named in \fBsendto\fR(3SOCKET) calls. Datagrams are generally
165 187 received with \fBrecvfrom\fR(3SOCKET), which returns the next datagram with its
166 188 return address.
167 189 .sp
168 190 .LP
169 191 An \fBfcntl\fR(2) call can be used to specify a process group to receive a
170 192 \fBSIGURG\fR signal when the out-of-band data arrives. It can also enable
171 193 non-blocking I/O.
172 194 .sp
173 195 .LP
174 196 The operation of sockets is controlled by socket level \fIoptions\fR. These
175 197 options are defined in the file <\fBsys/socket.h\fR>. \fBsetsockopt\fR(3SOCKET)
176 198 and \fBgetsockopt\fR(3SOCKET) are used to set and get options, respectively.
177 199 .SH RETURN VALUES
178 200 .sp
179 201 .LP
180 202 Upon successful completion, a descriptor referencing the socket is returned.
181 203 Otherwise, -1 is returned and \fBerrno\fR is set to indicate the error.
182 204 .SH ERRORS
183 205 .sp
184 206 .LP
185 207 The \fBsocket()\fR function will fail if:
186 208 .sp
187 209 .ne 2
188 210 .na
189 211 \fB\fBEACCES\fR\fR
190 212 .ad
191 213 .RS 19n
192 214 Permission to create a socket of the specified type or protocol is denied.
193 215 .RE
194 216
195 217 .sp
196 218 .ne 2
197 219 .na
198 220 \fB\fBEAGAIN\fR\fR
199 221 .ad
200 222 .RS 19n
201 223 There were insufficient resources available to complete the operation.
202 224 .RE
203 225
204 226 .sp
205 227 .ne 2
206 228 .na
207 229 \fB\fBEAFNOSUPPORT\fR\fR
208 230 .ad
209 231 .RS 19n
210 232 The specified address family is not supported by the protocol family.
211 233 .RE
212 234
213 235 .sp
214 236 .ne 2
215 237 .na
216 238 \fB\fBEMFILE\fR\fR
217 239 .ad
218 240 .RS 19n
219 241 The per-process descriptor table is full.
220 242 .RE
221 243
222 244 .sp
223 245 .ne 2
224 246 .na
225 247 \fB\fBENOMEM\fR\fR
226 248 .ad
227 249 .RS 19n
228 250 Insufficient user memory is available.
229 251 .RE
230 252
231 253 .sp
232 254 .ne 2
233 255 .na
234 256 \fB\fBENOSR\fR\fR
235 257 .ad
236 258 .RS 19n
237 259 There were insufficient STREAMS resources available to complete the operation.
238 260 .RE
239 261
240 262 .sp
241 263 .ne 2
242 264 .na
243 265 \fB\fBEPFNOSUPPORT\fR\fR
244 266 .ad
245 267 .RS 19n
246 268 The specified protocol family is not supported.
247 269 .RE
248 270
249 271 .sp
250 272 .ne 2
251 273 .na
252 274 \fB\fBEPROTONOSUPPORT\fR\fR
253 275 .ad
254 276 .RS 19n
255 277 The protocol type is not supported by the address family.
256 278 .RE
|
↓ open down ↓ |
144 lines elided |
↑ open up ↑ |
257 279
258 280 .sp
259 281 .ne 2
260 282 .na
261 283 \fB\fBEPROTOTYPE\fR\fR
262 284 .ad
263 285 .RS 19n
264 286 The socket type is not supported by the protocol.
265 287 .RE
266 288
289 +.sp
290 +.ne 2
291 +.na
292 +\fB\fBEINVAL\fR\fR
293 +.ad
294 +.RS 19n
295 +One or more of the specified flags is not supported.
296 +.RE
297 +
267 298 .SH ATTRIBUTES
268 299 .sp
269 300 .LP
270 301 See \fBattributes\fR(5) for descriptions of the following attributes:
271 302 .sp
272 303
273 304 .sp
274 305 .TS
275 306 box;
276 307 c | c
277 308 l | l .
278 309 ATTRIBUTE TYPE ATTRIBUTE VALUE
279 310 _
280 311 MT-Level Safe
281 312 .TE
282 313
283 314 .SH SEE ALSO
284 315 .sp
285 316 .LP
286 317 \fBnca\fR(1), \fBclose\fR(2), \fBfcntl\fR(2), \fBioctl\fR(2), \fBread\fR(2),
287 318 \fBwrite\fR(2), \fBaccept\fR(3SOCKET), \fBbind\fR(3SOCKET), \fBexec\fR(2),
288 319 \fBconnect\fR(3SOCKET), \fBgetsockname\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET),
289 320 \fBin.h\fR(3HEAD),\fBlisten\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBopen\fR(2),
290 321 \fBsetsockopt\fR(3SOCKET), \fBsend\fR(3SOCKET), \fBshutdown\fR(3SOCKET),
291 322 \fBsocket.h\fR(3HEAD), \fBsocketpair\fR(3SOCKET), \fBattributes\fR(5)
292 323 .SH NOTES
293 324 .sp
294 325 .LP
295 326 Historically, \fBAF_\fR* was commonly used in places where \fBPF_\fR* was
296 327 meant. New code should be careful to use \fBPF_\fR* as necessary.
|
↓ open down ↓ |
20 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX