![[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.