2004-11-03 13:51:07 +00:00
|
|
|
'\" 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>
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified 2002-07-17 by Michael Kerrisk <mtk-manpages@gmx.net>
|
|
|
|
.\" Modified 2004-06-17 by Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.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
|
2005-06-30 09:31:55 +00:00
|
|
|
.BR socket ()
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2005-11-03 12:47:27 +00:00
|
|
|
.IR <sys/socket.h> .
|
2004-11-03 13:51:07 +00:00
|
|
|
The currently understood formats include:
|
|
|
|
.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
|
2005-06-30 09:31:55 +00:00
|
|
|
protocol family, in which case
|
2004-11-03 13:51:07 +00:00
|
|
|
.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)
|
2005-06-30 09:31:55 +00:00
|
|
|
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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
.B SOCK_DGRAM
|
|
|
|
and
|
|
|
|
.B SOCK_RAW
|
|
|
|
sockets allow sending of datagrams to correspondents named in
|
2005-06-30 09:31:55 +00:00
|
|
|
.BR sendto (2)
|
|
|
|
calls.
|
|
|
|
Datagrams are generally received with
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR recvfrom (2),
|
2005-06-30 09:31:55 +00:00
|
|
|
which returns the next datagram along with the address of its sender.
|
2004-11-03 13:51:07 +00:00
|
|
|
.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)
|
|
|
|
.B F_SETOWN
|
2005-06-30 09:31:55 +00:00
|
|
|
operation can be used to specify a process or process group to receive a
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SIGURG
|
|
|
|
signal when the out-of-band data arrives or
|
|
|
|
.B SIGPIPE
|
|
|
|
signal when a
|
|
|
|
.B SOCK_STREAM
|
|
|
|
connection breaks unexpectedly.
|
2005-06-30 09:31:55 +00:00
|
|
|
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 .
|
2004-11-03 13:51:07 +00:00
|
|
|
Using
|
|
|
|
.B F_SETOWN
|
|
|
|
is equivalent to an
|
|
|
|
.BR ioctl (2)
|
|
|
|
call with the
|
|
|
|
.B FIOSETOWN
|
|
|
|
or
|
|
|
|
.B SIOCSPGRP
|
|
|
|
argument.
|
|
|
|
.PP
|
2005-06-30 09:31:55 +00:00
|
|
|
When the network signals an error condition to the protocol module (e.g.,
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2005-11-03 12:47:27 +00:00
|
|
|
.IR <sys/socket.h> .
|
2004-11-03 13:51:07 +00:00
|
|
|
The functions
|
|
|
|
.BR setsockopt (2)
|
|
|
|
and
|
|
|
|
.BR getsockopt (2)
|
|
|
|
are used to set and get options, respectively.
|
|
|
|
.SH "RETURN VALUE"
|
2004-12-20 12:24:06 +00:00
|
|
|
On success, a file descriptor for the new socket is returned.
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
2004-11-03 13:51:07 +00:00
|
|
|
.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.
|
2005-06-30 09:31:55 +00:00
|
|
|
.BR socket ()
|
|
|
|
appeared in 4.2BSD. It is generally portable to/from
|
2004-11-03 13:51:07 +00:00
|
|
|
non-BSD systems supporting clones of the BSD socket layer (including
|
|
|
|
System V variants).
|
|
|
|
.SH NOTE
|
2005-07-18 15:05:56 +00:00
|
|
|
The manifest constants used under 4.x BSD for protocol families
|
2004-11-03 13:51:07 +00:00
|
|
|
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.
|