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