3b786a2f21b739b3cd47addc6e671c8d0093db82
[kopensolaris-gnu/glibc.git] / manual / llio.texi
1 @node Low-Level I/O, File System Interface, I/O on Streams, Top
2 @c %MENU% Low-level, less portable I/O
3 @chapter Low-Level Input/Output
4
5 This chapter describes functions for performing low-level input/output
6 operations on file descriptors.  These functions include the primitives
7 for the higher-level I/O functions described in @ref{I/O on Streams}, as
8 well as functions for performing low-level control operations for which
9 there are no equivalents on streams.
10
11 Stream-level I/O is more flexible and usually more convenient;
12 therefore, programmers generally use the descriptor-level functions only
13 when necessary.  These are some of the usual reasons:
14
15 @itemize @bullet
16 @item
17 For reading binary files in large chunks.
18
19 @item
20 For reading an entire file into core before parsing it.
21
22 @item
23 To perform operations other than data transfer, which can only be done
24 with a descriptor.  (You can use @code{fileno} to get the descriptor
25 corresponding to a stream.)
26
27 @item
28 To pass descriptors to a child process.  (The child can create its own
29 stream to use a descriptor that it inherits, but cannot inherit a stream
30 directly.)
31 @end itemize
32
33 @menu
34 * Opening and Closing Files::           How to open and close file
35                                          descriptors.
36 * I/O Primitives::                      Reading and writing data.
37 * File Position Primitive::             Setting a descriptor's file
38                                          position.
39 * Descriptors and Streams::             Converting descriptor to stream
40                                          or vice-versa.
41 * Stream/Descriptor Precautions::       Precautions needed if you use both
42                                          descriptors and streams.
43 * Scatter-Gather::                      Fast I/O to discontinuous buffers.
44 * Memory-mapped I/O::                   Using files like memory.
45 * Waiting for I/O::                     How to check for input or output
46                                          on multiple file descriptors.
47 * Synchronizing I/O::                   Making sure all I/O actions completed.
48 * Asynchronous I/O::                    Perform I/O in parallel.
49 * Control Operations::                  Various other operations on file
50                                          descriptors.
51 * Duplicating Descriptors::             Fcntl commands for duplicating
52                                          file descriptors.
53 * Descriptor Flags::                    Fcntl commands for manipulating
54                                          flags associated with file
55                                          descriptors.
56 * File Status Flags::                   Fcntl commands for manipulating
57                                          flags associated with open files.
58 * File Locks::                          Fcntl commands for implementing
59                                          file locking.
60 * Interrupt Input::                     Getting an asynchronous signal when
61                                          input arrives.
62 * IOCTLs::                              Generic I/O Control operations.
63 @end menu
64
65
66 @node Opening and Closing Files
67 @section Opening and Closing Files
68
69 @cindex opening a file descriptor
70 @cindex closing a file descriptor
71 This section describes the primitives for opening and closing files
72 using file descriptors.  The @code{open} and @code{creat} functions are
73 declared in the header file @file{fcntl.h}, while @code{close} is
74 declared in @file{unistd.h}.
75 @pindex unistd.h
76 @pindex fcntl.h
77
78 @comment fcntl.h
79 @comment POSIX.1
80 @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
81 The @code{open} function creates and returns a new file descriptor
82 for the file named by @var{filename}.  Initially, the file position
83 indicator for the file is at the beginning of the file.  The argument
84 @var{mode} is used only when a file is created, but it doesn't hurt
85 to supply the argument in any case.
86
87 The @var{flags} argument controls how the file is to be opened.  This is
88 a bit mask; you create the value by the bitwise OR of the appropriate
89 parameters (using the @samp{|} operator in C).
90 @xref{File Status Flags}, for the parameters available.
91
92 The normal return value from @code{open} is a non-negative integer file
93 descriptor.  In the case of an error, a value of @math{-1} is returned
94 instead.  In addition to the usual file name errors (@pxref{File
95 Name Errors}), the following @code{errno} error conditions are defined
96 for this function:
97
98 @table @code
99 @item EACCES
100 The file exists but is not readable/writable as requested by the @var{flags}
101 argument, the file does not exist and the directory is unwritable so
102 it cannot be created.
103
104 @item EEXIST
105 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
106 exists.
107
108 @item EINTR
109 The @code{open} operation was interrupted by a signal.
110 @xref{Interrupted Primitives}.
111
112 @item EISDIR
113 The @var{flags} argument specified write access, and the file is a directory.
114
115 @item EMFILE
116 The process has too many files open.
117 The maximum number of file descriptors is controlled by the
118 @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
119
120 @item ENFILE
121 The entire system, or perhaps the file system which contains the
122 directory, cannot support any additional open files at the moment.
123 (This problem cannot happen on the GNU system.)
124
125 @item ENOENT
126 The named file does not exist, and @code{O_CREAT} is not specified.
127
128 @item ENOSPC
129 The directory or file system that would contain the new file cannot be
130 extended, because there is no disk space left.
131
132 @item ENXIO
133 @code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
134 argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
135 FIFOs}), and no process has the file open for reading.
136
137 @item EROFS
138 The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
139 @code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
140 or @code{O_CREAT} is set and the file does not already exist.
141 @end table
142
143 @c !!! umask
144
145 If on a 32 bit machine the sources are translated with
146 @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
147 descriptor opened in the large file mode which enables the file handling
148 functions to use files up to @math{2^63} bytes in size and offset from
149 @math{-2^63} to @math{2^63}.  This happens transparently for the user
150 since all of the lowlevel file handling functions are equally replaced.
151
152 This function is a cancellation point in multi-threaded programs.  This
153 is a problem if the thread allocates some resources (like memory, file
154 descriptors, semaphores or whatever) at the time @code{open} is
155 called.  If the thread gets canceled these resources stay allocated
156 until the program ends.  To avoid this calls to @code{open} should be
157 protected using cancellation handlers.
158 @c ref pthread_cleanup_push / pthread_cleanup_pop
159
160 The @code{open} function is the underlying primitive for the @code{fopen}
161 and @code{freopen} functions, that create streams.
162 @end deftypefun
163
164 @comment fcntl.h
165 @comment Unix98
166 @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
167 This function is similar to @code{open}.  It returns a file descriptor
168 which can be used to access the file named by @var{filename}.  The only
169 difference is that on 32 bit systems the file is opened in the
170 large file mode.  I.e., file length and file offsets can exceed 31 bits.
171
172 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
173 function is actually available under the name @code{open}.  I.e., the
174 new, extended API using 64 bit file sizes and offsets transparently
175 replaces the old API.
176 @end deftypefun
177
178 @comment fcntl.h
179 @comment POSIX.1
180 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
181 This function is obsolete.  The call:
182
183 @smallexample
184 creat (@var{filename}, @var{mode})
185 @end smallexample
186
187 @noindent
188 is equivalent to:
189
190 @smallexample
191 open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
192 @end smallexample
193
194 If on a 32 bit machine the sources are translated with
195 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
196 descriptor opened in the large file mode which enables the file handling
197 functions to use files up to @math{2^63} in size and offset from
198 @math{-2^63} to @math{2^63}.  This happens transparently for the user
199 since all of the lowlevel file handling functions are equally replaced.
200 @end deftypefn
201
202 @comment fcntl.h
203 @comment Unix98
204 @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
205 This function is similar to @code{creat}.  It returns a file descriptor
206 which can be used to access the file named by @var{filename}.  The only
207 the difference is that on 32 bit systems the file is opened in the
208 large file mode.  I.e., file length and file offsets can exceed 31 bits.
209
210 To use this file descriptor one must not use the normal operations but
211 instead the counterparts named @code{*64}, e.g., @code{read64}.
212
213 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
214 function is actually available under the name @code{open}.  I.e., the
215 new, extended API using 64 bit file sizes and offsets transparently
216 replaces the old API.
217 @end deftypefn
218
219 @comment unistd.h
220 @comment POSIX.1
221 @deftypefun int close (int @var{filedes})
222 The function @code{close} closes the file descriptor @var{filedes}.
223 Closing a file has the following consequences:
224
225 @itemize @bullet
226 @item
227 The file descriptor is deallocated.
228
229 @item
230 Any record locks owned by the process on the file are unlocked.
231
232 @item
233 When all file descriptors associated with a pipe or FIFO have been closed,
234 any unread data is discarded.
235 @end itemize
236
237 This function is a cancellation point in multi-threaded programs.  This
238 is a problem if the thread allocates some resources (like memory, file
239 descriptors, semaphores or whatever) at the time @code{close} is
240 called.  If the thread gets canceled these resources stay allocated
241 until the program ends.  To avoid this, calls to @code{close} should be
242 protected using cancellation handlers.
243 @c ref pthread_cleanup_push / pthread_cleanup_pop
244
245 The normal return value from @code{close} is @math{0}; a value of @math{-1}
246 is returned in case of failure.  The following @code{errno} error
247 conditions are defined for this function:
248
249 @table @code
250 @item EBADF
251 The @var{filedes} argument is not a valid file descriptor.
252
253 @item EINTR
254 The @code{close} call was interrupted by a signal.
255 @xref{Interrupted Primitives}.
256 Here is an example of how to handle @code{EINTR} properly:
257
258 @smallexample
259 TEMP_FAILURE_RETRY (close (desc));
260 @end smallexample
261
262 @item ENOSPC
263 @itemx EIO
264 @itemx EDQUOT
265 When the file is accessed by NFS, these errors from @code{write} can sometimes
266 not be detected until @code{close}.  @xref{I/O Primitives}, for details
267 on their meaning.
268 @end table
269
270 Please note that there is @emph{no} separate @code{close64} function.
271 This is not necessary since this function does not determine nor depend
272 on the mode of the file.  The kernel which performs the @code{close}
273 operation knows which mode the descriptor is used for and can handle
274 this situation.
275 @end deftypefun
276
277 To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
278 of trying to close its underlying file descriptor with @code{close}.
279 This flushes any buffered output and updates the stream object to
280 indicate that it is closed.
281
282 @node I/O Primitives
283 @section Input and Output Primitives
284
285 This section describes the functions for performing primitive input and
286 output operations on file descriptors: @code{read}, @code{write}, and
287 @code{lseek}.  These functions are declared in the header file
288 @file{unistd.h}.
289 @pindex unistd.h
290
291 @comment unistd.h
292 @comment POSIX.1
293 @deftp {Data Type} ssize_t
294 This data type is used to represent the sizes of blocks that can be
295 read or written in a single operation.  It is similar to @code{size_t},
296 but must be a signed type.
297 @end deftp
298
299 @cindex reading from a file descriptor
300 @comment unistd.h
301 @comment POSIX.1
302 @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
303 The @code{read} function reads up to @var{size} bytes from the file
304 with descriptor @var{filedes}, storing the results in the @var{buffer}.
305 (This is not necessarily a character string, and no terminating null
306 character is added.)
307
308 @cindex end-of-file, on a file descriptor
309 The return value is the number of bytes actually read.  This might be
310 less than @var{size}; for example, if there aren't that many bytes left
311 in the file or if there aren't that many bytes immediately available.
312 The exact behavior depends on what kind of file it is.  Note that
313 reading less than @var{size} bytes is not an error.
314
315 A value of zero indicates end-of-file (except if the value of the
316 @var{size} argument is also zero).  This is not considered an error.
317 If you keep calling @code{read} while at end-of-file, it will keep
318 returning zero and doing nothing else.
319
320 If @code{read} returns at least one character, there is no way you can
321 tell whether end-of-file was reached.  But if you did reach the end, the
322 next read will return zero.
323
324 In case of an error, @code{read} returns @math{-1}.  The following
325 @code{errno} error conditions are defined for this function:
326
327 @table @code
328 @item EAGAIN
329 Normally, when no input is immediately available, @code{read} waits for
330 some input.  But if the @code{O_NONBLOCK} flag is set for the file
331 (@pxref{File Status Flags}), @code{read} returns immediately without
332 reading any data, and reports this error.
333
334 @strong{Compatibility Note:} Most versions of BSD Unix use a different
335 error code for this: @code{EWOULDBLOCK}.  In the GNU library,
336 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
337 which name you use.
338
339 On some systems, reading a large amount of data from a character special
340 file can also fail with @code{EAGAIN} if the kernel cannot find enough
341 physical memory to lock down the user's pages.  This is limited to
342 devices that transfer with direct memory access into the user's memory,
343 which means it does not include terminals, since they always use
344 separate buffers inside the kernel.  This problem never happens in the
345 GNU system.
346
347 Any condition that could result in @code{EAGAIN} can instead result in a
348 successful @code{read} which returns fewer bytes than requested.
349 Calling @code{read} again immediately would result in @code{EAGAIN}.
350
351 @item EBADF
352 The @var{filedes} argument is not a valid file descriptor,
353 or is not open for reading.
354
355 @item EINTR
356 @code{read} was interrupted by a signal while it was waiting for input.
357 @xref{Interrupted Primitives}.  A signal will not necessary cause
358 @code{read} to return @code{EINTR}; it may instead result in a
359 successful @code{read} which returns fewer bytes than requested.
360
361 @item EIO
362 For many devices, and for disk files, this error code indicates
363 a hardware error.
364
365 @code{EIO} also occurs when a background process tries to read from the
366 controlling terminal, and the normal action of stopping the process by
367 sending it a @code{SIGTTIN} signal isn't working.  This might happen if
368 the signal is being blocked or ignored, or because the process group is
369 orphaned.  @xref{Job Control}, for more information about job control,
370 and @ref{Signal Handling}, for information about signals.
371 @end table
372
373 Please note that there is no function named @code{read64}.  This is not
374 necessary since this function does not directly modify or handle the
375 possibly wide file offset.  Since the kernel handles this state
376 internally, the @code{read} function can be used for all cases.
377
378 This function is a cancellation point in multi-threaded programs.  This
379 is a problem if the thread allocates some resources (like memory, file
380 descriptors, semaphores or whatever) at the time @code{read} is
381 called.  If the thread gets canceled these resources stay allocated
382 until the program ends.  To avoid this, calls to @code{read} should be
383 protected using cancellation handlers.
384 @c ref pthread_cleanup_push / pthread_cleanup_pop
385
386 The @code{read} function is the underlying primitive for all of the
387 functions that read from streams, such as @code{fgetc}.
388 @end deftypefun
389
390 @comment unistd.h
391 @comment Unix98
392 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
393 The @code{pread} function is similar to the @code{read} function.  The
394 first three arguments are identical, and the return values and error
395 codes also correspond.
396
397 The difference is the fourth argument and its handling.  The data block
398 is not read from the current position of the file descriptor
399 @code{filedes}.  Instead the data is read from the file starting at
400 position @var{offset}.  The position of the file descriptor itself is
401 not affected by the operation.  The value is the same as before the call.
402
403 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
404 @code{pread} function is in fact @code{pread64} and the type
405 @code{off_t} has 64 bits, which makes it possible to handle files up to
406 @math{2^63} bytes in length.
407
408 The return value of @code{pread} describes the number of bytes read.
409 In the error case it returns @math{-1} like @code{read} does and the
410 error codes are also the same, with these additions:
411
412 @table @code
413 @item EINVAL
414 The value given for @var{offset} is negative and therefore illegal.
415
416 @item ESPIPE
417 The file descriptor @var{filedes} is associate with a pipe or a FIFO and
418 this device does not allow positioning of the file pointer.
419 @end table
420
421 The function is an extension defined in the Unix Single Specification
422 version 2.
423 @end deftypefun
424
425 @comment unistd.h
426 @comment Unix98
427 @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
428 This function is similar to the @code{pread} function.  The difference
429 is that the @var{offset} parameter is of type @code{off64_t} instead of
430 @code{off_t} which makes it possible on 32 bit machines to address
431 files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
432 file descriptor @code{filedes} must be opened using @code{open64} since
433 otherwise the large offsets possible with @code{off64_t} will lead to
434 errors with a descriptor in small file mode.
435
436 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
437 32 bit machine this function is actually available under the name
438 @code{pread} and so transparently replaces the 32 bit interface.
439 @end deftypefun
440
441 @cindex writing to a file descriptor
442 @comment unistd.h
443 @comment POSIX.1
444 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
445 The @code{write} function writes up to @var{size} bytes from
446 @var{buffer} to the file with descriptor @var{filedes}.  The data in
447 @var{buffer} is not necessarily a character string and a null character is
448 output like any other character.
449
450 The return value is the number of bytes actually written.  This may be
451 @var{size}, but can always be smaller.  Your program should always call
452 @code{write} in a loop, iterating until all the data is written.
453
454 Once @code{write} returns, the data is enqueued to be written and can be
455 read back right away, but it is not necessarily written out to permanent
456 storage immediately.  You can use @code{fsync} when you need to be sure
457 your data has been permanently stored before continuing.  (It is more
458 efficient for the system to batch up consecutive writes and do them all
459 at once when convenient.  Normally they will always be written to disk
460 within a minute or less.)  Modern systems provide another function
461 @code{fdatasync} which guarantees integrity only for the file data and
462 is therefore faster.
463 @c !!! xref fsync, fdatasync
464 You can use the @code{O_FSYNC} open mode to make @code{write} always
465 store the data to disk before returning; @pxref{Operating Modes}.
466
467 In the case of an error, @code{write} returns @math{-1}.  The following
468 @code{errno} error conditions are defined for this function:
469
470 @table @code
471 @item EAGAIN
472 Normally, @code{write} blocks until the write operation is complete.
473 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
474 Operations}), it returns immediately without writing any data and
475 reports this error.  An example of a situation that might cause the
476 process to block on output is writing to a terminal device that supports
477 flow control, where output has been suspended by receipt of a STOP
478 character.
479
480 @strong{Compatibility Note:} Most versions of BSD Unix use a different
481 error code for this: @code{EWOULDBLOCK}.  In the GNU library,
482 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
483 which name you use.
484
485 On some systems, writing a large amount of data from a character special
486 file can also fail with @code{EAGAIN} if the kernel cannot find enough
487 physical memory to lock down the user's pages.  This is limited to
488 devices that transfer with direct memory access into the user's memory,
489 which means it does not include terminals, since they always use
490 separate buffers inside the kernel.  This problem does not arise in the
491 GNU system.
492
493 @item EBADF
494 The @var{filedes} argument is not a valid file descriptor,
495 or is not open for writing.
496
497 @item EFBIG
498 The size of the file would become larger than the implementation can support.
499
500 @item EINTR
501 The @code{write} operation was interrupted by a signal while it was
502 blocked waiting for completion.  A signal will not necessarily cause
503 @code{write} to return @code{EINTR}; it may instead result in a
504 successful @code{write} which writes fewer bytes than requested.
505 @xref{Interrupted Primitives}.
506
507 @item EIO
508 For many devices, and for disk files, this error code indicates
509 a hardware error.
510
511 @item ENOSPC
512 The device containing the file is full.
513
514 @item EPIPE
515 This error is returned when you try to write to a pipe or FIFO that
516 isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
517 signal is also sent to the process; see @ref{Signal Handling}.
518 @end table
519
520 Unless you have arranged to prevent @code{EINTR} failures, you should
521 check @code{errno} after each failing call to @code{write}, and if the
522 error was @code{EINTR}, you should simply repeat the call.
523 @xref{Interrupted Primitives}.  The easy way to do this is with the
524 macro @code{TEMP_FAILURE_RETRY}, as follows:
525
526 @smallexample
527 nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
528 @end smallexample
529
530 Please note that there is no function named @code{write64}.  This is not
531 necessary since this function does not directly modify or handle the
532 possibly wide file offset.  Since the kernel handles this state
533 internally the @code{write} function can be used for all cases.
534
535 This function is a cancellation point in multi-threaded programs.  This
536 is a problem if the thread allocates some resources (like memory, file
537 descriptors, semaphores or whatever) at the time @code{write} is
538 called.  If the thread gets canceled these resources stay allocated
539 until the program ends.  To avoid this, calls to @code{write} should be
540 protected using cancellation handlers.
541 @c ref pthread_cleanup_push / pthread_cleanup_pop
542
543 The @code{write} function is the underlying primitive for all of the
544 functions that write to streams, such as @code{fputc}.
545 @end deftypefun
546
547 @comment unistd.h
548 @comment Unix98
549 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
550 The @code{pwrite} function is similar to the @code{write} function.  The
551 first three arguments are identical, and the return values and error codes
552 also correspond.
553
554 The difference is the fourth argument and its handling.  The data block
555 is not written to the current position of the file descriptor
556 @code{filedes}.  Instead the data is written to the file starting at
557 position @var{offset}.  The position of the file descriptor itself is
558 not affected by the operation.  The value is the same as before the call.
559
560 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
561 @code{pwrite} function is in fact @code{pwrite64} and the type
562 @code{off_t} has 64 bits, which makes it possible to handle files up to
563 @math{2^63} bytes in length.
564
565 The return value of @code{pwrite} describes the number of written bytes.
566 In the error case it returns @math{-1} like @code{write} does and the
567 error codes are also the same, with these additions:
568
569 @table @code
570 @item EINVAL
571 The value given for @var{offset} is negative and therefore illegal.
572
573 @item ESPIPE
574 The file descriptor @var{filedes} is associated with a pipe or a FIFO and
575 this device does not allow positioning of the file pointer.
576 @end table
577
578 The function is an extension defined in the Unix Single Specification
579 version 2.
580 @end deftypefun
581
582 @comment unistd.h
583 @comment Unix98
584 @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
585 This function is similar to the @code{pwrite} function.  The difference
586 is that the @var{offset} parameter is of type @code{off64_t} instead of
587 @code{off_t} which makes it possible on 32 bit machines to address
588 files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
589 file descriptor @code{filedes} must be opened using @code{open64} since
590 otherwise the large offsets possible with @code{off64_t} will lead to
591 errors with a descriptor in small file mode.
592
593 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
594 32 bit machine this function is actually available under the name
595 @code{pwrite} and so transparently replaces the 32 bit interface.
596 @end deftypefun
597
598
599 @node File Position Primitive
600 @section Setting the File Position of a Descriptor
601
602 Just as you can set the file position of a stream with @code{fseek}, you
603 can set the file position of a descriptor with @code{lseek}.  This
604 specifies the position in the file for the next @code{read} or
605 @code{write} operation.  @xref{File Positioning}, for more information
606 on the file position and what it means.
607
608 To read the current file position value from a descriptor, use
609 @code{lseek (@var{desc}, 0, SEEK_CUR)}.
610
611 @cindex file positioning on a file descriptor
612 @cindex positioning a file descriptor
613 @cindex seeking on a file descriptor
614 @comment unistd.h
615 @comment POSIX.1
616 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
617 The @code{lseek} function is used to change the file position of the
618 file with descriptor @var{filedes}.
619
620 The @var{whence} argument specifies how the @var{offset} should be
621 interpreted, in the same way as for the @code{fseek} function, and it must
622 be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
623 @code{SEEK_END}.
624
625 @table @code
626 @item SEEK_SET
627 Specifies that @var{whence} is a count of characters from the beginning
628 of the file.
629
630 @item SEEK_CUR
631 Specifies that @var{whence} is a count of characters from the current
632 file position.  This count may be positive or negative.
633
634 @item SEEK_END
635 Specifies that @var{whence} is a count of characters from the end of
636 the file.  A negative count specifies a position within the current
637 extent of the file; a positive count specifies a position past the
638 current end.  If you set the position past the current end, and
639 actually write data, you will extend the file with zeros up to that
640 position.
641 @end table
642
643 The return value from @code{lseek} is normally the resulting file
644 position, measured in bytes from the beginning of the file.
645 You can use this feature together with @code{SEEK_CUR} to read the
646 current file position.
647
648 If you want to append to the file, setting the file position to the
649 current end of file with @code{SEEK_END} is not sufficient.  Another
650 process may write more data after you seek but before you write,
651 extending the file so the position you write onto clobbers their data.
652 Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
653
654 You can set the file position past the current end of the file.  This
655 does not by itself make the file longer; @code{lseek} never changes the
656 file.  But subsequent output at that position will extend the file.
657 Characters between the previous end of file and the new position are
658 filled with zeros.  Extending the file in this way can create a
659 ``hole'': the blocks of zeros are not actually allocated on disk, so the
660 file takes up less space than it appears to; it is then called a
661 ``sparse file''.
662 @cindex sparse files
663 @cindex holes in files
664
665 If the file position cannot be changed, or the operation is in some way
666 invalid, @code{lseek} returns a value of @math{-1}.  The following
667 @code{errno} error conditions are defined for this function:
668
669 @table @code
670 @item EBADF
671 The @var{filedes} is not a valid file descriptor.
672
673 @item EINVAL
674 The @var{whence} argument value is not valid, or the resulting
675 file offset is not valid.  A file offset is invalid.
676
677 @item ESPIPE
678 The @var{filedes} corresponds to an object that cannot be positioned,
679 such as a pipe, FIFO or terminal device.  (POSIX.1 specifies this error
680 only for pipes and FIFOs, but in the GNU system, you always get
681 @code{ESPIPE} if the object is not seekable.)
682 @end table
683
684 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
685 @code{lseek} function is in fact @code{lseek64} and the type
686 @code{off_t} has 64 bits which makes it possible to handle files up to
687 @math{2^63} bytes in length.
688
689 This function is a cancellation point in multi-threaded programs.  This
690 is a problem if the thread allocates some resources (like memory, file
691 descriptors, semaphores or whatever) at the time @code{lseek} is
692 called.  If the thread gets canceled these resources stay allocated
693 until the program ends.  To avoid this calls to @code{lseek} should be
694 protected using cancellation handlers.
695 @c ref pthread_cleanup_push / pthread_cleanup_pop
696
697 The @code{lseek} function is the underlying primitive for the
698 @code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
699 @code{rewind} functions, which operate on streams instead of file
700 descriptors.
701 @end deftypefun
702
703 @comment unistd.h
704 @comment Unix98
705 @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
706 This function is similar to the @code{lseek} function.  The difference
707 is that the @var{offset} parameter is of type @code{off64_t} instead of
708 @code{off_t} which makes it possible on 32 bit machines to address
709 files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
710 file descriptor @code{filedes} must be opened using @code{open64} since
711 otherwise the large offsets possible with @code{off64_t} will lead to
712 errors with a descriptor in small file mode.
713
714 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
715 32 bits machine this function is actually available under the name
716 @code{lseek} and so transparently replaces the 32 bit interface.
717 @end deftypefun
718
719 You can have multiple descriptors for the same file if you open the file
720 more than once, or if you duplicate a descriptor with @code{dup}.
721 Descriptors that come from separate calls to @code{open} have independent
722 file positions; using @code{lseek} on one descriptor has no effect on the
723 other.  For example,
724
725 @smallexample
726 @group
727 @{
728   int d1, d2;
729   char buf[4];
730   d1 = open ("foo", O_RDONLY);
731   d2 = open ("foo", O_RDONLY);
732   lseek (d1, 1024, SEEK_SET);
733   read (d2, buf, 4);
734 @}
735 @end group
736 @end smallexample
737
738 @noindent
739 will read the first four characters of the file @file{foo}.  (The
740 error-checking code necessary for a real program has been omitted here
741 for brevity.)
742
743 By contrast, descriptors made by duplication share a common file
744 position with the original descriptor that was duplicated.  Anything
745 which alters the file position of one of the duplicates, including
746 reading or writing data, affects all of them alike.  Thus, for example,
747
748 @smallexample
749 @{
750   int d1, d2, d3;
751   char buf1[4], buf2[4];
752   d1 = open ("foo", O_RDONLY);
753   d2 = dup (d1);
754   d3 = dup (d2);
755   lseek (d3, 1024, SEEK_SET);
756   read (d1, buf1, 4);
757   read (d2, buf2, 4);
758 @}
759 @end smallexample
760
761 @noindent
762 will read four characters starting with the 1024'th character of
763 @file{foo}, and then four more characters starting with the 1028'th
764 character.
765
766 @comment sys/types.h
767 @comment POSIX.1
768 @deftp {Data Type} off_t
769 This is an arithmetic data type used to represent file sizes.
770 In the GNU system, this is equivalent to @code{fpos_t} or @code{long int}.
771
772 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
773 is transparently replaced by @code{off64_t}.
774 @end deftp
775
776 @comment sys/types.h
777 @comment Unix98
778 @deftp {Data Type} off64_t
779 This type is used similar to @code{off_t}.  The difference is that even
780 on 32 bit machines, where the @code{off_t} type would have 32 bits,
781 @code{off64_t} has 64 bits and so is able to address files up to
782 @math{2^63} bytes in length.
783
784 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
785 available under the name @code{off_t}.
786 @end deftp
787
788 These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
789 of compatibility with older BSD systems.  They are defined in two
790 different header files: @file{fcntl.h} and @file{sys/file.h}.
791
792 @table @code
793 @item L_SET
794 An alias for @code{SEEK_SET}.
795
796 @item L_INCR
797 An alias for @code{SEEK_CUR}.
798
799 @item L_XTND
800 An alias for @code{SEEK_END}.
801 @end table
802
803 @node Descriptors and Streams
804 @section Descriptors and Streams
805 @cindex streams, and file descriptors
806 @cindex converting file descriptor to stream
807 @cindex extracting file descriptor from stream
808
809 Given an open file descriptor, you can create a stream for it with the
810 @code{fdopen} function.  You can get the underlying file descriptor for
811 an existing stream with the @code{fileno} function.  These functions are
812 declared in the header file @file{stdio.h}.
813 @pindex stdio.h
814
815 @comment stdio.h
816 @comment POSIX.1
817 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
818 The @code{fdopen} function returns a new stream for the file descriptor
819 @var{filedes}.
820
821 The @var{opentype} argument is interpreted in the same way as for the
822 @code{fopen} function (@pxref{Opening Streams}), except that
823 the @samp{b} option is not permitted; this is because GNU makes no
824 distinction between text and binary files.  Also, @code{"w"} and
825 @code{"w+"} do not cause truncation of the file; these have an effect only
826 when opening a file, and in this case the file has already been opened.
827 You must make sure that the @var{opentype} argument matches the actual
828 mode of the open file descriptor.
829
830 The return value is the new stream.  If the stream cannot be created
831 (for example, if the modes for the file indicated by the file descriptor
832 do not permit the access specified by the @var{opentype} argument), a
833 null pointer is returned instead.
834
835 In some other systems, @code{fdopen} may fail to detect that the modes
836 for file descriptor do not permit the access specified by
837 @code{opentype}.  The GNU C library always checks for this.
838 @end deftypefun
839
840 For an example showing the use of the @code{fdopen} function,
841 see @ref{Creating a Pipe}.
842
843 @comment stdio.h
844 @comment POSIX.1
845 @deftypefun int fileno (FILE *@var{stream})
846 This function returns the file descriptor associated with the stream
847 @var{stream}.  If an error is detected (for example, if the @var{stream}
848 is not valid) or if @var{stream} does not do I/O to a file,
849 @code{fileno} returns @math{-1}.
850 @end deftypefun
851
852 @comment stdio.h
853 @comment GNU
854 @deftypefun int fileno_unlocked (FILE *@var{stream})
855 The @code{fileno_unlocked} function is equivalent to the @code{fileno}
856 function except that it does not implicitly lock the stream if the state
857 is @code{FSETLOCKING_INTERNAL}.
858
859 This function is a GNU extension.
860 @end deftypefun
861
862 @cindex standard file descriptors
863 @cindex file descriptors, standard
864 There are also symbolic constants defined in @file{unistd.h} for the
865 file descriptors belonging to the standard streams @code{stdin},
866 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
867 @pindex unistd.h
868
869 @comment unistd.h
870 @comment POSIX.1
871 @table @code
872 @item STDIN_FILENO
873 @vindex STDIN_FILENO
874 This macro has value @code{0}, which is the file descriptor for
875 standard input.
876 @cindex standard input file descriptor
877
878 @comment unistd.h
879 @comment POSIX.1
880 @item STDOUT_FILENO
881 @vindex STDOUT_FILENO
882 This macro has value @code{1}, which is the file descriptor for
883 standard output.
884 @cindex standard output file descriptor
885
886 @comment unistd.h
887 @comment POSIX.1
888 @item STDERR_FILENO
889 @vindex STDERR_FILENO
890 This macro has value @code{2}, which is the file descriptor for
891 standard error output.
892 @end table
893 @cindex standard error file descriptor
894
895 @node Stream/Descriptor Precautions
896 @section Dangers of Mixing Streams and Descriptors
897 @cindex channels
898 @cindex streams and descriptors
899 @cindex descriptors and streams
900 @cindex mixing descriptors and streams
901
902 You can have multiple file descriptors and streams (let's call both
903 streams and descriptors ``channels'' for short) connected to the same
904 file, but you must take care to avoid confusion between channels.  There
905 are two cases to consider: @dfn{linked} channels that share a single
906 file position value, and @dfn{independent} channels that have their own
907 file positions.
908
909 It's best to use just one channel in your program for actual data
910 transfer to any given file, except when all the access is for input.
911 For example, if you open a pipe (something you can only do at the file
912 descriptor level), either do all I/O with the descriptor, or construct a
913 stream from the descriptor with @code{fdopen} and then do all I/O with
914 the stream.
915
916 @menu
917 * Linked Channels::        Dealing with channels sharing a file position.
918 * Independent Channels::   Dealing with separately opened, unlinked channels.
919 * Cleaning Streams::       Cleaning a stream makes it safe to use
920                             another channel.
921 @end menu
922
923 @node Linked Channels
924 @subsection Linked Channels
925 @cindex linked channels
926
927 Channels that come from a single opening share the same file position;
928 we call them @dfn{linked} channels.  Linked channels result when you
929 make a stream from a descriptor using @code{fdopen}, when you get a
930 descriptor from a stream with @code{fileno}, when you copy a descriptor
931 with @code{dup} or @code{dup2}, and when descriptors are inherited
932 during @code{fork}.  For files that don't support random access, such as
933 terminals and pipes, @emph{all} channels are effectively linked.  On
934 random-access files, all append-type output streams are effectively
935 linked to each other.
936
937 @cindex cleaning up a stream
938 If you have been using a stream for I/O (or have just opened the stream),
939 and you want to do I/O using
940 another channel (either a stream or a descriptor) that is linked to it,
941 you must first @dfn{clean up} the stream that you have been using.
942 @xref{Cleaning Streams}.
943
944 Terminating a process, or executing a new program in the process,
945 destroys all the streams in the process.  If descriptors linked to these
946 streams persist in other processes, their file positions become
947 undefined as a result.  To prevent this, you must clean up the streams
948 before destroying them.
949
950 @node Independent Channels
951 @subsection Independent Channels
952 @cindex independent channels
953
954 When you open channels (streams or descriptors) separately on a seekable
955 file, each channel has its own file position.  These are called
956 @dfn{independent channels}.
957
958 The system handles each channel independently.  Most of the time, this
959 is quite predictable and natural (especially for input): each channel
960 can read or write sequentially at its own place in the file.  However,
961 if some of the channels are streams, you must take these precautions:
962
963 @itemize @bullet
964 @item
965 You should clean an output stream after use, before doing anything else
966 that might read or write from the same part of the file.
967
968 @item
969 You should clean an input stream before reading data that may have been
970 modified using an independent channel.  Otherwise, you might read
971 obsolete data that had been in the stream's buffer.
972 @end itemize
973
974 If you do output to one channel at the end of the file, this will
975 certainly leave the other independent channels positioned somewhere
976 before the new end.  You cannot reliably set their file positions to the
977 new end of file before writing, because the file can always be extended
978 by another process between when you set the file position and when you
979 write the data.  Instead, use an append-type descriptor or stream; they
980 always output at the current end of the file.  In order to make the
981 end-of-file position accurate, you must clean the output channel you
982 were using, if it is a stream.
983
984 It's impossible for two channels to have separate file pointers for a
985 file that doesn't support random access.  Thus, channels for reading or
986 writing such files are always linked, never independent.  Append-type
987 channels are also always linked.  For these channels, follow the rules
988 for linked channels; see @ref{Linked Channels}.
989
990 @node Cleaning Streams
991 @subsection Cleaning Streams
992
993 On the GNU system, you can clean up any stream with @code{fclean}:
994
995 @comment stdio.h
996 @comment GNU
997 @deftypefun int fclean (FILE *@var{stream})
998 Clean up the stream @var{stream} so that its buffer is empty.  If
999 @var{stream} is doing output, force it out.  If @var{stream} is doing
1000 input, give the data in the buffer back to the system, arranging to
1001 reread it.
1002 @end deftypefun
1003
1004 On other systems, you can use @code{fflush} to clean a stream in most
1005 cases.
1006
1007 You can skip the @code{fclean} or @code{fflush} if you know the stream
1008 is already clean.  A stream is clean whenever its buffer is empty.  For
1009 example, an unbuffered stream is always clean.  An input stream that is
1010 at end-of-file is clean.  A line-buffered stream is clean when the last
1011 character output was a newline.  However, a just-opened input stream
1012 might not be clean, as its input buffer might not be empty.
1013
1014 There is one case in which cleaning a stream is impossible on most
1015 systems.  This is when the stream is doing input from a file that is not
1016 random-access.  Such streams typically read ahead, and when the file is
1017 not random access, there is no way to give back the excess data already
1018 read.  When an input stream reads from a random-access file,
1019 @code{fflush} does clean the stream, but leaves the file pointer at an
1020 unpredictable place; you must set the file pointer before doing any
1021 further I/O.  On the GNU system, using @code{fclean} avoids both of
1022 these problems.
1023
1024 Closing an output-only stream also does @code{fflush}, so this is a
1025 valid way of cleaning an output stream.  On the GNU system, closing an
1026 input stream does @code{fclean}.
1027
1028 You need not clean a stream before using its descriptor for control
1029 operations such as setting terminal modes; these operations don't affect
1030 the file position and are not affected by it.  You can use any
1031 descriptor for these operations, and all channels are affected
1032 simultaneously.  However, text already ``output'' to a stream but still
1033 buffered by the stream will be subject to the new terminal modes when
1034 subsequently flushed.  To make sure ``past'' output is covered by the
1035 terminal settings that were in effect at the time, flush the output
1036 streams for that terminal before setting the modes.  @xref{Terminal
1037 Modes}.
1038
1039 @node Scatter-Gather
1040 @section Fast Scatter-Gather I/O
1041 @cindex scatter-gather
1042
1043 Some applications may need to read or write data to multiple buffers,
1044 which are separated in memory.  Although this can be done easily enough
1045 with multiple calls to @code{read} and @code{write}, it is inefficient
1046 because there is overhead associated with each kernel call.
1047
1048 Instead, many platforms provide special high-speed primitives to perform
1049 these @dfn{scatter-gather} operations in a single kernel call.  The GNU C
1050 library will provide an emulation on any system that lacks these
1051 primitives, so they are not a portability threat.  They are defined in
1052 @code{sys/uio.h}.
1053
1054 These functions are controlled with arrays of @code{iovec} structures,
1055 which describe the location and size of each buffer.
1056
1057 @comment sys/uio.h
1058 @comment BSD
1059 @deftp {Data Type} {struct iovec}
1060
1061 The @code{iovec} structure describes a buffer. It contains two fields:
1062
1063 @table @code
1064
1065 @item void *iov_base
1066 Contains the address of a buffer.
1067
1068 @item size_t iov_len
1069 Contains the length of the buffer.
1070
1071 @end table
1072 @end deftp
1073
1074 @comment sys/uio.h
1075 @comment BSD
1076 @deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
1077
1078 The @code{readv} function reads data from @var{filedes} and scatters it
1079 into the buffers described in @var{vector}, which is taken to be
1080 @var{count} structures long.  As each buffer is filled, data is sent to the
1081 next.
1082
1083 Note that @code{readv} is not guaranteed to fill all the buffers.
1084 It may stop at any point, for the same reasons @code{read} would.
1085
1086 The return value is a count of bytes (@emph{not} buffers) read, @math{0}
1087 indicating end-of-file, or @math{-1} indicating an error.  The possible
1088 errors are the same as in @code{read}.
1089
1090 @end deftypefun
1091
1092 @comment sys/uio.h
1093 @comment BSD
1094 @deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
1095
1096 The @code{writev} function gathers data from the buffers described in
1097 @var{vector}, which is taken to be @var{count} structures long, and writes
1098 them to @code{filedes}.  As each buffer is written, it moves on to the
1099 next.
1100
1101 Like @code{readv}, @code{writev} may stop midstream under the same
1102 conditions @code{write} would.
1103
1104 The return value is a count of bytes written, or @math{-1} indicating an
1105 error.  The possible errors are the same as in @code{write}.
1106
1107 @end deftypefun
1108
1109 @c Note - I haven't read this anywhere. I surmised it from my knowledge
1110 @c of computer science. Thus, there could be subtleties I'm missing.
1111
1112 Note that if the buffers are small (under about 1kB), high-level streams
1113 may be easier to use than these functions.  However, @code{readv} and
1114 @code{writev} are more efficient when the individual buffers themselves
1115 (as opposed to the total output), are large.  In that case, a high-level
1116 stream would not be able to cache the data effectively.
1117
1118 @node Memory-mapped I/O
1119 @section Memory-mapped I/O
1120
1121 On modern operating systems, it is possible to @dfn{mmap} (pronounced
1122 ``em-map'') a file to a region of memory.  When this is done, the file can
1123 be accessed just like an array in the program.
1124
1125 This is more efficient than @code{read} or @code{write}, as only the regions
1126 of the file that a program actually accesses are loaded.  Accesses to
1127 not-yet-loaded parts of the mmapped region are handled in the same way as
1128 swapped out pages.
1129
1130 Since mmapped pages can be stored back to their file when physical
1131 memory is low, it is possible to mmap files orders of magnitude larger
1132 than both the physical memory @emph{and} swap space.  The only limit is
1133 address space.  The theoretical limit is 4GB on a 32-bit machine -
1134 however, the actual limit will be smaller since some areas will be
1135 reserved for other purposes.  If the LFS interface is used the file size
1136 on 32-bit systems is not limited to 2GB (offsets are signed which
1137 reduces the addressable area of 4GB by half); the full 64-bit are
1138 available.
1139
1140 Memory mapping only works on entire pages of memory.  Thus, addresses
1141 for mapping must be page-aligned, and length values will be rounded up.
1142 To determine the size of a page the machine uses one should use
1143
1144 @vindex _SC_PAGESIZE
1145 @smallexample
1146 size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
1147 @end smallexample
1148
1149 @noindent
1150 These functions are declared in @file{sys/mman.h}.
1151
1152 @comment sys/mman.h
1153 @comment POSIX
1154 @deftypefun {void *} mmap (void *@var{address}, size_t @var{length},int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset})
1155
1156 The @code{mmap} function creates a new mapping, connected to bytes
1157 (@var{offset}) to (@var{offset} + @var{length} - 1) in the file open on
1158 @var{filedes}.  A new reference for the file specified by @var{filedes}
1159 is created, which is not removed by closing the file.
1160
1161 @var{address} gives a preferred starting address for the mapping.
1162 @code{NULL} expresses no preference. Any previous mapping at that
1163 address is automatically removed. The address you give may still be
1164 changed, unless you use the @code{MAP_FIXED} flag.
1165
1166 @vindex PROT_READ
1167 @vindex PROT_WRITE
1168 @vindex PROT_EXEC
1169 @var{protect} contains flags that control what kind of access is
1170 permitted.  They include @code{PROT_READ}, @code{PROT_WRITE}, and
1171 @code{PROT_EXEC}, which permit reading, writing, and execution,
1172 respectively.  Inappropriate access will cause a segfault (@pxref{Program
1173 Error Signals}).
1174
1175 Note that most hardware designs cannot support write permission without
1176 read permission, and many do not distinguish read and execute permission.
1177 Thus, you may receive wider permissions than you ask for, and mappings of
1178 write-only files may be denied even if you do not use @code{PROT_READ}.
1179
1180 @var{flags} contains flags that control the nature of the map.
1181 One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified.
1182
1183 They include:
1184
1185 @vtable @code
1186 @item MAP_PRIVATE
1187 This specifies that writes to the region should never be written back
1188 to the attached file.  Instead, a copy is made for the process, and the
1189 region will be swapped normally if memory runs low.  No other process will
1190 see the changes.
1191
1192 Since private mappings effectively revert to ordinary memory
1193 when written to, you must have enough virtual memory for a copy of
1194 the entire mmapped region if you use this mode with @code{PROT_WRITE}.
1195
1196 @item MAP_SHARED
1197 This specifies that writes to the region will be written back to the
1198 file.  Changes made will be shared immediately with other processes
1199 mmaping the same file.
1200
1201 Note that actual writing may take place at any time.  You need to use
1202 @code{msync}, described below, if it is important that other processes
1203 using conventional I/O get a consistent view of the file.
1204
1205 @item MAP_FIXED
1206 This forces the system to use the exact mapping address specified in
1207 @var{address} and fail if it can't.
1208
1209 @c One of these is official - the other is obviously an obsolete synonym
1210 @c Which is which?
1211 @item MAP_ANONYMOUS
1212 @itemx MAP_ANON
1213 This flag tells the system to create an anonymous mapping, not connected
1214 to a file.  @var{filedes} and @var{off} are ignored, and the region is
1215 initialized with zeros.
1216
1217 Anonymous maps are used as the basic primitive to extend the heap on some
1218 systems.  They are also useful to share data between multiple tasks
1219 without creating a file.
1220
1221 On some systems using private anonymous mmaps is more efficient than using
1222 @code{malloc} for large blocks.  This is not an issue with the GNU C library,
1223 as the included @code{malloc} automatically uses @code{mmap} where appropriate.
1224
1225 @c Linux has some other MAP_ options, which I have not discussed here.
1226 @c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to
1227 @c user programs (and I don't understand the last two). MAP_LOCKED does
1228 @c not appear to be implemented.
1229
1230 @end vtable
1231
1232 @code{mmap} returns the address of the new mapping, or @math{-1} for an
1233 error.
1234
1235 Possible errors include:
1236
1237 @table @code
1238
1239 @item EINVAL
1240
1241 Either @var{address} was unusable, or inconsistent @var{flags} were
1242 given.
1243
1244 @item EACCES
1245
1246 @var{filedes} was not open for the type of access specified in @var{protect}.
1247
1248 @item ENOMEM
1249
1250 Either there is not enough memory for the operation, or the process is
1251 out of address space.
1252
1253 @item ENODEV
1254
1255 This file is of a type that doesn't support mapping.
1256
1257 @item ENOEXEC
1258
1259 The file is on a filesystem that doesn't support mapping.
1260
1261 @c On Linux, EAGAIN will appear if the file has a conflicting mandatory lock.
1262 @c However mandatory locks are not discussed in this manual.
1263 @c
1264 @c Similarly, ETXTBSY will occur if the MAP_DENYWRITE flag (not documented
1265 @c here) is used and the file is already open for writing.
1266
1267 @end table
1268
1269 @end deftypefun
1270
1271 @comment sys/mman.h
1272 @comment LFS
1273 @deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length},int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset})
1274 The @code{mmap64} function is equivalent to the @code{mmap} function but
1275 the @var{offset} parameter is of type @code{off64_t}.  On 32-bit systems
1276 this allows the file associated with the @var{filedes} descriptor to be
1277 larger than 2GB.  @var{filedes} must be a descriptor returned from a
1278 call to @code{open64} or @code{fopen64} and @code{freopen64} where the
1279 descriptor is retrieved with @code{fileno}.
1280
1281 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
1282 function is actually available under the name @code{mmap}.  I.e., the
1283 new, extended API using 64 bit file sizes and offsets transparently
1284 replaces the old API.
1285 @end deftypefun
1286
1287 @comment sys/mman.h
1288 @comment POSIX
1289 @deftypefun int munmap (void *@var{addr}, size_t @var{length})
1290
1291 @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} +
1292 @var{length}).  @var{length} should be the length of the mapping.
1293
1294 It is safe to unmap multiple mappings in one command, or include unmapped
1295 space in the range.  It is also possible to unmap only part of an existing
1296 mapping.  However, only entire pages can be removed.  If @var{length} is not
1297 an even number of pages, it will be rounded up.
1298
1299 It returns @math{0} for success and @math{-1} for an error.
1300
1301 One error is possible:
1302
1303 @table @code
1304
1305 @item EINVAL
1306 The memory range given was outside the user mmap range or wasn't page
1307 aligned.
1308
1309 @end table
1310
1311 @end deftypefun
1312
1313 @comment sys/mman.h
1314 @comment POSIX
1315 @deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags})
1316
1317 When using shared mappings, the kernel can write the file at any time
1318 before the mapping is removed.  To be certain data has actually been
1319 written to the file and will be accessible to non-memory-mapped I/O, it
1320 is necessary to use this function.
1321
1322 It operates on the region @var{address} to (@var{address} + @var{length}).
1323 It may be used on part of a mapping or multiple mappings, however the
1324 region given should not contain any unmapped space.
1325
1326 @var{flags} can contain some options:
1327
1328 @vtable @code
1329
1330 @item MS_SYNC
1331
1332 This flag makes sure the data is actually written @emph{to disk}.
1333 Normally @code{msync} only makes sure that accesses to a file with
1334 conventional I/O reflect the recent changes.
1335
1336 @item MS_ASYNC
1337
1338 This tells @code{msync} to begin the synchronization, but not to wait for
1339 it to complete.
1340
1341 @c Linux also has MS_INVALIDATE, which I don't understand.
1342
1343 @end vtable
1344
1345 @code{msync} returns @math{0} for success and @math{-1} for
1346 error.  Errors include:
1347
1348 @table @code
1349
1350 @item EINVAL
1351 An invalid region was given, or the @var{flags} were invalid.
1352
1353 @item EFAULT
1354 There is no existing mapping in at least part of the given region.
1355
1356 @end table
1357
1358 @end deftypefun
1359
1360 @comment sys/mman.h
1361 @comment GNU
1362 @deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag})
1363
1364 This function can be used to change the size of an existing memory
1365 area. @var{address} and @var{length} must cover a region entirely mapped
1366 in the same @code{mmap} statement. A new mapping with the same
1367 characteristics will be returned with the length @var{new_length}.
1368
1369 One option is possible, @code{MREMAP_MAYMOVE}. If it is given in
1370 @var{flags}, the system may remove the existing mapping and create a new
1371 one of the desired length in another location.
1372
1373 The address of the resulting mapping is returned, or @math{-1}. Possible
1374 error codes include:
1375
1376 @table @code
1377
1378 @item EFAULT
1379 There is no existing mapping in at least part of the original region, or
1380 the region covers two or more distinct mappings.
1381
1382 @item EINVAL
1383 The address given is misaligned or inappropriate.
1384
1385 @item EAGAIN
1386 The region has pages locked, and if extended it would exceed the
1387 process's resource limit for locked pages.  @xref{Limits on Resources}.
1388
1389 @item ENOMEM
1390 The region is private writable, and insufficient virtual memory is
1391 available to extend it.  Also, this error will occur if
1392 @code{MREMAP_MAYMOVE} is not given and the extension would collide with
1393 another mapped region.
1394
1395 @end table
1396 @end deftypefun
1397
1398 This function is only available on a few systems.  Except for performing
1399 optional optimizations one should not rely on this function.
1400
1401 Not all file descriptors may be mapped.  Sockets, pipes, and most devices
1402 only allow sequential access and do not fit into the mapping abstraction.
1403 In addition, some regular files may not be mmapable, and older kernels may
1404 not support mapping at all.  Thus, programs using @code{mmap} should
1405 have a fallback method to use should it fail. @xref{Mmap,,,standards,GNU
1406 Coding Standards}.
1407
1408 @comment sys/mman.h
1409 @comment POSIX
1410 @deftypefun int madvise (void *@var{addr}, size_t @var{length}, int @var{advice})
1411
1412 This function can be used to provide the system with @var{advice} about
1413 the intended usage patterns of the memory region starting at @var{addr}
1414 and extending @var{length} bytes.
1415
1416 The valid BSD values for @var{advice} are:
1417
1418 @table @code
1419
1420 @item MADV_NORMAL
1421 The region should receive no further special treatment.
1422
1423 @item MADV_RANDOM
1424 The region will be accessed via random page references. The kernel
1425 should page-in the minimal number of pages for each page fault.
1426
1427 @item MADV_SEQUENTIAL
1428 The region will be accessed via sequential page references. This
1429 may cause the kernel to aggressively read-ahead, expecting further
1430 sequential references after any page fault within this region.
1431
1432 @item MADV_WILLNEED
1433 The region will be needed.  The pages within this region may
1434 be pre-faulted in by the kernel.
1435
1436 @item MADV_DONTNEED
1437 The region is no longer needed.  The kernel may free these pages,
1438 causing any changes to the pages to be lost, as well as swapped
1439 out pages to be discarded.
1440
1441 @end table
1442
1443 The POSIX names are slightly different, but with the same meanings:
1444
1445 @table @code
1446
1447 @item POSIX_MADV_NORMAL
1448 This corresponds with BSD's @code{MADV_NORMAL}.
1449
1450 @item POSIX_MADV_RANDOM
1451 This corresponds with BSD's @code{MADV_RANDOM}.
1452
1453 @item POSIX_MADV_SEQUENTIAL
1454 This corresponds with BSD's @code{MADV_SEQUENTIAL}.
1455
1456 @item POSIX_MADV_WILLNEED
1457 This corresponds with BSD's @code{MADV_WILLNEED}.
1458
1459 @item POSIX_MADV_DONTNEED
1460 This corresponds with BSD's @code{MADV_DONTNEED}.
1461
1462 @end table
1463
1464 @code{msync} returns @math{0} for success and @math{-1} for
1465 error.  Errors include:
1466 @table @code
1467
1468 @item EINVAL
1469 An invalid region was given, or the @var{advice} was invalid.
1470
1471 @item EFAULT
1472 There is no existing mapping in at least part of the given region.
1473
1474 @end table
1475 @end deftypefun
1476
1477 @node Waiting for I/O
1478 @section Waiting for Input or Output
1479 @cindex waiting for input or output
1480 @cindex multiplexing input
1481 @cindex input from multiple files
1482
1483 Sometimes a program needs to accept input on multiple input channels
1484 whenever input arrives.  For example, some workstations may have devices
1485 such as a digitizing tablet, function button box, or dial box that are
1486 connected via normal asynchronous serial interfaces; good user interface
1487 style requires responding immediately to input on any device.  Another
1488 example is a program that acts as a server to several other processes
1489 via pipes or sockets.
1490
1491 You cannot normally use @code{read} for this purpose, because this
1492 blocks the program until input is available on one particular file
1493 descriptor; input on other channels won't wake it up.  You could set
1494 nonblocking mode and poll each file descriptor in turn, but this is very
1495 inefficient.
1496
1497 A better solution is to use the @code{select} function.  This blocks the
1498 program until input or output is ready on a specified set of file
1499 descriptors, or until a timer expires, whichever comes first.  This
1500 facility is declared in the header file @file{sys/types.h}.
1501 @pindex sys/types.h
1502
1503 In the case of a server socket (@pxref{Listening}), we say that
1504 ``input'' is available when there are pending connections that could be
1505 accepted (@pxref{Accepting Connections}).  @code{accept} for server
1506 sockets blocks and interacts with @code{select} just as @code{read} does
1507 for normal input.
1508
1509 @cindex file descriptor sets, for @code{select}
1510 The file descriptor sets for the @code{select} function are specified
1511 as @code{fd_set} objects.  Here is the description of the data type
1512 and some macros for manipulating these objects.
1513
1514 @comment sys/types.h
1515 @comment BSD
1516 @deftp {Data Type} fd_set
1517 The @code{fd_set} data type represents file descriptor sets for the
1518 @code{select} function.  It is actually a bit array.
1519 @end deftp
1520
1521 @comment sys/types.h
1522 @comment BSD
1523 @deftypevr Macro int FD_SETSIZE
1524 The value of this macro is the maximum number of file descriptors that a
1525 @code{fd_set} object can hold information about.  On systems with a
1526 fixed maximum number, @code{FD_SETSIZE} is at least that number.  On
1527 some systems, including GNU, there is no absolute limit on the number of
1528 descriptors open, but this macro still has a constant value which
1529 controls the number of bits in an @code{fd_set}; if you get a file
1530 descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
1531 that descriptor into an @code{fd_set}.
1532 @end deftypevr
1533
1534 @comment sys/types.h
1535 @comment BSD
1536 @deftypefn Macro void FD_ZERO (fd_set *@var{set})
1537 This macro initializes the file descriptor set @var{set} to be the
1538 empty set.
1539 @end deftypefn
1540
1541 @comment sys/types.h
1542 @comment BSD
1543 @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
1544 This macro adds @var{filedes} to the file descriptor set @var{set}.
1545
1546 The @var{filedes} parameter must not have side effects since it is
1547 evaluated more than once.
1548 @end deftypefn
1549
1550 @comment sys/types.h
1551 @comment BSD
1552 @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
1553 This macro removes @var{filedes} from the file descriptor set @var{set}.
1554
1555 The @var{filedes} parameter must not have side effects since it is
1556 evaluated more than once.
1557 @end deftypefn
1558
1559 @comment sys/types.h
1560 @comment BSD
1561 @deftypefn Macro int FD_ISSET (int @var{filedes}, fd_set *@var{set})
1562 This macro returns a nonzero value (true) if @var{filedes} is a member
1563 of the file descriptor set @var{set}, and zero (false) otherwise.
1564
1565 The @var{filedes} parameter must not have side effects since it is
1566 evaluated more than once.
1567 @end deftypefn
1568
1569 Next, here is the description of the @code{select} function itself.
1570
1571 @comment sys/types.h
1572 @comment BSD
1573 @deftypefun int select (int @var{nfds}, fd_set *@var{read-fds}, fd_set *@var{write-fds}, fd_set *@var{except-fds}, struct timeval *@var{timeout})
1574 The @code{select} function blocks the calling process until there is
1575 activity on any of the specified sets of file descriptors, or until the
1576 timeout period has expired.
1577
1578 The file descriptors specified by the @var{read-fds} argument are
1579 checked to see if they are ready for reading; the @var{write-fds} file
1580 descriptors are checked to see if they are ready for writing; and the
1581 @var{except-fds} file descriptors are checked for exceptional
1582 conditions.  You can pass a null pointer for any of these arguments if
1583 you are not interested in checking for that kind of condition.
1584
1585 A file descriptor is considered ready for reading if it is not at end of
1586 file.  A server socket is considered ready for reading if there is a
1587 pending connection which can be accepted with @code{accept};
1588 @pxref{Accepting Connections}.  A client socket is ready for writing when
1589 its connection is fully established; @pxref{Connecting}.
1590
1591 ``Exceptional conditions'' does not mean errors---errors are reported
1592 immediately when an erroneous system call is executed, and do not
1593 constitute a state of the descriptor.  Rather, they include conditions
1594 such as the presence of an urgent message on a socket.  (@xref{Sockets},
1595 for information on urgent messages.)
1596
1597 The @code{select} function checks only the first @var{nfds} file
1598 descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
1599 of this argument.
1600
1601 The @var{timeout} specifies the maximum time to wait.  If you pass a
1602 null pointer for this argument, it means to block indefinitely until one
1603 of the file descriptors is ready.  Otherwise, you should provide the
1604 time in @code{struct timeval} format; see @ref{High-Resolution
1605 Calendar}.  Specify zero as the time (a @code{struct timeval} containing
1606 all zeros) if you want to find out which descriptors are ready without
1607 waiting if none are ready.
1608
1609 The normal return value from @code{select} is the total number of ready file
1610 descriptors in all of the sets.  Each of the argument sets is overwritten
1611 with information about the descriptors that are ready for the corresponding
1612 operation.  Thus, to see if a particular descriptor @var{desc} has input,
1613 use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
1614
1615 If @code{select} returns because the timeout period expires, it returns
1616 a value of zero.
1617
1618 Any signal will cause @code{select} to return immediately.  So if your
1619 program uses signals, you can't rely on @code{select} to keep waiting
1620 for the full time specified.  If you want to be sure of waiting for a
1621 particular amount of time, you must check for @code{EINTR} and repeat
1622 the @code{select} with a newly calculated timeout based on the current
1623 time.  See the example below.  See also @ref{Interrupted Primitives}.
1624
1625 If an error occurs, @code{select} returns @code{-1} and does not modify
1626 the argument file descriptor sets.  The following @code{errno} error
1627 conditions are defined for this function:
1628
1629 @table @code
1630 @item EBADF
1631 One of the file descriptor sets specified an invalid file descriptor.
1632
1633 @item EINTR
1634 The operation was interrupted by a signal.  @xref{Interrupted Primitives}.
1635
1636 @item EINVAL
1637 The @var{timeout} argument is invalid; one of the components is negative
1638 or too large.
1639 @end table
1640 @end deftypefun
1641
1642 @strong{Portability Note:}  The @code{select} function is a BSD Unix
1643 feature.
1644
1645 Here is an example showing how you can use @code{select} to establish a
1646 timeout period for reading from a file descriptor.  The @code{input_timeout}
1647 function blocks the calling process until input is available on the
1648 file descriptor, or until the timeout period expires.
1649
1650 @smallexample
1651 @include select.c.texi
1652 @end smallexample
1653
1654 There is another example showing the use of @code{select} to multiplex
1655 input from multiple sockets in @ref{Server Example}.
1656
1657
1658 @node Synchronizing I/O
1659 @section Synchronizing I/O operations
1660
1661 @cindex synchronizing
1662 In most modern operating systems, the normal I/O operations are not
1663 executed synchronously.  I.e., even if a @code{write} system call
1664 returns, this does not mean the data is actually written to the media,
1665 e.g., the disk.
1666
1667 In situations where synchronization points are necessary, you can use
1668 special functions which ensure that all operations finish before
1669 they return.
1670
1671 @comment unistd.h
1672 @comment X/Open
1673 @deftypefun int sync (void)
1674 A call to this function will not return as long as there is data which
1675 has not been written to the device.  All dirty buffers in the kernel will
1676 be written and so an overall consistent system can be achieved (if no
1677 other process in parallel writes data).
1678
1679 A prototype for @code{sync} can be found in @file{unistd.h}.
1680
1681 The return value is zero to indicate no error.
1682 @end deftypefun
1683
1684 Programs more often want to ensure that data written to a given file is
1685 committed, rather than all data in the system.  For this, @code{sync} is overkill.
1686
1687
1688 @comment unistd.h
1689 @comment POSIX
1690 @deftypefun int fsync (int @var{fildes})
1691 The @code{fsync} function can be used to make sure all data associated with
1692 the open file @var{fildes} is written to the device associated with the
1693 descriptor.  The function call does not return unless all actions have
1694 finished.
1695
1696 A prototype for @code{fsync} can be found in @file{unistd.h}.
1697
1698 This function is a cancellation point in multi-threaded programs.  This
1699 is a problem if the thread allocates some resources (like memory, file
1700 descriptors, semaphores or whatever) at the time @code{fsync} is
1701 called.  If the thread gets canceled these resources stay allocated
1702 until the program ends.  To avoid this, calls to @code{fsync} should be
1703 protected using cancellation handlers.
1704 @c ref pthread_cleanup_push / pthread_cleanup_pop
1705
1706 The return value of the function is zero if no error occurred.  Otherwise
1707 it is @math{-1} and the global variable @var{errno} is set to the
1708 following values:
1709 @table @code
1710 @item EBADF
1711 The descriptor @var{fildes} is not valid.
1712
1713 @item EINVAL
1714 No synchronization is possible since the system does not implement this.
1715 @end table
1716 @end deftypefun
1717
1718 Sometimes it is not even necessary to write all data associated with a
1719 file descriptor.  E.g., in database files which do not change in size it
1720 is enough to write all the file content data to the device.
1721 Meta-information, like the modification time etc., are not that important
1722 and leaving such information uncommitted does not prevent a successful
1723 recovering of the file in case of a problem.
1724
1725 @comment unistd.h
1726 @comment POSIX
1727 @deftypefun int fdatasync (int @var{fildes})
1728 When a call to the @code{fdatasync} function returns, it is ensured
1729 that all of the file data is written to the device.  For all pending I/O
1730 operations, the parts guaranteeing data integrity finished.
1731
1732 Not all systems implement the @code{fdatasync} operation.  On systems
1733 missing this functionality @code{fdatasync} is emulated by a call to
1734 @code{fsync} since the performed actions are a superset of those
1735 required by @code{fdatasync}.
1736
1737 The prototype for @code{fdatasync} is in @file{unistd.h}.
1738
1739 The return value of the function is zero if no error occurred.  Otherwise
1740 it is @math{-1} and the global variable @var{errno} is set to the
1741 following values:
1742 @table @code
1743 @item EBADF
1744 The descriptor @var{fildes} is not valid.
1745
1746 @item EINVAL
1747 No synchronization is possible since the system does not implement this.
1748 @end table
1749 @end deftypefun
1750
1751
1752 @node Asynchronous I/O
1753 @section Perform I/O Operations in Parallel
1754
1755 The POSIX.1b standard defines a new set of I/O operations which can
1756 significantly reduce the time an application spends waiting at I/O.  The
1757 new functions allow a program to initiate one or more I/O operations and
1758 then immediately resume normal work while the I/O operations are
1759 executed in parallel.  This functionality is available if the
1760 @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
1761
1762 These functions are part of the library with realtime functions named
1763 @file{librt}.  They are not actually part of the @file{libc} binary.
1764 The implementation of these functions can be done using support in the
1765 kernel (if available) or using an implementation based on threads at
1766 userlevel.  In the latter case it might be necessary to link applications
1767 with the thread library @file{libpthread} in addition to @file{librt}.
1768
1769 All AIO operations operate on files which were opened previously.  There
1770 might be arbitrarily many operations running for one file.  The
1771 asynchronous I/O operations are controlled using a data structure named
1772 @code{struct aiocb} (@dfn{AIO control block}).  It is defined in
1773 @file{aio.h} as follows.
1774
1775 @comment aio.h
1776 @comment POSIX.1b
1777 @deftp {Data Type} {struct aiocb}
1778 The POSIX.1b standard mandates that the @code{struct aiocb} structure
1779 contains at least the members described in the following table.  There
1780 might be more elements which are used by the implementation, but
1781 depending upon these elements is not portable and is highly deprecated.
1782
1783 @table @code
1784 @item int aio_fildes
1785 This element specifies the file descriptor to be used for the
1786 operation.  It must be a legal descriptor, otherwise the operation will
1787 fail.
1788
1789 The device on which the file is opened must allow the seek operation.
1790 I.e., it is not possible to use any of the AIO operations on devices
1791 like terminals where an @code{lseek} call would lead to an error.
1792
1793 @item off_t aio_offset
1794 This element specifies the offset in the file at which the operation (input
1795 or output) is performed.  Since the operations are carried out in arbitrary
1796 order and more than one operation for one file descriptor can be
1797 started, one cannot expect a current read/write position of the file
1798 descriptor.
1799
1800 @item volatile void *aio_buf
1801 This is a pointer to the buffer with the data to be written or the place
1802 where the read data is stored.
1803
1804 @item size_t aio_nbytes
1805 This element specifies the length of the buffer pointed to by @code{aio_buf}.
1806
1807 @item int aio_reqprio
1808 If the platform has defined @code{_POSIX_PRIORITIZED_IO} and
1809 @code{_POSIX_PRIORITY_SCHEDULING}, the AIO requests are
1810 processed based on the current scheduling priority.  The
1811 @code{aio_reqprio} element can then be used to lower the priority of the
1812 AIO operation.
1813
1814 @item struct sigevent aio_sigevent
1815 This element specifies how the calling process is notified once the
1816 operation terminates.  If the @code{sigev_notify} element is
1817 @code{SIGEV_NONE}, no notification is sent.  If it is @code{SIGEV_SIGNAL},
1818 the signal determined by @code{sigev_signo} is sent.  Otherwise,
1819 @code{sigev_notify} must be @code{SIGEV_THREAD}.  In this case, a thread
1820 is created which starts executing the function pointed to by
1821 @code{sigev_notify_function}.
1822
1823 @item int aio_lio_opcode
1824 This element is only used by the @code{lio_listio} and
1825 @code{lio_listio64} functions.  Since these functions allow an
1826 arbitrary number of operations to start at once, and each operation can be
1827 input or output (or nothing), the information must be stored in the
1828 control block.  The possible values are:
1829
1830 @vtable @code
1831 @item LIO_READ
1832 Start a read operation.  Read from the file at position
1833 @code{aio_offset} and store the next @code{aio_nbytes} bytes in the
1834 buffer pointed to by @code{aio_buf}.
1835
1836 @item LIO_WRITE
1837 Start a write operation.  Write @code{aio_nbytes} bytes starting at
1838 @code{aio_buf} into the file starting at position @code{aio_offset}.
1839
1840 @item LIO_NOP
1841 Do nothing for this control block.  This value is useful sometimes when
1842 an array of @code{struct aiocb} values contains holes, i.e., some of the
1843 values must not be handled although the whole array is presented to the
1844 @code{lio_listio} function.
1845 @end vtable
1846 @end table
1847
1848 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
1849 32 bit machine, this type is in fact @code{struct aiocb64}, since the LFS
1850 interface transparently replaces the @code{struct aiocb} definition.
1851 @end deftp
1852
1853 For use with the AIO functions defined in the LFS, there is a similar type
1854 defined which replaces the types of the appropriate members with larger
1855 types but otherwise is equivalent to @code{struct aiocb}.  Particularly,
1856 all member names are the same.
1857
1858 @comment aio.h
1859 @comment POSIX.1b
1860 @deftp {Data Type} {struct aiocb64}
1861 @table @code
1862 @item int aio_fildes
1863 This element specifies the file descriptor which is used for the
1864 operation.  It must be a legal descriptor since otherwise the operation
1865 fails for obvious reasons.
1866
1867 The device on which the file is opened must allow the seek operation.
1868 I.e., it is not possible to use any of the AIO operations on devices
1869 like terminals where an @code{lseek} call would lead to an error.
1870
1871 @item off64_t aio_offset
1872 This element specifies at which offset in the file the operation (input
1873 or output) is performed.  Since the operation are carried in arbitrary
1874 order and more than one operation for one file descriptor can be
1875 started, one cannot expect a current read/write position of the file
1876 descriptor.
1877
1878 @item volatile void *aio_buf
1879 This is a pointer to the buffer with the data to be written or the place
1880 where the read data is stored.
1881
1882 @item size_t aio_nbytes
1883 This element specifies the length of the buffer pointed to by @code{aio_buf}.
1884
1885 @item int aio_reqprio
1886 If for the platform @code{_POSIX_PRIORITIZED_IO} and
1887 @code{_POSIX_PRIORITY_SCHEDULING} are defined the AIO requests are
1888 processed based on the current scheduling priority.  The
1889 @code{aio_reqprio} element can then be used to lower the priority of the
1890 AIO operation.
1891
1892 @item struct sigevent aio_sigevent
1893 This element specifies how the calling process is notified once the
1894 operation terminates.  If the @code{sigev_notify}, element is
1895 @code{SIGEV_NONE} no notification is sent.  If it is @code{SIGEV_SIGNAL},
1896 the signal determined by @code{sigev_signo} is sent.  Otherwise,
1897 @code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
1898 which starts executing the function pointed to by
1899 @code{sigev_notify_function}.
1900
1901 @item int aio_lio_opcode
1902 This element is only used by the @code{lio_listio} and
1903 @code{[lio_listio64} functions.  Since these functions allow an
1904 arbitrary number of operations to start at once, and since each operation can be
1905 input or output (or nothing), the information must be stored in the
1906 control block.  See the description of @code{struct aiocb} for a description
1907 of the possible values.
1908 @end table
1909
1910 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
1911 32 bit machine, this type is available under the name @code{struct
1912 aiocb64}, since the LFS transparently replaces the old interface.
1913 @end deftp
1914
1915 @menu
1916 * Asynchronous Reads/Writes::    Asynchronous Read and Write Operations.
1917 * Status of AIO Operations::     Getting the Status of AIO Operations.
1918 * Synchronizing AIO Operations:: Getting into a consistent state.
1919 * Cancel AIO Operations::        Cancellation of AIO Operations.
1920 * Configuration of AIO::         How to optimize the AIO implementation.
1921 @end menu
1922
1923 @node Asynchronous Reads/Writes
1924 @subsection Asynchronous Read and Write Operations
1925
1926 @comment aio.h
1927 @comment POSIX.1b
1928 @deftypefun int aio_read (struct aiocb *@var{aiocbp})
1929 This function initiates an asynchronous read operation.  It
1930 immediately returns after the operation was enqueued or when an
1931 error was encountered.
1932
1933 The first @code{aiocbp->aio_nbytes} bytes of the file for which
1934 @code{aiocbp->aio_fildes} is a descriptor are written to the buffer
1935 starting at @code{aiocbp->aio_buf}.  Reading starts at the absolute
1936 position @code{aiocbp->aio_offset} in the file.
1937
1938 If prioritized I/O is supported by the platform the
1939 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
1940 the request is actually enqueued.
1941
1942 The calling process is notified about the termination of the read
1943 request according to the @code{aiocbp->aio_sigevent} value.
1944
1945 When @code{aio_read} returns, the return value is zero if no error
1946 occurred that can be found before the process is enqueued.  If such an
1947 early error is found, the function returns @math{-1} and sets
1948 @code{errno} to one of the following values:
1949
1950 @table @code
1951 @item EAGAIN
1952 The request was not enqueued due to (temporarily) exceeded resource
1953 limitations.
1954 @item ENOSYS
1955 The @code{aio_read} function is not implemented.
1956 @item EBADF
1957 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
1958 need not be recognized before enqueueing the request and so this error
1959 might also be signaled asynchronously.
1960 @item EINVAL
1961 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
1962 invalid.  This condition need not be recognized before enqueueing the
1963 request and so this error might also be signaled asynchronously.
1964 @end table
1965
1966 If @code{aio_read} returns zero, the current status of the request
1967 can be queried using @code{aio_error} and @code{aio_return} functions.
1968 As long as the value returned by @code{aio_error} is @code{EINPROGRESS}
1969 the operation has not yet completed.  If @code{aio_error} returns zero,
1970 the operation successfully terminated, otherwise the value is to be
1971 interpreted as an error code.  If the function terminated, the result of
1972 the operation can be obtained using a call to @code{aio_return}.  The
1973 returned value is the same as an equivalent call to @code{read} would
1974 have returned.  Possible error codes returned by @code{aio_error} are:
1975
1976 @table @code
1977 @item EBADF
1978 The @code{aiocbp->aio_fildes} descriptor is not valid.
1979 @item ECANCELED
1980 The operation was canceled before the operation was finished
1981 (@pxref{Cancel AIO Operations})
1982 @item EINVAL
1983 The @code{aiocbp->aio_offset} value is invalid.
1984 @end table
1985
1986 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1987 function is in fact @code{aio_read64} since the LFS interface transparently
1988 replaces the normal implementation.
1989 @end deftypefun
1990
1991 @comment aio.h
1992 @comment Unix98
1993 @deftypefun int aio_read64 (struct aiocb *@var{aiocbp})
1994 This function is similar to the @code{aio_read} function.  The only
1995 difference is that on @w{32 bit} machines, the file descriptor should
1996 be opened in the large file mode.  Internally, @code{aio_read64} uses
1997 functionality equivalent to @code{lseek64} (@pxref{File Position
1998 Primitive}) to position the file descriptor correctly for the reading,
1999 as opposed to @code{lseek} functionality used in @code{aio_read}.
2000
2001 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2002 function is available under the name @code{aio_read} and so transparently
2003 replaces the interface for small files on 32 bit machines.
2004 @end deftypefun
2005
2006 To write data asynchronously to a file, there exists an equivalent pair
2007 of functions with a very similar interface.
2008
2009 @comment aio.h
2010 @comment POSIX.1b
2011 @deftypefun int aio_write (struct aiocb *@var{aiocbp})
2012 This function initiates an asynchronous write operation.  The function
2013 call immediately returns after the operation was enqueued or if before
2014 this happens an error was encountered.
2015
2016 The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at
2017 @code{aiocbp->aio_buf} are written to the file for which
2018 @code{aiocbp->aio_fildes} is an descriptor, starting at the absolute
2019 position @code{aiocbp->aio_offset} in the file.
2020
2021 If prioritized I/O is supported by the platform, the
2022 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
2023 the request is actually enqueued.
2024
2025 The calling process is notified about the termination of the read
2026 request according to the @code{aiocbp->aio_sigevent} value.
2027
2028 When @code{aio_write} returns, the return value is zero if no error
2029 occurred that can be found before the process is enqueued.  If such an
2030 early error is found the function returns @math{-1} and sets
2031 @code{errno} to one of the following values.
2032
2033 @table @code
2034 @item EAGAIN
2035 The request was not enqueued due to (temporarily) exceeded resource
2036 limitations.
2037 @item ENOSYS
2038 The @code{aio_write} function is not implemented.
2039 @item EBADF
2040 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
2041 may not be recognized before enqueueing the request, and so this error
2042 might also be signaled asynchronously.
2043 @item EINVAL
2044 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqprio} value is
2045 invalid.  This condition may not be recognized before enqueueing the
2046 request and so this error might also be signaled asynchronously.
2047 @end table
2048
2049 In the case @code{aio_write} returns zero, the current status of the
2050 request can be queried using @code{aio_error} and @code{aio_return}
2051 functions.  As long as the value returned by @code{aio_error} is
2052 @code{EINPROGRESS} the operation has not yet completed.  If
2053 @code{aio_error} returns zero, the operation successfully terminated,
2054 otherwise the value is to be interpreted as an error code.  If the
2055 function terminated, the result of the operation can be get using a call
2056 to @code{aio_return}.  The returned value is the same as an equivalent
2057 call to @code{read} would have returned.  Possible error codes returned
2058 by @code{aio_error} are:
2059
2060 @table @code
2061 @item EBADF
2062 The @code{aiocbp->aio_fildes} descriptor is not valid.
2063 @item ECANCELED
2064 The operation was canceled before the operation was finished.
2065 (@pxref{Cancel AIO Operations})
2066 @item EINVAL
2067 The @code{aiocbp->aio_offset} value is invalid.
2068 @end table
2069
2070 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2071 function is in fact @code{aio_write64} since the LFS interface transparently
2072 replaces the normal implementation.
2073 @end deftypefun
2074
2075 @comment aio.h
2076 @comment Unix98
2077 @deftypefun int aio_write64 (struct aiocb *@var{aiocbp})
2078 This function is similar to the @code{aio_write} function.  The only
2079 difference is that on @w{32 bit} machines the file descriptor should
2080 be opened in the large file mode.  Internally @code{aio_write64} uses
2081 functionality equivalent to @code{lseek64} (@pxref{File Position
2082 Primitive}) to position the file descriptor correctly for the writing,
2083 as opposed to @code{lseek} functionality used in @code{aio_write}.
2084
2085 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2086 function is available under the name @code{aio_write} and so transparently
2087 replaces the interface for small files on 32 bit machines.
2088 @end deftypefun
2089
2090 Besides these functions with the more or less traditional interface,
2091 POSIX.1b also defines a function which can initiate more than one
2092 operation at a time, and which can handle freely mixed read and write
2093 operations.  It is therefore similar to a combination of @code{readv} and
2094 @code{writev}.
2095
2096 @comment aio.h
2097 @comment POSIX.1b
2098 @deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
2099 The @code{lio_listio} function can be used to enqueue an arbitrary
2100 number of read and write requests at one time.  The requests can all be
2101 meant for the same file, all for different files or every solution in
2102 between.
2103
2104 @code{lio_listio} gets the @var{nent} requests from the array pointed to
2105 by @var{list}.  The operation to be performed is determined by the
2106 @code{aio_lio_opcode} member in each element of @var{list}.  If this
2107 field is @code{LIO_READ} a read operation is enqueued, similar to a call
2108 of @code{aio_read} for this element of the array (except that the way
2109 the termination is signalled is different, as we will see below).  If
2110 the @code{aio_lio_opcode} member is @code{LIO_WRITE} a write operation
2111 is enqueued.  Otherwise the @code{aio_lio_opcode} must be @code{LIO_NOP}
2112 in which case this element of @var{list} is simply ignored.  This
2113 ``operation'' is useful in situations where one has a fixed array of
2114 @code{struct aiocb} elements from which only a few need to be handled at
2115 a time.  Another situation is where the @code{lio_listio} call was
2116 canceled before all requests are processed (@pxref{Cancel AIO
2117 Operations}) and the remaining requests have to be reissued.
2118
2119 The other members of each element of the array pointed to by
2120 @code{list} must have values suitable for the operation as described in
2121 the documentation for @code{aio_read} and @code{aio_write} above.
2122
2123 The @var{mode} argument determines how @code{lio_listio} behaves after
2124 having enqueued all the requests.  If @var{mode} is @code{LIO_WAIT} it
2125 waits until all requests terminated.  Otherwise @var{mode} must be
2126 @code{LIO_NOWAIT} and in this case the function returns immediately after
2127 having enqueued all the requests.  In this case the caller gets a
2128 notification of the termination of all requests according to the
2129 @var{sig} parameter.  If @var{sig} is @code{NULL} no notification is
2130 send.  Otherwise a signal is sent or a thread is started, just as
2131 described in the description for @code{aio_read} or @code{aio_write}.
2132
2133 If @var{mode} is @code{LIO_WAIT}, the return value of @code{lio_listio}
2134 is @math{0} when all requests completed successfully.  Otherwise the
2135 function return @math{-1} and @code{errno} is set accordingly.  To find
2136 out which request or requests failed one has to use the @code{aio_error}
2137 function on all the elements of the array @var{list}.
2138
2139 In case @var{mode} is @code{LIO_NOWAIT}, the function returns @math{0} if
2140 all requests were enqueued correctly.  The current state of the requests
2141 can be found using @code{aio_error} and @code{aio_return} as described
2142 above.  If @code{lio_listio} returns @math{-1} in this mode, the
2143 global variable @code{errno} is set accordingly.  If a request did not
2144 yet terminate, a call to @code{aio_error} returns @code{EINPROGRESS}.  If
2145 the value is different, the request is finished and the error value (or
2146 @math{0}) is returned and the result of the operation can be retrieved
2147 using @code{aio_return}.
2148
2149 Possible values for @code{errno} are:
2150
2151 @table @code
2152 @item EAGAIN
2153 The resources necessary to queue all the requests are not available at
2154 the moment.  The error status for each element of @var{list} must be
2155 checked to determine which request failed.
2156
2157 Another reason could be that the system wide limit of AIO requests is
2158 exceeded.  This cannot be the case for the implementation on GNU systems
2159 since no arbitrary limits exist.
2160 @item EINVAL
2161 The @var{mode} parameter is invalid or @var{nent} is larger than
2162 @code{AIO_LISTIO_MAX}.
2163 @item EIO
2164 One or more of the request's I/O operations failed.  The error status of
2165 each request should be checked to determine which one failed.
2166 @item ENOSYS
2167 The @code{lio_listio} function is not supported.
2168 @end table
2169
2170 If the @var{mode} parameter is @code{LIO_NOWAIT} and the caller cancels
2171 a request, the error status for this request returned by
2172 @code{aio_error} is @code{ECANCELED}.
2173
2174 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2175 function is in fact @code{lio_listio64} since the LFS interface
2176 transparently replaces the normal implementation.
2177 @end deftypefun
2178
2179 @comment aio.h
2180 @comment Unix98
2181 @deftypefun int lio_listio64 (int @var{mode}, struct aiocb *const @var{list}, int @var{nent}, struct sigevent *@var{sig})
2182 This function is similar to the @code{lio_listio} function.  The only
2183 difference is that on @w{32 bit} machines, the file descriptor should
2184 be opened in the large file mode.  Internally, @code{lio_listio64} uses
2185 functionality equivalent to @code{lseek64} (@pxref{File Position
2186 Primitive}) to position the file descriptor correctly for the reading or
2187 writing, as opposed to @code{lseek} functionality used in
2188 @code{lio_listio}.
2189
2190 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2191 function is available under the name @code{lio_listio} and so
2192 transparently replaces the interface for small files on 32 bit
2193 machines.
2194 @end deftypefun
2195
2196 @node Status of AIO Operations
2197 @subsection Getting the Status of AIO Operations
2198
2199 As already described in the documentation of the functions in the last
2200 section, it must be possible to get information about the status of an I/O
2201 request.  When the operation is performed truly asynchronously (as with
2202 @code{aio_read} and @code{aio_write} and with @code{lio_listio} when the
2203 mode is @code{LIO_NOWAIT}), one sometimes needs to know whether a
2204 specific request already terminated and if so, what the result was.
2205 The following two functions allow you to get this kind of information.
2206
2207 @comment aio.h
2208 @comment POSIX.1b
2209 @deftypefun int aio_error (const struct aiocb *@var{aiocbp})
2210 This function determines the error state of the request described by the
2211 @code{struct aiocb} variable pointed to by @var{aiocbp}.  If the
2212 request has not yet terminated the value returned is always
2213 @code{EINPROGRESS}.  Once the request has terminated the value
2214 @code{aio_error} returns is either @math{0} if the request completed
2215 successfully or it returns the value which would be stored in the
2216 @code{errno} variable if the request would have been done using
2217 @code{read}, @code{write}, or @code{fsync}.
2218
2219 The function can return @code{ENOSYS} if it is not implemented.  It
2220 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2221 refer to an asynchronous operation whose return status is not yet known.
2222
2223 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2224 function is in fact @code{aio_error64} since the LFS interface
2225 transparently replaces the normal implementation.
2226 @end deftypefun
2227
2228 @comment aio.h
2229 @comment Unix98
2230 @deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp})
2231 This function is similar to @code{aio_error} with the only difference
2232 that the argument is a reference to a variable of type @code{struct
2233 aiocb64}.
2234
2235 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2236 function is available under the name @code{aio_error} and so
2237 transparently replaces the interface for small files on 32 bit
2238 machines.
2239 @end deftypefun
2240
2241 @comment aio.h
2242 @comment POSIX.1b
2243 @deftypefun ssize_t aio_return (const struct aiocb *@var{aiocbp})
2244 This function can be used to retrieve the return status of the operation
2245 carried out by the request described in the variable pointed to by
2246 @var{aiocbp}.  As long as the error status of this request as returned
2247 by @code{aio_error} is @code{EINPROGRESS} the return of this function is
2248 undefined.
2249
2250 Once the request is finished this function can be used exactly once to
2251 retrieve the return value.  Following calls might lead to undefined
2252 behavior.  The return value itself is the value which would have been
2253 returned by the @code{read}, @code{write}, or @code{fsync} call.
2254
2255 The function can return @code{ENOSYS} if it is not implemented.  It
2256 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2257 refer to an asynchronous operation whose return status is not yet known.
2258
2259 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2260 function is in fact @code{aio_return64} since the LFS interface
2261 transparently replaces the normal implementation.
2262 @end deftypefun
2263
2264 @comment aio.h
2265 @comment Unix98
2266 @deftypefun int aio_return64 (const struct aiocb64 *@var{aiocbp})
2267 This function is similar to @code{aio_return} with the only difference
2268 that the argument is a reference to a variable of type @code{struct
2269 aiocb64}.
2270
2271 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2272 function is available under the name @code{aio_return} and so
2273 transparently replaces the interface for small files on 32 bit
2274 machines.
2275 @end deftypefun
2276
2277 @node Synchronizing AIO Operations
2278 @subsection Getting into a Consistent State
2279
2280 When dealing with asynchronous operations it is sometimes necessary to
2281 get into a consistent state.  This would mean for AIO that one wants to
2282 know whether a certain request or a group of request were processed.
2283 This could be done by waiting for the notification sent by the system
2284 after the operation terminated, but this sometimes would mean wasting
2285 resources (mainly computation time).  Instead POSIX.1b defines two
2286 functions which will help with most kinds of consistency.
2287
2288 The @code{aio_fsync} and @code{aio_fsync64} functions are only available
2289 if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}.
2290
2291 @cindex synchronizing
2292 @comment aio.h
2293 @comment POSIX.1b
2294 @deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp})
2295 Calling this function forces all I/O operations operating queued at the
2296 time of the function call operating on the file descriptor
2297 @code{aiocbp->aio_fildes} into the synchronized I/O completion state
2298 (@pxref{Synchronizing I/O}).  The @code{aio_fsync} function returns
2299 immediately but the notification through the method described in
2300 @code{aiocbp->aio_sigevent} will happen only after all requests for this
2301 file descriptor have terminated and the file is synchronized.  This also
2302 means that requests for this very same file descriptor which are queued
2303 after the synchronization request are not affected.
2304
2305 If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
2306 to @code{fdatasync}.  Otherwise @var{op} should be @code{O_SYNC} and
2307 the synchronization happens as with @code{fsync}.
2308
2309 As long as the synchronization has not happened, a call to
2310 @code{aio_error} with the reference to the object pointed to by
2311 @var{aiocbp} returns @code{EINPROGRESS}.  Once the synchronization is
2312 done @code{aio_error} return @math{0} if the synchronization was not
2313 successful.  Otherwise the value returned is the value to which the
2314 @code{fsync} or @code{fdatasync} function would have set the
2315 @code{errno} variable.  In this case nothing can be assumed about the
2316 consistency for the data written to this file descriptor.
2317
2318 The return value of this function is @math{0} if the request was
2319 successfully enqueued.  Otherwise the return value is @math{-1} and
2320 @code{errno} is set to one of the following values:
2321
2322 @table @code
2323 @item EAGAIN
2324 The request could not be enqueued due to temporary lack of resources.
2325 @item EBADF
2326 The file descriptor @code{aiocbp->aio_fildes} is not valid or not open
2327 for writing.
2328 @item EINVAL
2329 The implementation does not support I/O synchronization or the @var{op}
2330 parameter is other than @code{O_DSYNC} and @code{O_SYNC}.
2331 @item ENOSYS
2332 This function is not implemented.
2333 @end table
2334
2335 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2336 function is in fact @code{aio_fsync64} since the LFS interface
2337 transparently replaces the normal implementation.
2338 @end deftypefun
2339
2340 @comment aio.h
2341 @comment Unix98
2342 @deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp})
2343 This function is similar to @code{aio_fsync} with the only difference
2344 that the argument is a reference to a variable of type @code{struct
2345 aiocb64}.
2346
2347 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2348 function is available under the name @code{aio_fsync} and so
2349 transparently replaces the interface for small files on 32 bit
2350 machines.
2351 @end deftypefun
2352
2353 Another method of synchronization is to wait until one or more requests of a
2354 specific set terminated.  This could be achieved by the @code{aio_*}
2355 functions to notify the initiating process about the termination but in
2356 some situations this is not the ideal solution.  In a program which
2357 constantly updates clients somehow connected to the server it is not
2358 always the best solution to go round robin since some connections might
2359 be slow.  On the other hand letting the @code{aio_*} function notify the
2360 caller might also be not the best solution since whenever the process
2361 works on preparing data for on client it makes no sense to be
2362 interrupted by a notification since the new client will not be handled
2363 before the current client is served.  For situations like this
2364 @code{aio_suspend} should be used.
2365
2366 @comment aio.h
2367 @comment POSIX.1b
2368 @deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
2369 When calling this function, the calling thread is suspended until at
2370 least one of the requests pointed to by the @var{nent} elements of the
2371 array @var{list} has completed.  If any of the requests has already
2372 completed at the time @code{aio_suspend} is called, the function returns
2373 immediately.  Whether a request has terminated or not is determined by
2374 comparing the error status of the request with @code{EINPROGRESS}.  If
2375 an element of @var{list} is @code{NULL}, the entry is simply ignored.
2376
2377 If no request has finished, the calling process is suspended.  If
2378 @var{timeout} is @code{NULL}, the process is not woken until a request
2379 has finished.  If @var{timeout} is not @code{NULL}, the process remains
2380 suspended at least as long as specified in @var{timeout}.  In this case,
2381 @code{aio_suspend} returns with an error.
2382
2383 The return value of the function is @math{0} if one or more requests
2384 from the @var{list} have terminated.  Otherwise the function returns
2385 @math{-1} and @code{errno} is set to one of the following values:
2386
2387 @table @code
2388 @item EAGAIN
2389 None of the requests from the @var{list} completed in the time specified
2390 by @var{timeout}.
2391 @item EINTR
2392 A signal interrupted the @code{aio_suspend} function.  This signal might
2393 also be sent by the AIO implementation while signalling the termination
2394 of one of the requests.
2395 @item ENOSYS
2396 The @code{aio_suspend} function is not implemented.
2397 @end table
2398
2399 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2400 function is in fact @code{aio_suspend64} since the LFS interface
2401 transparently replaces the normal implementation.
2402 @end deftypefun
2403
2404 @comment aio.h
2405 @comment Unix98
2406 @deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
2407 This function is similar to @code{aio_suspend} with the only difference
2408 that the argument is a reference to a variable of type @code{struct
2409 aiocb64}.
2410
2411 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2412 function is available under the name @code{aio_suspend} and so
2413 transparently replaces the interface for small files on 32 bit
2414 machines.
2415 @end deftypefun
2416
2417 @node Cancel AIO Operations
2418 @subsection Cancellation of AIO Operations
2419
2420 When one or more requests are asynchronously processed, it might be
2421 useful in some situations to cancel a selected operation, e.g., if it
2422 becomes obvious that the written data is no longer accurate and would
2423 have to be overwritten soon.  As an example, assume an application, which
2424 writes data in files in a situation where new incoming data would have
2425 to be written in a file which will be updated by an enqueued request.
2426 The POSIX AIO implementation provides such a function, but this function
2427 is not capable of forcing the cancellation of the request.  It is up to the
2428 implementation to decide whether it is possible to cancel the operation
2429 or not.  Therefore using this function is merely a hint.
2430
2431 @comment aio.h
2432 @comment POSIX.1b
2433 @deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp})
2434 The @code{aio_cancel} function can be used to cancel one or more
2435 outstanding requests.  If the @var{aiocbp} parameter is @code{NULL}, the
2436 function tries to cancel all of the outstanding requests which would process
2437 the file descriptor @var{fildes} (i.e., whose @code{aio_fildes} member
2438 is @var{fildes}).  If @var{aiocbp} is not @code{NULL}, @code{aio_cancel}
2439 attempts to cancel the specific request pointed to by @var{aiocbp}.
2440
2441 For requests which were successfully canceled, the normal notification
2442 about the termination of the request should take place.  I.e., depending
2443 on the @code{struct sigevent} object which controls this, nothing
2444 happens, a signal is sent or a thread is started.  If the request cannot
2445 be canceled, it terminates the usual way after performing the operation.
2446
2447 After a request is successfully canceled, a call to @code{aio_error} with
2448 a reference to this request as the parameter will return
2449 @code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
2450 If the request wasn't canceled and is still running the error status is
2451 still @code{EINPROGRESS}.
2452
2453 The return value of the function is @code{AIO_CANCELED} if there were
2454 requests which haven't terminated and which were successfully canceled.
2455 If there is one or more requests left which couldn't be canceled, the
2456 return value is @code{AIO_NOTCANCELED}.  In this case @code{aio_error}
2457 must be used to find out which of the, perhaps multiple, requests (in
2458 @var{aiocbp} is @code{NULL}) weren't successfully canceled.  If all
2459 requests already terminated at the time @code{aio_cancel} is called the
2460 return value is @code{AIO_ALLDONE}.
2461
2462 If an error occurred during the execution of @code{aio_cancel} the
2463 function returns @math{-1} and sets @code{errno} to one of the following
2464 values.
2465
2466 @table @code
2467 @item EBADF
2468 The file descriptor @var{fildes} is not valid.
2469 @item ENOSYS
2470 @code{aio_cancel} is not implemented.
2471 @end table
2472
2473 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2474 function is in fact @code{aio_cancel64} since the LFS interface
2475 transparently replaces the normal implementation.
2476 @end deftypefun
2477
2478 @comment aio.h
2479 @comment Unix98
2480 @deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb64 *@var{aiocbp})
2481 This function is similar to @code{aio_cancel} with the only difference
2482 that the argument is a reference to a variable of type @code{struct
2483 aiocb64}.
2484
2485 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2486 function is available under the name @code{aio_cancel} and so
2487 transparently replaces the interface for small files on 32 bit
2488 machines.
2489 @end deftypefun
2490
2491 @node Configuration of AIO
2492 @subsection How to optimize the AIO implementation
2493
2494 The POSIX standard does not specify how the AIO functions are
2495 implemented.  They could be system calls, but it is also possible to
2496 emulate them at userlevel.
2497
2498 At the point of this writing, the available implementation is a userlevel
2499 implementation which uses threads for handling the enqueued requests.
2500 While this implementation requires making some decisions about
2501 limitations, hard limitations are something which is best avoided
2502 in the GNU C library.  Therefore, the GNU C library provides a means
2503 for tuning the AIO implementation according to the individual use.
2504
2505 @comment aio.h
2506 @comment GNU
2507 @deftp {Data Type} {struct aioinit}
2508 This data type is used to pass the configuration or tunable parameters
2509 to the implementation.  The program has to initialize the members of
2510 this struct and pass it to the implementation using the @code{aio_init}
2511 function.
2512
2513 @table @code
2514 @item int aio_threads
2515 This member specifies the maximal number of threads which may be used
2516 at any one time.
2517 @item int aio_num
2518 This number provides an estimate on the maximal number of simultaneously
2519 enqueued requests.
2520 @item int aio_locks
2521 Unused.
2522 @item int aio_usedba
2523 Unused.
2524 @item int aio_debug
2525 Unused.
2526 @item int aio_numusers
2527 Unused.
2528 @item int aio_reserved[2]
2529 Unused.
2530 @end table
2531 @end deftp
2532
2533 @comment aio.h
2534 @comment GNU
2535 @deftypefun void aio_init (const struct aioinit *@var{init})
2536 This function must be called before any other AIO function.  Calling it
2537 is completely voluntary, as it is only meant to help the AIO
2538 implementation perform better.
2539
2540 Before calling the @code{aio_init}, function the members of a variable of
2541 type @code{struct aioinit} must be initialized.  Then a reference to
2542 this variable is passed as the parameter to @code{aio_init} which itself
2543 may or may not pay attention to the hints.
2544
2545 The function has no return value and no error cases are defined.  It is
2546 a extension which follows a proposal from the SGI implementation in
2547 @w{Irix 6}.  It is not covered by POSIX.1b or Unix98.
2548 @end deftypefun
2549
2550 @node Control Operations
2551 @section Control Operations on Files
2552
2553 @cindex control operations on files
2554 @cindex @code{fcntl} function
2555 This section describes how you can perform various other operations on
2556 file descriptors, such as inquiring about or setting flags describing
2557 the status of the file descriptor, manipulating record locks, and the
2558 like.  All of these operations are performed by the function @code{fcntl}.
2559
2560 The second argument to the @code{fcntl} function is a command that
2561 specifies which operation to perform.  The function and macros that name
2562 various flags that are used with it are declared in the header file
2563 @file{fcntl.h}.  Many of these flags are also used by the @code{open}
2564 function; see @ref{Opening and Closing Files}.
2565 @pindex fcntl.h
2566
2567 @comment fcntl.h
2568 @comment POSIX.1
2569 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
2570 The @code{fcntl} function performs the operation specified by
2571 @var{command} on the file descriptor @var{filedes}.  Some commands
2572 require additional arguments to be supplied.  These additional arguments
2573 and the return value and error conditions are given in the detailed
2574 descriptions of the individual commands.
2575
2576 Briefly, here is a list of what the various commands are.
2577
2578 @table @code
2579 @item F_DUPFD
2580 Duplicate the file descriptor (return another file descriptor pointing
2581 to the same open file).  @xref{Duplicating Descriptors}.
2582
2583 @item F_GETFD
2584 Get flags associated with the file descriptor.  @xref{Descriptor Flags}.
2585
2586 @item F_SETFD
2587 Set flags associated with the file descriptor.  @xref{Descriptor Flags}.
2588
2589 @item F_GETFL
2590 Get flags associated with the open file.  @xref{File Status Flags}.
2591
2592 @item F_SETFL
2593 Set flags associated with the open file.  @xref{File Status Flags}.
2594
2595 @item F_GETLK
2596 Get a file lock.  @xref{File Locks}.
2597
2598 @item F_SETLK
2599 Set or clear a file lock.  @xref{File Locks}.
2600
2601 @item F_SETLKW
2602 Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.
2603
2604 @item F_GETOWN
2605 Get process or process group ID to receive @code{SIGIO} signals.
2606 @xref{Interrupt Input}.
2607
2608 @item F_SETOWN
2609 Set process or process group ID to receive @code{SIGIO} signals.
2610 @xref{Interrupt Input}.
2611 @end table
2612
2613 This function is a cancellation point in multi-threaded programs.  This
2614 is a problem if the thread allocates some resources (like memory, file
2615 descriptors, semaphores or whatever) at the time @code{fcntl} is
2616 called.  If the thread gets canceled these resources stay allocated
2617 until the program ends.  To avoid this calls to @code{fcntl} should be
2618 protected using cancellation handlers.
2619 @c ref pthread_cleanup_push / pthread_cleanup_pop
2620 @end deftypefun
2621
2622
2623 @node Duplicating Descriptors
2624 @section Duplicating Descriptors
2625
2626 @cindex duplicating file descriptors
2627 @cindex redirecting input and output
2628
2629 You can @dfn{duplicate} a file descriptor, or allocate another file
2630 descriptor that refers to the same open file as the original.  Duplicate
2631 descriptors share one file position and one set of file status flags
2632 (@pxref{File Status Flags}), but each has its own set of file descriptor
2633 flags (@pxref{Descriptor Flags}).
2634
2635 The major use of duplicating a file descriptor is to implement
2636 @dfn{redirection} of input or output:  that is, to change the
2637 file or pipe that a particular file descriptor corresponds to.
2638
2639 You can perform this operation using the @code{fcntl} function with the
2640 @code{F_DUPFD} command, but there are also convenient functions
2641 @code{dup} and @code{dup2} for duplicating descriptors.
2642
2643 @pindex unistd.h
2644 @pindex fcntl.h
2645 The @code{fcntl} function and flags are declared in @file{fcntl.h},
2646 while prototypes for @code{dup} and @code{dup2} are in the header file
2647 @file{unistd.h}.
2648
2649 @comment unistd.h
2650 @comment POSIX.1
2651 @deftypefun int dup (int @var{old})
2652 This function copies descriptor @var{old} to the first available
2653 descriptor number (the first number not currently open).  It is
2654 equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
2655 @end deftypefun
2656
2657 @comment unistd.h
2658 @comment POSIX.1
2659 @deftypefun int dup2 (int @var{old}, int @var{new})
2660 This function copies the descriptor @var{old} to descriptor number
2661 @var{new}.
2662
2663 If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
2664 does not close @var{new}.  Otherwise, the new duplicate of @var{old}
2665 replaces any previous meaning of descriptor @var{new}, as if @var{new}
2666 were closed first.
2667
2668 If @var{old} and @var{new} are different numbers, and @var{old} is a
2669 valid descriptor number, then @code{dup2} is equivalent to:
2670
2671 @smallexample
2672 close (@var{new});
2673 fcntl (@var{old}, F_DUPFD, @var{new})
2674 @end smallexample
2675
2676 However, @code{dup2} does this atomically; there is no instant in the
2677 middle of calling @code{dup2} at which @var{new} is closed and not yet a
2678 duplicate of @var{old}.
2679 @end deftypefun
2680
2681 @comment fcntl.h
2682 @comment POSIX.1
2683 @deftypevr Macro int F_DUPFD
2684 This macro is used as the @var{command} argument to @code{fcntl}, to
2685 copy the file descriptor given as the first argument.
2686
2687 The form of the call in this case is:
2688
2689 @smallexample
2690 fcntl (@var{old}, F_DUPFD, @var{next-filedes})
2691 @end smallexample
2692
2693 The @var{next-filedes} argument is of type @code{int} and specifies that
2694 the file descriptor returned should be the next available one greater
2695 than or equal to this value.
2696
2697 The return value from @code{fcntl} with this command is normally the value
2698 of the new file descriptor.  A return value of @math{-1} indicates an
2699 error.  The following @code{errno} error conditions are defined for
2700 this command:
2701
2702 @table @code
2703 @item EBADF
2704 The @var{old} argument is invalid.
2705
2706 @item EINVAL
2707 The @var{next-filedes} argument is invalid.
2708
2709 @item EMFILE
2710 There are no more file descriptors available---your program is already
2711 using the maximum.  In BSD and GNU, the maximum is controlled by a
2712 resource limit that can be changed; @pxref{Limits on Resources}, for
2713 more information about the @code{RLIMIT_NOFILE} limit.
2714 @end table
2715
2716 @code{ENFILE} is not a possible error code for @code{dup2} because
2717 @code{dup2} does not create a new opening of a file; duplicate
2718 descriptors do not count toward the limit which @code{ENFILE}
2719 indicates.  @code{EMFILE} is possible because it refers to the limit on
2720 distinct descriptor numbers in use in one process.
2721 @end deftypevr
2722
2723 Here is an example showing how to use @code{dup2} to do redirection.
2724 Typically, redirection of the standard streams (like @code{stdin}) is
2725 done by a shell or shell-like program before calling one of the
2726 @code{exec} functions (@pxref{Executing a File}) to execute a new
2727 program in a child process.  When the new program is executed, it
2728 creates and initializes the standard streams to point to the
2729 corresponding file descriptors, before its @code{main} function is
2730 invoked.
2731
2732 So, to redirect standard input to a file, the shell could do something
2733 like:
2734
2735 @smallexample
2736 pid = fork ();
2737 if (pid == 0)
2738   @{
2739     char *filename;
2740     char *program;
2741     int file;
2742     @dots{}
2743     file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
2744     dup2 (file, STDIN_FILENO);
2745     TEMP_FAILURE_RETRY (close (file));
2746     execv (program, NULL);
2747   @}
2748 @end smallexample
2749
2750 There is also a more detailed example showing how to implement redirection
2751 in the context of a pipeline of processes in @ref{Launching Jobs}.
2752
2753
2754 @node Descriptor Flags
2755 @section File Descriptor Flags
2756 @cindex file descriptor flags
2757
2758 @dfn{File descriptor flags} are miscellaneous attributes of a file
2759 descriptor.  These flags are associated with particular file
2760 descriptors, so that if you have created duplicate file descriptors
2761 from a single opening of a file, each descriptor has its own set of flags.
2762
2763 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
2764 which causes the descriptor to be closed if you use any of the
2765 @code{exec@dots{}} functions (@pxref{Executing a File}).
2766
2767 The symbols in this section are defined in the header file
2768 @file{fcntl.h}.
2769 @pindex fcntl.h
2770
2771 @comment fcntl.h
2772 @comment POSIX.1
2773 @deftypevr Macro int F_GETFD
2774 This macro is used as the @var{command} argument to @code{fcntl}, to
2775 specify that it should return the file descriptor flags associated
2776 with the @var{filedes} argument.
2777
2778 The normal return value from @code{fcntl} with this command is a
2779 nonnegative number which can be interpreted as the bitwise OR of the
2780 individual flags (except that currently there is only one flag to use).
2781
2782 In case of an error, @code{fcntl} returns @math{-1}.  The following
2783 @code{errno} error conditions are defined for this command:
2784
2785 @table @code
2786 @item EBADF
2787 The @var{filedes} argument is invalid.
2788 @end table
2789 @end deftypevr
2790
2791
2792 @comment fcntl.h
2793 @comment POSIX.1
2794 @deftypevr Macro int F_SETFD
2795 This macro is used as the @var{command} argument to @code{fcntl}, to
2796 specify that it should set the file descriptor flags associated with the
2797 @var{filedes} argument.  This requires a third @code{int} argument to
2798 specify the new flags, so the form of the call is:
2799
2800 @smallexample
2801 fcntl (@var{filedes}, F_SETFD, @var{new-flags})
2802 @end smallexample
2803
2804 The normal return value from @code{fcntl} with this command is an
2805 unspecified value other than @math{-1}, which indicates an error.
2806 The flags and error conditions are the same as for the @code{F_GETFD}
2807 command.
2808 @end deftypevr
2809
2810 The following macro is defined for use as a file descriptor flag with
2811 the @code{fcntl} function.  The value is an integer constant usable
2812 as a bit mask value.
2813
2814 @comment fcntl.h
2815 @comment POSIX.1
2816 @deftypevr Macro int FD_CLOEXEC
2817 @cindex close-on-exec (file descriptor flag)
2818 This flag specifies that the file descriptor should be closed when
2819 an @code{exec} function is invoked; see @ref{Executing a File}.  When
2820 a file descriptor is allocated (as with @code{open} or @code{dup}),
2821 this bit is initially cleared on the new file descriptor, meaning that
2822 descriptor will survive into the new program after @code{exec}.
2823 @end deftypevr
2824
2825 If you want to modify the file descriptor flags, you should get the
2826 current flags with @code{F_GETFD} and modify the value.  Don't assume
2827 that the flags listed here are the only ones that are implemented; your
2828 program may be run years from now and more flags may exist then.  For
2829 example, here is a function to set or clear the flag @code{FD_CLOEXEC}
2830 without altering any other flags:
2831
2832 @smallexample
2833 /* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
2834    @r{or clear the flag if @var{value} is 0.}
2835    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
2836
2837 int
2838 set_cloexec_flag (int desc, int value)
2839 @{
2840   int oldflags = fcntl (desc, F_GETFD, 0);
2841   /* @r{If reading the flags failed, return error indication now.} */
2842   if (oldflags < 0)
2843     return oldflags;
2844   /* @r{Set just the flag we want to set.} */
2845   if (value != 0)
2846     oldflags |= FD_CLOEXEC;
2847   else
2848     oldflags &= ~FD_CLOEXEC;
2849   /* @r{Store modified flag word in the descriptor.} */
2850   return fcntl (desc, F_SETFD, oldflags);
2851 @}
2852 @end smallexample
2853
2854 @node File Status Flags
2855 @section File Status Flags
2856 @cindex file status flags
2857
2858 @dfn{File status flags} are used to specify attributes of the opening of a
2859 file.  Unlike the file descriptor flags discussed in @ref{Descriptor
2860 Flags}, the file status flags are shared by duplicated file descriptors
2861 resulting from a single opening of the file.  The file status flags are
2862 specified with the @var{flags} argument to @code{open};
2863 @pxref{Opening and Closing Files}.
2864
2865 File status flags fall into three categories, which are described in the
2866 following sections.
2867
2868 @itemize @bullet
2869 @item
2870 @ref{Access Modes}, specify what type of access is allowed to the
2871 file: reading, writing, or both.  They are set by @code{open} and are
2872 returned by @code{fcntl}, but cannot be changed.
2873
2874 @item
2875 @ref{Open-time Flags}, control details of what @code{open} will do.
2876 These flags are not preserved after the @code{open} call.
2877
2878 @item
2879 @ref{Operating Modes}, affect how operations such as @code{read} and
2880 @code{write} are done.  They are set by @code{open}, and can be fetched or
2881 changed with @code{fcntl}.
2882 @end itemize
2883
2884 The symbols in this section are defined in the header file
2885 @file{fcntl.h}.
2886 @pindex fcntl.h
2887
2888 @menu
2889 * Access Modes::                Whether the descriptor can read or write.
2890 * Open-time Flags::             Details of @code{open}.
2891 * Operating Modes::             Special modes to control I/O operations.
2892 * Getting File Status Flags::   Fetching and changing these flags.
2893 @end menu
2894
2895 @node Access Modes
2896 @subsection File Access Modes
2897
2898 The file access modes allow a file descriptor to be used for reading,
2899 writing, or both.  (In the GNU system, they can also allow none of these,
2900 and allow execution of the file as a program.)  The access modes are chosen
2901 when the file is opened, and never change.
2902
2903 @comment fcntl.h
2904 @comment POSIX.1
2905 @deftypevr Macro int O_RDONLY
2906 Open the file for read access.
2907 @end deftypevr
2908
2909 @comment fcntl.h
2910 @comment POSIX.1
2911 @deftypevr Macro int O_WRONLY
2912 Open the file for write access.
2913 @end deftypevr
2914
2915 @comment fcntl.h
2916 @comment POSIX.1
2917 @deftypevr Macro int O_RDWR
2918 Open the file for both reading and writing.
2919 @end deftypevr
2920
2921 In the GNU system (and not in other systems), @code{O_RDONLY} and
2922 @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
2923 and it is valid for either bit to be set or clear.  This means that
2924 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}.  A file access
2925 mode of zero is permissible; it allows no operations that do input or
2926 output to the file, but does allow other operations such as
2927 @code{fchmod}.  On the GNU system, since ``read-only'' or ``write-only''
2928 is a misnomer, @file{fcntl.h} defines additional names for the file
2929 access modes.  These names are preferred when writing GNU-specific code.
2930 But most programs will want to be portable to other POSIX.1 systems and
2931 should use the POSIX.1 names above instead.
2932
2933 @comment fcntl.h
2934 @comment GNU
2935 @deftypevr Macro int O_READ
2936 Open the file for reading.  Same as @code{O_RDONLY}; only defined on GNU.
2937 @end deftypevr
2938
2939 @comment fcntl.h
2940 @comment GNU
2941 @deftypevr Macro int O_WRITE
2942 Open the file for writing.  Same as @code{O_WRONLY}; only defined on GNU.
2943 @end deftypevr
2944
2945 @comment fcntl.h
2946 @comment GNU
2947 @deftypevr Macro int O_EXEC
2948 Open the file for executing.  Only defined on GNU.
2949 @end deftypevr
2950
2951 To determine the file access mode with @code{fcntl}, you must extract
2952 the access mode bits from the retrieved file status flags.  In the GNU
2953 system, you can just test the @code{O_READ} and @code{O_WRITE} bits in
2954 the flags word.  But in other POSIX.1 systems, reading and writing
2955 access modes are not stored as distinct bit flags.  The portable way to
2956 extract the file access mode bits is with @code{O_ACCMODE}.
2957
2958 @comment fcntl.h
2959 @comment POSIX.1
2960 @deftypevr Macro int O_ACCMODE
2961 This macro stands for a mask that can be bitwise-ANDed with the file
2962 status flag value to produce a value representing the file access mode.
2963 The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
2964 (In the GNU system it could also be zero, and it never includes the
2965 @code{O_EXEC} bit.)
2966 @end deftypevr
2967
2968 @node Open-time Flags
2969 @subsection Open-time Flags
2970
2971 The open-time flags specify options affecting how @code{open} will behave.
2972 These options are not preserved once the file is open.  The exception to
2973 this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
2974 @emph{is} saved.  @xref{Opening and Closing Files}, for how to call
2975 @code{open}.
2976
2977 There are two sorts of options specified by open-time flags.
2978
2979 @itemize @bullet
2980 @item
2981 @dfn{File name translation flags} affect how @code{open} looks up the
2982 file name to locate the file, and whether the file can be created.
2983 @cindex file name translation flags
2984 @cindex flags, file name translation
2985
2986 @item
2987 @dfn{Open-time action flags} specify extra operations that @code{open} will
2988 perform on the file once it is open.
2989 @cindex open-time action flags
2990 @cindex flags, open-time action
2991 @end itemize
2992
2993 Here are the file name translation flags.
2994
2995 @comment fcntl.h
2996 @comment POSIX.1
2997 @deftypevr Macro int O_CREAT
2998 If set, the file will be created if it doesn't already exist.
2999 @c !!! mode arg, umask
3000 @cindex create on open (file status flag)
3001 @end deftypevr
3002
3003 @comment fcntl.h
3004 @comment POSIX.1
3005 @deftypevr Macro int O_EXCL
3006 If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
3007 if the specified file already exists.  This is guaranteed to never
3008 clobber an existing file.
3009 @end deftypevr
3010
3011 @comment fcntl.h
3012 @comment POSIX.1
3013 @deftypevr Macro int O_NONBLOCK
3014 @cindex non-blocking open
3015 This prevents @code{open} from blocking for a ``long time'' to open the
3016 file.  This is only meaningful for some kinds of files, usually devices
3017 such as serial ports; when it is not meaningful, it is harmless and
3018 ignored.  Often opening a port to a modem blocks until the modem reports
3019 carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
3020 return immediately without a carrier.
3021
3022 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
3023 mode and a file name translation flag.  This means that specifying
3024 @code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
3025 @pxref{Operating Modes}.  To open the file without blocking but do normal
3026 I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
3027 then call @code{fcntl} to turn the bit off.
3028 @end deftypevr
3029
3030 @comment fcntl.h
3031 @comment POSIX.1
3032 @deftypevr Macro int O_NOCTTY
3033 If the named file is a terminal device, don't make it the controlling
3034 terminal for the process.  @xref{Job Control}, for information about
3035 what it means to be the controlling terminal.
3036
3037 In the GNU system and 4.4 BSD, opening a file never makes it the
3038 controlling terminal and @code{O_NOCTTY} is zero.  However, other
3039 systems may use a nonzero value for @code{O_NOCTTY} and set the
3040 controlling terminal when you open a file that is a terminal device; so
3041 to be portable, use @code{O_NOCTTY} when it is important to avoid this.
3042 @cindex controlling terminal, setting
3043 @end deftypevr
3044
3045 The following three file name translation flags exist only in the GNU system.
3046
3047 @comment fcntl.h
3048 @comment GNU
3049 @deftypevr Macro int O_IGNORE_CTTY
3050 Do not recognize the named file as the controlling terminal, even if it
3051 refers to the process's existing controlling terminal device.  Operations
3052 on the new file descriptor will never induce job control signals.
3053 @xref{Job Control}.
3054 @end deftypevr
3055
3056 @comment fcntl.h
3057 @comment GNU
3058 @deftypevr Macro int O_NOLINK
3059 If the named file is a symbolic link, open the link itself instead of
3060 the file it refers to.  (@code{fstat} on the new file descriptor will
3061 return the information returned by @code{lstat} on the link's name.)
3062 @cindex symbolic link, opening
3063 @end deftypevr
3064
3065 @comment fcntl.h
3066 @comment GNU
3067 @deftypevr Macro int O_NOTRANS
3068 If the named file is specially translated, do not invoke the translator.
3069 Open the bare file the translator itself sees.
3070 @end deftypevr
3071
3072
3073 The open-time action flags tell @code{open} to do additional operations
3074 which are not really related to opening the file.  The reason to do them
3075 as part of @code{open} instead of in separate calls is that @code{open}
3076 can do them @i{atomically}.
3077
3078 @comment fcntl.h
3079 @comment POSIX.1
3080 @deftypevr Macro int O_TRUNC
3081 Truncate the file to zero length.  This option is only useful for
3082 regular files, not special files such as directories or FIFOs.  POSIX.1
3083 requires that you open the file for writing to use @code{O_TRUNC}.  In
3084 BSD and GNU you must have permission to write the file to truncate it,
3085 but you need not open for write access.
3086
3087 This is the only open-time action flag specified by POSIX.1.  There is
3088 no good reason for truncation to be done by @code{open}, instead of by
3089 calling @code{ftruncate} afterwards.  The @code{O_TRUNC} flag existed in
3090 Unix before @code{ftruncate} was invented, and is retained for backward
3091 compatibility.
3092 @end deftypevr
3093
3094 The remaining operating modes are BSD extensions.  They exist only
3095 on some systems.  On other systems, these macros are not defined.
3096
3097 @comment fcntl.h
3098 @comment BSD
3099 @deftypevr Macro int O_SHLOCK
3100 Acquire a shared lock on the file, as with @code{flock}.
3101 @xref{File Locks}.
3102
3103 If @code{O_CREAT} is specified, the locking is done atomically when
3104 creating the file.  You are guaranteed that no other process will get
3105 the lock on the new file first.
3106 @end deftypevr
3107
3108 @comment fcntl.h
3109 @comment BSD
3110 @deftypevr Macro int O_EXLOCK
3111 Acquire an exclusive lock on the file, as with @code{flock}.
3112 @xref{File Locks}.  This is atomic like @code{O_SHLOCK}.
3113 @end deftypevr
3114
3115 @node Operating Modes
3116 @subsection I/O Operating Modes
3117
3118 The operating modes affect how input and output operations using a file
3119 descriptor work.  These flags are set by @code{open} and can be fetched
3120 and changed with @code{fcntl}.
3121
3122 @comment fcntl.h
3123 @comment POSIX.1
3124 @deftypevr Macro int O_APPEND
3125 The bit that enables append mode for the file.  If set, then all
3126 @code{write} operations write the data at the end of the file, extending
3127 it, regardless of the current file position.  This is the only reliable
3128 way to append to a file.  In append mode, you are guaranteed that the
3129 data you write will always go to the current end of the file, regardless
3130 of other processes writing to the file.  Conversely, if you simply set
3131 the file position to the end of file and write, then another process can
3132 extend the file after you set the file position but before you write,
3133 resulting in your data appearing someplace before the real end of file.
3134 @end deftypevr
3135
3136 @comment fcntl.h
3137 @comment POSIX.1
3138 @deftypevr Macro int O_NONBLOCK
3139 The bit that enables nonblocking mode for the file.  If this bit is set,
3140 @code{read} requests on the file can return immediately with a failure
3141 status if there is no input immediately available, instead of blocking.
3142 Likewise, @code{write} requests can also return immediately with a
3143 failure status if the output can't be written immediately.
3144
3145 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
3146 operating mode and a file name translation flag; @pxref{Open-time Flags}.
3147 @end deftypevr
3148
3149 @comment fcntl.h
3150 @comment BSD
3151 @deftypevr Macro int O_NDELAY
3152 This is an obsolete name for @code{O_NONBLOCK}, provided for
3153 compatibility with BSD.  It is not defined by the POSIX.1 standard.
3154 @end deftypevr
3155
3156 The remaining operating modes are BSD and GNU extensions.  They exist only
3157 on some systems.  On other systems, these macros are not defined.
3158
3159 @comment fcntl.h
3160 @comment BSD
3161 @deftypevr Macro int O_ASYNC
3162 The bit that enables asynchronous input mode.  If set, then @code{SIGIO}
3163 signals will be generated when input is available.  @xref{Interrupt Input}.
3164
3165 Asynchronous input mode is a BSD feature.
3166 @end deftypevr
3167
3168 @comment fcntl.h
3169 @comment BSD
3170 @deftypevr Macro int O_FSYNC
3171 The bit that enables synchronous writing for the file.  If set, each
3172 @code{write} call will make sure the data is reliably stored on disk before
3173 returning. @c !!! xref fsync
3174
3175 Synchronous writing is a BSD feature.
3176 @end deftypevr
3177
3178 @comment fcntl.h
3179 @comment BSD
3180 @deftypevr Macro int O_SYNC
3181 This is another name for @code{O_FSYNC}.  They have the same value.
3182 @end deftypevr
3183
3184 @comment fcntl.h
3185 @comment GNU
3186 @deftypevr Macro int O_NOATIME
3187 If this bit is set, @code{read} will not update the access time of the
3188 file.  @xref{File Times}.  This is used by programs that do backups, so
3189 that backing a file up does not count as reading it.
3190 Only the owner of the file or the superuser may use this bit.
3191
3192 This is a GNU extension.
3193 @end deftypevr
3194
3195 @node Getting File Status Flags
3196 @subsection Getting and Setting File Status Flags
3197
3198 The @code{fcntl} function can fetch or change file status flags.
3199
3200 @comment fcntl.h
3201 @comment POSIX.1
3202 @deftypevr Macro int F_GETFL
3203 This macro is used as the @var{command} argument to @code{fcntl}, to
3204 read the file status flags for the open file with descriptor
3205 @var{filedes}.
3206
3207 The normal return value from @code{fcntl} with this command is a
3208 nonnegative number which can be interpreted as the bitwise OR of the
3209 individual flags.  Since the file access modes are not single-bit values,
3210 you can mask off other bits in the returned flags with @code{O_ACCMODE}
3211 to compare them.
3212
3213 In case of an error, @code{fcntl} returns @math{-1}.  The following
3214 @code{errno} error conditions are defined for this command:
3215
3216 @table @code
3217 @item EBADF
3218 The @var{filedes} argument is invalid.
3219 @end table
3220 @end deftypevr
3221
3222 @comment fcntl.h
3223 @comment POSIX.1
3224 @deftypevr Macro int F_SETFL
3225 This macro is used as the @var{command} argument to @code{fcntl}, to set
3226 the file status flags for the open file corresponding to the
3227 @var{filedes} argument.  This command requires a third @code{int}
3228 argument to specify the new flags, so the call looks like this:
3229
3230 @smallexample
3231 fcntl (@var{filedes}, F_SETFL, @var{new-flags})
3232 @end smallexample
3233
3234 You can't change the access mode for the file in this way; that is,
3235 whether the file descriptor was opened for reading or writing.
3236
3237 The normal return value from @code{fcntl} with this command is an
3238 unspecified value other than @math{-1}, which indicates an error.  The
3239 error conditions are the same as for the @code{F_GETFL} command.
3240 @end deftypevr
3241
3242 If you want to modify the file status flags, you should get the current
3243 flags with @code{F_GETFL} and modify the value.  Don't assume that the
3244 flags listed here are the only ones that are implemented; your program
3245 may be run years from now and more flags may exist then.  For example,
3246 here is a function to set or clear the flag @code{O_NONBLOCK} without
3247 altering any other flags:
3248
3249 @smallexample
3250 @group
3251 /* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
3252    @r{or clear the flag if @var{value} is 0.}
3253    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
3254
3255 int
3256 set_nonblock_flag (int desc, int value)
3257 @{
3258   int oldflags = fcntl (desc, F_GETFL, 0);
3259   /* @r{If reading the flags failed, return error indication now.} */
3260   if (oldflags == -1)
3261     return -1;
3262   /* @r{Set just the flag we want to set.} */
3263   if (value != 0)
3264     oldflags |= O_NONBLOCK;
3265   else
3266     oldflags &= ~O_NONBLOCK;
3267   /* @r{Store modified flag word in the descriptor.} */
3268   return fcntl (desc, F_SETFL, oldflags);
3269 @}
3270 @end group
3271 @end smallexample
3272
3273 @node File Locks
3274 @section File Locks
3275
3276 @cindex file locks
3277 @cindex record locking
3278 The remaining @code{fcntl} commands are used to support @dfn{record
3279 locking}, which permits multiple cooperating programs to prevent each
3280 other from simultaneously accessing parts of a file in error-prone
3281 ways.
3282
3283 @cindex exclusive lock
3284 @cindex write lock
3285 An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
3286 for writing to the specified part of the file.  While a write lock is in
3287 place, no other process can lock that part of the file.
3288
3289 @cindex shared lock
3290 @cindex read lock
3291 A @dfn{shared} or @dfn{read} lock prohibits any other process from
3292 requesting a write lock on the specified part of the file.  However,
3293 other processes can request read locks.
3294
3295 The @code{read} and @code{write} functions do not actually check to see
3296 whether there are any locks in place.  If you want to implement a
3297 locking protocol for a file shared by multiple processes, your application
3298 must do explicit @code{fcntl} calls to request and clear locks at the
3299 appropriate points.
3300
3301 Locks are associated with processes.  A process can only have one kind
3302 of lock set for each byte of a given file.  When any file descriptor for
3303 that file is closed by the process, all of the locks that process holds
3304 on that file are released, even if the locks were made using other
3305 descriptors that remain open.  Likewise, locks are released when a
3306 process exits, and are not inherited by child processes created using
3307 @code{fork} (@pxref{Creating a Process}).
3308
3309 When making a lock, use a @code{struct flock} to specify what kind of
3310 lock and where.  This data type and the associated macros for the
3311 @code{fcntl} function are declared in the header file @file{fcntl.h}.
3312 @pindex fcntl.h
3313
3314 @comment fcntl.h
3315 @comment POSIX.1
3316 @deftp {Data Type} {struct flock}
3317 This structure is used with the @code{fcntl} function to describe a file
3318 lock.  It has these members:
3319
3320 @table @code
3321 @item short int l_type
3322 Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
3323 @code{F_UNLCK}.
3324
3325 @item short int l_whence
3326 This corresponds to the @var{whence} argument to @code{fseek} or
3327 @code{lseek}, and specifies what the offset is relative to.  Its value
3328 can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
3329
3330 @item off_t l_start
3331 This specifies the offset of the start of the region to which the lock
3332 applies, and is given in bytes relative to the point specified by
3333 @code{l_whence} member.
3334
3335 @item off_t l_len
3336 This specifies the length of the region to be locked.  A value of
3337 @code{0} is treated specially; it means the region extends to the end of
3338 the file.
3339
3340 @item pid_t l_pid
3341 This field is the process ID (@pxref{Process Creation Concepts}) of the
3342 process holding the lock.  It is filled in by calling @code{fcntl} with
3343 the @code{F_GETLK} command, but is ignored when making a lock.
3344 @end table
3345 @end deftp
3346
3347 @comment fcntl.h
3348 @comment POSIX.1
3349 @deftypevr Macro int F_GETLK
3350 This macro is used as the @var{command} argument to @code{fcntl}, to
3351 specify that it should get information about a lock.  This command
3352 requires a third argument of type @w{@code{struct flock *}} to be passed
3353 to @code{fcntl}, so that the form of the call is:
3354
3355 @smallexample
3356 fcntl (@var{filedes}, F_GETLK, @var{lockp})
3357 @end smallexample
3358
3359 If there is a lock already in place that would block the lock described
3360 by the @var{lockp} argument, information about that lock overwrites
3361 @code{*@var{lockp}}.  Existing locks are not reported if they are
3362 compatible with making a new lock as specified.  Thus, you should
3363 specify a lock type of @code{F_WRLCK} if you want to find out about both
3364 read and write locks, or @code{F_RDLCK} if you want to find out about
3365 write locks only.
3366
3367 There might be more than one lock affecting the region specified by the
3368 @var{lockp} argument, but @code{fcntl} only returns information about
3369 one of them.  The @code{l_whence} member of the @var{lockp} structure is
3370 set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
3371 set to identify the locked region.
3372
3373 If no lock applies, the only change to the @var{lockp} structure is to
3374 update the @code{l_type} to a value of @code{F_UNLCK}.
3375
3376 The normal return value from @code{fcntl} with this command is an
3377 unspecified value other than @math{-1}, which is reserved to indicate an
3378 error.  The following @code{errno} error conditions are defined for
3379 this command:
3380
3381 @table @code
3382 @item EBADF
3383 The @var{filedes} argument is invalid.
3384
3385 @item EINVAL
3386 Either the @var{lockp} argument doesn't specify valid lock information,
3387 or the file associated with @var{filedes} doesn't support locks.
3388 @end table
3389 @end deftypevr
3390
3391 @comment fcntl.h
3392 @comment POSIX.1
3393 @deftypevr Macro int F_SETLK
3394 This macro is used as the @var{command} argument to @code{fcntl}, to
3395 specify that it should set or clear a lock.  This command requires a
3396 third argument of type @w{@code{struct flock *}} to be passed to
3397 @code{fcntl}, so that the form of the call is:
3398
3399 @smallexample
3400 fcntl (@var{filedes}, F_SETLK, @var{lockp})
3401 @end smallexample
3402
3403 If the process already has a lock on any part of the region, the old lock
3404 on that part is replaced with the new lock.  You can remove a lock
3405 by specifying a lock type of @code{F_UNLCK}.
3406
3407 If the lock cannot be set, @code{fcntl} returns immediately with a value
3408 of @math{-1}.  This function does not block waiting for other processes
3409 to release locks.  If @code{fcntl} succeeds, it return a value other
3410 than @math{-1}.
3411
3412 The following @code{errno} error conditions are defined for this
3413 function:
3414
3415 @table @code
3416 @item EAGAIN
3417 @itemx EACCES
3418 The lock cannot be set because it is blocked by an existing lock on the
3419 file.  Some systems use @code{EAGAIN} in this case, and other systems
3420 use @code{EACCES}; your program should treat them alike, after
3421 @code{F_SETLK}.  (The GNU system always uses @code{EAGAIN}.)
3422
3423 @item EBADF
3424 Either: the @var{filedes} argument is invalid; you requested a read lock
3425 but the @var{filedes} is not open for read access; or, you requested a
3426 write lock but the @var{filedes} is not open for write access.
3427
3428 @item EINVAL
3429 Either the @var{lockp} argument doesn't specify valid lock information,
3430 or the file associated with @var{filedes} doesn't support locks.
3431
3432 @item ENOLCK
3433 The system has run out of file lock resources; there are already too
3434 many file locks in place.
3435
3436 Well-designed file systems never report this error, because they have no
3437 limitation on the number of locks.  However, you must still take account
3438 of the possibility of this error, as it could result from network access
3439 to a file system on another machine.
3440 @end table
3441 @end deftypevr
3442
3443 @comment fcntl.h
3444 @comment POSIX.1
3445 @deftypevr Macro int F_SETLKW
3446 This macro is used as the @var{command} argument to @code{fcntl}, to
3447 specify that it should set or clear a lock.  It is just like the
3448 @code{F_SETLK} command, but causes the process to block (or wait)
3449 until the request can be specified.
3450
3451 This command requires a third argument of type @code{struct flock *}, as
3452 for the @code{F_SETLK} command.
3453
3454 The @code{fcntl} return values and errors are the same as for the
3455 @code{F_SETLK} command, but these additional @code{errno} error conditions
3456 are defined for this command:
3457
3458 @table @code
3459 @item EINTR
3460 The function was interrupted by a signal while it was waiting.
3461 @xref{Interrupted Primitives}.
3462
3463 @item EDEADLK
3464 The specified region is being locked by another process.  But that
3465 process is waiting to lock a region which the current process has
3466 locked, so waiting for the lock would result in deadlock.  The system
3467 does not guarantee that it will detect all such conditions, but it lets
3468 you know if it notices one.
3469 @end table
3470 @end deftypevr
3471
3472
3473 The following macros are defined for use as values for the @code{l_type}
3474 member of the @code{flock} structure.  The values are integer constants.
3475
3476 @table @code
3477 @comment fcntl.h
3478 @comment POSIX.1
3479 @vindex F_RDLCK
3480 @item F_RDLCK
3481 This macro is used to specify a read (or shared) lock.
3482
3483 @comment fcntl.h
3484 @comment POSIX.1
3485 @vindex F_WRLCK
3486 @item F_WRLCK
3487 This macro is used to specify a write (or exclusive) lock.
3488
3489 @comment fcntl.h
3490 @comment POSIX.1
3491 @vindex F_UNLCK
3492 @item F_UNLCK
3493 This macro is used to specify that the region is unlocked.
3494 @end table
3495
3496 As an example of a situation where file locking is useful, consider a
3497 program that can be run simultaneously by several different users, that
3498 logs status information to a common file.  One example of such a program
3499 might be a game that uses a file to keep track of high scores.  Another
3500 example might be a program that records usage or accounting information
3501 for billing purposes.
3502
3503 Having multiple copies of the program simultaneously writing to the
3504 file could cause the contents of the file to become mixed up.  But
3505 you can prevent this kind of problem by setting a write lock on the
3506 file before actually writing to the file.
3507
3508 If the program also needs to read the file and wants to make sure that
3509 the contents of the file are in a consistent state, then it can also use
3510 a read lock.  While the read lock is set, no other process can lock
3511 that part of the file for writing.
3512
3513 @c ??? This section could use an example program.
3514
3515 Remember that file locks are only a @emph{voluntary} protocol for
3516 controlling access to a file.  There is still potential for access to
3517 the file by programs that don't use the lock protocol.
3518
3519 @node Interrupt Input
3520 @section Interrupt-Driven Input
3521
3522 @cindex interrupt-driven input
3523 If you set the @code{O_ASYNC} status flag on a file descriptor
3524 (@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
3525 input or output becomes possible on that file descriptor.  The process
3526 or process group to receive the signal can be selected by using the
3527 @code{F_SETOWN} command to the @code{fcntl} function.  If the file
3528 descriptor is a socket, this also selects the recipient of @code{SIGURG}
3529 signals that are delivered when out-of-band data arrives on that socket;
3530 see @ref{Out-of-Band Data}.  (@code{SIGURG} is sent in any situation
3531 where @code{select} would report the socket as having an ``exceptional
3532 condition''.  @xref{Waiting for I/O}.)
3533
3534 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
3535 signals are sent to the foreground process group of the terminal.
3536 @xref{Job Control}.
3537
3538 @pindex fcntl.h
3539 The symbols in this section are defined in the header file
3540 @file{fcntl.h}.
3541
3542 @comment fcntl.h
3543 @comment BSD
3544 @deftypevr Macro int F_GETOWN
3545 This macro is used as the @var{command} argument to @code{fcntl}, to
3546 specify that it should get information about the process or process
3547 group to which @code{SIGIO} signals are sent.  (For a terminal, this is
3548 actually the foreground process group ID, which you can get using
3549 @code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
3550
3551 The return value is interpreted as a process ID; if negative, its
3552 absolute value is the process group ID.
3553
3554 The following @code{errno} error condition is defined for this command:
3555
3556 @table @code
3557 @item EBADF
3558 The @var{filedes} argument is invalid.
3559 @end table
3560 @end deftypevr
3561
3562 @comment fcntl.h
3563 @comment BSD
3564 @deftypevr Macro int F_SETOWN
3565 This macro is used as the @var{command} argument to @code{fcntl}, to
3566 specify that it should set the process or process group to which
3567 @code{SIGIO} signals are sent.  This command requires a third argument
3568 of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
3569 the call is:
3570
3571 @smallexample
3572 fcntl (@var{filedes}, F_SETOWN, @var{pid})
3573 @end smallexample
3574
3575 The @var{pid} argument should be a process ID.  You can also pass a
3576 negative number whose absolute value is a process group ID.
3577
3578 The return value from @code{fcntl} with this command is @math{-1}
3579 in case of error and some other value if successful.  The following
3580 @code{errno} error conditions are defined for this command:
3581
3582 @table @code
3583 @item EBADF
3584 The @var{filedes} argument is invalid.
3585
3586 @item ESRCH
3587 There is no process or process group corresponding to @var{pid}.
3588 @end table
3589 @end deftypevr
3590
3591 @c ??? This section could use an example program.
3592
3593 @node IOCTLs
3594 @section Generic I/O Control operations
3595 @cindex generic i/o control operations
3596 @cindex IOCTLs
3597
3598 The GNU system can handle most input/output operations on many different
3599 devices and objects in terms of a few file primitives - @code{read},
3600 @code{write} and @code{lseek}.  However, most devices also have a few
3601 peculiar operations which do not fit into this model. Such as:
3602
3603 @itemize @bullet
3604
3605 @item
3606 Changing the character font used on a terminal.
3607
3608 @item
3609 Telling a magnetic tape system to rewind or fast forward.  (Since they
3610 cannot move in byte increments, @code{lseek} is inapplicable).
3611
3612 @item
3613 Ejecting a disk from a drive.
3614
3615 @item
3616 Playing an audio track from a CD-ROM drive.
3617
3618 @item
3619 Maintaining routing tables for a network.
3620
3621 @end itemize
3622
3623 Although some such objects such as sockets and terminals
3624 @footnote{Actually, the terminal-specific functions are implemented with
3625 IOCTLs on many platforms.} have special functions of their own, it would
3626 not be practical to create functions for all these cases.
3627
3628 Instead these minor operations, known as @dfn{IOCTL}s, are assigned code
3629 numbers and multiplexed through the @code{ioctl} function, defined in
3630 @code{sys/ioctl.h}.  The code numbers themselves are defined in many
3631 different headers.
3632
3633 @comment sys/ioctl.h
3634 @comment BSD
3635 @deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{})
3636
3637 The @code{ioctl} function performs the generic I/O operation
3638 @var{command} on @var{filedes}.
3639
3640 A third argument is usually present, either a single number or a pointer
3641 to a structure.  The meaning of this argument, the returned value, and
3642 any error codes depends upon the command used.  Often @math{-1} is
3643 returned for a failure.
3644
3645 @end deftypefun
3646
3647 On some systems, IOCTLs used by different devices share the same numbers.
3648 Thus, although use of an inappropriate IOCTL @emph{usually} only produces
3649 an error, you should not attempt to use device-specific IOCTLs on an
3650 unknown device.
3651
3652 Most IOCTLs are OS-specific and/or only used in special system utilities,
3653 and are thus beyond the scope of this document.  For an example of the use
3654 of an IOCTL, see @ref{Out-of-Band Data}.