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