/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

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