diff options
Diffstat (limited to 'man/man2/socket.2')
| -rw-r--r-- | man/man2/socket.2 | 493 |
1 files changed, 493 insertions, 0 deletions
diff --git a/man/man2/socket.2 b/man/man2/socket.2 new file mode 100644 index 000000000..4490f6c1a --- /dev/null +++ b/man/man2/socket.2 @@ -0,0 +1,493 @@ +'\" t +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" $Id: socket.2,v 1.4 1999/05/13 11:33:42 freitag Exp $ +.\" +.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 1998, 1999 by Andi Kleen <ak@muc.de> +.\" Modified 2002-07-17 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH socket 2 (date) "Linux man-pages (unreleased)" +.SH NAME +socket \- create an endpoint for communication +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/socket.h> +.P +.BI "int socket(int " domain ", int " type ", int " protocol ); +.fi +.SH DESCRIPTION +.BR socket () +creates an endpoint for communication and returns a file descriptor +that refers to that endpoint. +The file descriptor returned by a successful call will be +the lowest-numbered file descriptor not currently open for the process. +.P +The +.I domain +argument specifies a communication domain; this selects the protocol +family which will be used for communication. +These families are defined in +.IR <sys/socket.h> . +The formats currently understood by the Linux kernel include: +.TS +tab(:); +l1 lw40 l. +Name:Purpose:Man page +T{ +.B AF_UNIX +T}:T{ +Local communication +T}:T{ +.BR unix (7) +T} +T{ +.B AF_LOCAL +T}:T{ +Synonym for +.B AF_UNIX +T}:T{ +T} +T{ +.B AF_INET +T}:IPv4 Internet protocols:T{ +.BR ip (7) +T} +T{ +.B AF_AX25 +T}:T{ +Amateur radio AX.25 protocol +T}:T{ +.\" Part of ax25-tools +.BR ax25 (4) +T} +T{ +.B AF_IPX +T}:IPX \- Novell protocols: +T{ +.B AF_APPLETALK +T}:AppleTalk:T{ +.BR ddp (7) +T} +T{ +.B AF_X25 +T}:ITU-T X.25 / ISO/IEC\~8208 protocol:T{ +.BR x25 (7) +T} +T{ +.B AF_INET6 +T}:IPv6 Internet protocols:T{ +.BR ipv6 (7) +T} +T{ +.B AF_DECnet +T}:T{ +DECet protocol sockets +T} +T{ +.B AF_KEY +T}:T{ +Key management protocol, originally developed for usage with IPsec +T} +T{ +.B AF_NETLINK +T}:T{ +Kernel user interface device +T}:T{ +.BR netlink (7) +T} +T{ +.B AF_PACKET +T}:T{ +Low-level packet interface +T}:T{ +.BR packet (7) +T} +T{ +.B AF_RDS +T}:T{ +.\" commit: 639b321b4d8f4e412bfbb2a4a19bfebc1e68ace4 +Reliable Datagram Sockets (RDS) protocol +T}:T{ +.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds.7 +.\" rds-tools: https://github.com/oracle/rds-tools/blob/master/rds-rdma.7 +.BR rds (7) +.br +.BR rds\-rdma (7) +T} +T{ +.B AF_PPPOX +T}:T{ +Generic PPP transport layer, for setting up L2 tunnels +(L2TP and PPPoE) +T} +T{ +.B AF_LLC +T}:T{ +.\" linux-history commit: 34beb106cde7da233d4df35dd3d6cf4fee937caa +Logical link control (IEEE 802.2 LLC) protocol +T} +T{ +.B AF_IB +T}:T{ +.\" commits: 8d36eb01da5d371f..ce117ffac2e93334 +InfiniBand native addressing +T} +T{ +.B AF_MPLS +T}:T{ +.\" commits: 0189197f441602acdca3f97750d392a895b778fd +Multiprotocol Label Switching +T} +T{ +.B AF_CAN +T}:T{ +.\" commits: 8dbde28d9711475a..5423dd67bd0108a1 +Controller Area Network automotive bus protocol +T} +T{ +.B AF_TIPC +T}:T{ +.\" commits: b97bf3fd8f6a16966d4f18983b2c40993ff937d4 +TIPC, "cluster domain sockets" protocol +T} +T{ +.B AF_BLUETOOTH +T}:T{ +.\" commits: 8d36eb01da5d371f..ce117ffac2e93334 +Bluetooth low-level socket protocol +T} +T{ +.B AF_ALG +T}:T{ +.\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 +Interface to kernel crypto API +T} +T{ +.B AF_VSOCK +T}:T{ +.\" commit: d021c344051af91f42c5ba9fdedc176740cbd238 +VSOCK (originally "VMWare VSockets") protocol +for hypervisor-guest communication +T}:T{ +.BR vsock (7) +T} +T{ +.B AF_KCM +T}:T{ +.\" commit: 03c8efc1ffeb6b82a22c1af8dd908af349563314 +KCM (kernel connection multiplexer) interface +T} +T{ +.B AF_XDP +T}:T{ +.\" commit: c0c77d8fb787cfe0c3fca689c2a30d1dad4eaba7 +XDP (express data path) interface +T} +.TE +.P +Further details of the above address families, +as well as information on several other address families, can be found in +.BR address_families (7). +.P +The socket has the indicated +.IR type , +which specifies the communication semantics. +Currently defined types +are: +.TP 16 +.B SOCK_STREAM +Provides sequenced, reliable, two-way, connection-based byte streams. +An out-of-band data transmission mechanism may be supported. +.TP +.B SOCK_DGRAM +Supports datagrams (connectionless, unreliable messages of a fixed +maximum length). +.TP +.B SOCK_SEQPACKET +Provides a sequenced, reliable, two-way connection-based data +transmission path for datagrams of fixed maximum length; a consumer is +required to read an entire packet with each input system call. +.TP +.B SOCK_RAW +Provides raw network protocol access. +.TP +.B SOCK_RDM +Provides a reliable datagram layer that does not guarantee ordering. +.TP +.B SOCK_PACKET +Obsolete and should not be used in new programs; +see +.BR packet (7). +.P +Some socket types may not be implemented by all protocol families. +.P +Since Linux 2.6.27, the +.I type +argument serves a second purpose: +in addition to specifying a socket type, +it may include the bitwise OR of any of the following values, +to modify the behavior of +.BR socket (): +.TP 16 +.B SOCK_NONBLOCK +Set the +.B O_NONBLOCK +file status flag on the open file description (see +.BR open (2)) +referred to by the new file descriptor. +Using this flag saves extra calls to +.BR fcntl (2) +to achieve the same result. +.TP +.B SOCK_CLOEXEC +Set the close-on-exec +.RB ( FD_CLOEXEC ) +flag on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2) +for reasons why this may be useful. +.P +The +.I protocol +specifies a particular protocol to be used with the socket. +Normally only a single protocol exists to support a particular +socket type within a given protocol family, in which case +.I protocol +can be specified as 0. +However, it is possible that many protocols may exist, in +which case a particular protocol must be specified in this manner. +The protocol number to use is specific to the \*(lqcommunication domain\*(rq +in which communication is to take place; see +.BR protocols (5). +See +.BR getprotoent (3) +on how to map protocol name strings to protocol numbers. +.P +Sockets of type +.B SOCK_STREAM +are full-duplex byte streams. +They do not preserve +record boundaries. +A stream socket must be in +a +.I connected +state before any data may be sent or received on it. +A connection to +another socket is created with a +.BR connect (2) +call. +Once connected, data may be transferred using +.BR read (2) +and +.BR write (2) +calls or some variant of the +.BR send (2) +and +.BR recv (2) +calls. +When a session has been completed a +.BR close (2) +may be performed. +Out-of-band data may also be transmitted as described in +.BR send (2) +and received as described in +.BR recv (2). +.P +The communications protocols which implement a +.B SOCK_STREAM +ensure that data is not lost or duplicated. +If a piece of data for which +the peer protocol has buffer space cannot be successfully transmitted +within a reasonable length of time, then the connection is considered +to be dead. +When +.B SO_KEEPALIVE +is enabled on the socket the protocol checks in a protocol-specific +manner if the other end is still alive. +A +.B SIGPIPE +signal is raised if a process sends or receives +on a broken stream; this causes naive processes, +which do not handle the signal, to exit. +.B SOCK_SEQPACKET +sockets employ the same system calls as +.B SOCK_STREAM +sockets. +The only difference is that +.BR read (2) +calls will return only the amount of data requested, +and any data remaining in the arriving packet will be discarded. +Also all message boundaries in incoming datagrams are preserved. +.P +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets allow sending of datagrams to correspondents named in +.BR sendto (2) +calls. +Datagrams are generally received with +.BR recvfrom (2), +which returns the next datagram along with the address of its sender. +.P +.B SOCK_PACKET +is an obsolete socket type to receive raw packets directly from the +device driver. +Use +.BR packet (7) +instead. +.P +An +.BR fcntl (2) +.B F_SETOWN +operation can be used to specify a process or process group to receive a +.B SIGURG +signal when the out-of-band data arrives or +.B SIGPIPE +signal when a +.B SOCK_STREAM +connection breaks unexpectedly. +This operation may also be used to set the process or process group +that receives the I/O and asynchronous notification of I/O events via +.BR SIGIO . +Using +.B F_SETOWN +is equivalent to an +.BR ioctl (2) +call with the +.B FIOSETOWN +or +.B SIOCSPGRP +argument. +.P +When the network signals an error condition to the protocol module (e.g., +using an ICMP message for IP) the pending error flag is set for the socket. +The next operation on this socket will return the error code of the pending +error. +For some protocols it is possible to enable a per-socket error queue +to retrieve detailed information about the error; see +.B IP_RECVERR +in +.BR ip (7). +.P +The operation of sockets is controlled by socket level +.IR options . +These options are defined in +.IR <sys/socket.h> . +The functions +.BR setsockopt (2) +and +.BR getsockopt (2) +are used to set and get options. +.SH RETURN VALUE +On success, a file descriptor for the new socket is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.TP +.B EAFNOSUPPORT +The implementation does not support the specified address family. +.TP +.B EINVAL +Unknown protocol, or protocol family not available. +.TP +.B EINVAL +.\" Since Linux 2.6.27 +Invalid flags in +.IR type . +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.BR ENOBUFS " or " ENOMEM +Insufficient memory is available. +The socket cannot be +created until sufficient resources are freed. +.TP +.B EPROTONOSUPPORT +The protocol type or the specified protocol is not +supported within this domain. +.P +Other errors may be generated by the underlying protocol modules. +.SH STANDARDS +POSIX.1-2008. +.P +.B SOCK_NONBLOCK +and +.B SOCK_CLOEXEC +are Linux-specific. +.SH HISTORY +POSIX.1-2001, 4.4BSD. +.P +.BR socket () +appeared in 4.2BSD. +It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System\ V variants). +.P +The manifest constants used under 4.x BSD for protocol families +are +.BR PF_UNIX , +.BR PF_INET , +and so on, while +.BR AF_UNIX , +.BR AF_INET , +and so on are used for address +families. +However, already the BSD man page promises: "The protocol +family generally is the same as the address family", and subsequent +standards use AF_* everywhere. +.SH EXAMPLES +An example of the use of +.BR socket () +is shown in +.BR getaddrinfo (3). +.SH SEE ALSO +.BR accept (2), +.BR bind (2), +.BR close (2), +.BR connect (2), +.BR fcntl (2), +.BR getpeername (2), +.BR getsockname (2), +.BR getsockopt (2), +.BR ioctl (2), +.BR listen (2), +.BR read (2), +.BR recv (2), +.BR select (2), +.BR send (2), +.BR shutdown (2), +.BR socketpair (2), +.BR write (2), +.BR getprotoent (3), +.BR address_families (7), +.BR ip (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.P +\[lq]An Introductory 4.3BSD Interprocess Communication Tutorial\[rq] +and +\[lq]BSD Interprocess Communication Tutorial\[rq], +reprinted in +.I UNIX Programmer's Supplementary Documents Volume 1. |