Update.
[glibc.git] / manual / llio.texi
blob6387eecbe062fd0ec87f0764685638088c610da3
1 @node Low-Level I/O, File System Interface, I/O on Streams, Top
2 @chapter Low-Level Input/Output
4 This chapter describes functions for performing low-level input/output
5 operations on file descriptors.  These functions include the primitives
6 for the higher-level I/O functions described in @ref{I/O on Streams}, as
7 well as functions for performing low-level control operations for which
8 there are no equivalents on streams.
10 Stream-level I/O is more flexible and usually more convenient;
11 therefore, programmers generally use the descriptor-level functions only
12 when necessary.  These are some of the usual reasons:
14 @itemize @bullet
15 @item
16 For reading binary files in large chunks.
18 @item
19 For reading an entire file into core before parsing it.
21 @item
22 To perform operations other than data transfer, which can only be done
23 with a descriptor.  (You can use @code{fileno} to get the descriptor
24 corresponding to a stream.)
26 @item
27 To pass descriptors to a child process.  (The child can create its own
28 stream to use a descriptor that it inherits, but cannot inherit a stream
29 directly.)
30 @end itemize
32 @menu
33 * Opening and Closing Files::           How to open and close file
34                                          descriptors.
35 * Truncating Files::                    Change the size of a file.
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 * Waiting for I/O::                     How to check for input or output
44                                          on multiple file descriptors.
45 * Synchronizing I/O::                   Making sure all I/O actions completed.
46 * Asynchronous I/O::                    Perform I/O in parallel.
47 * Control Operations::                  Various other operations on file
48                                          descriptors.
49 * Duplicating Descriptors::             Fcntl commands for duplicating
50                                          file descriptors.
51 * Descriptor Flags::                    Fcntl commands for manipulating
52                                          flags associated with file
53                                          descriptors.
54 * File Status Flags::                   Fcntl commands for manipulating
55                                          flags associated with open files.
56 * File Locks::                          Fcntl commands for implementing
57                                          file locking.
58 * Interrupt Input::                     Getting an asynchronous signal when
59                                          input arrives.
60 @end menu
63 @node Opening and Closing Files
64 @section Opening and Closing Files
66 @cindex opening a file descriptor
67 @cindex closing a file descriptor
68 This section describes the primitives for opening and closing files
69 using file descriptors.  The @code{open} and @code{creat} functions are
70 declared in the header file @file{fcntl.h}, while @code{close} is
71 declared in @file{unistd.h}.
72 @pindex unistd.h
73 @pindex fcntl.h
75 @comment fcntl.h
76 @comment POSIX.1
77 @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
78 The @code{open} function creates and returns a new file descriptor
79 for the file named by @var{filename}.  Initially, the file position
80 indicator for the file is at the beginning of the file.  The argument
81 @var{mode} is used only when a file is created, but it doesn't hurt
82 to supply the argument in any case.
84 The @var{flags} argument controls how the file is to be opened.  This is
85 a bit mask; you create the value by the bitwise OR of the appropriate
86 parameters (using the @samp{|} operator in C).
87 @xref{File Status Flags}, for the parameters available.
89 The normal return value from @code{open} is a non-negative integer file
90 descriptor.  In the case of an error, a value of @code{-1} is returned
91 instead.  In addition to the usual file name errors (@pxref{File
92 Name Errors}), the following @code{errno} error conditions are defined
93 for this function:
95 @table @code
96 @item EACCES
97 The file exists but is not readable/writable as requested by the @var{flags}
98 argument, the file does not exist and the directory is unwritable so
99 it cannot be created.
101 @item EEXIST
102 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
103 exists.
105 @item EINTR
106 The @code{open} operation was interrupted by a signal.
107 @xref{Interrupted Primitives}.
109 @item EISDIR
110 The @var{flags} argument specified write access, and the file is a directory.
112 @item EMFILE
113 The process has too many files open.
114 The maximum number of file descriptors is controlled by the
115 @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
117 @item ENFILE
118 The entire system, or perhaps the file system which contains the
119 directory, cannot support any additional open files at the moment.
120 (This problem cannot happen on the GNU system.)
122 @item ENOENT
123 The named file does not exist, and @code{O_CREAT} is not specified.
125 @item ENOSPC
126 The directory or file system that would contain the new file cannot be
127 extended, because there is no disk space left.
129 @item ENXIO
130 @code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
131 argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
132 FIFOs}), and no process has the file open for reading.
134 @item EROFS
135 The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
136 @code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
137 or @code{O_CREAT} is set and the file does not already exist.
138 @end table
140 @c !!! umask
142 If on a 32 bits machine the sources are translated with
143 @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
144 descriptor opened in the large file mode which enables the file handling
145 functions to use files up to @math{2^63} bytes in size and offset from
146 @math{-2^63} to @math{2^63}.  This happens transparently for the user
147 since all of the lowlevel file handling functions are equally replaced.
149 This function is a cancelation point in multi-threaded programs.  This
150 is a problem if the thread allocates some resources (like memory, file
151 descriptors, semaphores or whatever) at the time @code{open} is
152 called.  If the thread gets canceled these resources stay allocated
153 until the program ends.  To avoid this calls to @code{open} should be
154 protected using cancelation handlers.
155 @c ref pthread_cleanup_push / pthread_cleanup_pop
157 The @code{open} function is the underlying primitive for the @code{fopen}
158 and @code{freopen} functions, that create streams.
159 @end deftypefun
161 @comment fcntl.h
162 @comment Unix98
163 @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
164 This function is similar to @code{open}.  It returns a file descriptor
165 which can be used to access the file named by @var{filename}.  The only
166 the difference is that on 32 bits systems the file is opened in the
167 large file mode.  I.e., file length and file offsets can exceed 31 bits.
169 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
170 function is actually available under the name @code{open}.  I.e., the
171 new, extended API using 64 bit file sizes and offsets transparently
172 replaces the old API.
173 @end deftypefun
175 @comment fcntl.h
176 @comment POSIX.1
177 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
178 This function is obsolete.  The call:
180 @smallexample
181 creat (@var{filename}, @var{mode})
182 @end smallexample
184 @noindent
185 is equivalent to:
187 @smallexample
188 open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
189 @end smallexample
191 If on a 32 bits machine the sources are translated with
192 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
193 descriptor opened in the large file mode which enables the file handling
194 functions to use files up to @math{2^63} in size and offset from
195 @math{-2^63} to @math{2^63}.  This happens transparently for the user
196 since all of the lowlevel file handling functions are equally replaced.
197 @end deftypefn
199 @comment fcntl.h
200 @comment Unix98
201 @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
202 This function is similar to @code{creat}.  It returns a file descriptor
203 which can be used to access the file named by @var{filename}.  The only
204 the difference is that on 32 bits systems the file is opened in the
205 large file mode.  I.e., file length and file offsets can exceed 31 bits.
207 To use this file descriptor one must not use the normal operations but
208 instead the counterparts named @code{*64}, e.g., @code{read64}.
210 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
211 function is actually available under the name @code{open}.  I.e., the
212 new, extended API using 64 bit file sizes and offsets transparently
213 replaces the old API.
214 @end deftypefn
216 @comment unistd.h
217 @comment POSIX.1
218 @deftypefun int close (int @var{filedes})
219 The function @code{close} closes the file descriptor @var{filedes}.
220 Closing a file has the following consequences:
222 @itemize @bullet
223 @item
224 The file descriptor is deallocated.
226 @item
227 Any record locks owned by the process on the file are unlocked.
229 @item
230 When all file descriptors associated with a pipe or FIFO have been closed,
231 any unread data is discarded.
232 @end itemize
234 This function is a cancelation point in multi-threaded programs.  This
235 is a problem if the thread allocates some resources (like memory, file
236 descriptors, semaphores or whatever) at the time @code{close} is
237 called.  If the thread gets canceled these resources stay allocated
238 until the program ends.  To avoid this calls to @code{close} should be
239 protected using cancelation handlers.
240 @c ref pthread_cleanup_push / pthread_cleanup_pop
242 The normal return value from @code{close} is @code{0}; a value of @code{-1}
243 is returned in case of failure.  The following @code{errno} error
244 conditions are defined for this function:
246 @table @code
247 @item EBADF
248 The @var{filedes} argument is not a valid file descriptor.
250 @item EINTR
251 The @code{close} call was interrupted by a signal.
252 @xref{Interrupted Primitives}.
253 Here is an example of how to handle @code{EINTR} properly:
255 @smallexample
256 TEMP_FAILURE_RETRY (close (desc));
257 @end smallexample
259 @item ENOSPC
260 @itemx EIO
261 @itemx EDQUOT
262 When the file is accessed by NFS, these errors from @code{write} can sometimes
263 not be detected until @code{close}.  @xref{I/O Primitives}, for details
264 on their meaning.
265 @end table
267 Please note that there is @emph{no} separate @code{close64} function.
268 This is not necessary since this function does not determine nor depend
269 on the mode of the file.  The kernel which performs the @code{close}
270 operation knows for which mode the descriptor is used and can handle
271 this situation.
272 @end deftypefun
274 To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
275 of trying to close its underlying file descriptor with @code{close}.
276 This flushes any buffered output and updates the stream object to
277 indicate that it is closed.
280 @node Truncating Files
281 @section Change the size of a file
283 In some situations it is useful to explicitly determine the size of a
284 file.  Since the 4.2BSD days there is a function to truncate a file to
285 at most a given number of bytes and POSIX defines one additional
286 function.  The prototypes for these functions are in @file{unistd.h}.
288 @comment unistd.h
289 @comment X/Open
290 @deftypefun int truncate (const char *@var{name}, off_t @var{length})
291 The @code{truncation} function truncates the file named by @var{name} to
292 at most @var{length} bytes.  I.e., if the file was larger before the
293 extra bytes are stripped of.  If the file was small or equal to
294 @var{length} in size before nothing is done.  The file must be writable
295 by the user to perform this operation.
297 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
298 @code{truncate} function is in fact @code{truncate64} and the type
299 @code{off_t} has 64 bits which makes it possible to handle files up to
300 @math{2^63} bytes in length.
302 The return value is zero is everything went ok.  Otherwise the return
303 value is @math{-1} and the global variable @var{errno} is set to:
304 @table @code
305 @item EACCES
306 The file is not accessible to the user.
307 @item EINVAL
308 The @var{length} value is illegal.
309 @item EISDIR
310 The object named by @var{name} is a directory.
311 @item ENOENT
312 The file named by @var{name} does not exist.
313 @item ENOTDIR
314 One part of the @var{name} is not a directory.
315 @end table
317 This function was introduced in 4.2BSD but also was available in later
318 @w{System V} systems.  It is not added to POSIX since the authors felt
319 it is only of marginally additional utility.  See below.
320 @end deftypefun
322 @comment unistd.h
323 @comment Unix98
324 @deftypefun int truncate64 (const char *@var{name}, off64_t @var{length})
325 This function is similar to the @code{truncate} function.  The
326 difference is that the @var{length} argument is 64 bits wide even on 32
327 bits machines which allows to handle file with a size up to @math{2^63}
328 bytes.
330 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
331 32 bits machine this function is actually available under the name
332 @code{truncate} and so transparently replaces the 32 bits interface.
333 @end deftypefun
335 @comment unistd.h
336 @comment POSIX
337 @deftypefun int ftruncate (int @var{fd}, off_t @var{length})
338 The @code{ftruncate} function is similar to the @code{truncate}
339 function.  The main difference is that it takes a descriptor for an
340 opened file instead of a file name to identify the object.  The file
341 must be opened for writing to successfully carry out the operation.
343 The POSIX standard leaves it implementation defined what happens if the
344 specified new @var{length} of the file is bigger than the original size.
345 The @code{ftruncate} function might simply leave the file alone and do
346 nothing or it can increase the size to the desired size.  In this later
347 case the extended area should be zero-filled.  So using @code{ftruncate}
348 is no reliable way to increase the file size but if it is possible it is
349 probably the fastest way.  The function also operates on POSIX shared
350 memory segments if these are implemented by the system.
352 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
353 @code{ftruncate} function is in fact @code{ftruncate64} and the type
354 @code{off_t} has 64 bits which makes it possible to handle files up to
355 @math{2^63} bytes in length.
357 On success the function returns zero.  Otherwise it returns @math{-1}
358 and set @var{errno} to one of these values:
359 @table @code
360 @item EBADF
361 @var{fd} is no valid file descriptor or is not opened for writing.
362 @item EINVAL
363 The object referred to by @var{fd} does not permit this operation.
364 @item EROFS
365 The file is on a read-only file system.
366 @end table
367 @end deftypefun
369 @comment unistd.h
370 @comment Unix98
371 @deftypefun int ftruncate64 (int @var{id}, off64_t @var{length})
372 This function is similar to the @code{ftruncate} function.  The
373 difference is that the @var{length} argument is 64 bits wide even on 32
374 bits machines which allows to handle file with a size up to @math{2^63}
375 bytes.
377 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
378 32 bits machine this function is actually available under the name
379 @code{ftruncate} and so transparently replaces the 32 bits interface.
380 @end deftypefun
382 @node I/O Primitives
383 @section Input and Output Primitives
385 This section describes the functions for performing primitive input and
386 output operations on file descriptors: @code{read}, @code{write}, and
387 @code{lseek}.  These functions are declared in the header file
388 @file{unistd.h}.
389 @pindex unistd.h
391 @comment unistd.h
392 @comment POSIX.1
393 @deftp {Data Type} ssize_t
394 This data type is used to represent the sizes of blocks that can be
395 read or written in a single operation.  It is similar to @code{size_t},
396 but must be a signed type.
397 @end deftp
399 @cindex reading from a file descriptor
400 @comment unistd.h
401 @comment POSIX.1
402 @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
403 The @code{read} function reads up to @var{size} bytes from the file
404 with descriptor @var{filedes}, storing the results in the @var{buffer}.
405 (This is not necessarily a character string and there is no terminating
406 null character added.)
408 @cindex end-of-file, on a file descriptor
409 The return value is the number of bytes actually read.  This might be
410 less than @var{size}; for example, if there aren't that many bytes left
411 in the file or if there aren't that many bytes immediately available.
412 The exact behavior depends on what kind of file it is.  Note that
413 reading less than @var{size} bytes is not an error.
415 A value of zero indicates end-of-file (except if the value of the
416 @var{size} argument is also zero).  This is not considered an error.
417 If you keep calling @code{read} while at end-of-file, it will keep
418 returning zero and doing nothing else.
420 If @code{read} returns at least one character, there is no way you can
421 tell whether end-of-file was reached.  But if you did reach the end, the
422 next read will return zero.
424 In case of an error, @code{read} returns @code{-1}.  The following
425 @code{errno} error conditions are defined for this function:
427 @table @code
428 @item EAGAIN
429 Normally, when no input is immediately available, @code{read} waits for
430 some input.  But if the @code{O_NONBLOCK} flag is set for the file
431 (@pxref{File Status Flags}), @code{read} returns immediately without
432 reading any data, and reports this error.
434 @strong{Compatibility Note:} Most versions of BSD Unix use a different
435 error code for this: @code{EWOULDBLOCK}.  In the GNU library,
436 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
437 which name you use.
439 On some systems, reading a large amount of data from a character special
440 file can also fail with @code{EAGAIN} if the kernel cannot find enough
441 physical memory to lock down the user's pages.  This is limited to
442 devices that transfer with direct memory access into the user's memory,
443 which means it does not include terminals, since they always use
444 separate buffers inside the kernel.  This problem never happens in the
445 GNU system.
447 Any condition that could result in @code{EAGAIN} can instead result in a
448 successful @code{read} which returns fewer bytes than requested.
449 Calling @code{read} again immediately would result in @code{EAGAIN}.
451 @item EBADF
452 The @var{filedes} argument is not a valid file descriptor,
453 or is not open for reading.
455 @item EINTR
456 @code{read} was interrupted by a signal while it was waiting for input.
457 @xref{Interrupted Primitives}.  A signal will not necessary cause
458 @code{read} to return @code{EINTR}; it may instead result in a
459 successful @code{read} which returns fewer bytes than requested.
461 @item EIO
462 For many devices, and for disk files, this error code indicates
463 a hardware error.
465 @code{EIO} also occurs when a background process tries to read from the
466 controlling terminal, and the normal action of stopping the process by
467 sending it a @code{SIGTTIN} signal isn't working.  This might happen if
468 signal is being blocked or ignored, or because the process group is
469 orphaned.  @xref{Job Control}, for more information about job control,
470 and @ref{Signal Handling}, for information about signals.
471 @end table
473 Please note that there is no function named @code{read64}.  This is not
474 necessary since this function does not directly modify or handle the
475 possibly wide file offset.  Since the kernel handles this state
476 internally the @code{read} function can be used for all cases.
478 This function is a cancelation point in multi-threaded programs.  This
479 is a problem if the thread allocates some resources (like memory, file
480 descriptors, semaphores or whatever) at the time @code{read} is
481 called.  If the thread gets canceled these resources stay allocated
482 until the program ends.  To avoid this calls to @code{read} should be
483 protected using cancelation handlers.
484 @c ref pthread_cleanup_push / pthread_cleanup_pop
486 The @code{read} function is the underlying primitive for all of the
487 functions that read from streams, such as @code{fgetc}.
488 @end deftypefun
490 @comment unistd.h
491 @comment Unix98
492 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
493 The @code{pread} function is similar to the @code{read} function.  The
494 first three arguments are identical and also the return values and error
495 codes correspond.
497 The difference is the fourth argument and its handling.  The data block
498 is not read from the current position of the file descriptor
499 @code{filedes}.  Instead the data is read from the file starting at
500 position @var{offset}.  The position of the file descriptor itself is
501 not effected by the operation.  The value is the same as before the call.
503 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
504 @code{pread} function is in fact @code{pread64} and the type
505 @code{off_t} has 64 bits which makes it possible to handle files up to
506 @math{2^63} bytes in length.
508 The return value of @code{pread} describes the number of bytes read.
509 In the error case it returns @math{-1} like @code{read} does and the
510 error codes are also the same.  Only there are a few more error codes:
511 @table @code
512 @item EINVAL
513 The value given for @var{offset} is negative and therefore illegal.
515 @item ESPIPE
516 The file descriptor @var{filedes} is associate with a pipe or a FIFO and
517 this device does not allow positioning of the file pointer.
518 @end table
520 The function is an extension defined in the Unix Single Specification
521 version 2.
522 @end deftypefun
524 @comment unistd.h
525 @comment Unix98
526 @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
527 This function is similar to the @code{pread} function.  The difference
528 is that the @var{offset} parameter is of type @code{off64_t} instead of
529 @code{off_t} which makes it possible on 32 bits machines to address
530 files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
531 file descriptor @code{filedes} must be opened using @code{open64} since
532 otherwise the large offsets possible with @code{off64_t} will lead to
533 errors with a descriptor in small file mode.
535 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
536 32 bits machine this function is actually available under the name
537 @code{pread} and so transparently replaces the 32 bits interface.
538 @end deftypefun
540 @cindex writing to a file descriptor
541 @comment unistd.h
542 @comment POSIX.1
543 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
544 The @code{write} function writes up to @var{size} bytes from
545 @var{buffer} to the file with descriptor @var{filedes}.  The data in
546 @var{buffer} is not necessarily a character string and a null character is
547 output like any other character.
549 The return value is the number of bytes actually written.  This may be
550 @var{size}, but can always be smaller.  Your program should always call
551 @code{write} in a loop, iterating until all the data is written.
553 Once @code{write} returns, the data is enqueued to be written and can be
554 read back right away, but it is not necessarily written out to permanent
555 storage immediately.  You can use @code{fsync} when you need to be sure
556 your data has been permanently stored before continuing.  (It is more
557 efficient for the system to batch up consecutive writes and do them all
558 at once when convenient.  Normally they will always be written to disk
559 within a minute or less.)  Modern systems provide another function
560 @code{fdatasync} which guarantees integrity only for the file data and
561 is therefore faster.
562 @c !!! xref fsync, fdatasync
563 You can use the @code{O_FSYNC} open mode to make @code{write} always
564 store the data to disk before returning; @pxref{Operating Modes}.
566 In the case of an error, @code{write} returns @code{-1}.  The following
567 @code{errno} error conditions are defined for this function:
569 @table @code
570 @item EAGAIN
571 Normally, @code{write} blocks until the write operation is complete.
572 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
573 Operations}), it returns immediately without writing any data, and
574 reports this error.  An example of a situation that might cause the
575 process to block on output is writing to a terminal device that supports
576 flow control, where output has been suspended by receipt of a STOP
577 character.
579 @strong{Compatibility Note:} Most versions of BSD Unix use a different
580 error code for this: @code{EWOULDBLOCK}.  In the GNU library,
581 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
582 which name you use.
584 On some systems, writing a large amount of data from a character special
585 file can also fail with @code{EAGAIN} if the kernel cannot find enough
586 physical memory to lock down the user's pages.  This is limited to
587 devices that transfer with direct memory access into the user's memory,
588 which means it does not include terminals, since they always use
589 separate buffers inside the kernel.  This problem does not arise in the
590 GNU system.
592 @item EBADF
593 The @var{filedes} argument is not a valid file descriptor,
594 or is not open for writing.
596 @item EFBIG
597 The size of the file would become larger than the implementation can support.
599 @item EINTR
600 The @code{write} operation was interrupted by a signal while it was
601 blocked waiting for completion.  A signal will not necessary cause
602 @code{write} to return @code{EINTR}; it may instead result in a
603 successful @code{write} which writes fewer bytes than requested.
604 @xref{Interrupted Primitives}.
606 @item EIO
607 For many devices, and for disk files, this error code indicates
608 a hardware error.
610 @item ENOSPC
611 The device containing the file is full.
613 @item EPIPE
614 This error is returned when you try to write to a pipe or FIFO that
615 isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
616 signal is also sent to the process; see @ref{Signal Handling}.
617 @end table
619 Unless you have arranged to prevent @code{EINTR} failures, you should
620 check @code{errno} after each failing call to @code{write}, and if the
621 error was @code{EINTR}, you should simply repeat the call.
622 @xref{Interrupted Primitives}.  The easy way to do this is with the
623 macro @code{TEMP_FAILURE_RETRY}, as follows:
625 @smallexample
626 nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
627 @end smallexample
629 Please note that there is no function named @code{write64}.  This is not
630 necessary since this function does not directly modify or handle the
631 possibly wide file offset.  Since the kernel handles this state
632 internally the @code{write} function can be used for all cases.
634 This function is a cancelation point in multi-threaded programs.  This
635 is a problem if the thread allocates some resources (like memory, file
636 descriptors, semaphores or whatever) at the time @code{write} is
637 called.  If the thread gets canceled these resources stay allocated
638 until the program ends.  To avoid this calls to @code{write} should be
639 protected using cancelation handlers.
640 @c ref pthread_cleanup_push / pthread_cleanup_pop
642 The @code{write} function is the underlying primitive for all of the
643 functions that write to streams, such as @code{fputc}.
644 @end deftypefun
646 @comment unistd.h
647 @comment Unix98
648 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
649 The @code{pwrite} function is similar to the @code{write} function.  The
650 first three arguments are identical and also the return values and error
651 codes correspond.
653 The difference is the fourth argument and its handling.  The data block
654 is not written to the current position of the file descriptor
655 @code{filedes}.  Instead the data is written to the file starting at
656 position @var{offset}.  The position of the file descriptor itself is
657 not effected by the operation.  The value is the same as before the call.
659 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
660 @code{pwrite} function is in fact @code{pwrite64} and the type
661 @code{off_t} has 64 bits which makes it possible to handle files up to
662 @math{2^63} bytes in length.
664 The return value of @code{pwrite} describes the number of written bytes.
665 In the error case it returns @math{-1} like @code{write} does and the
666 error codes are also the same.  Only there are a few more error codes:
667 @table @code
668 @item EINVAL
669 The value given for @var{offset} is negative and therefore illegal.
671 @item ESPIPE
672 The file descriptor @var{filedes} is associate with a pipe or a FIFO and
673 this device does not allow positioning of the file pointer.
674 @end table
676 The function is an extension defined in the Unix Single Specification
677 version 2.
678 @end deftypefun
680 @comment unistd.h
681 @comment Unix98
682 @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
683 This function is similar to the @code{pwrite} function.  The difference
684 is that the @var{offset} parameter is of type @code{off64_t} instead of
685 @code{off_t} which makes it possible on 32 bits machines to address
686 files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
687 file descriptor @code{filedes} must be opened using @code{open64} since
688 otherwise the large offsets possible with @code{off64_t} will lead to
689 errors with a descriptor in small file mode.
691 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
692 32 bits machine this function is actually available under the name
693 @code{pwrite} and so transparently replaces the 32 bits interface.
694 @end deftypefun
697 @node File Position Primitive
698 @section Setting the File Position of a Descriptor
700 Just as you can set the file position of a stream with @code{fseek}, you
701 can set the file position of a descriptor with @code{lseek}.  This
702 specifies the position in the file for the next @code{read} or
703 @code{write} operation.  @xref{File Positioning}, for more information
704 on the file position and what it means.
706 To read the current file position value from a descriptor, use
707 @code{lseek (@var{desc}, 0, SEEK_CUR)}.
709 @cindex file positioning on a file descriptor
710 @cindex positioning a file descriptor
711 @cindex seeking on a file descriptor
712 @comment unistd.h
713 @comment POSIX.1
714 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
715 The @code{lseek} function is used to change the file position of the
716 file with descriptor @var{filedes}.
718 The @var{whence} argument specifies how the @var{offset} should be
719 interpreted in the same way as for the @code{fseek} function, and must be
720 one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
721 @code{SEEK_END}.
723 @table @code
724 @item SEEK_SET
725 Specifies that @var{whence} is a count of characters from the beginning
726 of the file.
728 @item SEEK_CUR
729 Specifies that @var{whence} is a count of characters from the current
730 file position.  This count may be positive or negative.
732 @item SEEK_END
733 Specifies that @var{whence} is a count of characters from the end of
734 the file.  A negative count specifies a position within the current
735 extent of the file; a positive count specifies a position past the
736 current end.  If you set the position past the current end, and
737 actually write data, you will extend the file with zeros up to that
738 position.@end table
740 The return value from @code{lseek} is normally the resulting file
741 position, measured in bytes from the beginning of the file.
742 You can use this feature together with @code{SEEK_CUR} to read the
743 current file position.
745 If you want to append to the file, setting the file position to the
746 current end of file with @code{SEEK_END} is not sufficient.  Another
747 process may write more data after you seek but before you write,
748 extending the file so the position you write onto clobbers their data.
749 Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
751 You can set the file position past the current end of the file.  This
752 does not by itself make the file longer; @code{lseek} never changes the
753 file.  But subsequent output at that position will extend the file.
754 Characters between the previous end of file and the new position are
755 filled with zeros.  Extending the file in this way can create a
756 ``hole'': the blocks of zeros are not actually allocated on disk, so the
757 file takes up less space than it appears so; it is then called a
758 ``sparse file''.
759 @cindex sparse files
760 @cindex holes in files
762 If the file position cannot be changed, or the operation is in some way
763 invalid, @code{lseek} returns a value of @code{-1}.  The following
764 @code{errno} error conditions are defined for this function:
766 @table @code
767 @item EBADF
768 The @var{filedes} is not a valid file descriptor.
770 @item EINVAL
771 The @var{whence} argument value is not valid, or the resulting
772 file offset is not valid.  A file offset is invalid.
774 @item ESPIPE
775 The @var{filedes} corresponds to an object that cannot be positioned,
776 such as a pipe, FIFO or terminal device.  (POSIX.1 specifies this error
777 only for pipes and FIFOs, but in the GNU system, you always get
778 @code{ESPIPE} if the object is not seekable.)
779 @end table
781 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
782 @code{lseek} function is in fact @code{lseek64} and the type
783 @code{off_t} has 64 bits which makes it possible to handle files up to
784 @math{2^63} bytes in length.
786 This function is a cancelation point in multi-threaded programs.  This
787 is a problem if the thread allocates some resources (like memory, file
788 descriptors, semaphores or whatever) at the time @code{lseek} is
789 called.  If the thread gets canceled these resources stay allocated
790 until the program ends.  To avoid this calls to @code{lseek} should be
791 protected using cancelation handlers.
792 @c ref pthread_cleanup_push / pthread_cleanup_pop
794 The @code{lseek} function is the underlying primitive for the
795 @code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
796 @code{rewind} functions, which operate on streams instead of file
797 descriptors.
798 @end deftypefun
800 @comment unistd.h
801 @comment Unix98
802 @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
803 This function is similar to the @code{lseek} function.  The difference
804 is that the @var{offset} parameter is of type @code{off64_t} instead of
805 @code{off_t} which makes it possible on 32 bits machines to address
806 files larger than @math{2^31} bytes and up to @math{2^63} bytes.  The
807 file descriptor @code{filedes} must be opened using @code{open64} since
808 otherwise the large offsets possible with @code{off64_t} will lead to
809 errors with a descriptor in small file mode.
811 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
812 32 bits machine this function is actually available under the name
813 @code{lseek} and so transparently replaces the 32 bits interface.
814 @end deftypefun
816 You can have multiple descriptors for the same file if you open the file
817 more than once, or if you duplicate a descriptor with @code{dup}.
818 Descriptors that come from separate calls to @code{open} have independent
819 file positions; using @code{lseek} on one descriptor has no effect on the
820 other.  For example,
822 @smallexample
823 @group
825   int d1, d2;
826   char buf[4];
827   d1 = open ("foo", O_RDONLY);
828   d2 = open ("foo", O_RDONLY);
829   lseek (d1, 1024, SEEK_SET);
830   read (d2, buf, 4);
832 @end group
833 @end smallexample
835 @noindent
836 will read the first four characters of the file @file{foo}.  (The
837 error-checking code necessary for a real program has been omitted here
838 for brevity.)
840 By contrast, descriptors made by duplication share a common file
841 position with the original descriptor that was duplicated.  Anything
842 which alters the file position of one of the duplicates, including
843 reading or writing data, affects all of them alike.  Thus, for example,
845 @smallexample
847   int d1, d2, d3;
848   char buf1[4], buf2[4];
849   d1 = open ("foo", O_RDONLY);
850   d2 = dup (d1);
851   d3 = dup (d2);
852   lseek (d3, 1024, SEEK_SET);
853   read (d1, buf1, 4);
854   read (d2, buf2, 4);
856 @end smallexample
858 @noindent
859 will read four characters starting with the 1024'th character of
860 @file{foo}, and then four more characters starting with the 1028'th
861 character.
863 @comment sys/types.h
864 @comment POSIX.1
865 @deftp {Data Type} off_t
866 This is an arithmetic data type used to represent file sizes.
867 In the GNU system, this is equivalent to @code{fpos_t} or @code{long int}.
869 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
870 is transparently replaced by @code{off64_t}.
871 @end deftp
873 @comment sys/types.h
874 @comment Unix98
875 @deftp {Data Type} off64_t
876 This type is used similar to @code{off_t}.  The difference is that even
877 on 32 bits machines, where the @code{off_t} type would have 32 bits,
878 @code{off64_t} has 64 bits and so is able to address files up to
879 @math{2^63} bytes in length.
881 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
882 available under the name @code{off_t}.
883 @end deftp
885 These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
886 of compatibility with older BSD systems.  They are defined in two
887 different header files: @file{fcntl.h} and @file{sys/file.h}.
889 @table @code
890 @item L_SET
891 An alias for @code{SEEK_SET}.
893 @item L_INCR
894 An alias for @code{SEEK_CUR}.
896 @item L_XTND
897 An alias for @code{SEEK_END}.
898 @end table
900 @node Descriptors and Streams
901 @section Descriptors and Streams
902 @cindex streams, and file descriptors
903 @cindex converting file descriptor to stream
904 @cindex extracting file descriptor from stream
906 Given an open file descriptor, you can create a stream for it with the
907 @code{fdopen} function.  You can get the underlying file descriptor for
908 an existing stream with the @code{fileno} function.  These functions are
909 declared in the header file @file{stdio.h}.
910 @pindex stdio.h
912 @comment stdio.h
913 @comment POSIX.1
914 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
915 The @code{fdopen} function returns a new stream for the file descriptor
916 @var{filedes}.
918 The @var{opentype} argument is interpreted in the same way as for the
919 @code{fopen} function (@pxref{Opening Streams}), except that
920 the @samp{b} option is not permitted; this is because GNU makes no
921 distinction between text and binary files.  Also, @code{"w"} and
922 @code{"w+"} do not cause truncation of the file; these have affect only
923 when opening a file, and in this case the file has already been opened.
924 You must make sure that the @var{opentype} argument matches the actual
925 mode of the open file descriptor.
927 The return value is the new stream.  If the stream cannot be created
928 (for example, if the modes for the file indicated by the file descriptor
929 do not permit the access specified by the @var{opentype} argument), a
930 null pointer is returned instead.
932 In some other systems, @code{fdopen} may fail to detect that the modes
933 for file descriptor do not permit the access specified by
934 @code{opentype}.  The GNU C library always checks for this.
935 @end deftypefun
937 For an example showing the use of the @code{fdopen} function,
938 see @ref{Creating a Pipe}.
940 @comment stdio.h
941 @comment POSIX.1
942 @deftypefun int fileno (FILE *@var{stream})
943 This function returns the file descriptor associated with the stream
944 @var{stream}.  If an error is detected (for example, if the @var{stream}
945 is not valid) or if @var{stream} does not do I/O to a file,
946 @code{fileno} returns @code{-1}.
947 @end deftypefun
949 @cindex standard file descriptors
950 @cindex file descriptors, standard
951 There are also symbolic constants defined in @file{unistd.h} for the
952 file descriptors belonging to the standard streams @code{stdin},
953 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
954 @pindex unistd.h
956 @comment unistd.h
957 @comment POSIX.1
958 @table @code
959 @item STDIN_FILENO
960 @vindex STDIN_FILENO
961 This macro has value @code{0}, which is the file descriptor for
962 standard input.
963 @cindex standard input file descriptor
965 @comment unistd.h
966 @comment POSIX.1
967 @item STDOUT_FILENO
968 @vindex STDOUT_FILENO
969 This macro has value @code{1}, which is the file descriptor for
970 standard output.
971 @cindex standard output file descriptor
973 @comment unistd.h
974 @comment POSIX.1
975 @item STDERR_FILENO
976 @vindex STDERR_FILENO
977 This macro has value @code{2}, which is the file descriptor for
978 standard error output.
979 @end table
980 @cindex standard error file descriptor
982 @node Stream/Descriptor Precautions
983 @section Dangers of Mixing Streams and Descriptors
984 @cindex channels
985 @cindex streams and descriptors
986 @cindex descriptors and streams
987 @cindex mixing descriptors and streams
989 You can have multiple file descriptors and streams (let's call both
990 streams and descriptors ``channels'' for short) connected to the same
991 file, but you must take care to avoid confusion between channels.  There
992 are two cases to consider: @dfn{linked} channels that share a single
993 file position value, and @dfn{independent} channels that have their own
994 file positions.
996 It's best to use just one channel in your program for actual data
997 transfer to any given file, except when all the access is for input.
998 For example, if you open a pipe (something you can only do at the file
999 descriptor level), either do all I/O with the descriptor, or construct a
1000 stream from the descriptor with @code{fdopen} and then do all I/O with
1001 the stream.
1003 @menu
1004 * Linked Channels::        Dealing with channels sharing a file position.
1005 * Independent Channels::   Dealing with separately opened, unlinked channels.
1006 * Cleaning Streams::       Cleaning a stream makes it safe to use
1007                             another channel.
1008 @end menu
1010 @node Linked Channels
1011 @subsection Linked Channels
1012 @cindex linked channels
1014 Channels that come from a single opening share the same file position;
1015 we call them @dfn{linked} channels.  Linked channels result when you
1016 make a stream from a descriptor using @code{fdopen}, when you get a
1017 descriptor from a stream with @code{fileno}, when you copy a descriptor
1018 with @code{dup} or @code{dup2}, and when descriptors are inherited
1019 during @code{fork}.  For files that don't support random access, such as
1020 terminals and pipes, @emph{all} channels are effectively linked.  On
1021 random-access files, all append-type output streams are effectively
1022 linked to each other.
1024 @cindex cleaning up a stream
1025 If you have been using a stream for I/O, and you want to do I/O using
1026 another channel (either a stream or a descriptor) that is linked to it,
1027 you must first @dfn{clean up} the stream that you have been using.
1028 @xref{Cleaning Streams}.
1030 Terminating a process, or executing a new program in the process,
1031 destroys all the streams in the process.  If descriptors linked to these
1032 streams persist in other processes, their file positions become
1033 undefined as a result.  To prevent this, you must clean up the streams
1034 before destroying them.
1036 @node Independent Channels
1037 @subsection Independent Channels
1038 @cindex independent channels
1040 When you open channels (streams or descriptors) separately on a seekable
1041 file, each channel has its own file position.  These are called
1042 @dfn{independent channels}.
1044 The system handles each channel independently.  Most of the time, this
1045 is quite predictable and natural (especially for input): each channel
1046 can read or write sequentially at its own place in the file.  However,
1047 if some of the channels are streams, you must take these precautions:
1049 @itemize @bullet
1050 @item
1051 You should clean an output stream after use, before doing anything else
1052 that might read or write from the same part of the file.
1054 @item
1055 You should clean an input stream before reading data that may have been
1056 modified using an independent channel.  Otherwise, you might read
1057 obsolete data that had been in the stream's buffer.
1058 @end itemize
1060 If you do output to one channel at the end of the file, this will
1061 certainly leave the other independent channels positioned somewhere
1062 before the new end.  You cannot reliably set their file positions to the
1063 new end of file before writing, because the file can always be extended
1064 by another process between when you set the file position and when you
1065 write the data.  Instead, use an append-type descriptor or stream; they
1066 always output at the current end of the file.  In order to make the
1067 end-of-file position accurate, you must clean the output channel you
1068 were using, if it is a stream.
1070 It's impossible for two channels to have separate file pointers for a
1071 file that doesn't support random access.  Thus, channels for reading or
1072 writing such files are always linked, never independent.  Append-type
1073 channels are also always linked.  For these channels, follow the rules
1074 for linked channels; see @ref{Linked Channels}.
1076 @node Cleaning Streams
1077 @subsection Cleaning Streams
1079 On the GNU system, you can clean up any stream with @code{fclean}:
1081 @comment stdio.h
1082 @comment GNU
1083 @deftypefun int fclean (FILE *@var{stream})
1084 Clean up the stream @var{stream} so that its buffer is empty.  If
1085 @var{stream} is doing output, force it out.  If @var{stream} is doing
1086 input, give the data in the buffer back to the system, arranging to
1087 reread it.
1088 @end deftypefun
1090 On other systems, you can use @code{fflush} to clean a stream in most
1091 cases.
1093 You can skip the @code{fclean} or @code{fflush} if you know the stream
1094 is already clean.  A stream is clean whenever its buffer is empty.  For
1095 example, an unbuffered stream is always clean.  An input stream that is
1096 at end-of-file is clean.  A line-buffered stream is clean when the last
1097 character output was a newline.
1099 There is one case in which cleaning a stream is impossible on most
1100 systems.  This is when the stream is doing input from a file that is not
1101 random-access.  Such streams typically read ahead, and when the file is
1102 not random access, there is no way to give back the excess data already
1103 read.  When an input stream reads from a random-access file,
1104 @code{fflush} does clean the stream, but leaves the file pointer at an
1105 unpredictable place; you must set the file pointer before doing any
1106 further I/O.  On the GNU system, using @code{fclean} avoids both of
1107 these problems.
1109 Closing an output-only stream also does @code{fflush}, so this is a
1110 valid way of cleaning an output stream.  On the GNU system, closing an
1111 input stream does @code{fclean}.
1113 You need not clean a stream before using its descriptor for control
1114 operations such as setting terminal modes; these operations don't affect
1115 the file position and are not affected by it.  You can use any
1116 descriptor for these operations, and all channels are affected
1117 simultaneously.  However, text already ``output'' to a stream but still
1118 buffered by the stream will be subject to the new terminal modes when
1119 subsequently flushed.  To make sure ``past'' output is covered by the
1120 terminal settings that were in effect at the time, flush the output
1121 streams for that terminal before setting the modes.  @xref{Terminal
1122 Modes}.
1124 @node Waiting for I/O
1125 @section Waiting for Input or Output
1126 @cindex waiting for input or output
1127 @cindex multiplexing input
1128 @cindex input from multiple files
1130 Sometimes a program needs to accept input on multiple input channels
1131 whenever input arrives.  For example, some workstations may have devices
1132 such as a digitizing tablet, function button box, or dial box that are
1133 connected via normal asynchronous serial interfaces; good user interface
1134 style requires responding immediately to input on any device.  Another
1135 example is a program that acts as a server to several other processes
1136 via pipes or sockets.
1138 You cannot normally use @code{read} for this purpose, because this
1139 blocks the program until input is available on one particular file
1140 descriptor; input on other channels won't wake it up.  You could set
1141 nonblocking mode and poll each file descriptor in turn, but this is very
1142 inefficient.
1144 A better solution is to use the @code{select} function.  This blocks the
1145 program until input or output is ready on a specified set of file
1146 descriptors, or until a timer expires, whichever comes first.  This
1147 facility is declared in the header file @file{sys/types.h}.
1148 @pindex sys/types.h
1150 In the case of a server socket (@pxref{Listening}), we say that
1151 ``input'' is available when there are pending connections that could be
1152 accepted (@pxref{Accepting Connections}).  @code{accept} for server
1153 sockets blocks and interacts with @code{select} just as @code{read} does
1154 for normal input.
1156 @cindex file descriptor sets, for @code{select}
1157 The file descriptor sets for the @code{select} function are specified
1158 as @code{fd_set} objects.  Here is the description of the data type
1159 and some macros for manipulating these objects.
1161 @comment sys/types.h
1162 @comment BSD
1163 @deftp {Data Type} fd_set
1164 The @code{fd_set} data type represents file descriptor sets for the
1165 @code{select} function.  It is actually a bit array.
1166 @end deftp
1168 @comment sys/types.h
1169 @comment BSD
1170 @deftypevr Macro int FD_SETSIZE
1171 The value of this macro is the maximum number of file descriptors that a
1172 @code{fd_set} object can hold information about.  On systems with a
1173 fixed maximum number, @code{FD_SETSIZE} is at least that number.  On
1174 some systems, including GNU, there is no absolute limit on the number of
1175 descriptors open, but this macro still has a constant value which
1176 controls the number of bits in an @code{fd_set}; if you get a file
1177 descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
1178 that descriptor into an @code{fd_set}.
1179 @end deftypevr
1181 @comment sys/types.h
1182 @comment BSD
1183 @deftypefn Macro void FD_ZERO (fd_set *@var{set})
1184 This macro initializes the file descriptor set @var{set} to be the
1185 empty set.
1186 @end deftypefn
1188 @comment sys/types.h
1189 @comment BSD
1190 @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
1191 This macro adds @var{filedes} to the file descriptor set @var{set}.
1192 @end deftypefn
1194 @comment sys/types.h
1195 @comment BSD
1196 @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
1197 This macro removes @var{filedes} from the file descriptor set @var{set}.
1198 @end deftypefn
1200 @comment sys/types.h
1201 @comment BSD
1202 @deftypefn Macro int FD_ISSET (int @var{filedes}, fd_set *@var{set})
1203 This macro returns a nonzero value (true) if @var{filedes} is a member
1204 of the file descriptor set @var{set}, and zero (false) otherwise.
1205 @end deftypefn
1207 Next, here is the description of the @code{select} function itself.
1209 @comment sys/types.h
1210 @comment BSD
1211 @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})
1212 The @code{select} function blocks the calling process until there is
1213 activity on any of the specified sets of file descriptors, or until the
1214 timeout period has expired.
1216 The file descriptors specified by the @var{read-fds} argument are
1217 checked to see if they are ready for reading; the @var{write-fds} file
1218 descriptors are checked to see if they are ready for writing; and the
1219 @var{except-fds} file descriptors are checked for exceptional
1220 conditions.  You can pass a null pointer for any of these arguments if
1221 you are not interested in checking for that kind of condition.
1223 A file descriptor is considered ready for reading if it is at end of
1224 file.  A server socket is considered ready for reading if there is a
1225 pending connection which can be accepted with @code{accept};
1226 @pxref{Accepting Connections}.  A client socket is ready for writing when
1227 its connection is fully established; @pxref{Connecting}.
1229 ``Exceptional conditions'' does not mean errors---errors are reported
1230 immediately when an erroneous system call is executed, and do not
1231 constitute a state of the descriptor.  Rather, they include conditions
1232 such as the presence of an urgent message on a socket.  (@xref{Sockets},
1233 for information on urgent messages.)
1235 The @code{select} function checks only the first @var{nfds} file
1236 descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
1237 of this argument.
1239 The @var{timeout} specifies the maximum time to wait.  If you pass a
1240 null pointer for this argument, it means to block indefinitely until one
1241 of the file descriptors is ready.  Otherwise, you should provide the
1242 time in @code{struct timeval} format; see @ref{High-Resolution
1243 Calendar}.  Specify zero as the time (a @code{struct timeval} containing
1244 all zeros) if you want to find out which descriptors are ready without
1245 waiting if none are ready.
1247 The normal return value from @code{select} is the total number of ready file
1248 descriptors in all of the sets.  Each of the argument sets is overwritten
1249 with information about the descriptors that are ready for the corresponding
1250 operation.  Thus, to see if a particular descriptor @var{desc} has input,
1251 use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
1253 If @code{select} returns because the timeout period expires, it returns
1254 a value of zero.
1256 Any signal will cause @code{select} to return immediately.  So if your
1257 program uses signals, you can't rely on @code{select} to keep waiting
1258 for the full time specified.  If you want to be sure of waiting for a
1259 particular amount of time, you must check for @code{EINTR} and repeat
1260 the @code{select} with a newly calculated timeout based on the current
1261 time.  See the example below.  See also @ref{Interrupted Primitives}.
1263 If an error occurs, @code{select} returns @code{-1} and does not modify
1264 the argument file descriptor sets.  The following @code{errno} error
1265 conditions are defined for this function:
1267 @table @code
1268 @item EBADF
1269 One of the file descriptor sets specified an invalid file descriptor.
1271 @item EINTR
1272 The operation was interrupted by a signal.  @xref{Interrupted Primitives}.
1274 @item EINVAL
1275 The @var{timeout} argument is invalid; one of the components is negative
1276 or too large.
1277 @end table
1278 @end deftypefun
1280 @strong{Portability Note:}  The @code{select} function is a BSD Unix
1281 feature.
1283 Here is an example showing how you can use @code{select} to establish a
1284 timeout period for reading from a file descriptor.  The @code{input_timeout}
1285 function blocks the calling process until input is available on the
1286 file descriptor, or until the timeout period expires.
1288 @smallexample
1289 @include select.c.texi
1290 @end smallexample
1292 There is another example showing the use of @code{select} to multiplex
1293 input from multiple sockets in @ref{Server Example}.
1296 @node Synchronizing I/O
1297 @section Synchronizing I/O operations
1299 @cindex synchronizing
1300 In most modern operation systems the normal I/O operations are not
1301 executed synchronously.  I.e., even if a @code{write} system call
1302 returns this does not mean the data is actually written to the media,
1303 e.g., the disk.
1305 In situations where synchronization points are necessary the user can
1306 use special functions which ensure that all operations finished before
1307 they return.
1309 @comment unistd.h
1310 @comment X/Open
1311 @deftypefun int sync (void)
1312 A call to this function will not return as long as there is data which
1313 that is not written to the device.  All dirty buffers in the kernel will
1314 be written and so an overall consistent system can be achieved (if no
1315 other process in parallel writes data).
1317 A prototype for @code{sync} can be found in @file{unistd.h}.
1319 The return value is zero to indicate no error.
1320 @end deftypefun
1322 More often it is wanted that not all data in the system is committed.
1323 Programs want to ensure that data written to a given file are all
1324 committed and in this situation @code{sync} is overkill.
1326 @comment unistd.h
1327 @comment POSIX
1328 @deftypefun int fsync (int @var{fildes})
1329 The @code{fsync} can be used to make sure all data associated with the
1330 open file @var{fildes} is written to the device associated with the
1331 descriptor.  The function call does not return unless all actions have
1332 finished.
1334 A prototype for @code{fsync} can be found in @file{unistd.h}.
1336 This function is a cancelation point in multi-threaded programs.  This
1337 is a problem if the thread allocates some resources (like memory, file
1338 descriptors, semaphores or whatever) at the time @code{fsync} is
1339 called.  If the thread gets canceled these resources stay allocated
1340 until the program ends.  To avoid this calls to @code{fsync} should be
1341 protected using cancelation handlers.
1342 @c ref pthread_cleanup_push / pthread_cleanup_pop
1344 The return value of the function is zero if no error occured.  Otherwise
1345 it is @math{-1} and the global variable @var{errno} is set to the
1346 following values:
1347 @table @code
1348 @item EBADF
1349 The descriptor @var{fildes} is not valid.
1351 @item EINVAL
1352 No synchronization is possible since the system does not implement this.
1353 @end table
1354 @end deftypefun
1356 Sometimes it is not even necessary to write all data associated with a
1357 file descriptor.  E.g., in database files which do not change in size it
1358 is enough to write all the file content data to the device.
1359 Meta-information like the modification time etc. are not that important
1360 and leaving such information uncommitted does not prevent a successful
1361 recovering of the file in case of a problem.
1363 @comment unistd.h
1364 @comment POSIX
1365 @deftypefun int fdatasync (int @var{fildes})
1366 When a call to the @code{fdatasync} function returns it is made sure
1367 that all of the file data is written to the device.  For all pending I/O
1368 operations the parts guaranteeing data integrity finished.
1370 Not all systems implement the @code{fdatasync} operation.  On systems
1371 missing this functionality @code{fdatasync} is emulated by a call to
1372 @code{fsync} since the performed actions are a superset of those
1373 required by @code{fdatasyn}.
1375 The prototype for @code{fdatasync} is in @file{unistd.h}.
1377 The return value of the function is zero if no error occured.  Otherwise
1378 it is @math{-1} and the global variable @var{errno} is set to the
1379 following values:
1380 @table @code
1381 @item EBADF
1382 The descriptor @var{fildes} is not valid.
1384 @item EINVAL
1385 No synchronization is possible since the system does not implement this.
1386 @end table
1387 @end deftypefun
1390 @node Asynchronous I/O
1391 @section Perform I/O Operations in Parallel
1393 The POSIX.1b standard defines a new set of I/O operations which can
1394 reduce the time an application spends waiting at I/O significantly.  The
1395 new functions allow a program to initiate one or more I/O operations and
1396 then immediately resume the normal work while the I/O operations are
1397 executed in parallel.  The functionality is available if the
1398 @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
1400 These functions are part of the library with realtime functions named
1401 @file{librt}.  They are not actually part of the @file{libc} binary.
1402 The implementation of these functions can be done using support in the
1403 kernel (if available) or using an implementation based on threads at
1404 userlevel.  In the latter case it might be necessary to link applications
1405 with the thread library @file{libpthread} in addition to @file{librt}.
1407 All AIO operations operate on files which were opened previously.  There
1408 might be arbitrary many operations for one file running.  The
1409 asynchronous I/O operations are controlled using a data structure named
1410 @code{struct aiocb} (@dfn{AIO control block}).  It is defined in
1411 @file{aio.h} as follows.
1413 @comment aio.h
1414 @comment POSIX.1b
1415 @deftp {Data Type} {struct aiocb}
1416 The POSIX.1b standard mandates that the @code{struct aiocb} structure
1417 contains at least the members described in the following table.  There
1418 might be more elements which are used by the implementation but
1419 depending on these elements is not portable and is highly deprecated.
1421 @table @code
1422 @item int aio_fildes
1423 This element specifies the file descriptor which is used for the
1424 operation.  It must be a legal descriptor since otherwise the operation
1425 fails for obvious reasons.
1427 The device on which the file is opened must allow the seek operation.
1428 I.e., it is not possible to use any of the AIO operations on devices
1429 like terminals where an @code{lseek} call would lead to an error.
1431 @item off_t aio_offset
1432 This element specifies at which offset in the file the operation (input
1433 or output) is performed.  Since the operations are carried out in arbitrary
1434 order and more than one operation for one file descriptor can be
1435 started, one cannot expect a current read/write position of the file
1436 descriptor.
1438 @item volatile void *aio_buf
1439 This is a pointer to the buffer with the data to be written or the place
1440 where the read data is stored.
1442 @item size_t aio_nbytes
1443 This element specifies the length of the buffer pointed to by @code{aio_buf}.
1445 @item int aio_reqprio
1446 If the platform has defined @code{_POSIX_PRIORITIZED_IO} and
1447 @code{_POSIX_PRIORITY_SCHEDULING} the AIO requests are
1448 processed based on the current scheduling priority.  The
1449 @code{aio_reqprio} element can then be used to lower the priority of the
1450 AIO operation.
1452 @item struct sigevent aio_sigevent
1453 This element specifies how the calling process is notified once the
1454 operation terminates.  If the @code{sigev_notify} element is
1455 @code{SIGEV_NONE} no notification is send.  If it is @code{SIGEV_SIGNAL}
1456 the signal determined by @code{sigev_signo} is send.  Otherwise
1457 @code{sigev_notify} must be @code{SIGEV_THREAD}.  In this case a thread
1458 is created which starts executing the function pointed to by
1459 @code{sigev_notify_function}.
1461 @item int aio_lio_opcode
1462 This element is only used by the @code{lio_listio} and
1463 @code{lio_listio64} functions.  Since these functions allow to start an
1464 arbitrary number of operations at once and since each operation can be
1465 input or output (or nothing) the information must be stored in the
1466 control block.  The possible values are:
1468 @vtable @code
1469 @item LIO_READ
1470 Start a read operation.  Read from the file at position
1471 @code{aio_offset} and store the next @code{aio_nbytes} bytes in the
1472 buffer pointed to by @code{aio_buf}.
1474 @item LIO_WRITE
1475 Start a write operation.  Write @code{aio_nbytes} bytes starting at
1476 @code{aio_buf} into the file starting at position @code{aio_offset}.
1478 @item LIO_NOP
1479 Do nothing for this control block.  This value is useful sometimes when
1480 an array of @code{struct aiocb} values contains holes, i.e., some of the
1481 values must not be handled although the whole array is presented to the
1482 @code{lio_listio} function.
1483 @end vtable
1484 @end table
1486 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
1487 32 bits machine this type is in fact @code{struct aiocb64} since the LFS
1488 interface transparently replaces the @code{struct aiocb} definition.
1489 @end deftp
1491 For use with the AIO functions defined in the LFS there is a similar type
1492 defined which replaces the types of the appropriate members with larger
1493 types but otherwise is equivalent to @code{struct aiocb}.  Especially
1494 all member names are the same.
1496 @comment aio.h
1497 @comment POSIX.1b
1498 @deftp {Data Type} {struct aiocb64}
1499 @table @code
1500 @item int aio_fildes
1501 This element specifies the file descriptor which is used for the
1502 operation.  It must be a legal descriptor since otherwise the operation
1503 fails for obvious reasons.
1505 The device on which the file is opened must allow the seek operation.
1506 I.e., it is not possible to use any of the AIO operations on devices
1507 like terminals where an @code{lseek} call would lead to an error.
1509 @item off64_t aio_offset
1510 This element specified at which offset in the file the operation (input
1511 or output) is performed.  Since the operation are carried in arbitrary
1512 order and more than one operation for one file descriptor can be
1513 started, one cannot expect a current read/write position of the file
1514 descriptor.
1516 @item volatile void *aio_buf
1517 This is a pointer to the buffer with the data to be written or the place
1518 where the ead data is stored.
1520 @item size_t aio_nbytes
1521 This element specifies the length of the buffer pointed to by @code{aio_buf}.
1523 @item int aio_reqprio
1524 If for the platform @code{_POSIX_PRIORITIZED_IO} and
1525 @code{_POSIX_PRIORITY_SCHEDULING} is defined the AIO requests are
1526 processed based on the current scheduling priority.  The
1527 @code{aio_reqprio} element can then be used to lower the priority of the
1528 AIO operation.
1530 @item struct sigevent aio_sigevent
1531 This element specifies how the calling process is notified once the
1532 operation terminates.  If the @code{sigev_notify} element is
1533 @code{SIGEV_NONE} no notification is send.  If it is @code{SIGEV_SIGNAL}
1534 the signal determined by @code{sigev_signo} is send.  Otherwise
1535 @code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
1536 which starts executing the function pointeed to by
1537 @code{sigev_notify_function}.
1539 @item int aio_lio_opcode
1540 This element is only used by the @code{lio_listio} and
1541 @code{[lio_listio64} functions.  Since these functions allow to start an
1542 arbitrary number of operations at once and since each operation can be
1543 input or output (or nothing) the information must be stored in the
1544 control block.  See the description of @code{struct aiocb} for a description
1545 of the possible values.
1546 @end table
1548 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
1549 32 bits machine this type is available under the name @code{struct
1550 aiocb64} since the LFS replaces transparently the old interface.
1551 @end deftp
1553 @menu
1554 * Asynchronous Reads/Writes::    Asynchronous Read and Write Operations.
1555 * Status of AIO Operations::     Getting the Status of AIO Operations.
1556 * Synchronizing AIO Operations:: Getting into a consistent state.
1557 * Cancel AIO Operations::        Cancelation of AIO Operations.
1558 * Configuration of AIO::         How to optimize the AIO implementation.
1559 @end menu
1561 @node Asynchronous Reads/Writes
1562 @subsection Asynchronous Read and Write Operations
1564 @comment aio.h
1565 @comment POSIX.1b
1566 @deftypefun int aio_read (struct aiocb *@var{aiocbp})
1567 This function initiates an asynchronous read operation.  The function
1568 call immediately returns after the operation was enqueued or when an
1569 error was encountered.
1571 The first @code{aiocbp->aio_nbytes} bytes of the file for which
1572 @code{aiocbp->aio_fildes} is a descriptor are written to the buffer
1573 starting at @code{aiocbp->aio_buf}.  Reading starts at the absolute
1574 position @code{aiocbp->aio_offset} in the file.
1576 If prioritized I/O is supported by the platform the
1577 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
1578 the request is actually enqueued.
1580 The calling process is notified about the termination of the read
1581 request according to the @code{aiocbp->aio_sigevent} value.
1583 When @code{aio_read} returns the return value is zero if no error
1584 occurred that can be found before the process is enqueued.  If such an
1585 early error is found the function returns @math{-1} and sets
1586 @code{errno} to one of the following values.
1588 @table @code
1589 @item EAGAIN
1590 The request was not enqueued due to (temporarily) exceeded resource
1591 limitations.
1592 @item ENOSYS
1593 The @code{aio_read} function is not implemented.
1594 @item EBADF
1595 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
1596 needs not be recognized before enqueueing the request and so this error
1597 might also be signaled asynchronously.
1598 @item EINVAL
1599 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
1600 invalid.  This condition need not be recognized before enqueueing the
1601 request and so this error might also be signaled asynchrously.
1602 @end table
1604 In the case @code{aio_read} returns zero the current status of the
1605 request can be queried using @code{aio_error} and @code{aio_return}
1606 functions.  As long as the value returned by @code{aio_error} is
1607 @code{EINPROGRESS} the operation has not yet completed.  If
1608 @code{aio_error} returns zero the operation successfully terminated,
1609 otherwise the value is to be interpreted as an error code.  If the
1610 function terminated the result of the operation can be get using a call
1611 to @code{aio_return}.  The returned value is the same as an equivalent
1612 call to @code{read} would have returned.  Possible error codes returned
1613 by @code{aio_error} are:
1615 @table @code
1616 @item EBADF
1617 The @code{aiocbp->aio_fildes} descriptor is not valid.
1618 @item ECANCELED
1619 The operation was canceled before the operation was finished
1620 (@pxref{Cancel AIO Operations})
1621 @item EINVAL
1622 The @code{aiocbp->aio_offset} value is invalid.
1623 @end table
1625 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1626 function is in fact @code{aio_read64} since the LFS interface transparently
1627 replaces the normal implementation.
1628 @end deftypefun
1630 @comment aio.h
1631 @comment Unix98
1632 @deftypefun int aio_read64 (struct aiocb *@var{aiocbp})
1633 This function is similar to the @code{aio_read} function.  The only
1634 difference is that on @w{32 bits} machines the file descriptor should
1635 be opened in the large file mode.  Internally @code{aio_read64} uses
1636 functionality equivalent to @code{lseek64} (@pxref{File Position
1637 Primitive}) to position the file descriptor correctly for the reading,
1638 as opposed to @code{lseek} functionality used in @code{aio_read}.
1640 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1641 function is available under the name @code{aio_read} and so transparently
1642 replaces the interface for small files on 32 bits machines.
1643 @end deftypefun
1645 To write data asynchronously to a file there exists an equivalent pair
1646 of functions with a very similar interface.
1648 @comment aio.h
1649 @comment POSIX.1b
1650 @deftypefun int aio_write (struct aiocb *@var{aiocbp})
1651 This function initiates an asynchronous write operation.  The function
1652 call immediately returns after the operation was enqueued or if before
1653 this happens an error was encountered.
1655 The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at
1656 @code{aiocbp->aio_buf} are written to the file for which
1657 @code{aiocbp->aio_fildes} is an descriptor, starting at the absolute
1658 position @code{aiocbp->aio_offset} in the file.
1660 If prioritized I/O is supported by the platform the
1661 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
1662 the request is actually enqueued.
1664 The calling process is notified about the termination of the read
1665 request according to the @code{aiocbp->aio_sigevent} value.
1667 When @code{aio_write} returns the return value is zero if no error
1668 occurred that can be found before the process is enqueued.  If such an
1669 early error is found the function returns @math{-1} and sets
1670 @code{errno} to one of the following values.
1672 @table @code
1673 @item EAGAIN
1674 The request was not enqueued due to (temporarily) exceeded resource
1675 limitations.
1676 @item ENOSYS
1677 The @code{aio_write} function is not implemented.
1678 @item EBADF
1679 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
1680 needs not be recognized before enqueueing the request and so this error
1681 might also be signaled asynchronously.
1682 @item EINVAL
1683 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
1684 invalid.  This condition needs not be recognized before enqueueing the
1685 request and so this error might also be signaled asynchronously.
1686 @end table
1688 In the case @code{aio_write} returns zero the current status of the
1689 request can be queried using @code{aio_error} and @code{aio_return}
1690 functions.  As long as the value returned by @code{aio_error} is
1691 @code{EINPROGRESS} the operation has not yet completed.  If
1692 @code{aio_error} returns zero the operation successfully terminated,
1693 otherwise the value is to be interpreted as an error code.  If the
1694 function terminated the result of the operation can be get using a call
1695 to @code{aio_return}.  The returned value is the same as an equivalent
1696 call to @code{read} would have returned.  Possible error code returned
1697 by @code{aio_error} are:
1699 @table @code
1700 @item EBADF
1701 The @code{aiocbp->aio_fildes} descriptor is not valid.
1702 @item ECANCELED
1703 The operation was canceled before the operation was finished
1704 (@pxref{Cancel AIO Operations})
1705 @item EINVAL
1706 The @code{aiocbp->aio_offset} value is invalid.
1707 @end table
1709 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1710 function is in fact @code{aio_write64} since the LFS interface transparently
1711 replaces the normal implementation.
1712 @end deftypefun
1714 @comment aio.h
1715 @comment Unix98
1716 @deftypefun int aio_write64 (struct aiocb *@var{aiocbp})
1717 This function is similar to the @code{aio_write} function.  The only
1718 difference is that on @w{32 bits} machines the file descriptor should
1719 be opened in the large file mode.  Internally @code{aio_write64} uses
1720 functionality equivalent to @code{lseek64} (@pxref{File Position
1721 Primitive}) to position the file descriptor correctly for the writing,
1722 as opposed to @code{lseek} functionality used in @code{aio_write}.
1724 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1725 function is available under the name @code{aio_write} and so transparently
1726 replaces the interface for small files on 32 bits machines.
1727 @end deftypefun
1729 Beside these functions with the more or less traditional interface
1730 POSIX.1b also defines a function with can initiate more than one
1731 operation at once and which can handled freely mixed read and write
1732 operation.  It is therefore similar to a combination of @code{readv} and
1733 @code{writev}.
1735 @comment aio.h
1736 @comment POSIX.1b
1737 @deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
1738 The @code{lio_listio} function can be used to enqueue an arbitrary
1739 number of read and write requests at one time.  The requests can all be
1740 meant for the same file, all for different files or every solution in
1741 between.
1743 @code{lio_listio} gets the @var{nent} requests from the array pointed to
1744 by @var{list}.  What operation has to be performed is determined by the
1745 @code{aio_lio_opcode} member in each element of @var{list}.  If this
1746 field is @code{LIO_READ} an read operation is queued, similar to a call
1747 of @code{aio_read} for this element of the array (except that the way
1748 the termination is signalled is different, as we will see below).  If
1749 the @code{aio_lio_opcode} member is @code{LIO_WRITE} an write operation
1750 is enqueued.  Otherwise the @code{aio_lio_opcode} must be @code{LIO_NOP}
1751 in which case this element of @var{list} is simply ignored.  This
1752 ``operation'' is useful in situations where one has a fixed array of
1753 @code{struct aiocb} elements from which only a few need to be handled at
1754 a time.  Another situation is where the @code{lio_listio} call was
1755 cancelled before all requests are processed (@pxref{Cancel AIO
1756 Operations}) and the remaining requests have to be reissued.
1758 The other members of each element of the array pointed to by
1759 @code{list} must have values suitable for the operation as described in
1760 the documentation for @code{aio_read} and @code{aio_write} above.
1762 The @var{mode} argument determines how @code{lio_listio} behaves after
1763 having enqueued all the requests.  If @var{mode} is @code{LIO_WAIT} it
1764 waits until all requests terminated.  Otherwise @var{mode} must be
1765 @code{LIO_NOWAIT} and in this case the function returns immediately after
1766 having enqueued all the requests.  In this case the caller gets a
1767 notification of the termination of all requests according to the
1768 @var{sig} parameter.  If @var{sig} is @code{NULL} no notification is
1769 send.  Otherwise a signal is sent or a thread is started, just as
1770 described in the description for @code{aio_read} or @code{aio_write}.
1772 If @var{mode} is @code{LIO_WAIT} the return value of @code{lio_listio}
1773 is @math{0} when all requests completed successfully.  Otherwise the
1774 function return @math{-1} and @code{errno} is set accordingly.  To find
1775 out which request or requests failed one has to use the @code{aio_error}
1776 function on all the elements of the array @var{list}.
1778 In case @var{mode} is @code{LIO_NOWAIT} the function return @math{0} if
1779 all requests were enqueued correctly.  The current state of the requests
1780 can be found using @code{aio_error} and @code{aio_return} as described
1781 above.  In case @code{lio_listio} returns @math{-1} in this mode the
1782 global variable @code{errno} is set accordingly.  If a request did not
1783 yet terminate a call to @code{aio_error} returns @code{EINPROGRESS}.  If
1784 the value is different the request is finished and the error value (or
1785 @math{0}) is returned and the result of the operation can be retrieved
1786 using @code{aio_return}.
1788 Possible values for @code{errno} are:
1790 @table @code
1791 @item EAGAIN
1792 The resources necessary to queue all the requests are not available in
1793 the moment.  The error status for each element of @var{list} must be
1794 checked which request failed.
1796 Another reason could be that the system wide limit of AIO requests is
1797 exceeded.  This cannot be the case for the implementation on GNU systems
1798 since no arbitrary limits exist.
1799 @item EINVAL
1800 The @var{mode} parameter is invalid or @var{nent} is larger than
1801 @code{AIO_LISTIO_MAX}.
1802 @item EIO
1803 One or more of the request's I/O operations failed.  The error status of
1804 each request should be checked for which one failed.
1805 @item ENOSYS
1806 The @code{lio_listio} function is not supported.
1807 @end table
1809 If the @var{mode} parameter is @code{LIO_NOWAIT} and the caller cancels
1810 an request the error status for this request returned by
1811 @code{aio_error} is @code{ECANCELED}.
1813 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1814 function is in fact @code{lio_listio64} since the LFS interface
1815 transparently replaces the normal implementation.
1816 @end deftypefun
1818 @comment aio.h
1819 @comment Unix98
1820 @deftypefun int lio_listio64 (int @var{mode}, struct aiocb *const @var{list}, int @var{nent}, struct sigevent *@var{sig})
1821 This function is similar to the @code{aio_listio} function.  The only
1822 difference is that only @w{32 bits} machines the file descriptor should
1823 be opened in the large file mode.  Internally @code{lio_listio64} uses
1824 functionality equivalent to @code{lseek64} (@pxref{File Position
1825 Primitive}) to position the file descriptor correctly for the reading or
1826 writing, as opposed to @code{lseek} functionality used in
1827 @code{lio_listio}.
1829 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1830 function is available under the name @code{lio_listio} and so
1831 transparently replaces the interface for small files on 32 bits
1832 machines.
1833 @end deftypefun
1835 @node Status of AIO Operations
1836 @subsection Getting the Status of AIO Operations
1838 As already described in the documentation of the functions in the last
1839 section it must be possible to get information about the status of a I/O
1840 request.  When the operation is performed really asynchronous (as with
1841 @code{aio_read} and @code{aio_write} and with @code{aio_listio} when the
1842 mode is @code{LIO_NOWAIT}) one sometimes needs to know whether a
1843 specific request already terminated and if yes, what the result was..
1844 The following two function allow to get this kind of information.
1846 @comment aio.h
1847 @comment POSIX.1b
1848 @deftypefun int aio_error (const struct aiocb *@var{aiocbp})
1849 This function determines the error state of the request described by the
1850 @code{struct aiocb} variable pointed to by @var{aiocbp}.  If the
1851 request has not yet terminated the value returned is always
1852 @code{EINPROGRESS}.  Once the request has terminated the value
1853 @code{aio_error} returns is either @math{0} if the request completed
1854 successfully or it returns the value which would be stored in the
1855 @code{errno} variable if the request would have been done using
1856 @code{read}, @code{write}, or @code{fsync}.
1858 The function can return @code{ENOSYS} if it is not implemented.  It
1859 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
1860 refer to an asynchronous operation whose return status is not yet known.
1862 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1863 function is in fact @code{aio_error64} since the LFS interface
1864 transparently replaces the normal implementation.
1865 @end deftypefun
1867 @comment aio.h
1868 @comment Unix98
1869 @deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp})
1870 This function is similar to @code{aio_error} with the only difference
1871 that the argument is a reference to a variable of type @code{struct
1872 aiocb64}.
1874 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1875 function is available under the name @code{aio_error} and so
1876 transparently replaces the interface for small files on 32 bits
1877 machines.
1878 @end deftypefun
1880 @comment aio.h
1881 @comment POSIX.1b
1882 @deftypefun ssize_t aio_return (const struct aiocb *@var{aiocbp})
1883 This function can be used to retrieve the return status of the operation
1884 carried out by the request described in the variable pointed to by
1885 @var{aiocbp}.  As long as the error status of this request as returned
1886 by @code{aio_error} is @code{EINPROGRESS} the return of this function is
1887 undefined.
1889 Once the request is finished this function can be used exactly once to
1890 retrieve the return value.  Following calls might lead to undefined
1891 behaviour.  The return value itself is the value which would have been
1892 returned by the @code{read}, @code{write}, or @code{fsync} call.
1894 The function can return @code{ENOSYS} if it is not implemented.  It
1895 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
1896 refer to an asynchronous operation whose return status is not yet known.
1898 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1899 function is in fact @code{aio_return64} since the LFS interface
1900 transparently replaces the normal implementation.
1901 @end deftypefun
1903 @comment aio.h
1904 @comment Unix98
1905 @deftypefun int aio_return64 (const struct aiocb64 *@var{aiocbp})
1906 This function is similar to @code{aio_return} with the only difference
1907 that the argument is a reference to a variable of type @code{struct
1908 aiocb64}.
1910 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1911 function is available under the name @code{aio_return} and so
1912 transparently replaces the interface for small files on 32 bits
1913 machines.
1914 @end deftypefun
1916 @node Synchronizing AIO Operations
1917 @subsection Getting into a Consistent State
1919 When dealing with asynchronous operations it is sometimes necessary to
1920 get into a consistent state.  This would mean for AIO that one wants to
1921 know whether a certain request or a group of request were processed.
1922 This could be done by waiting for the notification sent by the system
1923 after the operation terminated but this sometimes would mean wasting
1924 resources (mainly computation time).  Instead POSIX.1b defines two
1925 functions which will help with most kinds of consistency.
1927 The @code{aio_fsync} and @code{aio_fsync64} functions are only available
1928 if in @file{unistd.h} the symbol @code{_POSIX_SYNCHRONIZED_IO} is
1929 defined.
1931 @cindex synchronizing
1932 @comment aio.h
1933 @comment POSIX.1b
1934 @deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp})
1935 Calling this function forces all I/O operations operating queued at the
1936 time of the function call operating on the file descriptor
1937 @code{aiocbp->aio_fildes} into the synchronized I/O completion state
1938 (@pxref{Synchronizing I/O}).  The @code{aio_fsync} function return
1939 immediately but the notification through the method described in
1940 @code{aiocbp->aio_sigevent} will happen only after all requests for this
1941 file descriptor terminated and the file is synchronized.  This also
1942 means that requests for this very same file descriptor which are queued
1943 after the synchronization request are not effected.
1945 If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
1946 to @code{fdatasync}.  Otherwise @var{op} should be @code{O_SYNC} and
1947 the synchronization happens as with @code{fsync}.
1949 As long as the synchronization has not happened a call to
1950 @code{aio_error} with the reference to the object pointed to by
1951 @var{aiocbp} returns @code{EINPROGRESS}.  Once the synchronization is
1952 done @code{aio_error} return @math{0} if the synchronization was not
1953 successful.  Otherwise the value returned is the value to which the
1954 @code{fsync} or @code{fdatasync} function would have set the
1955 @code{errno} variable.  In this case nothing can be assumed about the
1956 consistency for the data written to this file descriptor.
1958 The return value of this function is @math{0} if the request was
1959 successfully filed.  Otherwise the return value is @math{-1} and
1960 @code{errno} is set to one of the following values:
1962 @table @code
1963 @item EAGAIN
1964 The request could not be enqueued due to temporary lack of resources.
1965 @item EBADF
1966 The file descriptor @code{aiocbp->aio_fildes} is not valid or not open
1967 for writing.
1968 @item EINVAL
1969 The implementation does not support I/O synchronization or the @var{op}
1970 parameter is other than @code{O_DSYNC} and @code{O_SYNC}.
1971 @item ENOSYS
1972 This function is not implemented.
1973 @end table
1975 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1976 function is in fact @code{aio_return64} since the LFS interface
1977 transparently replaces the normal implementation.
1978 @end deftypefun
1980 @comment aio.h
1981 @comment Unix98
1982 @deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp})
1983 This function is similar to @code{aio_fsync} with the only difference
1984 that the argument is a reference to a variable of type @code{struct
1985 aiocb64}.
1987 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1988 function is available under the name @code{aio_fsync} and so
1989 transparently replaces the interface for small files on 32 bits
1990 machines.
1991 @end deftypefun
1993 Another method of synchronization is to wait until one or more requests of a
1994 specific set terminated.  This could be achieved by the @code{aio_*}
1995 functions to notify the initiating process about the termination but in
1996 some situations this is not the ideal solution.  In a program which
1997 constantly updates clients somehow connected to the server it is not
1998 always the best solution to go round robin since some connections might
1999 be slow.  On the other hand letting the @code{aio_*} function notify the
2000 caller might also be not the best solution since whenever the process
2001 works on preparing data for on client it makes no sense to be
2002 interrupted by a notification since the new client will not be handled
2003 before the current client is served.  For situations like this
2004 @code{aio_suspend} should be used.
2006 @comment aio.h
2007 @comment POSIX.1b
2008 @deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
2009 When calling this function the calling thread is suspended until at
2010 least one of the requests pointed to by the @var{nent} elements of the
2011 array @var{list} has completed.  If any of the requests already has
2012 completed at the time @code{aio_suspend} is called the function returns
2013 immediately.  Whether a request has terminated or not is done by
2014 comparing the error status of the request with @code{EINPROGRESS}.  If
2015 an element of @var{list} is @code{NULL} the entry is simply ignored.
2017 If no request has finished the calling process is suspended.  If
2018 @var{timeout} is @code{NULL} the process is not waked until a request
2019 finished.  If @var{timeout} is not @code{NULL} the process remains
2020 suspended at as long as specified in @var{timeout}.  In this case
2021 @code{aio_suspend} returns with an error.
2023 The return value of the function is @math{0} if one or more requests
2024 from the @var{list} have terminated.  Otherwise the function returns
2025 @math{-1} and @code{errno} is set to one of the following values:
2027 @table @code
2028 @item EAGAIN
2029 None of the requests from the @var{list} completed in the time specified
2030 by @var{timeout}.
2031 @item EINTR
2032 A signal interrupted the @code{aio_suspend} function.  This signal might
2033 also be sent by the AIO implementation while signalling the termination
2034 of one of the requests.
2035 @item ENOSYS
2036 The @code{aio_suspend} function is not implemented.
2037 @end table
2039 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2040 function is in fact @code{aio_suspend64} since the LFS interface
2041 transparently replaces the normal implementation.
2042 @end deftypefun
2044 @comment aio.h
2045 @comment Unix98
2046 @deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
2047 This function is similar to @code{aio_suspend} with the only difference
2048 that the argument is a reference to a variable of type @code{struct
2049 aiocb64}.
2051 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2052 function is available under the name @code{aio_suspend} and so
2053 transparently replaces the interface for small files on 32 bits
2054 machines.
2055 @end deftypefun
2057 @node Cancel AIO Operations
2058 @subsection Cancelation of AIO Operations
2060 When one or more requests are asynchronously processed it might be
2061 useful in some situations to cancel a selected operation, e.g., if it
2062 becomes obvious that the written data is not anymore accurate and would
2063 have to be overwritten soon.  As an example assume an application, which
2064 writes data in files in a situation where new incoming data would have
2065 to be written in a file which will be updated by an enqueued request.
2066 The POSIX AIO implementation provides such a function but this function
2067 is not capable to force the cancelation of the request.  It is up to the
2068 implementation to decide whether it is possible to cancel the operation
2069 or not.  Therefore using this function is merely a hint.
2071 @comment aio.h
2072 @comment POSIX.1b
2073 @deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp})
2074 The @code{aio_cancel} function can be used to cancel one or more
2075 outstanding requests.  If the @var{aiocbp} parameter is @code{NULL} the
2076 function tries to cancel all outstanding requests which would process
2077 the file descriptor @var{fildes} (i.e.,, whose @code{aio_fildes} member
2078 is @var{fildes}).  If @var{aiocbp} is not @code{NULL} the very specific
2079 request pointed to by @var{aiocbp} is tried to be canceled.
2081 For requests which were successfully canceled the normal notification
2082 about the termination of the request should take place.  I.e., depending
2083 on the @code{struct sigevent} object which controls this, nothing
2084 happens, a signal is sent or a thread is started.  If the request cannot
2085 be canceled it terminates the usual way after performing te operation.
2087 After a request is successfully canceled a call to @code{aio_error} with
2088 a reference to this request as the parameter will return
2089 @code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
2090 If the request wasn't canceled and is still running the error status is
2091 still @code{EINPROGRESS}.
2093 The return value of the function is @code{AIO_CANCELED} if there were
2094 requests which haven't terminated and which successfully were canceled.
2095 If there is one or more request left which couldn't be canceled the
2096 return value is @code{AIO_NOTCANCELED}.  In this case @code{aio_error}
2097 must be used to find out which of the perhaps multiple requests (in
2098 @var{aiocbp} is @code{NULL}) wasn't successfully canceled.  If all
2099 requests already terminated at the time @code{aio_cancel} is called the
2100 return value is @code{AIO_ALLDONE}.
2102 If an error occurred during the execution of @code{aio_cancel} the
2103 function returns @math{-1} and sets @code{errno} to one of the following
2104 values.
2106 @table @code
2107 @item EBADF
2108 The file descriptor @var{fildes} is not valid.
2109 @item ENOSYS
2110 @code{aio_cancel} is not implemented.
2111 @end table
2113 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2114 function is in fact @code{aio_cancel64} since the LFS interface
2115 transparently replaces the normal implementation.
2116 @end deftypefun
2118 @comment aio.h
2119 @comment Unix98
2120 @deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb *@var{aiocbp})
2121 This function is similar to @code{aio_cancel} with the only difference
2122 that the argument is a reference to a variable of type @code{struct
2123 aiocb64}.
2125 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2126 function is available under the name @code{aio_cancel} and so
2127 transparently replaces the interface for small files on 32 bits
2128 machines.
2129 @end deftypefun
2131 @node Configuration of AIO
2132 @subsection How to optimize the AIO implementation
2134 The POSIX standard does not specify how the AIO functions are
2135 implemented.  They could be system calls but it is also possible to
2136 emulate them at userlevel.
2138 At least the available implementation at the point of this writing is a
2139 userlevel implementation which uses threads for handling the enqueued
2140 requests.  This implementation requires to make some decisions about
2141 limitations but hard limitations are something which better should be
2142 avoided the GNU C library implementation provides a mean to tune the AIO
2143 implementation individually for each use.
2145 @comment aio.h
2146 @comment GNU
2147 @deftp {Data Type} {struct aioinit}
2148 This data type is used to pass the configuration or tunable parameters
2149 to the implementation.  The program has to initialize the members of
2150 this struct and pass it to the implementation using the @code{aio_init}
2151 function.
2153 @table @code
2154 @item int aio_threads
2155 This member specifies the maximal number of threads which must be used
2156 at any one time.
2157 @item int aio_num
2158 This number provides an estimate on the maximal number of simultaneously
2159 enqueued requests.
2160 @item int aio_locks
2161 @c What?
2162 @item int aio_usedba
2163 @c What?
2164 @item int aio_debug
2165 @c What?
2166 @item int aio_numusers
2167 @c What?
2168 @item int aio_reserved[2]
2169 @c What?
2170 @end table
2171 @end deftp
2173 @comment aio.h
2174 @comment GNU
2175 @deftypefun void aio_init (const struct aioinit *@var{init})
2176 This function must be called before any other AIO function.  Calling it
2177 is completely voluntarily since it only is meant to help the AIO
2178 implementation to perform better.
2180 Before calling the @code{aio_init} function the members of a variable of
2181 type @code{struct aioinit} must be initialized.  Then a reference to
2182 this variable is passed as the parameter to @code{aio_init} which itself
2183 may or may not pay attention to the hints.
2185 The function has no return value and no error cases are defined.  It is
2186 a extension which follows a proposal from the SGI implementation in
2187 @w{Irix 6}.  It is not covered by POSIX.1b or Unix98.
2188 @end deftypefun
2190 @node Control Operations
2191 @section Control Operations on Files
2193 @cindex control operations on files
2194 @cindex @code{fcntl} function
2195 This section describes how you can perform various other operations on
2196 file descriptors, such as inquiring about or setting flags describing
2197 the status of the file descriptor, manipulating record locks, and the
2198 like.  All of these operations are performed by the function @code{fcntl}.
2200 The second argument to the @code{fcntl} function is a command that
2201 specifies which operation to perform.  The function and macros that name
2202 various flags that are used with it are declared in the header file
2203 @file{fcntl.h}.  Many of these flags are also used by the @code{open}
2204 function; see @ref{Opening and Closing Files}.
2205 @pindex fcntl.h
2207 @comment fcntl.h
2208 @comment POSIX.1
2209 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
2210 The @code{fcntl} function performs the operation specified by
2211 @var{command} on the file descriptor @var{filedes}.  Some commands
2212 require additional arguments to be supplied.  These additional arguments
2213 and the return value and error conditions are given in the detailed
2214 descriptions of the individual commands.
2216 Briefly, here is a list of what the various commands are.
2218 @table @code
2219 @item F_DUPFD
2220 Duplicate the file descriptor (return another file descriptor pointing
2221 to the same open file).  @xref{Duplicating Descriptors}.
2223 @item F_GETFD
2224 Get flags associated with the file descriptor.  @xref{Descriptor Flags}.
2226 @item F_SETFD
2227 Set flags associated with the file descriptor.  @xref{Descriptor Flags}.
2229 @item F_GETFL
2230 Get flags associated with the open file.  @xref{File Status Flags}.
2232 @item F_SETFL
2233 Set flags associated with the open file.  @xref{File Status Flags}.
2235 @item F_GETLK
2236 Get a file lock.  @xref{File Locks}.
2238 @item F_SETLK
2239 Set or clear a file lock.  @xref{File Locks}.
2241 @item F_SETLKW
2242 Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.
2244 @item F_GETOWN
2245 Get process or process group ID to receive @code{SIGIO} signals.
2246 @xref{Interrupt Input}.
2248 @item F_SETOWN
2249 Set process or process group ID to receive @code{SIGIO} signals.
2250 @xref{Interrupt Input}.
2251 @end table
2253 This function is a cancelation point in multi-threaded programs.  This
2254 is a problem if the thread allocates some resources (like memory, file
2255 descriptors, semaphores or whatever) at the time @code{fcntl} is
2256 called.  If the thread gets canceled these resources stay allocated
2257 until the program ends.  To avoid this calls to @code{fcntl} should be
2258 protected using cancelation handlers.
2259 @c ref pthread_cleanup_push / pthread_cleanup_pop
2260 @end deftypefun
2263 @node Duplicating Descriptors
2264 @section Duplicating Descriptors
2266 @cindex duplicating file descriptors
2267 @cindex redirecting input and output
2269 You can @dfn{duplicate} a file descriptor, or allocate another file
2270 descriptor that refers to the same open file as the original.  Duplicate
2271 descriptors share one file position and one set of file status flags
2272 (@pxref{File Status Flags}), but each has its own set of file descriptor
2273 flags (@pxref{Descriptor Flags}).
2275 The major use of duplicating a file descriptor is to implement
2276 @dfn{redirection} of input or output:  that is, to change the
2277 file or pipe that a particular file descriptor corresponds to.
2279 You can perform this operation using the @code{fcntl} function with the
2280 @code{F_DUPFD} command, but there are also convenient functions
2281 @code{dup} and @code{dup2} for duplicating descriptors.
2283 @pindex unistd.h
2284 @pindex fcntl.h
2285 The @code{fcntl} function and flags are declared in @file{fcntl.h},
2286 while prototypes for @code{dup} and @code{dup2} are in the header file
2287 @file{unistd.h}.
2289 @comment unistd.h
2290 @comment POSIX.1
2291 @deftypefun int dup (int @var{old})
2292 This function copies descriptor @var{old} to the first available
2293 descriptor number (the first number not currently open).  It is
2294 equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
2295 @end deftypefun
2297 @comment unistd.h
2298 @comment POSIX.1
2299 @deftypefun int dup2 (int @var{old}, int @var{new})
2300 This function copies the descriptor @var{old} to descriptor number
2301 @var{new}.
2303 If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
2304 does not close @var{new}.  Otherwise, the new duplicate of @var{old}
2305 replaces any previous meaning of descriptor @var{new}, as if @var{new}
2306 were closed first.
2308 If @var{old} and @var{new} are different numbers, and @var{old} is a
2309 valid descriptor number, then @code{dup2} is equivalent to:
2311 @smallexample
2312 close (@var{new});
2313 fcntl (@var{old}, F_DUPFD, @var{new})
2314 @end smallexample
2316 However, @code{dup2} does this atomically; there is no instant in the
2317 middle of calling @code{dup2} at which @var{new} is closed and not yet a
2318 duplicate of @var{old}.
2319 @end deftypefun
2321 @comment fcntl.h
2322 @comment POSIX.1
2323 @deftypevr Macro int F_DUPFD
2324 This macro is used as the @var{command} argument to @code{fcntl}, to
2325 copy the file descriptor given as the first argument.
2327 The form of the call in this case is:
2329 @smallexample
2330 fcntl (@var{old}, F_DUPFD, @var{next-filedes})
2331 @end smallexample
2333 The @var{next-filedes} argument is of type @code{int} and specifies that
2334 the file descriptor returned should be the next available one greater
2335 than or equal to this value.
2337 The return value from @code{fcntl} with this command is normally the value
2338 of the new file descriptor.  A return value of @code{-1} indicates an
2339 error.  The following @code{errno} error conditions are defined for
2340 this command:
2342 @table @code
2343 @item EBADF
2344 The @var{old} argument is invalid.
2346 @item EINVAL
2347 The @var{next-filedes} argument is invalid.
2349 @item EMFILE
2350 There are no more file descriptors available---your program is already
2351 using the maximum.  In BSD and GNU, the maximum is controlled by a
2352 resource limit that can be changed; @pxref{Limits on Resources}, for
2353 more information about the @code{RLIMIT_NOFILE} limit.
2354 @end table
2356 @code{ENFILE} is not a possible error code for @code{dup2} because
2357 @code{dup2} does not create a new opening of a file; duplicate
2358 descriptors do not count toward the limit which @code{ENFILE}
2359 indicates.  @code{EMFILE} is possible because it refers to the limit on
2360 distinct descriptor numbers in use in one process.
2361 @end deftypevr
2363 Here is an example showing how to use @code{dup2} to do redirection.
2364 Typically, redirection of the standard streams (like @code{stdin}) is
2365 done by a shell or shell-like program before calling one of the
2366 @code{exec} functions (@pxref{Executing a File}) to execute a new
2367 program in a child process.  When the new program is executed, it
2368 creates and initializes the standard streams to point to the
2369 corresponding file descriptors, before its @code{main} function is
2370 invoked.
2372 So, to redirect standard input to a file, the shell could do something
2373 like:
2375 @smallexample
2376 pid = fork ();
2377 if (pid == 0)
2378   @{
2379     char *filename;
2380     char *program;
2381     int file;
2382     @dots{}
2383     file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
2384     dup2 (file, STDIN_FILENO);
2385     TEMP_FAILURE_RETRY (close (file));
2386     execv (program, NULL);
2387   @}
2388 @end smallexample
2390 There is also a more detailed example showing how to implement redirection
2391 in the context of a pipeline of processes in @ref{Launching Jobs}.
2394 @node Descriptor Flags
2395 @section File Descriptor Flags
2396 @cindex file descriptor flags
2398 @dfn{File descriptor flags} are miscellaneous attributes of a file
2399 descriptor.  These flags are associated with particular file
2400 descriptors, so that if you have created duplicate file descriptors
2401 from a single opening of a file, each descriptor has its own set of flags.
2403 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
2404 which causes the descriptor to be closed if you use any of the
2405 @code{exec@dots{}} functions (@pxref{Executing a File}).
2407 The symbols in this section are defined in the header file
2408 @file{fcntl.h}.
2409 @pindex fcntl.h
2411 @comment fcntl.h
2412 @comment POSIX.1
2413 @deftypevr Macro int F_GETFD
2414 This macro is used as the @var{command} argument to @code{fcntl}, to
2415 specify that it should return the file descriptor flags associated
2416 with the @var{filedes} argument.
2418 The normal return value from @code{fcntl} with this command is a
2419 nonnegative number which can be interpreted as the bitwise OR of the
2420 individual flags (except that currently there is only one flag to use).
2422 In case of an error, @code{fcntl} returns @code{-1}.  The following
2423 @code{errno} error conditions are defined for this command:
2425 @table @code
2426 @item EBADF
2427 The @var{filedes} argument is invalid.
2428 @end table
2429 @end deftypevr
2432 @comment fcntl.h
2433 @comment POSIX.1
2434 @deftypevr Macro int F_SETFD
2435 This macro is used as the @var{command} argument to @code{fcntl}, to
2436 specify that it should set the file descriptor flags associated with the
2437 @var{filedes} argument.  This requires a third @code{int} argument to
2438 specify the new flags, so the form of the call is:
2440 @smallexample
2441 fcntl (@var{filedes}, F_SETFD, @var{new-flags})
2442 @end smallexample
2444 The normal return value from @code{fcntl} with this command is an
2445 unspecified value other than @code{-1}, which indicates an error.
2446 The flags and error conditions are the same as for the @code{F_GETFD}
2447 command.
2448 @end deftypevr
2450 The following macro is defined for use as a file descriptor flag with
2451 the @code{fcntl} function.  The value is an integer constant usable
2452 as a bit mask value.
2454 @comment fcntl.h
2455 @comment POSIX.1
2456 @deftypevr Macro int FD_CLOEXEC
2457 @cindex close-on-exec (file descriptor flag)
2458 This flag specifies that the file descriptor should be closed when
2459 an @code{exec} function is invoked; see @ref{Executing a File}.  When
2460 a file descriptor is allocated (as with @code{open} or @code{dup}),
2461 this bit is initially cleared on the new file descriptor, meaning that
2462 descriptor will survive into the new program after @code{exec}.
2463 @end deftypevr
2465 If you want to modify the file descriptor flags, you should get the
2466 current flags with @code{F_GETFD} and modify the value.  Don't assume
2467 that the flags listed here are the only ones that are implemented; your
2468 program may be run years from now and more flags may exist then.  For
2469 example, here is a function to set or clear the flag @code{FD_CLOEXEC}
2470 without altering any other flags:
2472 @smallexample
2473 /* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
2474    @r{or clear the flag if @var{value} is 0.}
2475    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
2478 set_cloexec_flag (int desc, int value)
2480   int oldflags = fcntl (desc, F_GETFD, 0);
2481   /* @r{If reading the flags failed, return error indication now.}
2482   if (oldflags < 0)
2483     return oldflags;
2484   /* @r{Set just the flag we want to set.} */
2485   if (value != 0)
2486     oldflags |= FD_CLOEXEC;
2487   else
2488     oldflags &= ~FD_CLOEXEC;
2489   /* @r{Store modified flag word in the descriptor.} */
2490   return fcntl (desc, F_SETFD, oldflags);
2492 @end smallexample
2494 @node File Status Flags
2495 @section File Status Flags
2496 @cindex file status flags
2498 @dfn{File status flags} are used to specify attributes of the opening of a
2499 file.  Unlike the file descriptor flags discussed in @ref{Descriptor
2500 Flags}, the file status flags are shared by duplicated file descriptors
2501 resulting from a single opening of the file.  The file status flags are
2502 specified with the @var{flags} argument to @code{open};
2503 @pxref{Opening and Closing Files}.
2505 File status flags fall into three categories, which are described in the
2506 following sections.
2508 @itemize @bullet
2509 @item
2510 @ref{Access Modes}, specify what type of access is allowed to the
2511 file: reading, writing, or both.  They are set by @code{open} and are
2512 returned by @code{fcntl}, but cannot be changed.
2514 @item
2515 @ref{Open-time Flags}, control details of what @code{open} will do.
2516 These flags are not preserved after the @code{open} call.
2518 @item
2519 @ref{Operating Modes}, affect how operations such as @code{read} and
2520 @code{write} are done.  They are set by @code{open}, and can be fetched or
2521 changed with @code{fcntl}.
2522 @end itemize
2524 The symbols in this section are defined in the header file
2525 @file{fcntl.h}.
2526 @pindex fcntl.h
2528 @menu
2529 * Access Modes::                Whether the descriptor can read or write.
2530 * Open-time Flags::             Details of @code{open}.
2531 * Operating Modes::             Special modes to control I/O operations.
2532 * Getting File Status Flags::   Fetching and changing these flags.
2533 @end menu
2535 @node Access Modes
2536 @subsection File Access Modes
2538 The file access modes allow a file descriptor to be used for reading,
2539 writing, or both.  (In the GNU system, they can also allow none of these,
2540 and allow execution of the file as a program.)  The access modes are chosen
2541 when the file is opened, and never change.
2543 @comment fcntl.h
2544 @comment POSIX.1
2545 @deftypevr Macro int O_RDONLY
2546 Open the file for read access.
2547 @end deftypevr
2549 @comment fcntl.h
2550 @comment POSIX.1
2551 @deftypevr Macro int O_WRONLY
2552 Open the file for write access.
2553 @end deftypevr
2555 @comment fcntl.h
2556 @comment POSIX.1
2557 @deftypevr Macro int O_RDWR
2558 Open the file for both reading and writing.
2559 @end deftypevr
2561 In the GNU system (and not in other systems), @code{O_RDONLY} and
2562 @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
2563 and it is valid for either bit to be set or clear.  This means that
2564 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}.  A file access
2565 mode of zero is permissible; it allows no operations that do input or
2566 output to the file, but does allow other operations such as
2567 @code{fchmod}.  On the GNU system, since ``read-only'' or ``write-only''
2568 is a misnomer, @file{fcntl.h} defines additional names for the file
2569 access modes.  These names are preferred when writing GNU-specific code.
2570 But most programs will want to be portable to other POSIX.1 systems and
2571 should use the POSIX.1 names above instead.
2573 @comment fcntl.h
2574 @comment GNU
2575 @deftypevr Macro int O_READ
2576 Open the file for reading.  Same as @code{O_RDWR}; only defined on GNU.
2577 @end deftypevr
2579 @comment fcntl.h
2580 @comment GNU
2581 @deftypevr Macro int O_WRITE
2582 Open the file for reading.  Same as @code{O_WRONLY}; only defined on GNU.
2583 @end deftypevr
2585 @comment fcntl.h
2586 @comment GNU
2587 @deftypevr Macro int O_EXEC
2588 Open the file for executing.  Only defined on GNU.
2589 @end deftypevr
2591 To determine the file access mode with @code{fcntl}, you must extract
2592 the access mode bits from the retrieved file status flags.  In the GNU
2593 system, you can just test the @code{O_READ} and @code{O_WRITE} bits in
2594 the flags word.  But in other POSIX.1 systems, reading and writing
2595 access modes are not stored as distinct bit flags.  The portable way to
2596 extract the file access mode bits is with @code{O_ACCMODE}.
2598 @comment fcntl.h
2599 @comment POSIX.1
2600 @deftypevr Macro int O_ACCMODE
2601 This macro stands for a mask that can be bitwise-ANDed with the file
2602 status flag value to produce a value representing the file access mode.
2603 The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
2604 (In the GNU system it could also be zero, and it never includes the
2605 @code{O_EXEC} bit.)
2606 @end deftypevr
2608 @node Open-time Flags
2609 @subsection Open-time Flags
2611 The open-time flags specify options affecting how @code{open} will behave.
2612 These options are not preserved once the file is open.  The exception to
2613 this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
2614 @emph{is} saved.  @xref{Opening and Closing Files}, for how to call
2615 @code{open}.
2617 There are two sorts of options specified by open-time flags.
2619 @itemize @bullet
2620 @item
2621 @dfn{File name translation flags} affect how @code{open} looks up the
2622 file name to locate the file, and whether the file can be created.
2623 @cindex file name translation flags
2624 @cindex flags, file name translation
2626 @item
2627 @dfn{Open-time action flags} specify extra operations that @code{open} will
2628 perform on the file once it is open.
2629 @cindex open-time action flags
2630 @cindex flags, open-time action
2631 @end itemize
2633 Here are the file name translation flags.
2635 @comment fcntl.h
2636 @comment POSIX.1
2637 @deftypevr Macro int O_CREAT
2638 If set, the file will be created if it doesn't already exist.
2639 @c !!! mode arg, umask
2640 @cindex create on open (file status flag)
2641 @end deftypevr
2643 @comment fcntl.h
2644 @comment POSIX.1
2645 @deftypevr Macro int O_EXCL
2646 If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
2647 if the specified file already exists.  This is guaranteed to never
2648 clobber an existing file.
2649 @end deftypevr
2651 @comment fcntl.h
2652 @comment POSIX.1
2653 @deftypevr Macro int O_NONBLOCK
2654 @cindex non-blocking open
2655 This prevents @code{open} from blocking for a ``long time'' to open the
2656 file.  This is only meaningful for some kinds of files, usually devices
2657 such as serial ports; when it is not meaningful, it is harmless and
2658 ignored.  Often opening a port to a modem blocks until the modem reports
2659 carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
2660 return immediately without a carrier.
2662 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
2663 mode and a file name translation flag.  This means that specifying
2664 @code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
2665 @pxref{Operating Modes}.  To open the file without blocking but do normal
2666 I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
2667 then call @code{fcntl} to turn the bit off.
2668 @end deftypevr
2670 @comment fcntl.h
2671 @comment POSIX.1
2672 @deftypevr Macro int O_NOCTTY
2673 If the named file is a terminal device, don't make it the controlling
2674 terminal for the process.  @xref{Job Control}, for information about
2675 what it means to be the controlling terminal.
2677 In the GNU system and 4.4 BSD, opening a file never makes it the
2678 controlling terminal and @code{O_NOCTTY} is zero.  However, other
2679 systems may use a nonzero value for @code{O_NOCTTY} and set the
2680 controlling terminal when you open a file that is a terminal device; so
2681 to be portable, use @code{O_NOCTTY} when it is important to avoid this.
2682 @cindex controlling terminal, setting
2683 @end deftypevr
2685 The following three file name translation flags exist only in the GNU system.
2687 @comment fcntl.h
2688 @comment GNU
2689 @deftypevr Macro int O_IGNORE_CTTY
2690 Do not recognize the named file as the controlling terminal, even if it
2691 refers to the process's existing controlling terminal device.  Operations
2692 on the new file descriptor will never induce job control signals.
2693 @xref{Job Control}.
2694 @end deftypevr
2696 @comment fcntl.h
2697 @comment GNU
2698 @deftypevr Macro int O_NOLINK
2699 If the named file is a symbolic link, open the link itself instead of
2700 the file it refers to.  (@code{fstat} on the new file descriptor will
2701 return the information returned by @code{lstat} on the link's name.)
2702 @cindex symbolic link, opening
2703 @end deftypevr
2705 @comment fcntl.h
2706 @comment GNU
2707 @deftypevr Macro int O_NOTRANS
2708 If the named file is specially translated, do not invoke the translator.
2709 Open the bare file the translator itself sees.
2710 @end deftypevr
2713 The open-time action flags tell @code{open} to do additional operations
2714 which are not really related to opening the file.  The reason to do them
2715 as part of @code{open} instead of in separate calls is that @code{open}
2716 can do them @i{atomically}.
2718 @comment fcntl.h
2719 @comment POSIX.1
2720 @deftypevr Macro int O_TRUNC
2721 Truncate the file to zero length.  This option is only useful for
2722 regular files, not special files such as directories or FIFOs.  POSIX.1
2723 requires that you open the file for writing to use @code{O_TRUNC}.  In
2724 BSD and GNU you must have permission to write the file to truncate it,
2725 but you need not open for write access.
2727 This is the only open-time action flag specified by POSIX.1.  There is
2728 no good reason for truncation to be done by @code{open}, instead of by
2729 calling @code{ftruncate} afterwards.  The @code{O_TRUNC} flag existed in
2730 Unix before @code{ftruncate} was invented, and is retained for backward
2731 compatibility.
2732 @end deftypevr
2734 @comment fcntl.h
2735 @comment BSD
2736 @deftypevr Macro int O_SHLOCK
2737 Acquire a shared lock on the file, as with @code{flock}.
2738 @xref{File Locks}.
2740 If @code{O_CREAT} is specified, the locking is done atomically when
2741 creating the file.  You are guaranteed that no other process will get
2742 the lock on the new file first.
2743 @end deftypevr
2745 @comment fcntl.h
2746 @comment BSD
2747 @deftypevr Macro int O_EXLOCK
2748 Acquire an exclusive lock on the file, as with @code{flock}.
2749 @xref{File Locks}.  This is atomic like @code{O_SHLOCK}.
2750 @end deftypevr
2752 @node Operating Modes
2753 @subsection I/O Operating Modes
2755 The operating modes affect how input and output operations using a file
2756 descriptor work.  These flags are set by @code{open} and can be fetched
2757 and changed with @code{fcntl}.
2759 @comment fcntl.h
2760 @comment POSIX.1
2761 @deftypevr Macro int O_APPEND
2762 The bit that enables append mode for the file.  If set, then all
2763 @code{write} operations write the data at the end of the file, extending
2764 it, regardless of the current file position.  This is the only reliable
2765 way to append to a file.  In append mode, you are guaranteed that the
2766 data you write will always go to the current end of the file, regardless
2767 of other processes writing to the file.  Conversely, if you simply set
2768 the file position to the end of file and write, then another process can
2769 extend the file after you set the file position but before you write,
2770 resulting in your data appearing someplace before the real end of file.
2771 @end deftypevr
2773 @comment fcntl.h
2774 @comment POSIX.1
2775 @deftypevr Macro int O_NONBLOCK
2776 The bit that enables nonblocking mode for the file.  If this bit is set,
2777 @code{read} requests on the file can return immediately with a failure
2778 status if there is no input immediately available, instead of blocking.
2779 Likewise, @code{write} requests can also return immediately with a
2780 failure status if the output can't be written immediately.
2782 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
2783 operating mode and a file name translation flag; @pxref{Open-time Flags}.
2784 @end deftypevr
2786 @comment fcntl.h
2787 @comment BSD
2788 @deftypevr Macro int O_NDELAY
2789 This is an obsolete name for @code{O_NONBLOCK}, provided for
2790 compatibility with BSD.  It is not defined by the POSIX.1 standard.
2791 @end deftypevr
2793 The remaining operating modes are BSD and GNU extensions.  They exist only
2794 on some systems.  On other systems, these macros are not defined.
2796 @comment fcntl.h
2797 @comment BSD
2798 @deftypevr Macro int O_ASYNC
2799 The bit that enables asynchronous input mode.  If set, then @code{SIGIO}
2800 signals will be generated when input is available.  @xref{Interrupt Input}.
2802 Asynchronous input mode is a BSD feature.
2803 @end deftypevr
2805 @comment fcntl.h
2806 @comment BSD
2807 @deftypevr Macro int O_FSYNC
2808 The bit that enables synchronous writing for the file.  If set, each
2809 @code{write} call will make sure the data is reliably stored on disk before
2810 returning. @c !!! xref fsync
2812 Synchronous writing is a BSD feature.
2813 @end deftypevr
2815 @comment fcntl.h
2816 @comment BSD
2817 @deftypevr Macro int O_SYNC
2818 This is another name for @code{O_FSYNC}.  They have the same value.
2819 @end deftypevr
2821 @comment fcntl.h
2822 @comment GNU
2823 @deftypevr Macro int O_NOATIME
2824 If this bit is set, @code{read} will not update the access time of the
2825 file.  @xref{File Times}.  This is used by programs that do backups, so
2826 that backing a file up does not count as reading it.
2827 Only the owner of the file or the superuser may use this bit.
2829 This is a GNU extension.
2830 @end deftypevr
2832 @node Getting File Status Flags
2833 @subsection Getting and Setting File Status Flags
2835 The @code{fcntl} function can fetch or change file status flags.
2837 @comment fcntl.h
2838 @comment POSIX.1
2839 @deftypevr Macro int F_GETFL
2840 This macro is used as the @var{command} argument to @code{fcntl}, to
2841 read the file status flags for the open file with descriptor
2842 @var{filedes}.
2844 The normal return value from @code{fcntl} with this command is a
2845 nonnegative number which can be interpreted as the bitwise OR of the
2846 individual flags.  Since the file access modes are not single-bit values,
2847 you can mask off other bits in the returned flags with @code{O_ACCMODE}
2848 to compare them.
2850 In case of an error, @code{fcntl} returns @code{-1}.  The following
2851 @code{errno} error conditions are defined for this command:
2853 @table @code
2854 @item EBADF
2855 The @var{filedes} argument is invalid.
2856 @end table
2857 @end deftypevr
2859 @comment fcntl.h
2860 @comment POSIX.1
2861 @deftypevr Macro int F_SETFL
2862 This macro is used as the @var{command} argument to @code{fcntl}, to set
2863 the file status flags for the open file corresponding to the
2864 @var{filedes} argument.  This command requires a third @code{int}
2865 argument to specify the new flags, so the call looks like this:
2867 @smallexample
2868 fcntl (@var{filedes}, F_SETFL, @var{new-flags})
2869 @end smallexample
2871 You can't change the access mode for the file in this way; that is,
2872 whether the file descriptor was opened for reading or writing.
2874 The normal return value from @code{fcntl} with this command is an
2875 unspecified value other than @code{-1}, which indicates an error.  The
2876 error conditions are the same as for the @code{F_GETFL} command.
2877 @end deftypevr
2879 If you want to modify the file status flags, you should get the current
2880 flags with @code{F_GETFL} and modify the value.  Don't assume that the
2881 flags listed here are the only ones that are implemented; your program
2882 may be run years from now and more flags may exist then.  For example,
2883 here is a function to set or clear the flag @code{O_NONBLOCK} without
2884 altering any other flags:
2886 @smallexample
2887 @group
2888 /* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
2889    @r{or clear the flag if @var{value} is 0.}
2890    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
2893 set_nonblock_flag (int desc, int value)
2895   int oldflags = fcntl (desc, F_GETFL, 0);
2896   /* @r{If reading the flags failed, return error indication now.} */
2897   if (oldflags == -1)
2898     return -1;
2899   /* @r{Set just the flag we want to set.} */
2900   if (value != 0)
2901     oldflags |= O_NONBLOCK;
2902   else
2903     oldflags &= ~O_NONBLOCK;
2904   /* @r{Store modified flag word in the descriptor.} */
2905   return fcntl (desc, F_SETFL, oldflags);
2907 @end group
2908 @end smallexample
2910 @node File Locks
2911 @section File Locks
2913 @cindex file locks
2914 @cindex record locking
2915 The remaining @code{fcntl} commands are used to support @dfn{record
2916 locking}, which permits multiple cooperating programs to prevent each
2917 other from simultaneously accessing parts of a file in error-prone
2918 ways.
2920 @cindex exclusive lock
2921 @cindex write lock
2922 An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
2923 for writing to the specified part of the file.  While a write lock is in
2924 place, no other process can lock that part of the file.
2926 @cindex shared lock
2927 @cindex read lock
2928 A @dfn{shared} or @dfn{read} lock prohibits any other process from
2929 requesting a write lock on the specified part of the file.  However,
2930 other processes can request read locks.
2932 The @code{read} and @code{write} functions do not actually check to see
2933 whether there are any locks in place.  If you want to implement a
2934 locking protocol for a file shared by multiple processes, your application
2935 must do explicit @code{fcntl} calls to request and clear locks at the
2936 appropriate points.
2938 Locks are associated with processes.  A process can only have one kind
2939 of lock set for each byte of a given file.  When any file descriptor for
2940 that file is closed by the process, all of the locks that process holds
2941 on that file are released, even if the locks were made using other
2942 descriptors that remain open.  Likewise, locks are released when a
2943 process exits, and are not inherited by child processes created using
2944 @code{fork} (@pxref{Creating a Process}).
2946 When making a lock, use a @code{struct flock} to specify what kind of
2947 lock and where.  This data type and the associated macros for the
2948 @code{fcntl} function are declared in the header file @file{fcntl.h}.
2949 @pindex fcntl.h
2951 @comment fcntl.h
2952 @comment POSIX.1
2953 @deftp {Data Type} {struct flock}
2954 This structure is used with the @code{fcntl} function to describe a file
2955 lock.  It has these members:
2957 @table @code
2958 @item short int l_type
2959 Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
2960 @code{F_UNLCK}.
2962 @item short int l_whence
2963 This corresponds to the @var{whence} argument to @code{fseek} or
2964 @code{lseek}, and specifies what the offset is relative to.  Its value
2965 can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
2967 @item off_t l_start
2968 This specifies the offset of the start of the region to which the lock
2969 applies, and is given in bytes relative to the point specified by
2970 @code{l_whence} member.
2972 @item off_t l_len
2973 This specifies the length of the region to be locked.  A value of
2974 @code{0} is treated specially; it means the region extends to the end of
2975 the file.
2977 @item pid_t l_pid
2978 This field is the process ID (@pxref{Process Creation Concepts}) of the
2979 process holding the lock.  It is filled in by calling @code{fcntl} with
2980 the @code{F_GETLK} command, but is ignored when making a lock.
2981 @end table
2982 @end deftp
2984 @comment fcntl.h
2985 @comment POSIX.1
2986 @deftypevr Macro int F_GETLK
2987 This macro is used as the @var{command} argument to @code{fcntl}, to
2988 specify that it should get information about a lock.  This command
2989 requires a third argument of type @w{@code{struct flock *}} to be passed
2990 to @code{fcntl}, so that the form of the call is:
2992 @smallexample
2993 fcntl (@var{filedes}, F_GETLK, @var{lockp})
2994 @end smallexample
2996 If there is a lock already in place that would block the lock described
2997 by the @var{lockp} argument, information about that lock overwrites
2998 @code{*@var{lockp}}.  Existing locks are not reported if they are
2999 compatible with making a new lock as specified.  Thus, you should
3000 specify a lock type of @code{F_WRLCK} if you want to find out about both
3001 read and write locks, or @code{F_RDLCK} if you want to find out about
3002 write locks only.
3004 There might be more than one lock affecting the region specified by the
3005 @var{lockp} argument, but @code{fcntl} only returns information about
3006 one of them.  The @code{l_whence} member of the @var{lockp} structure is
3007 set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
3008 set to identify the locked region.
3010 If no lock applies, the only change to the @var{lockp} structure is to
3011 update the @code{l_type} to a value of @code{F_UNLCK}.
3013 The normal return value from @code{fcntl} with this command is an
3014 unspecified value other than @code{-1}, which is reserved to indicate an
3015 error.  The following @code{errno} error conditions are defined for
3016 this command:
3018 @table @code
3019 @item EBADF
3020 The @var{filedes} argument is invalid.
3022 @item EINVAL
3023 Either the @var{lockp} argument doesn't specify valid lock information,
3024 or the file associated with @var{filedes} doesn't support locks.
3025 @end table
3026 @end deftypevr
3028 @comment fcntl.h
3029 @comment POSIX.1
3030 @deftypevr Macro int F_SETLK
3031 This macro is used as the @var{command} argument to @code{fcntl}, to
3032 specify that it should set or clear a lock.  This command requires a
3033 third argument of type @w{@code{struct flock *}} to be passed to
3034 @code{fcntl}, so that the form of the call is:
3036 @smallexample
3037 fcntl (@var{filedes}, F_SETLK, @var{lockp})
3038 @end smallexample
3040 If the process already has a lock on any part of the region, the old lock
3041 on that part is replaced with the new lock.  You can remove a lock
3042 by specifying a lock type of @code{F_UNLCK}.
3044 If the lock cannot be set, @code{fcntl} returns immediately with a value
3045 of @code{-1}.  This function does not block waiting for other processes
3046 to release locks.  If @code{fcntl} succeeds, it return a value other
3047 than @code{-1}.
3049 The following @code{errno} error conditions are defined for this
3050 function:
3052 @table @code
3053 @item EAGAIN
3054 @itemx EACCES
3055 The lock cannot be set because it is blocked by an existing lock on the
3056 file.  Some systems use @code{EAGAIN} in this case, and other systems
3057 use @code{EACCES}; your program should treat them alike, after
3058 @code{F_SETLK}.  (The GNU system always uses @code{EAGAIN}.)
3060 @item EBADF
3061 Either: the @var{filedes} argument is invalid; you requested a read lock
3062 but the @var{filedes} is not open for read access; or, you requested a
3063 write lock but the @var{filedes} is not open for write access.
3065 @item EINVAL
3066 Either the @var{lockp} argument doesn't specify valid lock information,
3067 or the file associated with @var{filedes} doesn't support locks.
3069 @item ENOLCK
3070 The system has run out of file lock resources; there are already too
3071 many file locks in place.
3073 Well-designed file systems never report this error, because they have no
3074 limitation on the number of locks.  However, you must still take account
3075 of the possibility of this error, as it could result from network access
3076 to a file system on another machine.
3077 @end table
3078 @end deftypevr
3080 @comment fcntl.h
3081 @comment POSIX.1
3082 @deftypevr Macro int F_SETLKW
3083 This macro is used as the @var{command} argument to @code{fcntl}, to
3084 specify that it should set or clear a lock.  It is just like the
3085 @code{F_SETLK} command, but causes the process to block (or wait)
3086 until the request can be specified.
3088 This command requires a third argument of type @code{struct flock *}, as
3089 for the @code{F_SETLK} command.
3091 The @code{fcntl} return values and errors are the same as for the
3092 @code{F_SETLK} command, but these additional @code{errno} error conditions
3093 are defined for this command:
3095 @table @code
3096 @item EINTR
3097 The function was interrupted by a signal while it was waiting.
3098 @xref{Interrupted Primitives}.
3100 @item EDEADLK
3101 The specified region is being locked by another process.  But that
3102 process is waiting to lock a region which the current process has
3103 locked, so waiting for the lock would result in deadlock.  The system
3104 does not guarantee that it will detect all such conditions, but it lets
3105 you know if it notices one.
3106 @end table
3107 @end deftypevr
3110 The following macros are defined for use as values for the @code{l_type}
3111 member of the @code{flock} structure.  The values are integer constants.
3113 @table @code
3114 @comment fcntl.h
3115 @comment POSIX.1
3116 @vindex F_RDLCK
3117 @item F_RDLCK
3118 This macro is used to specify a read (or shared) lock.
3120 @comment fcntl.h
3121 @comment POSIX.1
3122 @vindex F_WRLCK
3123 @item F_WRLCK
3124 This macro is used to specify a write (or exclusive) lock.
3126 @comment fcntl.h
3127 @comment POSIX.1
3128 @vindex F_UNLCK
3129 @item F_UNLCK
3130 This macro is used to specify that the region is unlocked.
3131 @end table
3133 As an example of a situation where file locking is useful, consider a
3134 program that can be run simultaneously by several different users, that
3135 logs status information to a common file.  One example of such a program
3136 might be a game that uses a file to keep track of high scores.  Another
3137 example might be a program that records usage or accounting information
3138 for billing purposes.
3140 Having multiple copies of the program simultaneously writing to the
3141 file could cause the contents of the file to become mixed up.  But
3142 you can prevent this kind of problem by setting a write lock on the
3143 file before actually writing to the file.
3145 If the program also needs to read the file and wants to make sure that
3146 the contents of the file are in a consistent state, then it can also use
3147 a read lock.  While the read lock is set, no other process can lock
3148 that part of the file for writing.
3150 @c ??? This section could use an example program.
3152 Remember that file locks are only a @emph{voluntary} protocol for
3153 controlling access to a file.  There is still potential for access to
3154 the file by programs that don't use the lock protocol.
3156 @node Interrupt Input
3157 @section Interrupt-Driven Input
3159 @cindex interrupt-driven input
3160 If you set the @code{O_ASYNC} status flag on a file descriptor
3161 (@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
3162 input or output becomes possible on that file descriptor.  The process
3163 or process group to receive the signal can be selected by using the
3164 @code{F_SETOWN} command to the @code{fcntl} function.  If the file
3165 descriptor is a socket, this also selects the recipient of @code{SIGURG}
3166 signals that are delivered when out-of-band data arrives on that socket;
3167 see @ref{Out-of-Band Data}.  (@code{SIGURG} is sent in any situation
3168 where @code{select} would report the socket as having an ``exceptional
3169 condition''.  @xref{Waiting for I/O}.)
3171 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
3172 signals are sent to the foreground process group of the terminal.
3173 @xref{Job Control}.
3175 @pindex fcntl.h
3176 The symbols in this section are defined in the header file
3177 @file{fcntl.h}.
3179 @comment fcntl.h
3180 @comment BSD
3181 @deftypevr Macro int F_GETOWN
3182 This macro is used as the @var{command} argument to @code{fcntl}, to
3183 specify that it should get information about the process or process
3184 group to which @code{SIGIO} signals are sent.  (For a terminal, this is
3185 actually the foreground process group ID, which you can get using
3186 @code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
3188 The return value is interpreted as a process ID; if negative, its
3189 absolute value is the process group ID.
3191 The following @code{errno} error condition is defined for this command:
3193 @table @code
3194 @item EBADF
3195 The @var{filedes} argument is invalid.
3196 @end table
3197 @end deftypevr
3199 @comment fcntl.h
3200 @comment BSD
3201 @deftypevr Macro int F_SETOWN
3202 This macro is used as the @var{command} argument to @code{fcntl}, to
3203 specify that it should set the process or process group to which
3204 @code{SIGIO} signals are sent.  This command requires a third argument
3205 of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
3206 the call is:
3208 @smallexample
3209 fcntl (@var{filedes}, F_SETOWN, @var{pid})
3210 @end smallexample
3212 The @var{pid} argument should be a process ID.  You can also pass a
3213 negative number whose absolute value is a process group ID.
3215 The return value from @code{fcntl} with this command is @code{-1}
3216 in case of error and some other value if successful.  The following
3217 @code{errno} error conditions are defined for this command:
3219 @table @code
3220 @item EBADF
3221 The @var{filedes} argument is invalid.
3223 @item ESRCH
3224 There is no process or process group corresponding to @var{pid}.
3225 @end table
3226 @end deftypevr
3228 @c ??? This section could use an example program.