diff options
Diffstat (limited to 'man2/socket.2')
| -rw-r--r-- | man2/socket.2 | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/man2/socket.2 b/man2/socket.2 new file mode 100644 index 000000000..64f332582 --- /dev/null +++ b/man2/socket.2 @@ -0,0 +1,349 @@ +'\" t +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $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 <mtk16@ext.canterbury.ac.nz> +.\" Modified 2004-06-17 by Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" +.TH SOCKET 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +socket \- create an endpoint for communication +.SH SYNOPSIS +.B #include <sys/types.h> +.br +.B #include <sys/socket.h> +.sp +.BI "int socket(int " domain ", int " type ", int " protocol ); +.SH DESCRIPTION +.B Socket +creates an endpoint for communication and returns a descriptor. +.PP +The +.I domain +parameter specifies a communication domain; this selects the protocol +family which will be used for communication. These families are defined in +.BR <sys/socket.h> . +The currently understood formats include: +.PP +.TS +tab(:); +l l l. +Name:Purpose:Man page +T{ +.B "PF_UNIX,\ PF_LOCAL" +T}:T{ +Local communication +T}:T{ +.BR unix (7) +T} +T{ +.B PF_INET +T}:IPv4 Internet protocols:T{ +.BR ip (7) +T} +T{ +.B PF_INET6 +T}:IPv6 Internet protocols: +T{ +.B PF_IPX +T}:IPX \- Novell protocols: +T{ +.B PF_NETLINK +T}:T{ +Kernel user interface device +T}:T{ +.BR netlink (7) +T} +T{ +.B PF_X25 +T}:ITU-T X.25 / ISO-8208 protocol:T{ +.BR x25 (7) +T} +T{ +.B PF_AX25 +T}:T{ +Amateur radio AX.25 protocol +T}: +T{ +.B PF_ATMPVC +T}:Access to raw ATM PVCs: +T{ +.B PF_APPLETALK +T}:Appletalk:T{ +.BR ddp (7) +T} +T{ +.B PF_PACKET +T}:T{ +Low level packet interface +T}:T{ +.BR packet (7) +T} +.TE +.PP +The socket has the indicated +.IR type , +which specifies the communication semantics. Currently defined types +are: +.TP +.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 read 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). +.PP +Some socket types may not be implemented by all protocol families; for example, +.B SOCK_SEQPACKET +is not implemented for +.BR AF_INET . +.PP +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 a 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. +.PP +Sockets of type +.B SOCK_STREAM +are full-duplex byte streams, similar to pipes. 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). +.PP +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 remaining in +the arriving packet will be discarded. Also all message boundaries in +incoming datagrams are preserved. +.PP +.B SOCK_DGRAM +and +.B SOCK_RAW +sockets allow sending of datagrams to correspondents named in +.BR send (2) +calls. Datagrams are generally received with +.BR recvfrom (2), +which returns the next datagram with its return address. +.PP +.B SOCK_PACKET +is an obsolete socket type to receive raw packets directly from the +device driver. Use +.BR packet (7) +instead. +.PP +An +.BR fcntl (2) +call with the the +.B F_SETOWN +argument +can be used to specify a 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. +It 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. +.PP +When the network signals an error condition to the protocol module (e.g. +using a 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) . +.PP +The operation of sockets is controlled by socket level +.IR options . +These options are defined in +.BR <sys/socket.h> . +The functions +.BR setsockopt (2) +and +.BR getsockopt (2) +are used to set and get options, respectively. +.SH "RETURN VALUE" +\-1 is returned if an error occurs; otherwise the return value is a +descriptor referencing the socket. +.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 EMFILE +Process file table overflow. +.TP +.B ENFILE +The system 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. +.PP +Other errors may be generated by the underlying protocol modules. +.SH "CONFORMING TO" +4.4BSD, SUSv2, POSIX 1003.1-2001. +The +.B socket +function call appeared in 4.2BSD. It is generally portable to/from +non-BSD systems supporting clones of the BSD socket layer (including +System V variants). +.SH NOTE +The manifest constants used under BSD 4.* for protocol families +are PF_UNIX, PF_INET, etc., while AF_UNIX etc. 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 BUGS +.B SOCK_UUCP +is not implemented yet. +.SH "SEE ALSO" +.BR accept (2), +.BR bind (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 ip (7), +.BR socket (7), +.BR tcp (7), +.BR udp (7), +.BR unix (7) +.PP +\(lqAn Introductory 4.3 BSD Interprocess Communication Tutorial\(rq +is reprinted in +.I UNIX Programmer's Supplementary Documents Volume 1. +.PP +\(lqBSD Interprocess Communication Tutorial\(rq +is reprinted in +.I UNIX Programmer's Supplementary Documents Volume 1. |