255 lines
6.3 KiB
Plaintext
255 lines
6.3 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3n.socket @(#)socket 41.4 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} socket 3N "" "\&"
|
|
.if \nX=1 .ds x} socket 3N ""
|
|
.if \nX=2 .ds x} socket 3N "" "\&"
|
|
.if \nX=3 .ds x} socket "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4socket\fP \- create an endpoint for communication
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft 4
|
|
#include <sys/types.h>
|
|
#include <sys/socket.h>
|
|
.P
|
|
.ft 4
|
|
int socket(int domain, int type, int protocol);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.P
|
|
\f4socket\fP
|
|
creates an endpoint for communication and returns a descriptor.
|
|
.P
|
|
The
|
|
.I domain
|
|
parameter specifies a communications domain within which
|
|
communication will take place;
|
|
this selects the protocol family
|
|
which should be used.
|
|
The protocol family generally is the same as the address family
|
|
for the addresses supplied in later operations on the socket.
|
|
These families are defined in the include file
|
|
\f4sys/socket.h\fP.
|
|
There must be an entry in the \f4netconfig\fP(4) file for at least each
|
|
protocol family and type required.
|
|
If
|
|
.I protocol
|
|
has been specified, but no exact match for the tuplet family, type, protocol
|
|
is found, then the first entry containing the specified family and type
|
|
with zero for protocol will be used.
|
|
The currently understood formats are:
|
|
.P
|
|
.TP 20
|
|
\f4\s-1PF_UNIX\s0\fP
|
|
.SM UNIX
|
|
system internal protocols
|
|
.TP
|
|
\f4\s-1PF_INET\s0\fP
|
|
.SM ARPA
|
|
Internet protocols
|
|
.P
|
|
The socket has the indicated
|
|
.IR type ,
|
|
which specifies the communication semantics.
|
|
Currently defined types are:
|
|
.P
|
|
.RS
|
|
.nf
|
|
\f4\s-1SOCK_STREAM\s0\fP
|
|
\f4\s-1SOCK_DGRAM\s0\fP
|
|
\f4\s-1SOCK_RAW\s0\fP
|
|
\f4\s-1SOCK_SEQPACKET\s0\fP
|
|
\f4\s-1SOCK_RDM\s0\fP
|
|
.fi
|
|
.RE
|
|
.P
|
|
A \f4\s-1SOCK_STREAM\s0\fP
|
|
type provides sequenced, reliable,
|
|
two-way connection-based byte streams.
|
|
An out-of-band data transmission mechanism may be supported.
|
|
A
|
|
\f4\s-1SOCK_DGRAM\s0\fP
|
|
socket supports
|
|
datagrams (connectionless,
|
|
unreliable messages of
|
|
a fixed (typically small) maximum length).
|
|
A
|
|
\f4\s-1SOCK_SEQPACKET\s0\fP
|
|
socket may provide a sequenced,
|
|
reliable, two-way connection-based data
|
|
transmission path for datagrams
|
|
of fixed maximum length;
|
|
a consumer may be required to read
|
|
an entire packet with each read system call.
|
|
This facility is protocol specific,
|
|
and presently not implemented
|
|
for any protocol family.
|
|
\f4\s-1SOCK_RAW\s0\fP
|
|
sockets provide access to internal network interfaces.
|
|
The types
|
|
\f4\s-1SOCK_RAW\s0\fP,
|
|
which is available only to a privileged user,
|
|
and
|
|
\f4\s-1SOCK_RDM\s0\fP,
|
|
for which no implementation currently exists,
|
|
are not described here.
|
|
.P
|
|
.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.
|
|
However,
|
|
multiple protocols may exist,
|
|
in which case a particular protocol must be specified
|
|
in this manner.
|
|
The protocol number to use is particular to the
|
|
\*(lqcommunication domain\*(rq in which communication
|
|
is to take place.
|
|
If a protocol is specified by the caller, then it will be packaged into
|
|
a socket level option request and sent to the underlying protocol layers.
|
|
.\".I setsockopt()
|
|
.P
|
|
Sockets of type
|
|
\f4\s-1SOCK_STREAM\s0\fP
|
|
are full-duplex byte streams,
|
|
similar to pipes.
|
|
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
|
|
\f4connect\fP(3N)
|
|
call.
|
|
Once connected,
|
|
data may be transferred using
|
|
\f4read\fP(2)
|
|
and
|
|
\f4write\fP(2)
|
|
calls or some variant of the
|
|
\f4send\fP(3N)
|
|
and
|
|
\f4recv\fP(3N)
|
|
calls.
|
|
When a session has been completed, a
|
|
\f4close\fP(2)
|
|
may be performed.
|
|
Out-of-band data may also be transmitted as described on the
|
|
\f4send\fP(3N)
|
|
manual page
|
|
and received as described on
|
|
the
|
|
\f4recv\fP(3N) manual page.
|
|
.P
|
|
The communications protocols used to implement a
|
|
\f4\s-1SOCK_STREAM\s0\fP
|
|
insure 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 broken and calls
|
|
will indicate an error with
|
|
\-1 returns and with
|
|
\f4ETIMEDOUT\f1
|
|
as the specific code in the global variable
|
|
\f4errno\fP.
|
|
The protocols optionally keep sockets \*(lqwarm\*(rq by
|
|
forcing transmissions
|
|
roughly every minute in the absence of other activity.
|
|
An error is then indicated if no response can be
|
|
elicited on an otherwise
|
|
idle connection for a extended period (for
|
|
instance 5 minutes).
|
|
A
|
|
\f4\s-1SIGPIPE\s0\fP
|
|
signal is raised if a process sends
|
|
on a broken stream;
|
|
this causes naive processes,
|
|
which do not handle the signal,
|
|
to exit.
|
|
.P
|
|
\f4\s-1SOCK_SEQPACKET\s0\fP
|
|
sockets employ the same system calls as
|
|
\f4\s-1SOCK_STREAM\s0\fP
|
|
sockets.
|
|
The only difference is that
|
|
\f4read\fP
|
|
calls will return only the amount of data requested,
|
|
and any remaining in the arriving packet will be discarded.
|
|
.P
|
|
\f4\s-1SOCK_DGRAM\s0\fP
|
|
and
|
|
\f4\s-1SOCK_RAW\s0\fP
|
|
sockets allow datagrams to be sent to correspondents
|
|
named in
|
|
\f4sendto\fP
|
|
calls.
|
|
Datagrams are generally received with \f4recvfrom\fP,
|
|
which returns the next datagram with its return address.
|
|
.P
|
|
An
|
|
\f4fcntl\fP(2)
|
|
call can be used to specify a process group to receive a
|
|
\f4\s-1SIGURG\s0\fP
|
|
signal when the out-of-band data arrives.
|
|
It may also enable non-blocking I/O
|
|
and asynchronous notification of I/O events with
|
|
\f4\s-1SIGIO\s0\fP
|
|
signals.
|
|
.P
|
|
The operation of sockets is controlled by socket level
|
|
.IR options .
|
|
These options are defined in the file
|
|
\f4/usr/include/sys/socket.h\fP.
|
|
\f4setsockopt\fP(3N)
|
|
and
|
|
\f4getsockopt\fP(3N)
|
|
are used to set and get options, respectively.
|
|
.SH "RETURN VALUE"
|
|
A \-1 is returned if an error occurs.
|
|
Otherwise the return
|
|
value is a descriptor referencing the socket.
|
|
.SH ERRORS
|
|
.P
|
|
The
|
|
\f4socket(\|)\fP
|
|
call fails if:
|
|
.TP 20
|
|
\f4EPROTONOSUPPORT\f1
|
|
The protocol type or the specified protocol is not supported
|
|
within this domain.
|
|
.TP
|
|
\f4EMFILE\f1
|
|
The per-process descriptor table is full.
|
|
.TP
|
|
\f4EACCESS\f1
|
|
Permission to create a socket of the specified type and/or protocol
|
|
is denied.
|
|
.TP
|
|
\f4ENOMEM\f1
|
|
Insufficient user memory is available.
|
|
.TP
|
|
\f4ENOSR\f1
|
|
There were insufficient STREAMS resources available to complete
|
|
the operation.
|
|
.SH SEE ALSO
|
|
\f4close\fP(2),
|
|
\f4fcntl\fP(2),
|
|
\f4ioctl\fP(2),
|
|
\f4read\fP(2),
|
|
\f4write\fP(2),
|
|
\f4accept\fP(3N),
|
|
\f4bind\fP(3N),
|
|
\f4connect\fP(3N),
|
|
\f4getsockname\fP(3N),
|
|
\f4getsockopt\fP(3N),
|
|
\f4listen\fP(3N),
|
|
\f4recv\fP(3N),
|
|
.\"\f4select\fP(3N),
|
|
\f4send\fP(3N),
|
|
\f4shutdown\fP(3N),
|
|
\f4socketpair\fP(3N)
|