/share/doc/psd/05.sysman/2.3.t
https://bitbucket.org/freebsd/freebsd-head/ · Raku · 413 lines · 408 code · 0 blank · 5 comment · 54 complexity · 4307dd748e52ac9916f218095bb688cb MD5 · raw file
- .\" Copyright (c) 1983, 1993
- .\" 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.
- .\"
- .\" @(#)2.3.t 8.1 (Berkeley) 6/8/93
- .\" $FreeBSD$
- .\"
- .sh "Interprocess communications
- .NH 3
- Interprocess communication primitives
- .NH 4
- Communication domains
- .PP
- The system provides access to an extensible set of
- communication \fIdomains\fP. A communication domain
- is identified by a manifest constant defined in the
- file \fI<sys/socket.h>\fP.
- Important standard domains supported by the system are the ``unix''
- domain, AF_UNIX, for communication within the system, the ``Internet''
- domain for communication in the DARPA Internet, AF_INET,
- and the ``NS'' domain, AF_NS, for communication
- using the Xerox Network Systems protocols.
- Other domains can be added to the system.
- .NH 4
- Socket types and protocols
- .PP
- Within a domain, communication takes place between communication endpoints
- known as \fIsockets\fP. Each socket has the potential to exchange
- information with other sockets of an appropriate type within the domain.
- .PP
- Each socket has an associated
- abstract type, which describes the semantics of communication using that
- socket. Properties such as reliability, ordering, and prevention
- of duplication of messages are determined by the type.
- The basic set of socket types is defined in \fI<sys/socket.h>\fP:
- .DS
- /* Standard socket types */
- ._d
- #define SOCK_DGRAM 1 /* datagram */
- #define SOCK_STREAM 2 /* virtual circuit */
- #define SOCK_RAW 3 /* raw socket */
- #define SOCK_RDM 4 /* reliably-delivered message */
- #define SOCK_SEQPACKET 5 /* sequenced packets */
- .DE
- The SOCK_DGRAM type models the semantics of datagrams in network communication:
- messages may be lost or duplicated and may arrive out-of-order.
- A datagram socket may send messages to and receive messages from multiple
- peers.
- The SOCK_RDM type models the semantics of reliable datagrams: messages
- arrive unduplicated and in-order, the sender is notified if
- messages are lost.
- The \fIsend\fP and \fIreceive\fP operations (described below)
- generate reliable/unreliable datagrams.
- The SOCK_STREAM type models connection-based virtual circuits: two-way
- byte streams with no record boundaries.
- Connection setup is required before data communication may begin.
- The SOCK_SEQPACKET type models a connection-based,
- full-duplex, reliable, sequenced packet exchange;
- the sender is notified if messages are lost, and messages are never
- duplicated or presented out-of-order.
- Users of the last two abstractions may use the facilities for
- out-of-band transmission to send out-of-band data.
- .PP
- SOCK_RAW is used for unprocessed access to internal network layers
- and interfaces; it has no specific semantics.
- .PP
- Other socket types can be defined.
- .PP
- Each socket may have a specific \fIprotocol\fP associated with it.
- This protocol is used within the domain to provide the semantics
- required by the socket type.
- Not all socket types are supported by each domain;
- support depends on the existence and the implementation
- of a suitable protocol within the domain.
- For example, within the ``Internet'' domain, the SOCK_DGRAM type may be
- implemented by the UDP user datagram protocol, and the SOCK_STREAM
- type may be implemented by the TCP transmission control protocol, while
- no standard protocols to provide SOCK_RDM or SOCK_SEQPACKET sockets exist.
- .NH 4
- Socket creation, naming and service establishment
- .PP
- Sockets may be \fIconnected\fP or \fIunconnected\fP. An unconnected
- socket descriptor is obtained by the \fIsocket\fP call:
- .DS
- s = socket(domain, type, protocol);
- result int s; int domain, type, protocol;
- .DE
- The socket domain and type are as described above,
- and are specified using the definitions from \fI<sys/socket.h>\fP.
- The protocol may be given as 0, meaning any suitable protocol.
- One of several possible protocols may be selected using identifiers
- obtained from a library routine, \fIgetprotobyname\fP.
- .PP
- An unconnected socket descriptor of a connection-oriented type
- may yield a connected socket descriptor
- in one of two ways: either by actively connecting to another socket,
- or by becoming associated with a name in the communications domain and
- \fIaccepting\fP a connection from another socket.
- Datagram sockets need not establish connections before use.
- .PP
- To accept connections or to receive datagrams,
- a socket must first have a binding
- to a name (or address) within the communications domain.
- Such a binding may be established by a \fIbind\fP call:
- .DS
- bind(s, name, namelen);
- int s; struct sockaddr *name; int namelen;
- .DE
- Datagram sockets may have default bindings established when first
- sending data if not explicitly bound earlier.
- In either case,
- a socket's bound name may be retrieved with a \fIgetsockname\fP call:
- .DS
- getsockname(s, name, namelen);
- int s; result struct sockaddr *name; result int *namelen;
- .DE
- while the peer's name can be retrieved with \fIgetpeername\fP:
- .DS
- getpeername(s, name, namelen);
- int s; result struct sockaddr *name; result int *namelen;
- .DE
- Domains may support sockets with several names.
- .NH 4
- Accepting connections
- .PP
- Once a binding is made to a connection-oriented socket,
- it is possible to \fIlisten\fP for connections:
- .DS
- listen(s, backlog);
- int s, backlog;
- .DE
- The \fIbacklog\fP specifies the maximum count of connections
- that can be simultaneously queued awaiting acceptance.
- .PP
- An \fIaccept\fP call:
- .DS
- t = accept(s, name, anamelen);
- result int t; int s; result struct sockaddr *name; result int *anamelen;
- .DE
- returns a descriptor for a new, connected, socket
- from the queue of pending connections on \fIs\fP.
- If no new connections are queued for acceptance,
- the call will wait for a connection unless non-blocking I/O has been enabled.
- .NH 4
- Making connections
- .PP
- An active connection to a named socket is made by the \fIconnect\fP call:
- .DS
- connect(s, name, namelen);
- int s; struct sockaddr *name; int namelen;
- .DE
- Although datagram sockets do not establish connections,
- the \fIconnect\fP call may be used with such sockets
- to create an \fIassociation\fP with the foreign address.
- The address is recorded for use in future \fIsend\fP calls,
- which then need not supply destination addresses.
- Datagrams will be received only from that peer,
- and asynchronous error reports may be received.
- .PP
- It is also possible to create connected pairs of sockets without
- using the domain's name space to rendezvous; this is done with the
- \fIsocketpair\fP call\(dg:
- .FS
- \(dg 4.3BSD supports \fIsocketpair\fP creation only in the ``unix''
- communication domain.
- .FE
- .DS
- socketpair(domain, type, protocol, sv);
- int domain, type, protocol; result int sv[2];
- .DE
- Here the returned \fIsv\fP descriptors correspond to those obtained with
- \fIaccept\fP and \fIconnect\fP.
- .PP
- The call
- .DS
- pipe(pv)
- result int pv[2];
- .DE
- creates a pair of SOCK_STREAM sockets in the UNIX domain,
- with pv[0] only writable and pv[1] only readable.
- .NH 4
- Sending and receiving data
- .PP
- Messages may be sent from a socket by:
- .DS
- cc = sendto(s, buf, len, flags, to, tolen);
- result int cc; int s; caddr_t buf; int len, flags; caddr_t to; int tolen;
- .DE
- if the socket is not connected or:
- .DS
- cc = send(s, buf, len, flags);
- result int cc; int s; caddr_t buf; int len, flags;
- .DE
- if the socket is connected.
- The corresponding receive primitives are:
- .DS
- msglen = recvfrom(s, buf, len, flags, from, fromlenaddr);
- result int msglen; int s; result caddr_t buf; int len, flags;
- result caddr_t from; result int *fromlenaddr;
- .DE
- and
- .DS
- msglen = recv(s, buf, len, flags);
- result int msglen; int s; result caddr_t buf; int len, flags;
- .DE
- .PP
- In the unconnected case,
- the parameters \fIto\fP and \fItolen\fP
- specify the destination or source of the message, while
- the \fIfrom\fP parameter stores the source of the message,
- and \fI*fromlenaddr\fP initially gives the size of the \fIfrom\fP
- buffer and is updated to reflect the true length of the \fIfrom\fP
- address.
- .PP
- All calls cause the message to be received in or sent from
- the message buffer of length \fIlen\fP bytes, starting at address \fIbuf\fP.
- The \fIflags\fP specify
- peeking at a message without reading it or sending or receiving
- high-priority out-of-band messages, as follows:
- .DS
- ._d
- #define MSG_PEEK 0x1 /* peek at incoming message */
- #define MSG_OOB 0x2 /* process out-of-band data */
- .DE
- .NH 4
- Scatter/gather and exchanging access rights
- .PP
- It is possible scatter and gather data and to exchange access rights
- with messages. When either of these operations is involved,
- the number of parameters to the call becomes large.
- Thus the system defines a message header structure, in \fI<sys/socket.h>\fP,
- which can be
- used to conveniently contain the parameters to the calls:
- .DS
- .if t .ta .5i 1.25i 2i 2.7i
- .if n ._f
- struct msghdr {
- caddr_t msg_name; /* optional address */
- int msg_namelen; /* size of address */
- struct iov *msg_iov; /* scatter/gather array */
- int msg_iovlen; /* # elements in msg_iov */
- caddr_t msg_accrights; /* access rights sent/received */
- int msg_accrightslen; /* size of msg_accrights */
- };
- .DE
- Here \fImsg_name\fP and \fImsg_namelen\fP specify the source or destination
- address if the socket is unconnected; \fImsg_name\fP may be given as
- a null pointer if no names are desired or required.
- The \fImsg_iov\fP and \fImsg_iovlen\fP describe the scatter/gather
- locations, as described in section 2.1.3.
- Access rights to be sent along with the message are specified
- in \fImsg_accrights\fP, which has length \fImsg_accrightslen\fP.
- In the ``unix'' domain these are an array of integer descriptors,
- taken from the sending process and duplicated in the receiver.
- .PP
- This structure is used in the operations \fIsendmsg\fP and \fIrecvmsg\fP:
- .DS
- sendmsg(s, msg, flags);
- int s; struct msghdr *msg; int flags;
- msglen = recvmsg(s, msg, flags);
- result int msglen; int s; result struct msghdr *msg; int flags;
- .DE
- .NH 4
- Using read and write with sockets
- .PP
- The normal UNIX \fIread\fP and \fIwrite\fP calls may be
- applied to connected sockets and translated into \fIsend\fP and \fIreceive\fP
- calls from or to a single area of memory and discarding any rights
- received. A process may operate on a virtual circuit socket, a terminal
- or a file with blocking or non-blocking input/output
- operations without distinguishing the descriptor type.
- .NH 4
- Shutting down halves of full-duplex connections
- .PP
- A process that has a full-duplex socket such as a virtual circuit
- and no longer wishes to read from or write to this socket can
- give the call:
- .DS
- shutdown(s, direction);
- int s, direction;
- .DE
- where \fIdirection\fP is 0 to not read further, 1 to not
- write further, or 2 to completely shut the connection down.
- If the underlying protocol supports unidirectional or bidirectional shutdown,
- this indication will be passed to the peer.
- For example, a shutdown for writing might produce an end-of-file
- condition at the remote end.
- .NH 4
- Socket and protocol options
- .PP
- Sockets, and their underlying communication protocols, may
- support \fIoptions\fP. These options may be used to manipulate
- implementation- or protocol-specific facilities.
- The \fIgetsockopt\fP
- and \fIsetsockopt\fP calls are used to control options:
- .DS
- getsockopt(s, level, optname, optval, optlen)
- int s, level, optname; result caddr_t optval; result int *optlen;
- setsockopt(s, level, optname, optval, optlen)
- int s, level, optname; caddr_t optval; int optlen;
- .DE
- The option \fIoptname\fP is interpreted at the indicated
- protocol \fIlevel\fP for socket \fIs\fP. If a value is specified
- with \fIoptval\fP and \fIoptlen\fP, it is interpreted by
- the software operating at the specified \fIlevel\fP. The \fIlevel\fP
- SOL_SOCKET is reserved to indicate options maintained
- by the socket facilities. Other \fIlevel\fP values indicate
- a particular protocol which is to act on the option request;
- these values are normally interpreted as a ``protocol number''.
- .NH 3
- UNIX domain
- .PP
- This section describes briefly the properties of the UNIX communications
- domain.
- .NH 4
- Types of sockets
- .PP
- In the UNIX domain,
- the SOCK_STREAM abstraction provides pipe-like
- facilities, while SOCK_DGRAM provides (usually)
- reliable message-style communications.
- .NH 4
- Naming
- .PP
- Socket names are strings and may appear in the UNIX file
- system name space through portals\(dg.
- .FS
- \(dg The 4.3BSD implementation of the UNIX domain embeds
- bound sockets in the UNIX file system name space;
- this may change in future releases.
- .FE
- .NH 4
- Access rights transmission
- .PP
- The ability to pass UNIX descriptors with messages in this domain
- allows migration of service within the system and allows
- user processes to be used in building system facilities.
- .NH 3
- INTERNET domain
- .PP
- This section describes briefly how the Internet domain is
- mapped to the model described in this section. More
- information will be found in the document describing the
- network implementation in 4.3BSD.
- .NH 4
- Socket types and protocols
- .PP
- SOCK_STREAM is supported by the Internet TCP protocol;
- SOCK_DGRAM by the UDP protocol.
- Each is layered atop the transport-level Internet Protocol (IP).
- The Internet Control Message Protocol is implemented atop/beside IP
- and is accessible via a raw socket.
- The SOCK_SEQPACKET
- has no direct Internet family analogue; a protocol
- based on one from the XEROX NS family and layered on
- top of IP could be implemented to fill this gap.
- .NH 4
- Socket naming
- .PP
- Sockets in the Internet domain have names composed of the 32 bit
- Internet address, and a 16 bit port number.
- Options may be used to
- provide IP source routing or security options.
- The 32-bit address is composed of network and host parts;
- the network part is variable in size and is frequency encoded.
- The host part may optionally be interpreted as a subnet field
- plus the host on subnet; this is enabled by setting a network address
- mask at boot time.
- .NH 4
- Access rights transmission
- .PP
- No access rights transmission facilities are provided in the Internet domain.
- .NH 4
- Raw access
- .PP
- The Internet domain allows the super-user access to the raw facilities
- of IP.
- These interfaces are modeled as SOCK_RAW sockets.
- Each raw socket is associated with one IP protocol number,
- and receives all traffic received for that protocol.
- This allows administrative and debugging
- functions to occur,
- and enables user-level implementations of special-purpose protocols
- such as inter-gateway routing protocols.