Penguin
Recent Changes
Annotated edit history of socket(7) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 SOCKET
2 !!!SOCKET
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 SOCKET LAYER FUNCTIONS
7 SOCKET OPTIONS
8 SIGNALS
9 SYSCTLS
10 IOCTLS
11 NOTES
12 BUGS
13 VERSIONS
14 AUTHORS
15 SEE ALSO
16 ----
17 !!NAME
18
19
20 socket - Linux socket interface
21 !!SYNOPSIS
22
23
24 __#include __''
25 mysocket'' __= socket(int__ ''socket_family''__,
26 int__ ''socket_type''__, int__
27 ''protocol''__);__
28 !!DESCRIPTION
29
30
31 This manual page describes the Linux networking socket layer
32 user interface. The BSD compatible sockets are the uniform
33 interface between the user process and the network protocol
34 stacks in the kernel. The protocol modules are grouped into
35 ''protocol families'' like __PF_INET__, __PF_IPX__,
36 __PF_PACKET__ and ''socket types'' like
37 __SOCK_STREAM__ or __SOCK_DGRAM__. See
38 socket(2) for more information on families and
39 types.
40 !!SOCKET LAYER FUNCTIONS
41
42
43 These functions are used by the user process to send or
44 receive packets and to do other socket operations. For more
45 information see their respective manual pages.
46
47
48 socket(2) creates a socket, connect(2)
49 connects a socket to a remote socket address, the
50 bind(2) function binds a socket to a local socket
51 address, listen(2) tells the socket that new
52 connections shall be accepted, and accept(2) is used
53 to get a new socket with a new incomming connection.
54 socketpair(2) returns two connected anonymous sockets
55 (only implemented for a few local families like
56 __PF_UNIX__)
57
58
59 send(2), sendto(2), and sendmsg(2) send
60 data over a socket, and recv(2), recvfrom(2),
61 recvmsg(2) receive data from a socket. poll(2)
62 and select(2) wait for arriving data or a readiness
63 to send data. In addition, the standard I/O operations like
64 write(2), writev(2), sendfile(2),
65 read(2), and readv(2) can be used to read and
66 write data.
67
68
69 getsockname(2) returns the local socket address and
70 getpeername(2) returns the remote socket address.
71 getsockopt(2) and setsockopt(2) are used to
72 set or get socket layer or protocol options. ioctl(2)
73 can be used to set or read some other options.
74
75
76 close(2) is used to close a socket.
77 shutdown(2) closes parts of a full duplex socket
78 connection.
79
80
81 Seeking, or calling pread(2) or pwrite(2) with
82 a non-zero position is not supported on
83 sockets.
84
85
86 It is possible to do non-blocking IO on sockets by setting
87 the __O_NONBLOCK__ flag on a socket file descriptor using
88 fcntl(2). Then all operations that would block will
89 (usually) return with __EAGAIN__ (operation should be
90 retried later); connect(2) will return
91 __EINPROGRESS__ error. The user can then wait for various
92 events via poll(2) or select(2).
93
94
95 An alternative to poll/select is to let the kernel inform the application about events via a __SIGIO__ signal. For that the __FASYNC__ flag must be set on a socket file descriptor via fcntl(2) and a valid signal handler for __SIGIO__ must be installed via sigaction(2). See the ''SIGNALS'' discussion below.
96 !!SOCKET OPTIONS
97
98
99 These socket options can be set by using
100 setsockopt(2) and read with getsockopt(2) with
101 the socket level set to __SOL_SOCKET__ for all
102 sockets:
103
104
105 __SO_KEEPALIVE__
106
107
108 Enable sending of keep-alive messages on connection-oriented
109 sockets. Expects a integer boolean flag.
110
111
112 __SO_OOBINLINE__
113
114
115 If this option is enabled, out-of-band data is directly
116 placed into the receive data stream. Otherwise out-of-band
117 data is only passed when the __MSG_OOB__ flag is set
118 during receiving.
119
120
121 __SO_RCVLOWAT__ and __SO_SNDLOWAT__
122
123
124 Specify the minimum number of bytes in the buffer until the
125 socket layer will pass the data to the protocol
126 (__SO_SNDLOWAT__) or the user on receiving
127 (__SO_RCVLOWAT__). These two values are not changeable in
128 Linux and their argument size is always fixed to 1 byte.
129 __getsockopt__ is able to read them; __setsockopt__
130 will always return __ENOPROTOOPT__.
131
132
133 __SO_RCVTIMEO__ and __SO_SNDTIMEO__
134
135
136 Specify the sending or receiving timeouts until reporting an
137 error. They are fixed to a protocol specific setting in
138 Linux and cannot be read or written. Their functionality can
139 be emulated using alarm(2) or
140 setitimer(2).
141
142
143 __SO_BSDCOMPAT__
144
145
146 Enable BSD bug-to-bug compatibility. This is used only by
147 the UDP protocol module and scheduled to be removed in
148 future. If enabled ICMP errors received for a UDP socket
149 will not be passed to the user program. Linux 2.0 also
150 enabled BSD bug-to-bug compatibility options (random header
151 changing, skipping of the broadcast flag) for raw sockets
152 with this option, but that has been removed in Linux 2.2. It
153 is better to fix the user programs than to enable this
154 flag.
155
156
157 __SO_PASSCRED__
158
159
160 Enable or disable the receiving of the
161 __SCM_CREDENTIALS__ control message. For more information
162 see unix(7).
163
164
165 __SO_PEERCRED__
166
167
168 Return the credentials of the foreign process connected to
169 this socket. Only useful for __PF_UNIX__ sockets; see
170 unix(7). Argument is a __ucred__ structure. Only
171 valid as a __getsockopt__.
172
173
174 __SO_BINDTODEVICE__
175
176
177 Bind this socket to a particular device like ``eth0'', as
178 specified in the passed interface name. If the name is an
179 empty string or the option length is zero, the socket device
180 binding is removed. The passed option is a variable-length
181 null terminated interface name string with the maximum size
182 of __IFNAMSIZ__. If a socket is bound to an interface,
183 only packets received from that particular interface are
184 processed by the socket. Note that this only works for some
185 socket types, particularly __AF_INET__ sockets. It is not
186 supported for packet sockets (use normal bind(8)
187 there).
188
189
190 __SO_DEBUG__
191
192
193 Enable socket debugging. Only allowed for processes with the
194 __CAP_NET_ADMIN__ capability or an effective user id of
195 0.
196
197
198 __SO_REUSEADDR__
199
200
201 Indicates that the rules used in validating addresses
202 supplied in a bind(2) call should allow reuse of
203 local addresses. For __PF_INET__ sockets this means that
204 a socket may bind, except when there is an active listening
205 socket bound to the address. When the listening socket is
206 bound to __INADDR_ANY__ with a specific port then it is
207 not possible to bind to this port for any local
208 address.
209
210
211 __SO_TYPE__
212
213
214 Gets the socket type as an integer (like
215 __SOCK_STREAM__). Can be only read with
216 __getsockopt__.
217
218
219 __SO_DONTROUTE__
220
221
222 Don't send via a gateway, only send to directly connected
223 hosts. The same effect can be achieved by setting the
224 __MSG_DONTROUTE__ flag on a socket send(2)
225 operation. Expects an integer boolean flag.
226
227
228 __SO_BROADCAST__
229
230
231 Set or get the broadcast flag. When enabled, datagram
232 sockets receive packets sent to a broadcast address and they
233 are allowed to send packets to a broadcast address. This
234 option has no effect on stream-oriented
235 sockets.
236
237
238 __SO_SNDBUF__
239
240
241 Sets or gets the maximum socket send buffer in bytes. The
242 default value is set by the __wmem_default__ sysctl and
243 the maximum allowed value is set by the __wmem_max__
244 sysctl.
245
246
247 __SO_RCVBUF__
248
249
250 Sets or gets the maximum socket receive buffer in bytes. The
251 default value is set by the __rmem_default__ sysctl and
252 the maximum allowed value is set by the __rmem_max__
253 sysctl.
254
255
256 __SO_LINGER__
257
258
259 Sets or gets the __SO_LINGER__ option. The argument is a
260 __linger__ structure.
261
262
263 struct linger {
264 int l_onoff; /* linger active */
265 int l_linger; /* how many seconds to linger for */
266 };
267
268
269 When enabled, a close(2) or shutdown(2) will
270 not return until all queued messages for the socket have
271 been successfully sent or the linger timeout has been
272 reached. Otherwise, the call returns immediately and the
273 closing is done in the background. When the socket is closed
274 as part of exit(2), it always lingers in the
275 background.
276
277
278 __SO_PRIORITY__
279
280
281 Set the protocol-defined priority for all packets to be sent
282 on this socket. Linux uses this value to order the
283 networking queues: packets with a higher priority may be
284 processed first depending on the selected device queueing
285 discipline. For ip(7), this also sets the IP
286 type-of-service (TOS) field for outgoing
287 packets.
288
289
290 __SO_ERROR__
291
292
293 Get and clear the pending socket error. Only valid as a
294 __getsockopt__. Expects an integer.
295 !!SIGNALS
296
297
298 When writing onto a connection-oriented socket that has been
299 shut down (by the local or the remote end) __SIGPIPE__ is
300 sent to the writing process and __EPIPE__ is returned.
301 The signal is not sent when the write call specified the
302 __MSG_NOSIGNAL__ flag.
303
304
305 When requested with the __FIOCSETOWN__ fcntl or
306 __SIOCSPGRP__ ioctl, __SIGIO__ is sent when an I/O
307 event occurs. It is possible to use poll(2) or
308 select(2) in the signal handler to find out which
309 socket the event occurred on. An alternative (in Linux 2.2)
310 is to set a realtime signal using the __F_SETSIG__ fcntl;
311 the handler of the real time signal will be called with the
312 file descriptor in the ''si_fd'' field of its
313 ''siginfo_t''. See fcntl(2) for more
314 information.
315
316
317 Under some circumstances (e.g. multiple processes accessing
318 a single socket), the condition that caused the __SIGIO__
319 may have already disappeared when the process reacts to the
320 signal. If this happens, the process should wait again
321 because Linux will resend the signal later.
322 !!SYSCTLS
323
324
325 The core socket networking sysctls can be accessed using the
326 __/proc/sys/net/core/*__ files or with the
327 sysctl(2) interface.
328
329
330 __rmem_default__
331
332
333 contains the default setting in bytes of the socket receive
334 buffer.
335
336
337 __rmem_max__
338
339
340 contains the maximum socket receive buffer size in bytes
341 which a user may set by using the __SO_RCVBUF__ socket
342 option.
343
344
345 __wmem_default__
346
347
348 contains the default setting in bytes of the socket send
349 buffer.
350
351
352 __wmem_max__
353
354
355 contains the maximum socket send buffer size in bytes which
356 a user may set by using the __SO_SNDBUF__ socket
357 option.
358
359
360 __message_cost__ and __message_burst__
361
362
363 configure the token bucket filter used to load limit warning
364 messages caused by external network events.
365
366
367 __netdev_max_backlog__
368
369
370 Maximum number of packets in the global input
371 queue.
372
373
374 __optmem_max__
375
376
377 Maximum length of ancillary data and user control data like
378 the iovecs per socket.
379 !!IOCTLS
380
381
382 These ioctls can be accessed using
383 ioctl(2):
384
385
386 ''error'' __= ioctl(__''ip_socket''__,__ ''ioctl_type''__,__ ''''__);
387 __
388
389
390 __SIOCGSTAMP__
391
392
393 Return a __struct timeval__ with the receive timestamp of
394 the last packet passed to the user. This is useful for
395 accurate round trip time measurements. See
396 setitimer(2) for a description of __struct
397 timeval__.
398
399
400 __SIOCSPGRP__
401
402
403 Set the process or process group to send __SIGIO__ or
404 __SIGURG__ signals to when an asynchronous I/O operation
405 has finished or urgent data is available. The argument is a
406 pointer to a __pid_t__. If the argument is positive, send
407 the signals to that process. If the argument is negative,
408 send the signals to the process group with the id of the
409 absolute value of the argument. The process may only choose
410 itself or its own process group to receive signals unless it
411 has the __CAP_KILL__ capability or an effective UID of
412 0.
413
414
415 __FIOASYNC__
416
417
418 Change the __O_ASYNC__ flag to enable or disable
419 asynchronous IO mode of the socket. Asynchronous IO mode
420 means that the __SIGIO__ signal or the signal set with
421 __F_SETSIG__ is raised when a new I/O event
422 occurs.
423
424
425 Argument is a integer boolean flag.
426
427
428 __SIOCGPGRP__
429
430
431 Get the current process or process group that receives
432 __SIGIO__ or __SIGURG__ signals, or 0 when none is
433 set.
434
435
436 Valid fcntls:
437
438
439 __FIOCGETOWN__
440
441
442 The same as the SIOCGPGRP ioctl.
443
444
445 __FIOCSETOWN__
446
447
448 The same as the SIOCSPGRP ioctl
449 !!NOTES
450
451
452 Linux assumes that half of the send/receive buffer is used
453 for internal kernel structures; thus the sysctls are twice
454 what can be observed on the wire.
455 !!BUGS
456
457
458 The __CONFIG_FILTER__ socket options
459 __SO_ATTACH_FILTER__ and __SO_DETACH_FILTER__ are not
460 documented. The suggested interface to use them is via the
461 libpcap library.
462 !!VERSIONS
463
464
465 __SO_BINDTODEVICE__ was introduced in Linux 2.0.30.
466 __SO_PASSCRED__ is new in Linux 2.2. The sysctls are new
467 in Linux 2.2.
468 !!AUTHORS
469
470
471 This man page was written by Andi Kleen.
472 !!SEE ALSO
473
474
475 socket(2), ip(7), setsockopt(2),
476 getsockopt(2), packet(7),
477 ddp(7)
478 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.