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 >= readpos) return 0; 71 72 if (!flageof && readpos < sizeof buf) { 73 r = io_tryread(0,buf + readpos,sizeof buf - readpos); 74 if (r <= -2) return 111; /* read error other than <tt>EAGAIN</tt> */ 75 if (r == 0) flageof = 1; 76 if (r > 0) readpos += r; 77 } 78 79 if (writepos < readpos) { 80 r = io_trywrite(1,buf + writepos,readpos - writepos); 81 if (r <= -2) return 111; /* write error other than <tt>EAGAIN</tt> */ 82 if (r > 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 >= readpos) return 0; 125 126 if (!flageof && readpos < sizeof buf) io_wantread(0); 127 if (writepos < readpos) io_wantwrite(1); 128 io_wait(); 129 if (!flageof && readpos < sizeof buf) io_dontwantread(0); 130 if (writepos < readpos) io_dontwantwrite(1); 131 132 if (!flageof && readpos < sizeof buf) { 133 r = io_tryread(0,buf + readpos,sizeof buf - readpos); 134 if (r <= -2) return 111; /* read error other than <tt>EAGAIN</tt> */ 135 if (r == 0) flageof = 1; 136 if (r > 0) readpos += r; 137 } 138 139 if (writepos < readpos) { 140 r = io_trywrite(1,buf + writepos,readpos - writepos); 141 if (r <= -2) return 111; /* write error other than <tt>EAGAIN</tt> */ 142 if (r > 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(&<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(&<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>