/raw/man7/socket.7
Unknown | 557 lines | 551 code | 6 blank | 0 comment | 0 complexity | 5a728330de69192f5bc9f72948405306 MD5 | raw file
Possible License(s): CC-BY-SA-3.0
- '\" t
- .\" Don't change the first line, it tells man that we need tbl.
- .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
- .\" and copyright (c) 1999 Matthew Wilcox.
- .\" Permission is granted to distribute possibly modified copies
- .\" of this page provided the header is included verbatim,
- .\" and in case of nontrivial modification author and date
- .\" of the modification is added to the header.
- .\" $Id: socket.7,v 1.1 2003/12/20 03:31:53 bbbush Exp $
- .\"
- .\" 30 Oct 2002, Modified, Michael Kerrisk, mtk16@ext.canterbury.ac.nz
- .\" Added description of SO_ACCEPTCONN
- .\" Plus 1 language tidy-up
- .\"
- .TH SOCKET 7 1999-05-07 "Linux Man Page" "Linux Programmer's Manual"
- .SH NAME
- socket - Linux socket interface
- .SH SYNOPSIS
- .B #include <sys/socket.h>
- .br
- .IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol );
- .SH DESCRIPTION
- This manual page describes the Linux networking socket layer user
- interface. The BSD compatible sockets
- are the uniform interface
- between the user process and the network protocol stacks in the kernel.
- The protocol modules are grouped into
- .I protocol families
- like
- .BR PF_INET ", " PF_IPX ", " PF_PACKET
- and
- .I socket types
- like
- .B SOCK_STREAM
- or
- .BR SOCK_DGRAM .
- See
- .BR socket (2)
- for more information on families and types.
- .SH "SOCKET LAYER FUNCTIONS"
- These functions are used by the user process to send or receive packets and
- to do other socket operations. For more information see their respective
- manual pages.
- .BR socket (2)
- creates a socket,
- .BR connect (2)
- connects a socket to a remote socket address,
- the
- .BR bind (2)
- function binds a socket to a local socket address,
- .BR listen (2)
- tells the socket that new connections shall be accepted, and
- .BR accept (2)
- is used to get a new socket with a new incoming connection.
- .BR socketpair (2)
- returns two connected anonymous sockets (only implemented for a few
- local families like
- .BR PF_UNIX )
- .PP
- .BR send (2),
- .BR sendto (2),
- and
- .BR sendmsg (2)
- send data over a socket, and
- .BR recv (2),
- .BR recvfrom (2),
- .BR recvmsg (2)
- receive data from a socket.
- .BR poll (2)
- and
- .BR select (2)
- wait for arriving data or a readiness to send data.
- In addition, the standard I/O operations like
- .BR write (2),
- .BR writev (2),
- .BR sendfile (2),
- .BR read (2),
- and
- .BR readv (2)
- can be used to read and write data.
- .PP
- .BR getsockname (2)
- returns the local socket address and
- .BR getpeername (2)
- returns the remote socket address.
- .BR getsockopt (2)
- and
- .BR setsockopt (2)
- are used to set or get socket layer or protocol options.
- .BR ioctl (2)
- can be used to set or read some other options.
- .PP
- .BR close (2)
- is used to close a socket.
- .BR shutdown (2)
- closes parts of a full duplex socket connection.
- .PP
- Seeking, or calling
- .BR pread (2)
- or
- .BR pwrite (2)
- with a non-zero position is not supported on sockets.
- .PP
- It is possible to do non-blocking IO on sockets by setting the
- .B O_NONBLOCK
- flag on a socket file descriptor using
- .BR fcntl (2).
- Then all operations that would block will (usually)
- return with
- .B EAGAIN
- (operation should be retried later);
- .BR connect (2)
- will return
- .B EINPROGRESS
- error.
- The user can then wait for various events via
- .BR poll (2)
- or
- .BR select (2).
- .PP
- .TS
- tab(:) allbox;
- c s s
- l l l.
- I/O events
- Event:Poll flag:Occurrence
- Read:POLLIN:T{
- New data arrived.
- T}
- Read:POLLIN:T{
- A connection setup has been completed
- (for connection-oriented sockets)
- T}
- Read:POLLHUP:T{
- A disconnection request has been initiated by the other end.
- T}
- Read:POLLHUP:T{
- A connection is broken (only for connection-oriented protocols).
- When the socket is written
- .B SIGPIPE
- is also sent.
- T}
- Write:POLLOUT:T{
- Socket has enough send buffer space for writing new data.
- T}
- Read/Write:T{
- POLLIN|
- .br
- POLLOUT
- T}:T{
- An outgoing
- .BR connect (2)
- finished.
- T}
- Read/Write:POLLERR:An asynchronous error occurred.
- Read/Write:POLLHUP:The other end has shut down one direction.
- Exception:POLLPRI:T{
- Urgent data arrived.
- .B SIGURG
- is sent then.
- T}
- .\" XXX not true currently
- .\" It is no I/O event when the connection
- .\" is broken from the local end using
- .\" .BR shutdown (2)
- .\" or
- .\" .BR close (2)
- .\" .
- .TE
- .PP
- An alternative to poll/select
- is to let the kernel inform the application about events
- via a
- .B SIGIO
- signal. For that the
- .B FASYNC
- flag must be set on a socket file descriptor
- via
- .BR fcntl (2)
- and a valid signal handler for
- .B SIGIO
- must be installed via
- .BR sigaction (2).
- See the
- .I SIGNALS
- discussion below.
- .SH "SOCKET OPTIONS"
- These socket options can be set by using
- .BR setsockopt (2)
- and read with
- .BR getsockopt (2)
- with the socket level set to
- .B SOL_SOCKET
- for all sockets:
- .TP
- .B SO_KEEPALIVE
- Enable sending of keep-alive messages on connection-oriented sockets. Expects
- a integer boolean flag.
- .TP
- .B SO_OOBINLINE
- If this option is enabled, out-of-band data is directly placed into the receive
- data stream. Otherwise out-of-band data is only passed when the
- .B MSG_OOB
- flag is set during receiving.
- .\" don't document it because it can do too much harm.
- .\".B SO_NO_CHECK
- .TP
- .BR SO_RCVLOWAT " and " SO_SNDLOWAT
- Specify the minimum number of bytes in the buffer until the socket layer
- will pass the data to the protocol
- .RB ( SO_SNDLOWAT )
- or the user on receiving
- .RB ( SO_RCVLOWAT ).
- These two values are not changeable in Linux and their argument size
- is always fixed
- to 1 byte.
- .B getsockopt
- is able to read them;
- .B setsockopt
- will always return
- .BR ENOPROTOOPT .
- .TP
- .BR SO_RCVTIMEO " and " SO_SNDTIMEO
- Specify the sending or receiving timeouts until reporting an error.
- They are fixed to a protocol specific setting in Linux and cannot be read
- or written. Their functionality can be emulated using
- .BR alarm (2)
- or
- .BR setitimer (2).
- .TP
- .B SO_BSDCOMPAT
- Enable BSD bug-to-bug compatibility. This is used only by the UDP
- protocol module and scheduled to be removed in future.
- If enabled ICMP errors received for a UDP socket will not be passed
- to the user program. Linux 2.0 also enabled BSD bug-to-bug compatibility
- options (random header changing, skipping of the broadcast flag) for raw
- sockets with this option, but that has been removed in Linux 2.2. It is
- better to fix the user programs than to enable this flag.
- .TP
- .B SO_PASSCRED
- Enable or disable the receiving of the
- .B SCM_CREDENTIALS
- control message. For more information see
- .BR unix (7).
- .TP
- .B SO_PEERCRED
- Return the credentials of the foreign process connected to this socket.
- Only useful for
- .B PF_UNIX
- sockets; see
- .BR unix (7).
- Argument is a
- .B ucred
- structure. Only valid as a
- .BR getsockopt .
- .TP
- .B SO_BINDTODEVICE
- Bind this socket to a particular device like \(lqeth0\(rq,
- as specified in the passed interface name. If the
- name is an empty string or the option length is zero, the socket device
- binding is removed. The passed option is a variable-length null terminated
- interface name string with the maximum size of
- .BR IFNAMSIZ .
- If a socket is bound to an interface,
- only packets received from that particular interface are processed by the
- socket. Note that this only works for some socket types, particularly
- .B AF_INET
- sockets. It is not supported for packet sockets (use normal
- .BR bind (8)
- there).
- .TP
- .B SO_DEBUG
- Enable socket debugging. Only allowed for processes with the
- .B CAP_NET_ADMIN
- capability or an effective user id of 0.
- .TP
- .B SO_REUSEADDR
- Indicates that the rules used in validating addresses supplied in a
- .BR bind (2)
- call should allow reuse of local addresses. For
- .B PF_INET
- sockets this
- means that a socket may bind, except when there
- is an active listening socket bound to the address. When the listening
- socket is bound to
- .B INADDR_ANY
- with a specific port then it is not possible
- to bind to this port for any local address.
- .TP
- .B SO_TYPE
- Gets the socket type as an integer (like
- .BR SOCK_STREAM ).
- Can only be read
- with
- .BR getsockopt .
- .\" SO_ACCEPTCONN is in SUSv3, and its origin is explained in
- .\" W R Stevens, UNPv1
- .TP
- .B SO_ACCEPTCONN
- Returns a value indicating whether or not this socket has been marked
- to accept connections with
- .BR listen ().
- The value 0 indicates that this is not a listening socket,
- the value 1 indicates that this is a listening socket.
- Can only be read
- with
- .BR getsockopt .
- .TP
- .B SO_DONTROUTE
- Don't send via a gateway, only send to directly connected hosts.
- The same effect can be achieved by setting the
- .B MSG_DONTROUTE
- flag on a socket
- .BR send (2)
- operation. Expects an integer boolean flag.
- .TP
- .B SO_BROADCAST
- Set or get the broadcast flag. When enabled, datagram sockets
- receive packets sent to a broadcast address and they are allowed to send
- packets to a broadcast address.
- This option has no effect on stream-oriented sockets.
- .TP
- .B SO_SNDBUF
- Sets or gets the maximum socket send buffer in bytes. The default value is set
- by the
- .B wmem_default
- sysctl and the maximum allowed value is set by the
- .B wmem_max
- sysctl.
- .TP
- .B SO_RCVBUF
- Sets or gets the maximum socket receive buffer in bytes. The default value is
- set by the
- .B rmem_default
- sysctl and the maximum allowed value is set by the
- .B rmem_max
- sysctl.
- .TP
- .B SO_LINGER
- Sets or gets the
- .B SO_LINGER
- option. The argument is a
- .B linger
- structure.
- .PP
- .RS
- .nf
- .ta 4n 10n 22n
- struct linger {
- int l_onoff; /* linger active */
- int l_linger; /* how many seconds to linger for */
- };
- .ta
- .fi
- .RE
- .IP
- When enabled, a
- .BR close (2)
- or
- .BR shutdown (2)
- will not return until all queued messages for the socket have been
- successfully sent or the linger timeout has been reached. Otherwise,
- the call returns immediately and the closing is done in the background.
- When the socket is closed as part of
- .BR exit (2),
- it always lingers in the background.
- .TP
- .B SO_PRIORITY
- Set the protocol-defined priority for all packets to be sent on this socket.
- Linux uses this value to order the networking queues: packets with a higher
- priority may be processed first depending on the selected device queueing
- discipline. For
- .BR ip (7),
- this also sets the IP type-of-service (TOS) field for outgoing packets.
- .TP
- .B SO_ERROR
- Get and clear the pending socket error. Only valid as a
- .BR getsockopt .
- Expects an integer.
- .SH SIGNALS
- When writing onto a connection-oriented socket that has been shut down
- (by the local or the remote end)
- .B SIGPIPE
- is sent to the writing process and
- .B EPIPE
- is returned.
- The signal is not sent when the write call
- specified the
- .B MSG_NOSIGNAL
- flag.
- .PP
- When requested with the
- .B FIOSETOWN
- fcntl or
- .B SIOCSPGRP
- ioctl,
- .B SIGIO
- is sent when an I/O event occurs. It is possible to use
- .BR poll (2)
- or
- .BR select (2)
- in the signal handler to find out which socket the event occurred on.
- An alternative (in Linux 2.2) is to set a realtime signal using the
- .B F_SETSIG
- fcntl; the handler of the real time signal will be called with
- the file descriptor in the
- .I si_fd
- field of its
- .IR siginfo_t .
- See
- .BR fcntl (2)
- for more information.
- .PP
- Under some circumstances (e.g. multiple processes accessing a single socket),
- the condition that caused the
- .B SIGIO
- may have already disappeared when the process reacts to the signal.
- If this happens, the process should wait again because Linux will resend the
- signal later.
- .\" .SH ANCILLARY MESSAGES
- .SH SYSCTLS
- The core socket networking sysctls can be accessed using the
- .B /proc/sys/net/core/*
- files or with the
- .BR sysctl (2)
- interface.
- .TP
- .B rmem_default
- contains the default setting in bytes of the socket receive buffer.
- .TP
- .B rmem_max
- contains the maximum socket receive buffer size in bytes which a user may
- set by using the
- .B SO_RCVBUF
- socket option.
- .TP
- .B wmem_default
- contains the default setting in bytes of the socket send buffer.
- .TP
- .B wmem_max
- contains the maximum socket send buffer size in bytes which a user may
- set by using the
- .B SO_SNDBUF
- socket option.
- .TP
- .BR message_cost " and " message_burst
- configure the token bucket filter used to load limit warning messages
- caused by external network events.
- .TP
- .B netdev_max_backlog
- Maximum number of packets in the global input queue.
- .TP
- .B optmem_max
- Maximum length of ancillary data and user control data like the iovecs
- per socket.
- .\" netdev_fastroute is not documented because it is experimental
- .SH IOCTLS
- These ioctls can be accessed using
- .BR ioctl (2):
- .RS
- .nf
- .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");"
- .fi
- .RE
- .TP
- .B SIOCGSTAMP
- Return a
- .B struct timeval
- with the receive timestamp of the last packet passed to the user. This is useful
- for accurate round trip time measurements. See
- .BR setitimer (2)
- for a description of
- .BR "struct timeval" .
- .\"
- .TP
- .BR SIOCSPGRP
- Set the process or process group to send
- .B SIGIO
- or
- .B SIGURG
- signals
- to when an
- asynchronous I/O operation has finished or urgent data is available.
- The argument is a pointer to a
- .BR pid_t .
- If the argument is positive, send the signals to that process. If the
- argument is negative, send the signals to the process group with the id
- of the absolute value of the argument.
- The process may only choose itself or its own process group to receive
- signals unless it has the
- .B CAP_KILL
- capability or an effective UID of 0.
- .TP
- .B FIOASYNC
- Change the
- .B O_ASYNC
- flag to enable or disable asynchronous IO mode of the socket. Asynchronous IO
- mode means that the
- .B SIGIO
- signal or the signal set with
- .B F_SETSIG
- is raised when a new I/O event occurs.
- .IP
- Argument is a integer boolean flag.
- .\"
- .TP
- .BR SIOCGPGRP
- Get the current process or process group that receives
- .B SIGIO
- or
- .B SIGURG
- signals,
- or 0
- when none is set.
- .PP
- Valid fcntls:
- .TP
- .BR FIOGETOWN
- The same as the SIOCGPGRP ioctl.
- .TP
- .BR FIOSETOWN
- The same as the SIOCSPGRP ioctl
- .SH NOTES
- Linux assumes that half of the send/receive buffer is used for internal
- kernel structures; thus the sysctls are twice what can be observed
- on the wire.
- .SH BUGS
- The
- .B CONFIG_FILTER
- socket options
- .B SO_ATTACH_FILTER
- and
- .B SO_DETACH_FILTER
- are
- not documented. The suggested interface to use them is via the libpcap
- library.
- .SH VERSIONS
- .B SO_BINDTODEVICE
- was introduced in Linux 2.0.30.
- .B SO_PASSCRED
- is new in Linux 2.2.
- The sysctls are new in Linux 2.2.
- .SH AUTHORS
- This man page was written by Andi Kleen.
- .SH "SEE ALSO"
- .BR socket (2),
- .BR ip (7),
- .BR setsockopt (2),
- .BR getsockopt (2),
- .BR packet (7),
- .BR ddp (7)