2 .\" Don't change the first line, it tells man that we need tbl.
3 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
4 .\" and copyright (c) 1999 Matthew Wilcox.
5 .\" Permission is granted to distribute possibly modified copies
6 .\" of this page provided the header is included verbatim,
7 .\" and in case of nontrivial modification author and date
8 .\" of the modification is added to the header.
10 .\" 2002-10-30, Michael Kerrisk, <mtk.manpages@gmail.com>
11 .\" Added description of SO_ACCEPTCONN
12 .\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text.
13 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
14 .\" Added notes on capability requirements
15 .\" A few small grammar fixes
17 .\" FIXME probably all PF_* should be AF_* in this page, since
18 .\" POSIX only specifies the latter values.
20 .TH SOCKET 7 2007-12-28 Linux "Linux Programmer's Manual"
22 socket \- Linux socket interface
24 .B #include <sys/socket.h>
26 .IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol );
28 This manual page describes the Linux networking socket layer user
30 The BSD compatible sockets
31 are the uniform interface
32 between the user process and the network protocol stacks in the kernel.
33 The protocol modules are grouped into
36 .BR PF_INET ", " PF_IPX ", " PF_PACKET
45 for more information on families and types.
46 .SS Socket Layer Functions
47 These functions are used by the user process to send or receive packets
48 and to do other socket operations.
49 For more information see their respective manual pages.
54 connects a socket to a remote socket address,
57 function binds a socket to a local socket address,
59 tells the socket that new connections shall be accepted, and
61 is used to get a new socket with a new incoming connection.
63 returns two connected anonymous sockets (only implemented for a few
71 send data over a socket, and
75 receive data from a socket.
79 wait for arriving data or a readiness to send data.
80 In addition, the standard I/O operations like
87 can be used to read and write data.
90 returns the local socket address and
92 returns the remote socket address.
96 are used to set or get socket layer or protocol options.
98 can be used to set or read some other options.
101 is used to close a socket.
103 closes parts of a full-duplex socket connection.
109 with a non-zero position is not supported on sockets.
111 It is possible to do non-blocking I/O on sockets by setting the
113 flag on a socket file descriptor using
115 Then all operations that would block will (usually)
118 (operation should be retried later);
123 The user can then wait for various events via
132 Event:Poll flag:Occurrence
137 A connection setup has been completed
138 (for connection-oriented sockets)
141 A disconnection request has been initiated by the other end.
144 A connection is broken (only for connection-oriented protocols).
145 When the socket is written
150 Socket has enough send buffer space for writing new data.
161 Read/Write:POLLERR:An asynchronous error occurred.
162 Read/Write:POLLHUP:The other end has shut down one direction.
168 .\" FIXME . The following is not true currently:
169 .\" It is no I/O event when the connection
170 .\" is broken from the local end using
181 is to let the kernel inform the application about events
187 flag must be set on a socket file descriptor via
189 and a valid signal handler for
191 must be installed via
197 These socket options can be set by using
201 with the socket level set to
204 .\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in
205 .\" W R Stevens, UNPv1
208 Returns a value indicating whether or not this socket has been marked
209 to accept connections with
211 The value 0 indicates that this is not a listening socket,
212 the value 1 indicates that this is a listening socket.
218 Bind this socket to a particular device like \(lqeth0\(rq,
219 as specified in the passed interface name.
221 name is an empty string or the option length is zero, the socket device
223 The passed option is a variable-length null terminated
224 interface name string with the maximum size of
226 If a socket is bound to an interface,
227 only packets received from that particular interface are processed by the
229 Note that this only works for some socket types, particularly
232 It is not supported for packet sockets (use normal
237 Set or get the broadcast flag.
238 When enabled, datagram sockets
239 receive packets sent to a broadcast address and they are allowed to send
240 packets to a broadcast address.
241 This option has no effect on stream-oriented sockets.
244 Enable BSD bug-to-bug compatibility.
245 This is used by the UDP protocol module in Linux 2.0 and 2.2.
246 If enabled ICMP errors received for a UDP socket will not be passed
248 In later kernel versions, support for this option has been phased out:
249 Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning
250 (printk()) if a program uses this option.
251 Linux 2.0 also enabled BSD bug-to-bug compatibility
252 options (random header changing, skipping of the broadcast flag) for raw
253 sockets with this option, but that was removed in Linux 2.2.
256 Enable socket debugging.
257 Only allowed for processes with the
259 capability or an effective user ID of 0.
262 Get and clear the pending socket error.
268 Don't send via a gateway, only send to directly connected hosts.
269 The same effect can be achieved by setting the
274 Expects an integer boolean flag.
277 Enable sending of keep-alive messages on connection-oriented sockets.
278 Expects an integer boolean flag.
291 int l_onoff; /* linger active */
292 int l_linger; /* how many seconds to linger for */
301 will not return until all queued messages for the socket have been
302 successfully sent or the linger timeout has been reached.
304 the call returns immediately and the closing is done in the background.
305 When the socket is closed as part of
307 it always lingers in the background.
310 If this option is enabled,
311 out-of-band data is directly placed into the receive data stream.
312 Otherwise out-of-band data is only passed when the
314 flag is set during receiving.
315 .\" don't document it because it can do too much harm.
319 Enable or disable the receiving of the
322 For more information see
324 .\" FIXME Document SO_PASSSEC, added in 2.6.18; there is some info
325 .\" in the 2.6.18 ChangeLog
328 Return the credentials of the foreign process connected to this socket.
329 This is only possible for connected
333 stream and datagram socket pairs created using
337 The returned credentials are those that were in effect at the time
349 Set the protocol-defined priority for all packets to be sent on
351 Linux uses this value to order the networking queues:
352 packets with a higher priority may be processed first depending
353 on the selected device queueing discipline.
356 this also sets the IP type-of-service (TOS) field for outgoing packets.
357 Setting a priority outside the range 0 to 6 requires the
362 Sets or gets the maximum socket receive buffer in bytes.
363 The kernel doubles this value (to allow space for bookkeeping overhead)
365 .\" Most (all?) other implementations do not do this -- MTK, Dec 05
367 and this doubled value is returned by
369 The default value is set by the
371 sysctl and the maximum allowed value is set by the
374 The minimum (doubled) value for this option is 256.
376 .BR SO_RCVBUFFORCE " (since Linux 2.6.14)"
377 Using this socket option, a privileged
378 .RB ( CAP_NET_ADMIN )
379 process can perform the same task as
383 limit can be overridden.
385 .BR SO_RCVLOWAT " and " SO_SNDLOWAT
386 Specify the minimum number of bytes in the buffer until the socket layer
387 will pass the data to the protocol
389 or the user on receiving
391 These two values are initialized to 1.
393 is not changeable on Linux
399 only since Linux 2.4.
404 system calls currently do not respect the
407 and mark a socket readable when even a single byte of data is available.
408 A subsequent read from the socket will block until
411 .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2
412 .\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05
414 .BR SO_RCVTIMEO " and " SO_SNDTIMEO
415 .\" Not implemented in 2.0.
416 .\" Implemented in 2.1.11 for getsockopt: always return a zero struct.
417 .\" Implemented in 2.3.41 for setsockopt, and actually used.
418 Specify the receiving or sending timeouts until reporting an error.
420 .IR "struct timeval" .
421 If an input or output function blocks for this period of time, and
422 data has been sent or received, the return value of that function
423 will be the amount of data transferred; if no data has been transferred
424 and the timeout has been reached then \-1 is returned with
430 .\" in fact to EAGAIN
431 just as if the socket was specified to be non-blocking.
432 If the timeout is set to zero (the default)
433 then the operation will never timeout.
434 Timeouts only have effect for system calls that perform socket I/O (e.g.,
439 timeouts have no effect for
446 Indicates that the rules used in validating addresses supplied in a
448 call should allow reuse of local addresses.
452 means that a socket may bind, except when there
453 is an active listening socket bound to the address.
454 When the listening socket is bound to
456 with a specific port then it is not possible
457 to bind to this port for any local address.
458 Argument is an integer boolean flag.
461 Sets or gets the maximum socket send buffer in bytes.
462 The kernel doubles this value (to allow space for bookkeeping overhead)
464 .\" Most (all?) other implementations do not do this -- MTK, Dec 05
466 and this doubled value is returned by
468 The default value is set by the
470 sysctl and the maximum allowed value is set by the
473 The minimum (doubled) value for this option is 2048.
475 .BR SO_SNDBUFFORCE " (since Linux 2.6.14)"
476 Using this socket option, a privileged
477 .RB ( CAP_NET_ADMIN )
478 process can perform the same task as
482 limit can be overridden.
485 Enable or disable the receiving of the
488 The timestamp control message is sent with level
495 reception time of the last packet passed to the user in this call.
498 for details on control messages.
501 Gets the socket type as an integer (like
507 When writing onto a connection-oriented socket that has been shut down
508 (by the local or the remote end)
510 is sent to the writing process and
513 The signal is not sent when the write call
518 When requested with the
525 is sent when an I/O event occurs.
526 It is possible to use
530 in the signal handler to find out which socket the event occurred on.
531 An alternative (in Linux 2.2) is to set a real-time signal using the
534 the handler of the real time signal will be called with
535 the file descriptor in the
541 for more information.
543 Under some circumstances (e.g., multiple processes accessing a
544 single socket), the condition that caused the
546 may have already disappeared when the process reacts to the signal.
547 If this happens, the process should wait again because Linux
548 will resend the signal later.
549 .\" .SS Ancillary Messages
551 The core socket networking sysctls can be accessed using the
552 .I /proc/sys/net/core/*
558 contains the default setting in bytes of the socket receive buffer.
561 contains the maximum socket receive buffer size in bytes which a user may
567 contains the default setting in bytes of the socket send buffer.
570 contains the maximum socket send buffer size in bytes which a user may
575 .BR message_cost " and " message_burst
576 configure the token bucket filter used to load limit warning messages
577 caused by external network events.
579 .I netdev_max_backlog
580 Maximum number of packets in the global input queue.
583 Maximum length of ancillary data and user control data like the iovecs
585 .\" netdev_fastroute is not documented because it is experimental
587 These operations can be accessed using
592 .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");"
599 with the receive timestamp of the last packet passed to the user.
600 This is useful for accurate round trip time measurements.
604 .IR "struct timeval" .
606 This ioctl should only be used if the socket option
608 is not set on the socket.
609 Otherwise, it returns the timestamp of the
610 last packet that was received while
612 was not set, or it fails if no such packet has been received,
621 Set the process or process group to send
627 asynchronous I/O operation has finished or urgent data is available.
628 The argument is a pointer to a
630 If the argument is positive, send the signals to that process.
632 argument is negative, send the signals to the process group with the ID
633 of the absolute value of the argument.
634 The process may only choose itself or its own process group to receive
635 signals unless it has the
637 capability or an effective UID of 0.
642 flag to enable or disable asynchronous I/O mode of the socket.
643 Asynchronous I/O mode means that the
645 signal or the signal set with
647 is raised when a new I/O event occurs.
649 Argument is an integer boolean flag.
650 (This operation is synonymous with the use of
658 Get the current process or process group that receives
681 was introduced in Linux 2.0.30.
684 The sysctls are new in Linux 2.2.
688 are supported since Linux 2.3.41.
689 Earlier, timeouts were fixed to
690 a protocol-specific setting, and could not be read or written.
692 Linux assumes that half of the send/receive buffer is used for internal
693 kernel structures; thus the sysctls are twice what can be observed
696 Linux will only allow port re-use with the
699 when this option was set both in the previous program that performed a
701 to the port and in the program that wants to re-use the port.
702 This differs from some implementations (e.g., FreeBSD)
703 where only the later program needs to set the
706 Typically this difference is invisible, since, for example, a server
707 program is designed to always set this option.
717 The suggested interface to use them is via the libpcap
720 .\" This man page was written by Andi Kleen.
725 .BR capabilities (7),