![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to 2.t CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 08.ipc|
Return to 2.t CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 08.ipc |
1.1 ! root 1: .\" Copyright (c) 1986 The Regents of the University of California. ! 2: .\" All rights reserved. ! 3: .\" ! 4: .\" Redistribution and use in source and binary forms are permitted ! 5: .\" provided that the above copyright notice and this paragraph are ! 6: .\" duplicated in all such forms and that any documentation, ! 7: .\" advertising materials, and other materials related to such ! 8: .\" distribution and use acknowledge that the software was developed ! 9: .\" by the University of California, Berkeley. The name of the ! 10: .\" University may not be used to endorse or promote products derived ! 11: .\" from this software without specific prior written permission. ! 12: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR ! 13: .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED ! 14: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. ! 15: .\" ! 16: .\" @(#)2.t 1.4 (Berkeley) 3/7/89 ! 17: .\" ! 18: .\".ds RH "Basics ! 19: .bp ! 20: .nr H1 2 ! 21: .nr H2 0 ! 22: .bp ! 23: .LG ! 24: .B ! 25: .ce ! 26: 2. BASICS ! 27: .sp 2 ! 28: .R ! 29: .NL ! 30: .PP ! 31: The basic building block for communication is the \fIsocket\fP. ! 32: A socket is an endpoint of communication to which a name may ! 33: be \fIbound\fP. Each socket in use has a \fItype\fP ! 34: and one or more associated processes. Sockets exist within ! 35: \fIcommunication domains\fP. ! 36: A communication domain is an ! 37: abstraction introduced to bundle common properties of ! 38: processes communicating through sockets. ! 39: One such property is the scheme used to name sockets. For ! 40: example, in the UNIX communication domain sockets are ! 41: named with UNIX path names; e.g. a ! 42: socket may be named \*(lq/dev/foo\*(rq. Sockets normally ! 43: exchange data only with ! 44: sockets in the same domain (it may be possible to cross domain ! 45: boundaries, but only if some translation process is ! 46: performed). The ! 47: 4.3BSD IPC facilities support three separate communication domains: ! 48: the UNIX domain, for on-system communication; ! 49: the Internet domain, which is used by ! 50: processes which communicate ! 51: using the the DARPA standard communication protocols; ! 52: and the NS domain, which is used by processes which ! 53: communicate using the Xerox standard communication ! 54: protocols*. ! 55: .FS ! 56: * See \fIInternet Transport Protocols\fP, Xerox System Integration ! 57: Standard (XSIS)028112 for more information. This document is ! 58: almost a necessity for one trying to write NS applications. ! 59: .FE ! 60: The underlying communication ! 61: facilities provided by these domains have a significant influence ! 62: on the internal system implementation as well as the interface to ! 63: socket facilities available to a user. An example of the ! 64: latter is that a socket \*(lqoperating\*(rq in the UNIX domain ! 65: sees a subset of the error conditions which are possible ! 66: when operating in the Internet (or NS) domain. ! 67: .NH 2 ! 68: Socket types ! 69: .PP ! 70: Sockets are ! 71: typed according to the communication properties visible to a ! 72: user. ! 73: Processes are presumed to communicate only between sockets of ! 74: the same type, although there is ! 75: nothing that prevents communication between sockets of different ! 76: types should the underlying communication ! 77: protocols support this. ! 78: .PP ! 79: Four types of sockets currently are available to a user. ! 80: A \fIstream\fP socket provides for the bidirectional, reliable, ! 81: sequenced, and unduplicated flow of data without record boundaries. ! 82: Aside from the bidirectionality of data flow, a pair of connected ! 83: stream sockets provides an interface nearly identical to that of pipes\(dg. ! 84: .FS ! 85: \(dg In the UNIX domain, in fact, the semantics are identical and, ! 86: as one might expect, pipes have been implemented internally ! 87: as simply a pair of connected stream sockets. ! 88: .FE ! 89: .PP ! 90: A \fIdatagram\fP socket supports bidirectional flow of data which ! 91: is not promised to be sequenced, reliable, or unduplicated. ! 92: That is, a process ! 93: receiving messages on a datagram socket may find messages duplicated, ! 94: and, possibly, ! 95: in an order different from the order in which it was sent. ! 96: An important characteristic of a datagram ! 97: socket is that record boundaries in data are preserved. Datagram ! 98: sockets closely model the facilities found in many contemporary ! 99: packet switched networks such as the Ethernet. ! 100: .PP ! 101: A \fIraw\fP socket provides users access to ! 102: the underlying communication ! 103: protocols which support socket abstractions. ! 104: These sockets are normally datagram oriented, though their ! 105: exact characteristics are dependent on the interface provided by ! 106: the protocol. Raw sockets are not intended for the general user; they ! 107: have been provided mainly for those interested in developing new ! 108: communication protocols, or for gaining access to some of the more ! 109: esoteric facilities of an existing protocol. The use of raw sockets ! 110: is considered in section 5. ! 111: .PP ! 112: A \fIsequenced packet\fP socket is similar to a stream socket, ! 113: with the exception that record boundaries are preserved. This ! 114: interface is provided only as part of the NS socket abstraction, ! 115: and is very important in most serious NS applications. ! 116: Sequenced-packet sockets allow the user to manipulate the ! 117: SPP or IDP headers on a packet or a group of packets either ! 118: by writing a prototype header along with whatever data is ! 119: to be sent, or by specifying a default header to be used with ! 120: all outgoing data, and allows the user to receive the headers ! 121: on incoming packets. The use of these options is considered in ! 122: section 5. ! 123: .PP ! 124: Another potential socket type which has interesting properties is ! 125: the \fIreliably delivered ! 126: message\fP socket. ! 127: The reliably delivered message socket has ! 128: similar properties to a datagram socket, but with ! 129: reliable delivery. There is currently no support for this ! 130: type of socket, but a reliably delivered message protocol ! 131: similar to Xerox's Packet Exchange Protocol (PEX) may be ! 132: simulated at the user level. More information on this topic ! 133: can be found in section 5. ! 134: .NH 2 ! 135: Socket creation ! 136: .PP ! 137: To create a socket the \fIsocket\fP system call is used: ! 138: .DS ! 139: s = socket(domain, type, protocol); ! 140: .DE ! 141: This call requests that the system create a socket in the specified ! 142: \fIdomain\fP and of the specified \fItype\fP. A particular protocol may ! 143: also be requested. If the protocol is left unspecified (a value ! 144: of 0), the system will select an appropriate protocol from those ! 145: protocols which comprise the communication domain and which ! 146: may be used to support the requested socket type. The user is ! 147: returned a descriptor (a small integer number) which may be used ! 148: in later system calls which operate on sockets. The domain is specified as ! 149: one of the manifest constants defined in the file <\fIsys/socket.h\fP>. ! 150: For the UNIX domain the constant is AF_UNIX*; for the Internet ! 151: .FS ! 152: * The manifest constants are named AF_whatever as they indicate ! 153: the ``address format'' to use in interpreting names. ! 154: .FE ! 155: domain AF_INET; and for the NS domain, AF_NS. ! 156: The socket types are also defined in this file ! 157: and one of SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, or SOCK_SEQPACKET ! 158: must be specified. ! 159: To create a stream socket in the Internet domain the following ! 160: call might be used: ! 161: .DS ! 162: s = socket(AF_INET, SOCK_STREAM, 0); ! 163: .DE ! 164: This call would result in a stream socket being created with the TCP ! 165: protocol providing the underlying communication support. To ! 166: create a datagram socket for on-machine use the call might ! 167: be: ! 168: .DS ! 169: s = socket(AF_UNIX, SOCK_DGRAM, 0); ! 170: .DE ! 171: .PP ! 172: The default protocol (used when the \fIprotocol\fP argument to the ! 173: \fIsocket\fP call is 0) should be correct for most every ! 174: situation. However, it is possible to specify a protocol ! 175: other than the default; this will be covered in ! 176: section 5. ! 177: .PP ! 178: There are several reasons a socket call may fail. Aside from ! 179: the rare occurrence of lack of memory (ENOBUFS), a socket ! 180: request may fail due to a request for an unknown protocol ! 181: (EPROTONOSUPPORT), or a request for a type of socket for ! 182: which there is no supporting protocol (EPROTOTYPE). ! 183: .NH 2 ! 184: Binding local names ! 185: .PP ! 186: A socket is created without a name. Until a name is bound ! 187: to a socket, processes have no way to reference it and, consequently, ! 188: no messages may be received on it. ! 189: Communicating processes are bound ! 190: by an \fIassociation\fP. In the Internet and NS domains, ! 191: an association ! 192: is composed of local and foreign ! 193: addresses, and local and foreign ports, ! 194: while in the UNIX domain, an association is composed of ! 195: local and foreign path names (the phrase ``foreign pathname'' ! 196: means a pathname created by a foreign process, not a pathname ! 197: on a foreign system). ! 198: In most domains, associations must be unique. ! 199: In the Internet domain there ! 200: may never be duplicate <protocol, local address, local port, foreign ! 201: address, foreign port> tuples. UNIX domain sockets need not always ! 202: be bound to a name, but when bound ! 203: there may never be duplicate <protocol, local pathname, foreign ! 204: pathname> tuples. ! 205: The pathnames may not refer to files ! 206: already existing on the system ! 207: in 4.3; the situation may change in future releases. ! 208: .PP ! 209: The \fIbind\fP system call allows a process to specify half of ! 210: an association, <local address, local port> ! 211: (or <local pathname>), while the \fIconnect\fP ! 212: and \fIaccept\fP primitives are used to complete a socket's association. ! 213: .PP ! 214: In the Internet domain, ! 215: binding names to sockets can be fairly complex. ! 216: Fortunately, it is usually not necessary to specifically bind an ! 217: address and port number to a socket, because the ! 218: \fIconnect\fP and \fIsend\fP calls will automatically ! 219: bind an appropriate address if they are used with an ! 220: unbound socket. The process of binding names to NS ! 221: sockets is similar in most ways to that of ! 222: binding names to Internet sockets. ! 223: .PP ! 224: The \fIbind\fP system call is used as follows: ! 225: .DS ! 226: bind(s, name, namelen); ! 227: .DE ! 228: The bound name is a variable length byte string which is interpreted ! 229: by the supporting protocol(s). Its interpretation may vary from ! 230: communication domain to communication domain (this is one of ! 231: the properties which comprise the \*(lqdomain\*(rq). ! 232: As mentioned, in the ! 233: Internet domain names contain an Internet address and port ! 234: number. NS domain names contain an NS address and ! 235: port number. In the UNIX domain, names contain a path name and ! 236: a family, which is always AF_UNIX. If one wanted to bind ! 237: the name \*(lq/tmp/foo\*(rq to a UNIX domain socket, the ! 238: following code would be used*: ! 239: .FS ! 240: * Note that, although the tendency here is to call the \*(lqaddr\*(rq ! 241: structure \*(lqsun\*(rq, doing so would cause problems if the code ! 242: were ever ported to a Sun workstation. ! 243: .FE ! 244: .DS ! 245: #include <sys/un.h> ! 246: ... ! 247: struct sockaddr_un addr; ! 248: ... ! 249: strcpy(addr.sun_path, "/tmp/foo"); ! 250: addr.sun_family = AF_UNIX; ! 251: bind(s, (struct sockaddr *) &addr, strlen(addr.sun_path) + ! 252: sizeof (addr.sun_family)); ! 253: .DE ! 254: Note that in determining the size of a UNIX domain address null ! 255: bytes are not counted, which is why \fIstrlen\fP is used. In ! 256: the current implementation of UNIX domain IPC under 4.3BSD, ! 257: the file name ! 258: referred to in \fIaddr.sun_path\fP is created as a socket ! 259: in the system file space. ! 260: The caller must, therefore, have ! 261: write permission in the directory where ! 262: \fIaddr.sun_path\fP is to reside, and this file should be deleted by the ! 263: caller when it is no longer needed. Future versions of 4BSD ! 264: may not create this file. ! 265: .PP ! 266: In binding an Internet address things become more ! 267: complicated. The actual call is similar, ! 268: .DS ! 269: #include <sys/types.h> ! 270: #include <netinet/in.h> ! 271: ... ! 272: struct sockaddr_in sin; ! 273: ... ! 274: bind(s, (struct sockaddr *) &sin, sizeof (sin)); ! 275: .DE ! 276: but the selection of what to place in the address \fIsin\fP ! 277: requires some discussion. We will come back to the problem ! 278: of formulating Internet addresses in section 3 when ! 279: the library routines used in name resolution are discussed. ! 280: .PP ! 281: Binding an NS address to a socket is even more ! 282: difficult, ! 283: especially since the Internet library routines do not ! 284: work with NS hostnames. The actual call is again similar: ! 285: .DS ! 286: #include <sys/types.h> ! 287: #include <netns/ns.h> ! 288: ... ! 289: struct sockaddr_ns sns; ! 290: ... ! 291: bind(s, (struct sockaddr *) &sns, sizeof (sns)); ! 292: .DE ! 293: Again, discussion of what to place in a \*(lqstruct sockaddr_ns\*(rq ! 294: will be deferred to section 3. ! 295: .NH 2 ! 296: Connection establishment ! 297: .PP ! 298: Connection establishment is usually asymmetric, ! 299: with one process a \*(lqclient\*(rq and the other a \*(lqserver\*(rq. ! 300: The server, when willing to offer its advertised services, ! 301: binds a socket to a well-known address associated with the service ! 302: and then passively \*(lqlistens\*(rq on its socket. ! 303: It is then possible for an unrelated process to rendezvous ! 304: with the server. ! 305: The client requests services from the server by initiating a ! 306: \*(lqconnection\*(rq to the server's socket. ! 307: On the client side the \fIconnect\fP call is ! 308: used to initiate a connection. Using the UNIX domain, this ! 309: might appear as, ! 310: .DS ! 311: struct sockaddr_un server; ! 312: ... ! 313: connect(s, (struct sockaddr *)&server, strlen(server.sun_path) + ! 314: sizeof (server.sun_family)); ! 315: .DE ! 316: while in the Internet domain, ! 317: .DS ! 318: struct sockaddr_in server; ! 319: ... ! 320: connect(s, (struct sockaddr *)&server, sizeof (server)); ! 321: .DE ! 322: and in the NS domain, ! 323: .DS ! 324: struct sockaddr_ns server; ! 325: ... ! 326: connect(s, (struct sockaddr *)&server, sizeof (server)); ! 327: .DE ! 328: where \fIserver\fP in the example above would contain either the UNIX ! 329: pathname, Internet address and port number, or NS address and ! 330: port number of the server to which the ! 331: client process wishes to speak. ! 332: If the client process's socket is unbound at the time of ! 333: the connect call, ! 334: the system will automatically select and bind a name to ! 335: the socket if necessary; c.f. section 5.4. ! 336: This is the usual way that local addresses are bound ! 337: to a socket. ! 338: .PP ! 339: An error is returned if the connection was unsuccessful ! 340: (any name automatically bound by the system, however, remains). ! 341: Otherwise, the socket is associated with the server and ! 342: data transfer may begin. Some of the more common errors returned ! 343: when a connection attempt fails are: ! 344: .IP ETIMEDOUT ! 345: .br ! 346: After failing to establish a connection for a period of time, ! 347: the system decided there was no point in retrying the ! 348: connection attempt any more. This usually occurs because ! 349: the destination host is down, or because problems in ! 350: the network resulted in transmissions being lost. ! 351: .IP ECONNREFUSED ! 352: .br ! 353: The host refused service for some reason. ! 354: This is usually ! 355: due to a server process ! 356: not being present at the requested name. ! 357: .IP "ENETDOWN or EHOSTDOWN" ! 358: .br ! 359: These operational errors are ! 360: returned based on status information delivered to ! 361: the client host by the underlying communication services. ! 362: .IP "ENETUNREACH or EHOSTUNREACH" ! 363: .br ! 364: These operational errors can occur either because the network ! 365: or host is unknown (no route to the network or host is present), ! 366: or because of status information returned by intermediate ! 367: gateways or switching nodes. Many times the status returned ! 368: is not sufficient to distinguish a network being down from a ! 369: host being down, in which case the system ! 370: indicates the entire network is unreachable. ! 371: .PP ! 372: For the server to receive a client's connection it must perform ! 373: two steps after binding its socket. ! 374: The first is to indicate a willingness to listen for ! 375: incoming connection requests: ! 376: .DS ! 377: listen(s, 5); ! 378: .DE ! 379: The second parameter to the \fIlisten\fP call specifies the maximum ! 380: number of outstanding connections which may be queued awaiting ! 381: acceptance by the server process; this number ! 382: may be limited by the system. Should a connection be ! 383: requested while the queue is full, the connection will not be ! 384: refused, but rather the individual messages which comprise the ! 385: request will be ignored. This gives a harried server time to ! 386: make room in its pending connection queue while the client ! 387: retries the connection request. Had the connection been returned ! 388: with the ECONNREFUSED error, the client would be unable to tell ! 389: if the server was up or not. As it is now it is still possible ! 390: to get the ETIMEDOUT error back, though this is unlikely. The ! 391: backlog figure supplied with the listen call is currently limited ! 392: by the system to a maximum of 5 pending connections on any ! 393: one queue. This avoids the problem of processes hogging system ! 394: resources by setting an infinite backlog, then ignoring ! 395: all connection requests. ! 396: .PP ! 397: With a socket marked as listening, a server may \fIaccept\fP ! 398: a connection: ! 399: .DS ! 400: struct sockaddr_in from; ! 401: ... ! 402: fromlen = sizeof (from); ! 403: newsock = accept(s, (struct sockaddr *)&from, &fromlen); ! 404: .DE ! 405: (For the UNIX domain, \fIfrom\fP would be declared as a ! 406: \fIstruct sockaddr_un\fP, and for the NS domain, \fIfrom\fP ! 407: would be declared as a \fIstruct sockaddr_ns\fP, ! 408: but nothing different would need ! 409: to be done as far as \fIfromlen\fP is concerned. In the examples ! 410: which follow, only Internet routines will be discussed.) A new ! 411: descriptor is returned on receipt of a connection (along with ! 412: a new socket). If the server wishes to find out who its client is, ! 413: it may supply a buffer for the client socket's name. The value-result ! 414: parameter \fIfromlen\fP is initialized by the server to indicate how ! 415: much space is associated with \fIfrom\fP, then modified on return ! 416: to reflect the true size of the name. If the client's name is not ! 417: of interest, the second parameter may be a null pointer. ! 418: .PP ! 419: \fIAccept\fP normally blocks. That is, \fIaccept\fP ! 420: will not return until a connection is available or the system call ! 421: is interrupted by a signal to the process. Further, there is no ! 422: way for a process to indicate it will accept connections from only ! 423: a specific individual, or individuals. It is up to the user process ! 424: to consider who the connection is from and close down the connection ! 425: if it does not wish to speak to the process. If the server process ! 426: wants to accept connections on more than one socket, or wants to avoid blocking ! 427: on the accept call, there are alternatives; they will be considered ! 428: in section 5. ! 429: .NH 2 ! 430: Data transfer ! 431: .PP ! 432: With a connection established, data may begin to flow. To send ! 433: and receive data there are a number of possible calls. ! 434: With the peer entity at each end of a connection ! 435: anchored, a user can send or receive a message without specifying ! 436: the peer. As one might expect, in this case, then ! 437: the normal \fIread\fP and \fIwrite\fP system calls are usable, ! 438: .DS ! 439: write(s, buf, sizeof (buf)); ! 440: read(s, buf, sizeof (buf)); ! 441: .DE ! 442: In addition to \fIread\fP and \fIwrite\fP, ! 443: the new calls \fIsend\fP and \fIrecv\fP ! 444: may be used: ! 445: .DS ! 446: send(s, buf, sizeof (buf), flags); ! 447: recv(s, buf, sizeof (buf), flags); ! 448: .DE ! 449: While \fIsend\fP and \fIrecv\fP are virtually identical to ! 450: \fIread\fP and \fIwrite\fP, ! 451: the extra \fIflags\fP argument is important. The flags, ! 452: defined in \fI<sys/socket.h>\fP, may be ! 453: specified as a non-zero value if one or more ! 454: of the following is required: ! 455: .DS ! 456: .TS ! 457: l l. ! 458: MSG_OOB send/receive out of band data ! 459: MSG_PEEK look at data without reading ! 460: MSG_DONTROUTE send data without routing packets ! 461: .TE ! 462: .DE ! 463: Out of band data is a notion specific to stream sockets, and one ! 464: which we will not immediately consider. The option to have data ! 465: sent without routing applied to the outgoing packets is currently ! 466: used only by the routing table management process, and is ! 467: unlikely to be of interest to the casual user. The ability ! 468: to preview data is, however, of interest. When MSG_PEEK ! 469: is specified with a \fIrecv\fP call, any data present is returned ! 470: to the user, but treated as still \*(lqunread\*(rq. That ! 471: is, the next \fIread\fP or \fIrecv\fP call applied to the socket will ! 472: return the data previously previewed. ! 473: .NH 2 ! 474: Discarding sockets ! 475: .PP ! 476: Once a socket is no longer of interest, it may be discarded ! 477: by applying a \fIclose\fP to the descriptor, ! 478: .DS ! 479: close(s); ! 480: .DE ! 481: If data is associated with a socket which promises reliable delivery ! 482: (e.g. a stream socket) when a close takes place, the system will ! 483: continue to attempt to transfer the data. ! 484: However, after a fairly long period of ! 485: time, if the data is still undelivered, it will be discarded. ! 486: Should a user have no use for any pending data, it may ! 487: perform a \fIshutdown\fP on the socket prior to closing it. ! 488: This call is of the form: ! 489: .DS ! 490: shutdown(s, how); ! 491: .DE ! 492: where \fIhow\fP is 0 if the user is no longer interested in reading ! 493: data, 1 if no more data will be sent, or 2 if no data is to ! 494: be sent or received. ! 495: .NH 2 ! 496: Connectionless sockets ! 497: .PP ! 498: To this point we have been concerned mostly with sockets which ! 499: follow a connection oriented model. However, there is also ! 500: support for connectionless interactions typical of the datagram ! 501: facilities found in contemporary packet switched networks. ! 502: A datagram socket provides a symmetric interface to data ! 503: exchange. While processes are still likely to be client ! 504: and server, there is no requirement for connection establishment. ! 505: Instead, each message includes the destination address. ! 506: .PP ! 507: Datagram sockets are created as before. ! 508: If a particular local address is needed, ! 509: the \fIbind\fP operation must precede the first data transmission. ! 510: Otherwise, the system will set the local address and/or port ! 511: when data is first sent. ! 512: To send data, the \fIsendto\fP primitive is used, ! 513: .DS ! 514: sendto(s, buf, buflen, flags, (struct sockaddr *)&to, tolen); ! 515: .DE ! 516: The \fIs\fP, \fIbuf\fP, \fIbuflen\fP, and \fIflags\fP ! 517: parameters are used as before. ! 518: The \fIto\fP and \fItolen\fP ! 519: values are used to indicate the address of the intended recipient of the ! 520: message. When ! 521: using an unreliable datagram interface, it is ! 522: unlikely that any errors will be reported to the sender. When ! 523: information is present locally to recognize a message that can ! 524: not be delivered (for instance when a network is unreachable), ! 525: the call will return \-1 and the global value \fIerrno\fP will ! 526: contain an error number. ! 527: .PP ! 528: To receive messages on an unconnected datagram socket, the ! 529: \fIrecvfrom\fP primitive is provided: ! 530: .DS ! 531: recvfrom(s, buf, buflen, flags, (struct sockaddr *)&from, &fromlen); ! 532: .DE ! 533: Once again, the \fIfromlen\fP parameter is handled in ! 534: a value-result fashion, initially containing the size of ! 535: the \fIfrom\fP buffer, and modified on return to indicate ! 536: the actual size of the address from which the datagram was received. ! 537: .PP ! 538: In addition to the two calls mentioned above, datagram ! 539: sockets may also use the \fIconnect\fP call to associate ! 540: a socket with a specific destination address. In this case, any ! 541: data sent on the socket will automatically be addressed ! 542: to the connected peer, and only data received from that ! 543: peer will be delivered to the user. Only one connected ! 544: address is permitted for each socket at one time; ! 545: a second connect will change the destination address, ! 546: and a connect to a null address (family AF_UNSPEC) ! 547: will disconnect. ! 548: Connect requests on datagram sockets return immediately, ! 549: as this simply results in the system recording ! 550: the peer's address (as compared to a stream socket, where a ! 551: connect request initiates establishment of an end to end ! 552: connection). \fIAccept\fP and \fIlisten\fP are not ! 553: used with datagram sockets. ! 554: .PP ! 555: While a datagram socket socket is connected, ! 556: errors from recent \fIsend\fP calls may be returned ! 557: asynchronously. ! 558: These errors may be reported on subsequent operations ! 559: on the socket, ! 560: or a special socket option used with \fIgetsockopt\fP, SO_ERROR, ! 561: may be used to interrogate the error status. ! 562: A \fIselect\fP for reading or writing will return true ! 563: when an error indication has been received. ! 564: The next operation will return the error, and the error status is cleared. ! 565: Other of the less ! 566: important details of datagram sockets are described ! 567: in section 5. ! 568: .NH 2 ! 569: Input/Output multiplexing ! 570: .PP ! 571: One last facility often used in developing applications ! 572: is the ability to multiplex i/o requests among multiple ! 573: sockets and/or files. This is done using the \fIselect\fP ! 574: call: ! 575: .DS ! 576: #include <sys/time.h> ! 577: #include <sys/types.h> ! 578: ... ! 579: ! 580: fd_set readmask, writemask, exceptmask; ! 581: struct timeval timeout; ! 582: ... ! 583: select(nfds, &readmask, &writemask, &exceptmask, &timeout); ! 584: .DE ! 585: \fISelect\fP takes as arguments pointers to three sets, one for ! 586: the set of file descriptors for which the caller wishes to ! 587: be able to read data on, one for those descriptors to which ! 588: data is to be written, and one for which exceptional conditions ! 589: are pending; out-of-band data is the only ! 590: exceptional condition currently implemented by the socket ! 591: If the user is not interested ! 592: in certain conditions (i.e., read, write, or exceptions), ! 593: the corresponding argument to the \fIselect\fP should ! 594: be a null pointer. ! 595: .PP ! 596: Each set is actually a structure containing an array of ! 597: long integer bit masks; the size of the array is set ! 598: by the definition FD_SETSIZE. ! 599: The array is be ! 600: long enough to hold one bit for each of FD_SETSIZE file descriptors. ! 601: .PP ! 602: The macros FD_SET(\fIfd, &mask\fP) and ! 603: FD_CLR(\fIfd, &mask\fP) ! 604: have been provided for adding and removing file descriptor ! 605: \fIfd\fP in the set \fImask\fP. The ! 606: set should be zeroed before use, and ! 607: the macro FD_ZERO(\fI&mask\fP) has been provided ! 608: to clear the set \fImask\fP. ! 609: The parameter \fInfds\fP in the \fIselect\fP call specifies the range ! 610: of file descriptors (i.e. one plus the value of the largest ! 611: descriptor) to be examined in a set. ! 612: .PP ! 613: A timeout value may be specified if the selection ! 614: is not to last more than a predetermined period of time. If ! 615: the fields in \fItimeout\fP are set to 0, the selection takes ! 616: the form of a ! 617: \fIpoll\fP, returning immediately. If the last parameter is ! 618: a null pointer, the selection will block indefinitely*. ! 619: .FS ! 620: * To be more specific, a return takes place only when a ! 621: descriptor is selectable, or when a signal is received by ! 622: the caller, interrupting the system call. ! 623: .FE ! 624: \fISelect\fP normally returns the number of file descriptors selected; ! 625: if the \fIselect\fP call returns due to the timeout expiring, then ! 626: the value 0 is returned. ! 627: If the \fIselect\fP terminates because of an error or interruption, ! 628: a \-1 is returned with the error number in \fIerrno\fP, ! 629: and with the file descriptor masks unchanged. ! 630: .PP ! 631: Assuming a successful return, the three sets will ! 632: indicate which ! 633: file descriptors are ready to be read from, written to, or ! 634: have exceptional conditions pending. ! 635: The status of a file descriptor in a select mask may be ! 636: tested with the \fIFD_ISSET(fd, &mask)\fP macro, which ! 637: returns a non-zero value if \fIfd\fP is a member of the set ! 638: \fImask\fP, and 0 if it is not. ! 639: .PP ! 640: To determine if there are connections waiting ! 641: on a socket to be used with an \fIaccept\fP call, ! 642: \fIselect\fP can be used, followed by ! 643: a \fIFD_ISSET(fd, &mask)\fP macro to check for read ! 644: readiness on the appropriate socket. If \fIFD_ISSET\fP ! 645: returns a non-zero value, indicating permission to read, then a ! 646: connection is pending on the socket. ! 647: .PP ! 648: As an example, to read data from two sockets, \fIs1\fP and ! 649: \fIs2\fP as it is available from each and with a one-second ! 650: timeout, the following code ! 651: might be used: ! 652: .DS ! 653: #include <sys/time.h> ! 654: #include <sys/types.h> ! 655: ... ! 656: fd_set read_template; ! 657: struct timeval wait; ! 658: ... ! 659: for (;;) { ! 660: wait.tv_sec = 1; /* one second */ ! 661: wait.tv_usec = 0; ! 662: ! 663: FD_ZERO(&read_template); ! 664: ! 665: FD_SET(s1, &read_template); ! 666: FD_SET(s2, &read_template); ! 667: ! 668: nb = select(FD_SETSIZE, &read_template, (fd_set *) 0, (fd_set *) 0, &wait); ! 669: if (nb <= 0) { ! 670: \fIAn error occurred during the \fPselect\fI, or ! 671: the \fPselect\fI timed out.\fP ! 672: } ! 673: ! 674: if (FD_ISSET(s1, &read_template)) { ! 675: \fISocket #1 is ready to be read from.\fP ! 676: } ! 677: ! 678: if (FD_ISSET(s2, &read_template)) { ! 679: \fISocket #2 is ready to be read from.\fP ! 680: } ! 681: } ! 682: .DE ! 683: .PP ! 684: In 4.2, the arguments to \fIselect\fP were pointers to integers ! 685: instead of pointers to \fIfd_set\fPs. This type of call ! 686: will still work as long as the number of file descriptors ! 687: being examined is less than the number of bits in an ! 688: integer; however, the methods illustrated above should ! 689: be used in all current programs. ! 690: .PP ! 691: \fISelect\fP provides a synchronous multiplexing scheme. ! 692: Asynchronous notification of output completion, input availability, ! 693: and exceptional conditions is possible through use of the ! 694: SIGIO and SIGURG signals described in section 5.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.