share/doc/psd/05.sysman/2.3.t

   1 .\" Copyright (c) 1983, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)2.3.t       8.1 (Berkeley) 6/8/93
  29 .\"
  30 .sh "Interprocess communications
  31 .NH 3
  32 Interprocess communication primitives
  33 .NH 4
  34 Communication domains
  35 .PP
  36 The system provides access to an extensible set of
  37 communication \fIdomains\fP.  A communication domain
  38 is identified by a manifest constant defined in the
  39 file \fI<sys/socket.h>\fP.
  40 Important standard domains supported by the system are the ``unix''
  41 domain, AF_UNIX, for communication within the system, the ``Internet''
  42 domain for communication in the DARPA Internet, AF_INET,
  43 and the ``NS'' domain, AF_NS, for communication
  44 using the Xerox Network Systems protocols.
  45 Other domains can be added to the system.
  46 .NH 4
  47 Socket types and protocols
  48 .PP
  49 Within a domain, communication takes place between communication endpoints
  50 known as \fIsockets\fP.  Each socket has the potential to exchange
  51 information with other sockets of an appropriate type within the domain.
  52 .PP
  53 Each socket has an associated
  54 abstract type, which describes the semantics of communication using that
  55 socket.  Properties such as reliability, ordering, and prevention
  56 of duplication of messages are determined by the type.
  57 The basic set of socket types is defined in \fI<sys/socket.h>\fP:
  58 .DS
  59 /* Standard socket types */
  60 ._d
  61 #define SOCK_DGRAM      1       /* datagram */
  62 #define SOCK_STREAM     2       /* virtual circuit */
  63 #define SOCK_RAW        3       /* raw socket */
  64 #define SOCK_RDM        4       /* reliably-delivered message */
  65 #define SOCK_SEQPACKET  5       /* sequenced packets */
  66 .DE
  67 The SOCK_DGRAM type models the semantics of datagrams in network communication:
  68 messages may be lost or duplicated and may arrive out-of-order.
  69 A datagram socket may send messages to and receive messages from multiple
  70 peers.
  71 The SOCK_RDM type models the semantics of reliable datagrams: messages
  72 arrive unduplicated and in-order, the sender is notified if
  73 messages are lost.
  74 The \fIsend\fP and \fIreceive\fP operations (described below)
  75 generate reliable/unreliable datagrams.
  76 The SOCK_STREAM type models connection-based virtual circuits: two-way
  77 byte streams with no record boundaries.
  78 Connection setup is required before data communication may begin.
  79 The SOCK_SEQPACKET type models a connection-based,
  80 full-duplex, reliable, sequenced packet exchange;
  81 the sender is notified if messages are lost, and messages are never
  82 duplicated or presented out-of-order.
  83 Users of the last two abstractions may use the facilities for
  84 out-of-band transmission to send out-of-band data.
  85 .PP
  86 SOCK_RAW is used for unprocessed access to internal network layers
  87 and interfaces; it has no specific semantics.
  88 .PP
  89 Other socket types can be defined.
  90 .PP
  91 Each socket may have a specific \fIprotocol\fP associated with it.
  92 This protocol is used within the domain to provide the semantics
  93 required by the socket type.
  94 Not all socket types are supported by each domain;
  95 support depends on the existence and the implementation
  96 of a suitable protocol within the domain.
  97 For example, within the ``Internet'' domain, the SOCK_DGRAM type may be
  98 implemented by the UDP user datagram protocol, and the SOCK_STREAM
  99 type may be implemented by the TCP transmission control protocol, while
 100 no standard protocols to provide SOCK_RDM or SOCK_SEQPACKET sockets exist.
 101 .NH 4
 102 Socket creation, naming and service establishment
 103 .PP
 104 Sockets may be \fIconnected\fP or \fIunconnected\fP.  An unconnected
 105 socket descriptor is obtained by the \fIsocket\fP call:
 106 .DS
 107 s = socket(domain, type, protocol);
 108 result int s; int domain, type, protocol;
 109 .DE
 110 The socket domain and type are as described above,
 111 and are specified using the definitions from \fI<sys/socket.h>\fP.
 112 The protocol may be given as 0, meaning any suitable protocol.
 113 One of several possible protocols may be selected using identifiers
 114 obtained from a library routine, \fIgetprotobyname\fP.
 115 .PP
 116 An unconnected socket descriptor of a connection-oriented type
 117 may yield a connected socket descriptor
 118 in one of two ways: either by actively connecting to another socket,
 119 or by becoming associated with a name in the communications domain and
 120 \fIaccepting\fP a connection from another socket.
 121 Datagram sockets need not establish connections before use.
 122 .PP
 123 To accept connections or to receive datagrams,
 124 a socket must first have a binding
 125 to a name (or address) within the communications domain.
 126 Such a binding may be established by a \fIbind\fP call:
 127 .DS
 128 bind(s, name, namelen);
 129 int s; struct sockaddr *name; int namelen;
 130 .DE
 131 Datagram sockets may have default bindings established when first
 132 sending data if not explicitly bound earlier.
 133 In either case,
 134 a socket's bound name may be retrieved with a \fIgetsockname\fP call:
 135 .DS
 136 getsockname(s, name, namelen);
 137 int s; result struct sockaddr *name; result int *namelen;
 138 .DE
 139 while the peer's name can be retrieved with \fIgetpeername\fP:
 140 .DS
 141 getpeername(s, name, namelen);
 142 int s; result struct sockaddr *name; result int *namelen;
 143 .DE
 144 Domains may support sockets with several names.
 145 .NH 4
 146 Accepting connections
 147 .PP
 148 Once a binding is made to a connection-oriented socket,
 149 it is possible to \fIlisten\fP for connections:
 150 .DS
 151 listen(s, backlog);
 152 int s, backlog;
 153 .DE
 154 The \fIbacklog\fP specifies the maximum count of connections
 155 that can be simultaneously queued awaiting acceptance.
 156 .PP
 157 An \fIaccept\fP call:
 158 .DS
 159 t = accept(s, name, anamelen);
 160 result int t; int s; result struct sockaddr *name; result int *anamelen;
 161 .DE
 162 returns a descriptor for a new, connected, socket
 163 from the queue of pending connections on \fIs\fP.
 164 If no new connections are queued for acceptance,
 165 the call will wait for a connection unless non-blocking I/O has been enabled.
 166 .NH 4
 167 Making connections
 168 .PP
 169 An active connection to a named socket is made by the \fIconnect\fP call:
 170 .DS
 171 connect(s, name, namelen);
 172 int s; struct sockaddr *name; int namelen;
 173 .DE
 174 Although datagram sockets do not establish connections,
 175 the \fIconnect\fP call may be used with such sockets
 176 to create an \fIassociation\fP with the foreign address.
 177 The address is recorded for use in future \fIsend\fP calls,
 178 which then need not supply destination addresses.
 179 Datagrams will be received only from that peer,
 180 and asynchronous error reports may be received.
 181 .PP
 182 It is also possible to create connected pairs of sockets without
 183 using the domain's name space to rendezvous; this is done with the
 184 \fIsocketpair\fP call\(dg:
 185 .FS
 186 \(dg 4.3BSD supports \fIsocketpair\fP creation only in the ``unix''
 187 communication domain.
 188 .FE
 189 .DS
 190 socketpair(domain, type, protocol, sv);
 191 int domain, type, protocol; result int sv[2];
 192 .DE
 193 Here the returned \fIsv\fP descriptors correspond to those obtained with
 194 \fIaccept\fP and \fIconnect\fP.
 195 .PP
 196 The call
 197 .DS
 198 pipe(pv)
 199 result int pv[2];
 200 .DE
 201 creates a pair of SOCK_STREAM sockets in the UNIX domain,
 202 with pv[0] only writable and pv[1] only readable.
 203 .NH 4
 204 Sending and receiving data
 205 .PP
 206 Messages may be sent from a socket by:
 207 .DS
 208 cc = sendto(s, buf, len, flags, to, tolen);
 209 result int cc; int s; caddr_t buf; int len, flags; caddr_t to; int tolen;
 210 .DE
 211 if the socket is not connected or:
 212 .DS
 213 cc = send(s, buf, len, flags);
 214 result int cc; int s; caddr_t buf; int len, flags;
 215 .DE
 216 if the socket is connected.
 217 The corresponding receive primitives are:
 218 .DS
 219 msglen = recvfrom(s, buf, len, flags, from, fromlenaddr);
 220 result int msglen; int s; result caddr_t buf; int len, flags;
 221 result caddr_t from; result int *fromlenaddr;
 222 .DE
 223 and
 224 .DS
 225 msglen = recv(s, buf, len, flags);
 226 result int msglen; int s; result caddr_t buf; int len, flags;
 227 .DE
 228 .PP
 229 In the unconnected case,
 230 the parameters \fIto\fP and \fItolen\fP
 231 specify the destination or source of the message, while
 232 the \fIfrom\fP parameter stores the source of the message,
 233 and \fI*fromlenaddr\fP initially gives the size of the \fIfrom\fP
 234 buffer and is updated to reflect the true length of the \fIfrom\fP
 235 address.
 236 .PP
 237 All calls cause the message to be received in or sent from
 238 the message buffer of length \fIlen\fP bytes, starting at address \fIbuf\fP.
 239 The \fIflags\fP specify
 240 peeking at a message without reading it or sending or receiving
 241 high-priority out-of-band messages, as follows:
 242 .DS
 243 ._d
 244 #define MSG_PEEK        0x1     /* peek at incoming message */
 245 #define MSG_OOB 0x2     /* process out-of-band data */
 246 .DE
 247 .NH 4
 248 Scatter/gather and exchanging access rights
 249 .PP
 250 It is possible scatter and gather data and to exchange access rights
 251 with messages.  When either of these operations is involved,
 252 the number of parameters to the call becomes large.
 253 Thus the system defines a message header structure, in \fI<sys/socket.h>\fP,
 254 which can be
 255 used to conveniently contain the parameters to the calls:
 256 .DS
 257 .if t .ta .5i 1.25i 2i 2.7i
 258 .if n ._f
 259 struct msghdr {
 260         caddr_t msg_name;               /* optional address */
 261         int     msg_namelen;    /* size of address */
 262         struct  iov *msg_iov;   /* scatter/gather array */
 263         int     msg_iovlen;             /* # elements in msg_iov */
 264         caddr_t msg_accrights;  /* access rights sent/received */
 265         int     msg_accrightslen;       /* size of msg_accrights */
 266 };
 267 .DE
 268 Here \fImsg_name\fP and \fImsg_namelen\fP specify the source or destination
 269 address if the socket is unconnected; \fImsg_name\fP may be given as
 270 a null pointer if no names are desired or required.
 271 The \fImsg_iov\fP and \fImsg_iovlen\fP describe the scatter/gather
 272 locations, as described in section 2.1.3.
 273 Access rights to be sent along with the message are specified
 274 in \fImsg_accrights\fP, which has length \fImsg_accrightslen\fP.
 275 In the ``unix'' domain these are an array of integer descriptors,
 276 taken from the sending process and duplicated in the receiver.
 277 .PP
 278 This structure is used in the operations \fIsendmsg\fP and \fIrecvmsg\fP:
 279 .DS
 280 sendmsg(s, msg, flags);
 281 int s; struct msghdr *msg; int flags;
 282
 283 msglen = recvmsg(s, msg, flags);
 284 result int msglen; int s; result struct msghdr *msg; int flags;
 285 .DE
 286 .NH 4
 287 Using read and write with sockets
 288 .PP
 289 The normal UNIX \fIread\fP and \fIwrite\fP calls may be
 290 applied to connected sockets and translated into \fIsend\fP and \fIreceive\fP
 291 calls from or to a single area of memory and discarding any rights
 292 received.  A process may operate on a virtual circuit socket, a terminal
 293 or a file with blocking or non-blocking input/output
 294 operations without distinguishing the descriptor type.
 295 .NH 4
 296 Shutting down halves of full-duplex connections
 297 .PP
 298 A process that has a full-duplex socket such as a virtual circuit
 299 and no longer wishes to read from or write to this socket can
 300 give the call:
 301 .DS
 302 shutdown(s, direction);
 303 int s, direction;
 304 .DE
 305 where \fIdirection\fP is 0 to not read further, 1 to not
 306 write further, or 2 to completely shut the connection down.
 307 If the underlying protocol supports unidirectional or bidirectional shutdown,
 308 this indication will be passed to the peer.
 309 For example, a shutdown for writing might produce an end-of-file
 310 condition at the remote end.
 311 .NH 4
 312 Socket and protocol options
 313 .PP
 314 Sockets, and their underlying communication protocols, may
 315 support \fIoptions\fP.  These options may be used to manipulate
 316 implementation- or protocol-specific facilities.
 317 The \fIgetsockopt\fP
 318 and \fIsetsockopt\fP calls are used to control options:
 319 .DS
 320 getsockopt(s, level, optname, optval, optlen)
 321 int s, level, optname; result caddr_t optval; result int *optlen;
 322
 323 setsockopt(s, level, optname, optval, optlen)
 324 int s, level, optname; caddr_t optval; int optlen;
 325 .DE
 326 The option \fIoptname\fP is interpreted at the indicated
 327 protocol \fIlevel\fP for socket \fIs\fP.  If a value is specified
 328 with \fIoptval\fP and \fIoptlen\fP, it is interpreted by
 329 the software operating at the specified \fIlevel\fP.  The \fIlevel\fP
 330 SOL_SOCKET is reserved to indicate options maintained
 331 by the socket facilities.  Other \fIlevel\fP values indicate
 332 a particular protocol which is to act on the option request;
 333 these values are normally interpreted as a ``protocol number''.
 334 .NH 3
 335 UNIX domain
 336 .PP
 337 This section describes briefly the properties of the UNIX communications
 338 domain.
 339 .NH 4
 340 Types of sockets
 341 .PP
 342 In the UNIX domain,
 343 the SOCK_STREAM abstraction provides pipe-like
 344 facilities, while SOCK_DGRAM provides (usually)
 345 reliable message-style communications.
 346 .NH 4
 347 Naming
 348 .PP
 349 Socket names are strings and may appear in the UNIX file
 350 system name space through portals\(dg.
 351 .FS
 352 \(dg The 4.3BSD implementation of the UNIX domain embeds
 353 bound sockets in the UNIX file system name space;
 354 this may change in future releases.
 355 .FE
 356 .NH 4
 357 Access rights transmission
 358 .PP
 359 The ability to pass UNIX descriptors with messages in this domain
 360 allows migration of service within the system and allows
 361 user processes to be used in building system facilities.
 362 .NH 3
 363 INTERNET domain
 364 .PP
 365 This section describes briefly how the Internet domain is
 366 mapped to the model described in this section.  More
 367 information will be found in the document describing the
 368 network implementation in 4.3BSD.
 369 .NH 4
 370 Socket types and protocols
 371 .PP
 372 SOCK_STREAM is supported by the Internet TCP protocol;
 373 SOCK_DGRAM by the UDP protocol.
 374 Each is layered atop the transport-level Internet Protocol (IP).
 375 The Internet Control Message Protocol is implemented atop/beside IP
 376 and is accessible via a raw socket.
 377 The SOCK_SEQPACKET
 378 has no direct Internet family analogue; a protocol
 379 based on one from the XEROX NS family and layered on
 380 top of IP could be implemented to fill this gap.
 381 .NH 4
 382 Socket naming
 383 .PP
 384 Sockets in the Internet domain have names composed of the 32 bit
 385 Internet address, and a 16 bit port number.
 386 Options may be used to
 387 provide IP source routing or security options.
 388 The 32-bit address is composed of network and host parts;
 389 the network part is variable in size and is frequency encoded.
 390 The host part may optionally be interpreted as a subnet field
 391 plus the host on subnet; this is enabled by setting a network address
 392 mask at boot time.
 393 .NH 4
 394 Access rights transmission
 395 .PP
 396 No access rights transmission facilities are provided in the Internet domain.
 397 .NH 4
 398 Raw access
 399 .PP
 400 The Internet domain allows the super-user access to the raw facilities
 401 of IP.
 402 These interfaces are modeled as SOCK_RAW sockets.
 403 Each raw socket is associated with one IP protocol number,
 404 and receives all traffic received for that protocol.
 405 This allows administrative and debugging
 406 functions to occur,
 407 and enables user-level implementations of special-purpose protocols
 408 such as inter-gateway routing protocols.