suitcase

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

io.html (25595B)


      1 <html>
      2 <body>
      3 <a href="../djb.html">D. J. Bernstein</a>
      4 <h1>The io library interface</h1>
      5 This page starts with
      6 <a href="#intro">an introduction to the io library</a>.
      7 It continues by describing the io functions for
      8 <a href="#create">creating descriptors</a>,
      9 <a href="#read">reading data</a>,
     10 <a href="#write">writing data</a>,
     11 <a href="#timeout">setting time limits on descriptors</a>,
     12 <a href="#wait">waiting for ready descriptors</a>,
     13 and
     14 <a href="#absorb">using descriptors created in other ways</a>.
     15 <h2><a name="intro">Introduction to the io library</a></h2>
     16 A UNIX program receives information from external sources
     17 through ``file descriptors.''
     18 Despite the word ``file,''
     19 these sources are not necessarily files on disk;
     20 a file descriptor might be a ``socket''
     21 receiving information from the <tt>cnn.com</tt> web server,
     22 for example,
     23 or a ``tty'' receiving information from the user's keyboard.
     24 <p>
     25 Similarly,
     26 a UNIX program provides information to external sinks
     27 through file descriptors.
     28 <p>
     29 The io (input/output) library manages file descriptors.
     30 It can
     31 <ul>
     32 <li>create descriptors talking to disk files, other programs, etc.;
     33 <li>receive (``read'') data from a descriptor,
     34 if the descriptor has data to provide;
     35 <li>provide (``write'') data to a descriptor,
     36 if the descriptor has space for data;
     37 <li>if no descriptors are ready for reading or writing,
     38 pause until the situation changes; and
     39 <li>identify the descriptors that are ready
     40 for reading or writing.
     41 </ul>
     42 The descriptors are identified by nonnegative integers (0, 1, 2, etc.)
     43 stored in <tt>int64</tt> variables.
     44 <p>
     45 For example, a program that wants to read a file from disk
     46 can use <tt>io_readfile()</tt> to create a descriptor for the file,
     47 <tt>io_tryread()</tt> repeatedly to receive information from the file,
     48 and then <tt>io_close()</tt> to eliminate the descriptor.
     49 <p>
     50 The following program uses the io library
     51 to copy standard input (descriptor 0)
     52 to standard output (descriptor 1),
     53 with a 65536-byte buffer in the middle:
     54 <pre>
     55      #include "io.h"
     56      
     57      char buf[65536];
     58      int64 readpos = 0;
     59      int64 writepos = 0;
     60      int flageof = 0;
     61      
     62      int main()
     63      {
     64        int64 r;
     65      
     66        if (!io_fd(0)) return 111;
     67        if (!io_fd(1)) return 111;
     68      
     69        for (;;) {
     70          if (flageof && writepos &gt;= readpos) return 0;
     71      
     72          if (!flageof && readpos &lt; sizeof buf) {
     73            r = io_tryread(0,buf + readpos,sizeof buf - readpos);
     74            if (r &lt;= -2) return 111; /* read error other than <tt>EAGAIN</tt> */
     75            if (r == 0) flageof = 1;
     76            if (r &gt; 0) readpos += r;
     77          }
     78      
     79          if (writepos &lt; readpos) {
     80            r = io_trywrite(1,buf + writepos,readpos - writepos);
     81            if (r &lt;= -2) return 111; /* write error other than <tt>EAGAIN</tt> */
     82            if (r &gt; 0) {
     83              writepos += r;
     84              if (writepos == readpos) readpos = writepos = 0;
     85 	     /* if writepos is big, might want to left-shift buffer here */
     86            }
     87          }
     88        }
     89      }
     90 </pre>
     91 <tt>io_fd</tt> makes file descriptors 0 and 1 visible to the io library.
     92 <tt>io_tryread(0,...)</tt>
     93 reads data if descriptor 0 is readable,
     94 and <tt>io_trywrite(1,...)</tt>
     95 writes data if descriptor 1 is writable.
     96 If the buffer is partially full,
     97 the program will check both descriptors,
     98 rather than delaying further reads until the current data is written.
     99 <p>
    100 If descriptor 0 is unreadable (or there is no space in the buffer for new data)
    101 and descriptor 1 is unwritable (or the buffer is empty),
    102 the above program busy-loops:
    103 it calls <tt>io_tryread()</tt> and <tt>io_trywrite()</tt> repeatedly,
    104 making no progress until the situation changes.
    105 Here is a smarter program
    106 that instead goes to sleep until the situation changes,
    107 leaving the CPU free for other programs:
    108 <pre>
    109      #include "io.h"
    110      
    111      char buf[65536];
    112      int64 readpos = 0;
    113      int64 writepos = 0;
    114      int flageof = 0;
    115      
    116      int main()
    117      {
    118        int64 r;
    119      
    120        if (!io_fd(0)) return 111;
    121        if (!io_fd(1)) return 111;
    122      
    123        for (;;) {
    124          if (flageof && writepos &gt;= readpos) return 0;
    125      
    126          if (!flageof && readpos &lt; sizeof buf) io_wantread(0);
    127          if (writepos &lt; readpos) io_wantwrite(1);
    128          io_wait();
    129          if (!flageof && readpos &lt; sizeof buf) io_dontwantread(0);
    130          if (writepos &lt; readpos) io_dontwantwrite(1);
    131      
    132          if (!flageof && readpos &lt; sizeof buf) {
    133            r = io_tryread(0,buf + readpos,sizeof buf - readpos);
    134            if (r &lt;= -2) return 111; /* read error other than <tt>EAGAIN</tt> */
    135            if (r == 0) flageof = 1;
    136            if (r &gt; 0) readpos += r;
    137          }
    138      
    139          if (writepos &lt; readpos) {
    140            r = io_trywrite(1,buf + writepos,readpos - writepos);
    141            if (r &lt;= -2) return 111; /* write error other than <tt>EAGAIN</tt> */
    142            if (r &gt; 0) {
    143              writepos += r;
    144              if (writepos == readpos) readpos = writepos = 0;
    145 	     /* if writepos is big, might want to left-shift buffer here */
    146            }
    147          }
    148        }
    149      }
    150 </pre>
    151 <tt>io_wait</tt> watches the descriptors previously indicated by
    152 <tt>io_wantread</tt> and <tt>io_wantwrite</tt>.
    153 <hr>
    154 <h2><a name="create">Creating descriptors</a></h2>
    155 <pre>
    156      #include "io.h"
    157      char <i>s</i>[];
    158      int64 <i>d</i>;
    159      io_readfile(&amp;<i>d</i>,<i>s</i>);
    160 </pre>
    161 <tt>io_readfile</tt> sets <tt><i>d</i></tt> to the number of a new descriptor
    162 reading from the disk file named <tt><i>s</i></tt>,
    163 and returns 1.
    164 <p>
    165 If something goes wrong,
    166 <tt>io_readfile</tt> sets <tt>errno</tt> to indicate the error,
    167 and returns 0;
    168 it does not create a new descriptor,
    169 and it does not touch <tt><i>d</i></tt>.
    170 <hr>
    171 <pre>
    172      #include "io.h"
    173      char <i>s</i>[];
    174      int64 <i>d</i>;
    175      io_createfile(&amp;<i>d</i>,<i>s</i>);
    176 </pre>
    177 <tt>io_createfile</tt> sets <tt><i>d</i></tt> to the number of a new descriptor
    178 writing to the disk file named <tt><i>s</i></tt>,
    179 and returns 1.
    180 If <tt><i>s</i></tt> already existed, it is truncated to length 0;
    181 otherwise, it is created, with mode 0600.
    182 <p>
    183 If something goes wrong,
    184 <tt>io_createfile</tt> sets <tt>errno</tt> to indicate the error,
    185 and returns 0;
    186 it does not create a new descriptor,
    187 and it does not touch <tt><i>d</i></tt>.
    188 (However, it may have truncated or created the file.)
    189 <hr>
    190 <pre>
    191      #include "io.h"
    192      int64 <i>d</i>[2];
    193      io_pipe(<i>d</i>);
    194 </pre>
    195 <tt>io_pipe</tt> creates a new UNIX ``pipe.''
    196 The pipe can receive data and provide data;
    197 any bytes written to the pipe
    198 can then be read from the pipe in the same order.
    199 <p>
    200 A pipe is typically stored in an 8192-byte memory buffer;
    201 the exact number depends on the UNIX kernel.
    202 Bytes are written to the end of the buffer
    203 and read from the beginning of the buffer.
    204 Once a byte has been read, it is eliminated from the buffer,
    205 making space for another byte to be written;
    206 readers cannot ``rewind'' a pipe to read old data.
    207 Once 8192 bytes have been written to the buffer,
    208 the pipe will not be ready for further writing
    209 until some of the bytes have been read.
    210 Once all the bytes written have been read,
    211 the pipe will not be ready for further reading
    212 until more bytes are written.
    213 <p>
    214 <tt>io_pipe</tt> sets <tt><i>d</i>[0]</tt>
    215 to the number of a new descriptor reading from the pipe,
    216 and sets <tt><i>d</i>[1]</tt>
    217 to the number of a new descriptor writing to the pipe.
    218 It then returns 1 to indicate success.
    219 If something goes wrong,
    220 <tt>io_pipe</tt> returns 0, setting <tt>errno</tt> to indicate the error;
    221 in this case
    222 it frees any memory that it allocated for the new pipe,
    223 and it leaves <tt><i>d</i></tt> alone.
    224 <hr>
    225 <pre>
    226      #include "io.h"
    227      int64 <i>d</i>;
    228      io_close(<i>d</i>);
    229 </pre>
    230 <tt>io_close</tt> eliminates the descriptor numbered <tt><i>d</i></tt>.
    231 This usually does not mean eliminating the object that the descriptor
    232 is talking to.
    233 (For example, if a descriptor writes to a named disk file,
    234 closing the descriptor will not remove the file;
    235 it simply removes one way of writing to the file.
    236 On the other hand, a pipe disappears as soon as no descriptors refer to it.)
    237 <p>
    238 <tt>io_close</tt> has no return value;
    239 it always succeeds in deallocating the memory used for the descriptor.
    240 If <tt><i>d</i></tt> is not the number of a descriptor,
    241 <tt>io_close</tt> has no effect.
    242 <hr>
    243 <h2><a name="read">Reading data</a></h2>
    244 <pre>
    245      #include "io.h"
    246      int64 <i>d</i>;
    247      char <i>buf</i>[];
    248      int64 <i>len</i>;
    249      int64 <i>result</i>;
    250      <i>result</i> = io_tryread(<i>d</i>,<i>buf</i>,<i>len</i>);
    251 </pre>
    252 <tt>io_tryread</tt> tries to read <tt><i>len</i></tt> bytes of data
    253 from descriptor <tt><i>d</i></tt>
    254 into
    255 <tt><i>buf</i>[0]</tt>,
    256 <tt><i>buf</i>[1]</tt>,
    257 ...,
    258 <tt><i>buf</i>[<i>len</i>-1]</tt>.
    259 (The effects are undefined if <tt><i>len</i></tt> is 0 or smaller.)
    260 There are several possible results:
    261 <ul>
    262 <li><tt>io_tryread</tt> returns an integer between 1 and <tt><i>len</i></tt>:
    263 This number of bytes was available for immediate reading;
    264 the bytes were read into the beginning of <tt><i>buf</i></tt>.
    265 Note that this number can be, and often is, smaller than <tt><i>len</i></tt>;
    266 you must not assume that <tt>io_tryread</tt>
    267 always succeeds in reading exactly <tt><i>len</i></tt> bytes.
    268 <li><tt>io_tryread</tt> returns 0:
    269 No bytes were read,
    270 because the descriptor is at end of file.
    271 For example,
    272 this descriptor has reached the end of a disk file,
    273 or is reading an empty pipe that has been closed by all writers.
    274 <li><tt>io_tryread</tt> returns -1,
    275 setting <tt>errno</tt> to <tt>EAGAIN</tt>:
    276 No bytes were read,
    277 because the descriptor is not ready.
    278 For example, the descriptor is reading an empty pipe
    279 that could still be written to.
    280 <li><tt>io_tryread</tt> returns -3,
    281 setting <tt>errno</tt> to something other than <tt>EAGAIN</tt>:
    282 No bytes were read,
    283 because the read attempt encountered a persistent error,
    284 such as a serious disk failure (<tt>EIO</tt>),
    285 an unreachable network (<tt>ENETUNREACH</tt>),
    286 or an invalid descriptor number (<tt>EBADF</tt>).
    287 </ul>
    288 <tt>io_tryread</tt> does not pause waiting for a descriptor that is not ready.
    289 If you want to pause, use <tt>io_waitread</tt> or <tt>io_wait</tt>.
    290 <hr>
    291 <pre>
    292      #include "io.h"
    293      int64 <i>d</i>;
    294      char <i>buf</i>[];
    295      int64 <i>len</i>;
    296      int64 <i>result</i>;
    297      <i>result</i> = io_waitread(<i>d</i>,<i>buf</i>,<i>len</i>);
    298 </pre>
    299 <tt>io_waitread</tt> tries to read <tt><i>len</i></tt> bytes of data
    300 from descriptor <tt><i>d</i></tt>
    301 into
    302 <tt><i>buf</i>[0]</tt>,
    303 <tt><i>buf</i>[1]</tt>,
    304 ...,
    305 <tt><i>buf</i>[<i>len</i>-1]</tt>,
    306 pausing if necessary so that the descriptor is ready.
    307 (The effects are undefined if <tt><i>len</i></tt> is 0 or smaller.)
    308 There are several possible results:
    309 <ul>
    310 <li><tt>io_waitread</tt> returns an integer between 1 and <tt><i>len</i></tt>:
    311 This number of bytes was available for reading;
    312 the bytes were read into the beginning of <tt><i>buf</i></tt>.
    313 Note that this number can be, and often is, smaller than <tt><i>len</i></tt>;
    314 you must not assume that <tt>io_waitread</tt>
    315 always succeeds in reading exactly <tt><i>len</i></tt> bytes.
    316 <li><tt>io_waitread</tt> returns 0:
    317 No bytes were read,
    318 because the descriptor is at end of file.
    319 For example,
    320 this descriptor has reached the end of a disk file,
    321 or is reading an empty pipe that has been closed by all writers.
    322 <li><tt>io_waitread</tt> returns -3,
    323 setting <tt>errno</tt> to something other than <tt>EAGAIN</tt>:
    324 No bytes were read,
    325 because the read attempt encountered a persistent error,
    326 such as a serious disk failure (<tt>EIO</tt>),
    327 an unreachable network (<tt>ENETUNREACH</tt>),
    328 or an invalid descriptor number (<tt>EBADF</tt>).
    329 </ul>
    330 <hr>
    331 <h2><a name="write">Writing data</a></h2>
    332 <pre>
    333      #include "io.h"
    334      int64 <i>d</i>;
    335      const char <i>buf</i>[];
    336      int64 <i>len</i>;
    337      int64 <i>result</i>;
    338      <i>result</i> = io_trywrite(<i>d</i>,<i>buf</i>,<i>len</i>);
    339 </pre>
    340 <tt>io_trywrite</tt> tries to write <tt><i>len</i></tt> bytes of data
    341 from
    342 <tt><i>buf</i>[0]</tt>,
    343 <tt><i>buf</i>[1]</tt>,
    344 ...,
    345 <tt><i>buf</i>[<i>len</i>-1]</tt>
    346 to descriptor <tt><i>d</i></tt>.
    347 (The effects are undefined if <tt><i>len</i></tt> is 0 or smaller.)
    348 There are several possible results:
    349 <ul>
    350 <li><tt>io_trywrite</tt> returns an integer between 1 and <tt><i>len</i></tt>:
    351 This number of bytes was immediately written
    352 from the beginning of <tt><i>buf</i></tt>.
    353 Note that this number can be, and often is, smaller than <tt><i>len</i></tt>;
    354 you must not assume that <tt>io_trywrite</tt>
    355 always succeeds in writing exactly <tt><i>len</i></tt> bytes.
    356 <li><tt>io_trywrite</tt> returns -1,
    357 setting <tt>errno</tt> to <tt>EAGAIN</tt>:
    358 No bytes were written,
    359 because the descriptor is not ready.
    360 For example, the descriptor is writing to a full pipe
    361 that could still be read.
    362 <li><tt>io_trywrite</tt> returns -3,
    363 setting <tt>errno</tt> to something other than <tt>EAGAIN</tt>:
    364 No bytes were written,
    365 because the write attempt encountered a persistent error,
    366 such as a serious disk failure (<tt>EIO</tt>),
    367 a pipe that can no longer be read (<tt>EPIPE</tt>),
    368 an unreachable network (<tt>ENETUNREACH</tt>),
    369 or an invalid descriptor number (<tt>EBADF</tt>).
    370 </ul>
    371 <tt>io_trywrite</tt> does not pause waiting for a descriptor that is not ready.
    372 If you want to pause, use <tt>io_waitwrite</tt> or <tt>io_wait</tt>.
    373 <p>
    374 Once upon a time,
    375 many UNIX programs neglected to check the success of their writes.
    376 They would often encounter <tt>EPIPE</tt>,
    377 and would blithely continue writing,
    378 rather than exiting with an appropriate exit code.
    379 The UNIX kernel developers decided to send a <tt>SIGPIPE</tt> signal,
    380 which terminates the process by default,
    381 along with returning <tt>EPIPE</tt>.
    382 This papers over the problem without fixing it:
    383 the same programs ignore other errors such as <tt>EIO</tt>.
    384 One hopes that the programs have been fixed by now;
    385 kernels nevertheless continue to generate the <tt>SIGPIPE</tt> signal.
    386 The first time <tt>io_trywrite</tt> or <tt>io_waitwrite</tt> is called,
    387 it arranges for <tt>SIGPIPE</tt> to be ignored.
    388 (Technically, for <tt>SIGPIPE</tt> to be caught by an empty signal handler,
    389 so this doesn't affect child processes.)
    390 Do not use <tt>SIGPIPE</tt> elsewhere in the program.
    391 <hr>
    392 <pre>
    393      #include "io.h"
    394      int64 <i>d</i>;
    395      const char <i>buf</i>[];
    396      int64 <i>len</i>;
    397      int64 <i>result</i>;
    398      <i>result</i> = io_waitwrite(<i>d</i>,<i>buf</i>,<i>len</i>);
    399 </pre>
    400 <tt>io_waitwrite</tt> tries to write <tt><i>len</i></tt> bytes of data
    401 from
    402 <tt><i>buf</i>[0]</tt>,
    403 <tt><i>buf</i>[1]</tt>,
    404 ...,
    405 <tt><i>buf</i>[<i>len</i>-1]</tt>
    406 to descriptor <tt><i>d</i></tt>,
    407 pausing (perhaps repeatedly) until the descriptor is ready.
    408 (The effects are undefined if <tt><i>len</i></tt> is 0 or smaller.)
    409 There are several possible results:
    410 <ul>
    411 <li><tt>io_waitwrite</tt> returns <tt><i>len</i></tt>:
    412 All the bytes were written.
    413 <li><tt>io_waitwrite</tt> returns something between <tt>0</tt>
    414 and <tt><i>len</i>-1</tt>,
    415 setting <tt>errno</tt> to something other than <tt>EAGAIN</tt>:
    416 After this number of bytes was written,
    417 no further bytes were written,
    418 because the write attempt encountered a persistent error,
    419 such as a serious disk failure (<tt>EIO</tt>),
    420 a pipe that can no longer be read (<tt>EPIPE</tt>),
    421 an unreachable network (<tt>ENETUNREACH</tt>),
    422 or an invalid descriptor number (<tt>EBADF</tt>).
    423 </ul>
    424 <hr>
    425 <h2><a name="timeout">Setting time limits on descriptors</a></h2>
    426 <pre>
    427      #include "io.h"
    428      int64 <i>d</i>;
    429      tai6464 <i>t</i>;
    430      io_timeout(<i>d</i>,<i>t</i>);
    431 </pre>
    432 The io library keeps track of an optional ``timeout'' for each descriptor.
    433 The timeout is a specific moment in time,
    434 stored in a <tt>tai6464</tt> variable.
    435 <p>
    436 <tt>io_timeout(<i>d</i>,<i>t</i>)</tt>
    437 sets the timeout for descriptor <tt><i>d</i></tt>
    438 to <tt><i>t</i></tt>.
    439 <p>
    440 <tt>io_timeout</tt> has no return value; it always succeeds.
    441 (Space to store the timeout was already allocated as part of the descriptor.)
    442 It has no effect
    443 if <tt><i>d</i></tt> is not the number of a descriptor.
    444 <hr>
    445 <pre>
    446      #include "io.h"
    447      int64 <i>d</i>;
    448      char <i>buf</i>[];
    449      int64 <i>len</i>;
    450      int64 <i>result</i>;
    451      <i>result</i> = io_tryreadtimeout(<i>d</i>,<i>buf</i>,<i>len</i>);
    452 </pre>
    453 <tt>io_tryreadtimeout</tt> is identical to <tt>io_tryread</tt>,
    454 with the following exception: if
    455 <ul>
    456 <li><tt>io_tryread</tt> returns -1 (the descriptor is not ready for reading),
    457 and
    458 <li>the descriptor has a timeout, and
    459 <li>the read attempt was after the descriptor's timeout,
    460 </ul>
    461 then <tt>io_tryreadtimeout</tt> instead returns -2,
    462 with <tt>errno</tt> set to <tt>ETIMEDOUT</tt>.
    463 <hr>
    464 <pre>
    465      #include "io.h"
    466      int64 <i>d</i>;
    467      const char <i>buf</i>[];
    468      int64 <i>len</i>;
    469      int64 <i>result</i>;
    470      <i>result</i> = io_trywritetimeout(<i>d</i>,<i>buf</i>,<i>len</i>);
    471 </pre>
    472 <tt>io_trywritetimeout</tt> is identical to <tt>io_trywrite</tt>,
    473 with the following exception: if
    474 <ul>
    475 <li><tt>io_trywrite</tt> returns -1 (the descriptor is not ready for writing),
    476 and
    477 <li>the descriptor has a timeout, and
    478 <li>the write attempt was after the descriptor's timeout,
    479 </ul>
    480 then <tt>io_trywritetimeout</tt> instead returns -2,
    481 with <tt>errno</tt> set to <tt>ETIMEDOUT</tt>.
    482 <hr>
    483 <h2><a name="wait">Waiting for ready descriptors</a></h2>
    484 <pre>
    485      #include "io.h"
    486      int64 <i>d</i>;
    487      io_wantread(<i>d</i>);
    488      io_wantwrite(<i>d</i>);
    489      io_dontwantread(<i>d</i>);
    490      io_dontwantwrite(<i>d</i>);
    491 </pre>
    492 For each descriptor,
    493 the io library keeps track of the number of parts of the current program
    494 interested in reading the descriptor.
    495 The number is incremented by <tt>io_wantread</tt>
    496 and decremented by <tt>io_dontwantread</tt>.
    497 (The effects are undefined if the number is decremented below 0.)
    498 The number is 0 when the descriptor is created.
    499 Closing a descriptor implicitly sets the number to 0.
    500 <p>
    501 Similar comments apply to <tt>io_wantwrite</tt> and <tt>io_dontwantwrite</tt>.
    502 <p>
    503 These functions have no return value; they always succeed.
    504 (Space to store the numbers was already allocated as part of the descriptor.)
    505 They have no effect if <tt><i>d</i></tt> is not the number of a descriptor.
    506 <p>
    507 You do not have to indicate interest in a descriptor
    508 before using the descriptor.
    509 The importance of <tt>io_wantread</tt> and <tt>io_wantwrite</tt>
    510 is their interaction with <tt>io_wait</tt>,
    511 <tt>io_waituntil</tt>, and <tt>io_check</tt>.
    512 <hr>
    513 <pre>
    514      #include "io.h"
    515      tai6464 <i>t</i>;
    516      io_wait();
    517      io_waituntil(<i>t</i>);
    518      io_check();
    519 </pre>
    520 <tt>io_wait()</tt>
    521 checks the descriptors that the program is interested in
    522 to see whether any of them are ready.
    523 If none of them are ready,
    524 <tt>io_wait()</tt>
    525 tries to pause until one of them is ready,
    526 so that it does not take time away
    527 from other programs running on the same computer.
    528 <p>
    529 <tt>io_wait</tt> pays attention to timeouts:
    530 if a descriptor reaches its timeout,
    531 and the program is interested in reading or writing that descriptor,
    532 <tt>io_wait</tt> will return promptly.
    533 <p>
    534 Under some circumstances,
    535 <tt>io_wait</tt> will return even though no interesting descriptors are ready.
    536 Do not assume that a descriptor is ready
    537 merely because <tt>io_wait</tt> has returned.
    538 <p>
    539 <tt>io_wait</tt> is <i>not</i> interrupted by the delivery of a signal.
    540 Programs that expect interruption are unreliable:
    541 they will block if the same signal
    542 is delivered a moment before <tt>io_wait</tt>.
    543 The correct way to handle signals is with the
    544 <a href="../docs/selfpipe.html">self-pipe trick</a>.
    545 <p>
    546 <tt>io_waituntil(<i>t</i>)</tt>
    547 is like <tt>io_wait()</tt>
    548 but does not wait (noticeably) past time <tt><i>t</i></tt>.
    549 <tt>io_check()</tt>
    550 is like <tt>io_wait()</tt>
    551 but does not wait at all;
    552 its importance is its interaction
    553 with <tt>io_canread</tt> and <tt>io_canwrite</tt>.
    554 <hr>
    555 <pre>
    556      #include "io.h"
    557      int64 <i>d</i>;
    558      <i>d</i> = io_canread();
    559      <i>d</i> = io_canwrite();
    560 </pre>
    561 <tt>io_wait</tt>
    562 saves a list of numbers of the descriptors
    563 that are ready to be read (or that have timed out)
    564 and that the program is interested in reading.
    565 <tt>io_canread</tt> returns the next descriptor number on the list,
    566 or -1 if there are no more descriptor numbers on the list.
    567 The list is reset by the next call to <tt>io_wait</tt>.
    568 <p>
    569 <tt>io_waituntil</tt> and <tt>io_check</tt>
    570 interact with <tt>io_canread</tt> in the same way that <tt>io_wait</tt> does.
    571 <tt>io_wait</tt>, <tt>io_waituntil</tt>, and <tt>io_check</tt>
    572 share one list of descriptors.
    573 <p>
    574 Do not assume that data can actually be read
    575 merely because <tt>io_canread</tt> has pointed to a descriptor.
    576 Data that was readable a moment ago
    577 could already have been read by another program.
    578 Even worse, the low-level UNIX routines
    579 used by <tt>io_wait</tt> could have failed to allocate memory;
    580 in this case, <tt>io_canread</tt> has no choice but to indicate
    581 that all descriptors are ready.
    582 You must check the results of <tt>io_tryread</tt>.
    583 <p>
    584 Similar comments apply to <tt>io_canwrite</tt>.
    585 <p>
    586 You do not need to use <tt>io_canread</tt> and <tt>io_canwrite</tt>.
    587 You can call <tt>io_wait</tt>,
    588 try <tt>io_tryread</tt> and <tt>io_trywrite</tt> for every descriptor,
    589 and repeat.
    590 However, 
    591 if you have thousands of descriptors of which only a few are ready,
    592 most of the effort of trying descriptors will be wasted.
    593 It is faster to focus on the descriptors indicated by <tt>io_canread</tt>
    594 and <tt>io_canwrite</tt>.
    595 <p>
    596 (The <tt>io_wait</tt> implementation and underlying UNIX kernel routines
    597 might have their own speed problems with thousands of descriptors,
    598 but this problem can be solved without any change in programs that use
    599 <tt>io_wait</tt>.)
    600 <hr>
    601 <h2><a name="absorb">Using descriptors created in other ways</a></h2>
    602 <pre>
    603      #include "io.h"
    604      int64 <i>d</i>;
    605      io_fd(<i>d</i>);
    606 </pre>
    607 There is a slight difference between the io library's view of descriptors
    608 and the UNIX view of descriptors:
    609 the io library has its own list of descriptors,
    610 and will not work with UNIX descriptors that aren't on the list.
    611 In particular:
    612 <ul>
    613 <li>When a program starts,
    614 it typically ``inherits'' (is started with) UNIX descriptors
    615 numbered 0 (stdin: standard input),
    616 1 (stdout: standard output), and
    617 2 (stderr: standard error).
    618 More sophisticated UNIX programming
    619 often involves more startup descriptors.
    620 In contrast, the io library starts with an empty list.
    621 The startup descriptors should be passed to <tt>io_fd</tt>.
    622 <li>Various low-level mechanisms outside the io library,
    623 such as the UNIX <tt>socket</tt> function,
    624 create UNIX descriptors that aren't on the io list.
    625 These descriptors should be passed to
    626 <tt>io_closeonexec</tt>, <tt>io_nonblock</tt>, and <tt>io_fd</tt>.
    627 </ul>
    628 The <tt>io_fd</tt> function
    629 adds the UNIX descriptor numbered <tt>d</tt> to the io list,
    630 and returns 1.
    631 If the descriptor is already on the list,
    632 <tt>io_fd</tt> returns 1 without doing anything.
    633 If something goes wrong (such as running out of memory),
    634 <tt>io_fd</tt> returns 0, setting <tt>errno</tt> to indicate the error.
    635 <hr>
    636 <pre>
    637      #include "io.h"
    638      int64 <i>d</i>;
    639      io_nonblock(<i>d</i>);
    640 </pre>
    641 <tt>io_nonblock</tt> puts UNIX descriptor <tt><i>d</i></tt>
    642 into ``non-blocking mode.''
    643 Calling <tt>io_nonblock(<i>d</i>)</tt>
    644 <i>before</i> <tt>io_fd(<i>d</i>)</tt> saves some time in
    645 <tt>io_tryread</tt> and <tt>io_trywrite</tt>.
    646 <p>
    647 Actually, current UNIX kernels
    648 do not support non-blocking <i>descriptors</i>;
    649 they support non-blocking <i>open files</i>.
    650 Furthermore, many programs will break if they encounter non-blocking mode.
    651 This means that
    652 you must not use <tt>io_nonblock</tt> for a descriptor
    653 inherited from another program.
    654 <p>
    655 <tt>io_nonblock</tt> has no return value; it always succeeds.
    656 If <tt><i>d</i></tt> is not the number of a UNIX descriptor,
    657 <tt>io_nonblock</tt> has no effect.
    658 <p>
    659 If <tt>io_fd</tt> is given a descriptor in blocking mode,
    660 <tt>io_tryread</tt> and <tt>io_trywrite</tt> go through
    661 the following contortions to avoid blocking:
    662 <ol>
    663 <li>Stop if <tt>poll</tt> says that the descriptor is not ready.
    664 Otherwise there's a good chance, but not a guarantee:
    665 even if <tt>poll</tt> says the descriptor is ready,
    666 the descriptor might not be ready a moment later.
    667 (Furthermore, <tt>poll</tt> can fail on some systems.)
    668 <li>Catch <tt>SIGALRM</tt>.
    669 <tt>SIGALRM</tt> must not be blocked,
    670 and must not be used elsewhere in the program.
    671 <li>Set an interval timer
    672 so that any blocking call will be interrupted by <tt>SIGALRM</tt>
    673 within 10 milliseconds.
    674 (Current UNIX kernels do not allow any shorter interval.)
    675 Of course, this may still mean a 10-millisecond delay.
    676 </ol>
    677 If <tt>io_fd</tt> is given a descriptor in non-blocking mode
    678 (or a descriptor for a regular disk file),
    679 <tt>io_tryread</tt> and <tt>io_trywrite</tt> avoid these contortions.
    680 <p>
    681 Future versions of the io library may use
    682 <a href="../unix/nonblock.html">kernel extensions</a>
    683 to avoid these contortions.
    684 <hr>
    685 <pre>
    686      #include "io.h"
    687      int64 <i>d</i>;
    688      io_closeonexec(<i>d</i>);
    689 </pre>
    690 <tt>io_closeonexec</tt> arranges for UNIX descriptor <tt><i>d</i></tt>
    691 to <i>not</i> be inherited by children of the current process.
    692 You should do this for any descriptor obtained from a UNIX function
    693 such as <tt>socket</tt> and <tt>open</tt>;
    694 it's an unfortunate historical accident that the UNIX functions don't do this.
    695 (If you want a descriptor to be inherited by a child process,
    696 arrange that when you create the child process.)
    697 <p>
    698 <tt>io_closeonexec</tt> has no return value; it always succeeds.
    699 If <tt><i>d</i></tt> is not the number of a UNIX descriptor,
    700 <tt>io_closeonexec</tt> has no effect.
    701 </body>
    702 </html>