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