powerpc: Fix POWER9 implies
[glibc.git] / manual / llio.texi
blob019dea2c318980e7c1b629353a2e7f2e9328bf6e
1 @node Low-Level I/O, File System Interface, I/O on Streams, Top
2 @c %MENU% Low-level, less portable I/O
3 @chapter Low-Level Input/Output
5 This chapter describes functions for performing low-level input/output
6 operations on file descriptors.  These functions include the primitives
7 for the higher-level I/O functions described in @ref{I/O on Streams}, as
8 well as functions for performing low-level control operations for which
9 there are no equivalents on streams.
11 Stream-level I/O is more flexible and usually more convenient;
12 therefore, programmers generally use the descriptor-level functions only
13 when necessary.  These are some of the usual reasons:
15 @itemize @bullet
16 @item
17 For reading binary files in large chunks.
19 @item
20 For reading an entire file into core before parsing it.
22 @item
23 To perform operations other than data transfer, which can only be done
24 with a descriptor.  (You can use @code{fileno} to get the descriptor
25 corresponding to a stream.)
27 @item
28 To pass descriptors to a child process.  (The child can create its own
29 stream to use a descriptor that it inherits, but cannot inherit a stream
30 directly.)
31 @end itemize
33 @menu
34 * Opening and Closing Files::           How to open and close file
35                                          descriptors.
36 * I/O Primitives::                      Reading and writing data.
37 * File Position Primitive::             Setting a descriptor's file
38                                          position.
39 * Descriptors and Streams::             Converting descriptor to stream
40                                          or vice-versa.
41 * Stream/Descriptor Precautions::       Precautions needed if you use both
42                                          descriptors and streams.
43 * Scatter-Gather::                      Fast I/O to discontinuous buffers.
44 * Memory-mapped I/O::                   Using files like memory.
45 * Waiting for I/O::                     How to check for input or output
46                                          on multiple file descriptors.
47 * Synchronizing I/O::                   Making sure all I/O actions completed.
48 * Asynchronous I/O::                    Perform I/O in parallel.
49 * Control Operations::                  Various other operations on file
50                                          descriptors.
51 * Duplicating Descriptors::             Fcntl commands for duplicating
52                                          file descriptors.
53 * Descriptor Flags::                    Fcntl commands for manipulating
54                                          flags associated with file
55                                          descriptors.
56 * File Status Flags::                   Fcntl commands for manipulating
57                                          flags associated with open files.
58 * File Locks::                          Fcntl commands for implementing
59                                          file locking.
60 * Open File Description Locks::         Fcntl commands for implementing
61                                          open file description locking.
62 * Open File Description Locks Example:: An example of open file description lock
63                                          usage
64 * Interrupt Input::                     Getting an asynchronous signal when
65                                          input arrives.
66 * IOCTLs::                              Generic I/O Control operations.
67 @end menu
70 @node Opening and Closing Files
71 @section Opening and Closing Files
73 @cindex opening a file descriptor
74 @cindex closing a file descriptor
75 This section describes the primitives for opening and closing files
76 using file descriptors.  The @code{open} and @code{creat} functions are
77 declared in the header file @file{fcntl.h}, while @code{close} is
78 declared in @file{unistd.h}.
79 @pindex unistd.h
80 @pindex fcntl.h
82 @comment fcntl.h
83 @comment POSIX.1
84 @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
85 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
86 The @code{open} function creates and returns a new file descriptor for
87 the file named by @var{filename}.  Initially, the file position
88 indicator for the file is at the beginning of the file.  The argument
89 @var{mode} (@pxref{Permission Bits}) is used only when a file is
90 created, but it doesn't hurt to supply the argument in any case.
92 The @var{flags} argument controls how the file is to be opened.  This is
93 a bit mask; you create the value by the bitwise OR of the appropriate
94 parameters (using the @samp{|} operator in C).
95 @xref{File Status Flags}, for the parameters available.
97 The normal return value from @code{open} is a non-negative integer file
98 descriptor.  In the case of an error, a value of @math{-1} is returned
99 instead.  In addition to the usual file name errors (@pxref{File
100 Name Errors}), the following @code{errno} error conditions are defined
101 for this function:
103 @table @code
104 @item EACCES
105 The file exists but is not readable/writable as requested by the @var{flags}
106 argument, the file does not exist and the directory is unwritable so
107 it cannot be created.
109 @item EEXIST
110 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
111 exists.
113 @item EINTR
114 The @code{open} operation was interrupted by a signal.
115 @xref{Interrupted Primitives}.
117 @item EISDIR
118 The @var{flags} argument specified write access, and the file is a directory.
120 @item EMFILE
121 The process has too many files open.
122 The maximum number of file descriptors is controlled by the
123 @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
125 @item ENFILE
126 The entire system, or perhaps the file system which contains the
127 directory, cannot support any additional open files at the moment.
128 (This problem cannot happen on @gnuhurdsystems{}.)
130 @item ENOENT
131 The named file does not exist, and @code{O_CREAT} is not specified.
133 @item ENOSPC
134 The directory or file system that would contain the new file cannot be
135 extended, because there is no disk space left.
137 @item ENXIO
138 @code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
139 argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
140 FIFOs}), and no process has the file open for reading.
142 @item EROFS
143 The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
144 @code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
145 or @code{O_CREAT} is set and the file does not already exist.
146 @end table
148 @c !!! umask
150 If on a 32 bit machine the sources are translated with
151 @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file
152 descriptor opened in the large file mode which enables the file handling
153 functions to use files up to @twoexp{63} bytes in size and offset from
154 @minus{}@twoexp{63} to @twoexp{63}.  This happens transparently for the user
155 since all of the lowlevel file handling functions are equally replaced.
157 This function is a cancellation point in multi-threaded programs.  This
158 is a problem if the thread allocates some resources (like memory, file
159 descriptors, semaphores or whatever) at the time @code{open} is
160 called.  If the thread gets canceled these resources stay allocated
161 until the program ends.  To avoid this calls to @code{open} should be
162 protected using cancellation handlers.
163 @c ref pthread_cleanup_push / pthread_cleanup_pop
165 The @code{open} function is the underlying primitive for the @code{fopen}
166 and @code{freopen} functions, that create streams.
167 @end deftypefun
169 @comment fcntl.h
170 @comment Unix98
171 @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
172 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
173 This function is similar to @code{open}.  It returns a file descriptor
174 which can be used to access the file named by @var{filename}.  The only
175 difference is that on 32 bit systems the file is opened in the
176 large file mode.  I.e., file length and file offsets can exceed 31 bits.
178 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
179 function is actually available under the name @code{open}.  I.e., the
180 new, extended API using 64 bit file sizes and offsets transparently
181 replaces the old API.
182 @end deftypefun
184 @comment fcntl.h
185 @comment POSIX.1
186 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
187 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
188 This function is obsolete.  The call:
190 @smallexample
191 creat (@var{filename}, @var{mode})
192 @end smallexample
194 @noindent
195 is equivalent to:
197 @smallexample
198 open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
199 @end smallexample
201 If on a 32 bit machine the sources are translated with
202 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
203 descriptor opened in the large file mode which enables the file handling
204 functions to use files up to @twoexp{63} in size and offset from
205 @minus{}@twoexp{63} to @twoexp{63}.  This happens transparently for the user
206 since all of the lowlevel file handling functions are equally replaced.
207 @end deftypefn
209 @comment fcntl.h
210 @comment Unix98
211 @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
212 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
213 This function is similar to @code{creat}.  It returns a file descriptor
214 which can be used to access the file named by @var{filename}.  The only
215 the difference is that on 32 bit systems the file is opened in the
216 large file mode.  I.e., file length and file offsets can exceed 31 bits.
218 To use this file descriptor one must not use the normal operations but
219 instead the counterparts named @code{*64}, e.g., @code{read64}.
221 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
222 function is actually available under the name @code{open}.  I.e., the
223 new, extended API using 64 bit file sizes and offsets transparently
224 replaces the old API.
225 @end deftypefn
227 @comment unistd.h
228 @comment POSIX.1
229 @deftypefun int close (int @var{filedes})
230 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
231 The function @code{close} closes the file descriptor @var{filedes}.
232 Closing a file has the following consequences:
234 @itemize @bullet
235 @item
236 The file descriptor is deallocated.
238 @item
239 Any record locks owned by the process on the file are unlocked.
241 @item
242 When all file descriptors associated with a pipe or FIFO have been closed,
243 any unread data is discarded.
244 @end itemize
246 This function is a cancellation point in multi-threaded programs.  This
247 is a problem if the thread allocates some resources (like memory, file
248 descriptors, semaphores or whatever) at the time @code{close} is
249 called.  If the thread gets canceled these resources stay allocated
250 until the program ends.  To avoid this, calls to @code{close} should be
251 protected using cancellation handlers.
252 @c ref pthread_cleanup_push / pthread_cleanup_pop
254 The normal return value from @code{close} is @math{0}; a value of @math{-1}
255 is returned in case of failure.  The following @code{errno} error
256 conditions are defined for this function:
258 @table @code
259 @item EBADF
260 The @var{filedes} argument is not a valid file descriptor.
262 @item EINTR
263 The @code{close} call was interrupted by a signal.
264 @xref{Interrupted Primitives}.
265 Here is an example of how to handle @code{EINTR} properly:
267 @smallexample
268 TEMP_FAILURE_RETRY (close (desc));
269 @end smallexample
271 @item ENOSPC
272 @itemx EIO
273 @itemx EDQUOT
274 When the file is accessed by NFS, these errors from @code{write} can sometimes
275 not be detected until @code{close}.  @xref{I/O Primitives}, for details
276 on their meaning.
277 @end table
279 Please note that there is @emph{no} separate @code{close64} function.
280 This is not necessary since this function does not determine nor depend
281 on the mode of the file.  The kernel which performs the @code{close}
282 operation knows which mode the descriptor is used for and can handle
283 this situation.
284 @end deftypefun
286 To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
287 of trying to close its underlying file descriptor with @code{close}.
288 This flushes any buffered output and updates the stream object to
289 indicate that it is closed.
291 @node I/O Primitives
292 @section Input and Output Primitives
294 This section describes the functions for performing primitive input and
295 output operations on file descriptors: @code{read}, @code{write}, and
296 @code{lseek}.  These functions are declared in the header file
297 @file{unistd.h}.
298 @pindex unistd.h
300 @comment unistd.h
301 @comment POSIX.1
302 @deftp {Data Type} ssize_t
303 This data type is used to represent the sizes of blocks that can be
304 read or written in a single operation.  It is similar to @code{size_t},
305 but must be a signed type.
306 @end deftp
308 @cindex reading from a file descriptor
309 @comment unistd.h
310 @comment POSIX.1
311 @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
312 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
313 The @code{read} function reads up to @var{size} bytes from the file
314 with descriptor @var{filedes}, storing the results in the @var{buffer}.
315 (This is not necessarily a character string, and no terminating null
316 character is added.)
318 @cindex end-of-file, on a file descriptor
319 The return value is the number of bytes actually read.  This might be
320 less than @var{size}; for example, if there aren't that many bytes left
321 in the file or if there aren't that many bytes immediately available.
322 The exact behavior depends on what kind of file it is.  Note that
323 reading less than @var{size} bytes is not an error.
325 A value of zero indicates end-of-file (except if the value of the
326 @var{size} argument is also zero).  This is not considered an error.
327 If you keep calling @code{read} while at end-of-file, it will keep
328 returning zero and doing nothing else.
330 If @code{read} returns at least one character, there is no way you can
331 tell whether end-of-file was reached.  But if you did reach the end, the
332 next read will return zero.
334 In case of an error, @code{read} returns @math{-1}.  The following
335 @code{errno} error conditions are defined for this function:
337 @table @code
338 @item EAGAIN
339 Normally, when no input is immediately available, @code{read} waits for
340 some input.  But if the @code{O_NONBLOCK} flag is set for the file
341 (@pxref{File Status Flags}), @code{read} returns immediately without
342 reading any data, and reports this error.
344 @strong{Compatibility Note:} Most versions of BSD Unix use a different
345 error code for this: @code{EWOULDBLOCK}.  In @theglibc{},
346 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
347 which name you use.
349 On some systems, reading a large amount of data from a character special
350 file can also fail with @code{EAGAIN} if the kernel cannot find enough
351 physical memory to lock down the user's pages.  This is limited to
352 devices that transfer with direct memory access into the user's memory,
353 which means it does not include terminals, since they always use
354 separate buffers inside the kernel.  This problem never happens on
355 @gnuhurdsystems{}.
357 Any condition that could result in @code{EAGAIN} can instead result in a
358 successful @code{read} which returns fewer bytes than requested.
359 Calling @code{read} again immediately would result in @code{EAGAIN}.
361 @item EBADF
362 The @var{filedes} argument is not a valid file descriptor,
363 or is not open for reading.
365 @item EINTR
366 @code{read} was interrupted by a signal while it was waiting for input.
367 @xref{Interrupted Primitives}.  A signal will not necessary cause
368 @code{read} to return @code{EINTR}; it may instead result in a
369 successful @code{read} which returns fewer bytes than requested.
371 @item EIO
372 For many devices, and for disk files, this error code indicates
373 a hardware error.
375 @code{EIO} also occurs when a background process tries to read from the
376 controlling terminal, and the normal action of stopping the process by
377 sending it a @code{SIGTTIN} signal isn't working.  This might happen if
378 the signal is being blocked or ignored, or because the process group is
379 orphaned.  @xref{Job Control}, for more information about job control,
380 and @ref{Signal Handling}, for information about signals.
382 @item EINVAL
383 In some systems, when reading from a character or block device, position
384 and size offsets must be aligned to a particular block size.  This error
385 indicates that the offsets were not properly aligned.
386 @end table
388 Please note that there is no function named @code{read64}.  This is not
389 necessary since this function does not directly modify or handle the
390 possibly wide file offset.  Since the kernel handles this state
391 internally, the @code{read} function can be used for all cases.
393 This function is a cancellation point in multi-threaded programs.  This
394 is a problem if the thread allocates some resources (like memory, file
395 descriptors, semaphores or whatever) at the time @code{read} is
396 called.  If the thread gets canceled these resources stay allocated
397 until the program ends.  To avoid this, calls to @code{read} should be
398 protected using cancellation handlers.
399 @c ref pthread_cleanup_push / pthread_cleanup_pop
401 The @code{read} function is the underlying primitive for all of the
402 functions that read from streams, such as @code{fgetc}.
403 @end deftypefun
405 @comment unistd.h
406 @comment Unix98
407 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
408 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
409 @c This is usually a safe syscall.  The sysdeps/posix fallback emulation
410 @c is not MT-Safe because it uses lseek, read and lseek back, but is it
411 @c used anywhere?
412 The @code{pread} function is similar to the @code{read} function.  The
413 first three arguments are identical, and the return values and error
414 codes also correspond.
416 The difference is the fourth argument and its handling.  The data block
417 is not read from the current position of the file descriptor
418 @code{filedes}.  Instead the data is read from the file starting at
419 position @var{offset}.  The position of the file descriptor itself is
420 not affected by the operation.  The value is the same as before the call.
422 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
423 @code{pread} function is in fact @code{pread64} and the type
424 @code{off_t} has 64 bits, which makes it possible to handle files up to
425 @twoexp{63} bytes in length.
427 The return value of @code{pread} describes the number of bytes read.
428 In the error case it returns @math{-1} like @code{read} does and the
429 error codes are also the same, with these additions:
431 @table @code
432 @item EINVAL
433 The value given for @var{offset} is negative and therefore illegal.
435 @item ESPIPE
436 The file descriptor @var{filedes} is associate with a pipe or a FIFO and
437 this device does not allow positioning of the file pointer.
438 @end table
440 The function is an extension defined in the Unix Single Specification
441 version 2.
442 @end deftypefun
444 @comment unistd.h
445 @comment Unix98
446 @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
447 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
448 @c This is usually a safe syscall.  The sysdeps/posix fallback emulation
449 @c is not MT-Safe because it uses lseek64, read and lseek64 back, but is
450 @c it used anywhere?
451 This function is similar to the @code{pread} function.  The difference
452 is that the @var{offset} parameter is of type @code{off64_t} instead of
453 @code{off_t} which makes it possible on 32 bit machines to address
454 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
455 file descriptor @code{filedes} must be opened using @code{open64} since
456 otherwise the large offsets possible with @code{off64_t} will lead to
457 errors with a descriptor in small file mode.
459 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
460 32 bit machine this function is actually available under the name
461 @code{pread} and so transparently replaces the 32 bit interface.
462 @end deftypefun
464 @cindex writing to a file descriptor
465 @comment unistd.h
466 @comment POSIX.1
467 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
468 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
469 @c Some say write is thread-unsafe on Linux without O_APPEND.  In the VFS layer
470 @c the vfs_write() does no locking around the acquisition of a file offset and
471 @c therefore multiple threads / kernel tasks may race and get the same offset
472 @c resulting in data loss.
474 @c See:
475 @c http://thread.gmane.org/gmane.linux.kernel/397980
476 @c http://lwn.net/Articles/180387/
478 @c The counter argument is that POSIX only says that the write starts at the
479 @c file position and that the file position is updated *before* the function
480 @c returns.  What that really means is that any expectation of atomic writes is
481 @c strictly an invention of the interpretation of the reader.  Data loss could
482 @c happen if two threads start the write at the same time.  Only writes that
483 @c come after the return of another write are guaranteed to follow the other
484 @c write.
486 @c The other side of the coin is that POSIX goes on further to say in
487 @c "2.9.7 Thread Interactions with Regular File Operations" that threads
488 @c should never see interleaving sets of file operations, but it is insane
489 @c to do anything like that because it kills performance, so you don't get
490 @c those guarantees in Linux.
492 @c So we mark it thread safe, it doesn't blow up, but you might loose
493 @c data, and we don't strictly meet the POSIX requirements.
495 @c The fix for file offsets racing was merged in 3.14, the commits were:
496 @c 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4, and
497 @c d7a15f8d0777955986a2ab00ab181795cab14b01.  Therefore after Linux 3.14 you
498 @c should get mostly MT-safe writes.
499 The @code{write} function writes up to @var{size} bytes from
500 @var{buffer} to the file with descriptor @var{filedes}.  The data in
501 @var{buffer} is not necessarily a character string and a null character is
502 output like any other character.
504 The return value is the number of bytes actually written.  This may be
505 @var{size}, but can always be smaller.  Your program should always call
506 @code{write} in a loop, iterating until all the data is written.
508 Once @code{write} returns, the data is enqueued to be written and can be
509 read back right away, but it is not necessarily written out to permanent
510 storage immediately.  You can use @code{fsync} when you need to be sure
511 your data has been permanently stored before continuing.  (It is more
512 efficient for the system to batch up consecutive writes and do them all
513 at once when convenient.  Normally they will always be written to disk
514 within a minute or less.)  Modern systems provide another function
515 @code{fdatasync} which guarantees integrity only for the file data and
516 is therefore faster.
517 @c !!! xref fsync, fdatasync
518 You can use the @code{O_FSYNC} open mode to make @code{write} always
519 store the data to disk before returning; @pxref{Operating Modes}.
521 In the case of an error, @code{write} returns @math{-1}.  The following
522 @code{errno} error conditions are defined for this function:
524 @table @code
525 @item EAGAIN
526 Normally, @code{write} blocks until the write operation is complete.
527 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
528 Operations}), it returns immediately without writing any data and
529 reports this error.  An example of a situation that might cause the
530 process to block on output is writing to a terminal device that supports
531 flow control, where output has been suspended by receipt of a STOP
532 character.
534 @strong{Compatibility Note:} Most versions of BSD Unix use a different
535 error code for this: @code{EWOULDBLOCK}.  In @theglibc{},
536 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
537 which name you use.
539 On some systems, writing a large amount of data from a character special
540 file can also fail with @code{EAGAIN} if the kernel cannot find enough
541 physical memory to lock down the user's pages.  This is limited to
542 devices that transfer with direct memory access into the user's memory,
543 which means it does not include terminals, since they always use
544 separate buffers inside the kernel.  This problem does not arise on
545 @gnuhurdsystems{}.
547 @item EBADF
548 The @var{filedes} argument is not a valid file descriptor,
549 or is not open for writing.
551 @item EFBIG
552 The size of the file would become larger than the implementation can support.
554 @item EINTR
555 The @code{write} operation was interrupted by a signal while it was
556 blocked waiting for completion.  A signal will not necessarily cause
557 @code{write} to return @code{EINTR}; it may instead result in a
558 successful @code{write} which writes fewer bytes than requested.
559 @xref{Interrupted Primitives}.
561 @item EIO
562 For many devices, and for disk files, this error code indicates
563 a hardware error.
565 @item ENOSPC
566 The device containing the file is full.
568 @item EPIPE
569 This error is returned when you try to write to a pipe or FIFO that
570 isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
571 signal is also sent to the process; see @ref{Signal Handling}.
573 @item EINVAL
574 In some systems, when writing to a character or block device, position
575 and size offsets must be aligned to a particular block size.  This error
576 indicates that the offsets were not properly aligned.
577 @end table
579 Unless you have arranged to prevent @code{EINTR} failures, you should
580 check @code{errno} after each failing call to @code{write}, and if the
581 error was @code{EINTR}, you should simply repeat the call.
582 @xref{Interrupted Primitives}.  The easy way to do this is with the
583 macro @code{TEMP_FAILURE_RETRY}, as follows:
585 @smallexample
586 nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
587 @end smallexample
589 Please note that there is no function named @code{write64}.  This is not
590 necessary since this function does not directly modify or handle the
591 possibly wide file offset.  Since the kernel handles this state
592 internally the @code{write} function can be used for all cases.
594 This function is a cancellation point in multi-threaded programs.  This
595 is a problem if the thread allocates some resources (like memory, file
596 descriptors, semaphores or whatever) at the time @code{write} is
597 called.  If the thread gets canceled these resources stay allocated
598 until the program ends.  To avoid this, calls to @code{write} should be
599 protected using cancellation handlers.
600 @c ref pthread_cleanup_push / pthread_cleanup_pop
602 The @code{write} function is the underlying primitive for all of the
603 functions that write to streams, such as @code{fputc}.
604 @end deftypefun
606 @comment unistd.h
607 @comment Unix98
608 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
609 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
610 @c This is usually a safe syscall.  The sysdeps/posix fallback emulation
611 @c is not MT-Safe because it uses lseek, write and lseek back, but is it
612 @c used anywhere?
613 The @code{pwrite} function is similar to the @code{write} function.  The
614 first three arguments are identical, and the return values and error codes
615 also correspond.
617 The difference is the fourth argument and its handling.  The data block
618 is not written to the current position of the file descriptor
619 @code{filedes}.  Instead the data is written to the file starting at
620 position @var{offset}.  The position of the file descriptor itself is
621 not affected by the operation.  The value is the same as before the call.
623 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
624 @code{pwrite} function is in fact @code{pwrite64} and the type
625 @code{off_t} has 64 bits, which makes it possible to handle files up to
626 @twoexp{63} bytes in length.
628 The return value of @code{pwrite} describes the number of written bytes.
629 In the error case it returns @math{-1} like @code{write} does and the
630 error codes are also the same, with these additions:
632 @table @code
633 @item EINVAL
634 The value given for @var{offset} is negative and therefore illegal.
636 @item ESPIPE
637 The file descriptor @var{filedes} is associated with a pipe or a FIFO and
638 this device does not allow positioning of the file pointer.
639 @end table
641 The function is an extension defined in the Unix Single Specification
642 version 2.
643 @end deftypefun
645 @comment unistd.h
646 @comment Unix98
647 @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
648 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
649 @c This is usually a safe syscall.  The sysdeps/posix fallback emulation
650 @c is not MT-Safe because it uses lseek64, write and lseek64 back, but
651 @c is it used anywhere?
652 This function is similar to the @code{pwrite} function.  The difference
653 is that the @var{offset} parameter is of type @code{off64_t} instead of
654 @code{off_t} which makes it possible on 32 bit machines to address
655 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
656 file descriptor @code{filedes} must be opened using @code{open64} since
657 otherwise the large offsets possible with @code{off64_t} will lead to
658 errors with a descriptor in small file mode.
660 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
661 32 bit machine this function is actually available under the name
662 @code{pwrite} and so transparently replaces the 32 bit interface.
663 @end deftypefun
666 @node File Position Primitive
667 @section Setting the File Position of a Descriptor
669 Just as you can set the file position of a stream with @code{fseek}, you
670 can set the file position of a descriptor with @code{lseek}.  This
671 specifies the position in the file for the next @code{read} or
672 @code{write} operation.  @xref{File Positioning}, for more information
673 on the file position and what it means.
675 To read the current file position value from a descriptor, use
676 @code{lseek (@var{desc}, 0, SEEK_CUR)}.
678 @cindex file positioning on a file descriptor
679 @cindex positioning a file descriptor
680 @cindex seeking on a file descriptor
681 @comment unistd.h
682 @comment POSIX.1
683 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
684 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
685 The @code{lseek} function is used to change the file position of the
686 file with descriptor @var{filedes}.
688 The @var{whence} argument specifies how the @var{offset} should be
689 interpreted, in the same way as for the @code{fseek} function, and it must
690 be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
691 @code{SEEK_END}.
693 @table @code
694 @item SEEK_SET
695 Specifies that @var{offset} is a count of characters from the beginning
696 of the file.
698 @item SEEK_CUR
699 Specifies that @var{offset} is a count of characters from the current
700 file position.  This count may be positive or negative.
702 @item SEEK_END
703 Specifies that @var{offset} is a count of characters from the end of
704 the file.  A negative count specifies a position within the current
705 extent of the file; a positive count specifies a position past the
706 current end.  If you set the position past the current end, and
707 actually write data, you will extend the file with zeros up to that
708 position.
709 @end table
711 The return value from @code{lseek} is normally the resulting file
712 position, measured in bytes from the beginning of the file.
713 You can use this feature together with @code{SEEK_CUR} to read the
714 current file position.
716 If you want to append to the file, setting the file position to the
717 current end of file with @code{SEEK_END} is not sufficient.  Another
718 process may write more data after you seek but before you write,
719 extending the file so the position you write onto clobbers their data.
720 Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
722 You can set the file position past the current end of the file.  This
723 does not by itself make the file longer; @code{lseek} never changes the
724 file.  But subsequent output at that position will extend the file.
725 Characters between the previous end of file and the new position are
726 filled with zeros.  Extending the file in this way can create a
727 ``hole'': the blocks of zeros are not actually allocated on disk, so the
728 file takes up less space than it appears to; it is then called a
729 ``sparse file''.
730 @cindex sparse files
731 @cindex holes in files
733 If the file position cannot be changed, or the operation is in some way
734 invalid, @code{lseek} returns a value of @math{-1}.  The following
735 @code{errno} error conditions are defined for this function:
737 @table @code
738 @item EBADF
739 The @var{filedes} is not a valid file descriptor.
741 @item EINVAL
742 The @var{whence} argument value is not valid, or the resulting
743 file offset is not valid.  A file offset is invalid.
745 @item ESPIPE
746 The @var{filedes} corresponds to an object that cannot be positioned,
747 such as a pipe, FIFO or terminal device.  (POSIX.1 specifies this error
748 only for pipes and FIFOs, but on @gnusystems{}, you always get
749 @code{ESPIPE} if the object is not seekable.)
750 @end table
752 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
753 @code{lseek} function is in fact @code{lseek64} and the type
754 @code{off_t} has 64 bits which makes it possible to handle files up to
755 @twoexp{63} bytes in length.
757 This function is a cancellation point in multi-threaded programs.  This
758 is a problem if the thread allocates some resources (like memory, file
759 descriptors, semaphores or whatever) at the time @code{lseek} is
760 called.  If the thread gets canceled these resources stay allocated
761 until the program ends.  To avoid this calls to @code{lseek} should be
762 protected using cancellation handlers.
763 @c ref pthread_cleanup_push / pthread_cleanup_pop
765 The @code{lseek} function is the underlying primitive for the
766 @code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
767 @code{rewind} functions, which operate on streams instead of file
768 descriptors.
769 @end deftypefun
771 @comment unistd.h
772 @comment Unix98
773 @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
774 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
775 This function is similar to the @code{lseek} function.  The difference
776 is that the @var{offset} parameter is of type @code{off64_t} instead of
777 @code{off_t} which makes it possible on 32 bit machines to address
778 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes.  The
779 file descriptor @code{filedes} must be opened using @code{open64} since
780 otherwise the large offsets possible with @code{off64_t} will lead to
781 errors with a descriptor in small file mode.
783 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
784 32 bits machine this function is actually available under the name
785 @code{lseek} and so transparently replaces the 32 bit interface.
786 @end deftypefun
788 You can have multiple descriptors for the same file if you open the file
789 more than once, or if you duplicate a descriptor with @code{dup}.
790 Descriptors that come from separate calls to @code{open} have independent
791 file positions; using @code{lseek} on one descriptor has no effect on the
792 other.  For example,
794 @smallexample
795 @group
797   int d1, d2;
798   char buf[4];
799   d1 = open ("foo", O_RDONLY);
800   d2 = open ("foo", O_RDONLY);
801   lseek (d1, 1024, SEEK_SET);
802   read (d2, buf, 4);
804 @end group
805 @end smallexample
807 @noindent
808 will read the first four characters of the file @file{foo}.  (The
809 error-checking code necessary for a real program has been omitted here
810 for brevity.)
812 By contrast, descriptors made by duplication share a common file
813 position with the original descriptor that was duplicated.  Anything
814 which alters the file position of one of the duplicates, including
815 reading or writing data, affects all of them alike.  Thus, for example,
817 @smallexample
819   int d1, d2, d3;
820   char buf1[4], buf2[4];
821   d1 = open ("foo", O_RDONLY);
822   d2 = dup (d1);
823   d3 = dup (d2);
824   lseek (d3, 1024, SEEK_SET);
825   read (d1, buf1, 4);
826   read (d2, buf2, 4);
828 @end smallexample
830 @noindent
831 will read four characters starting with the 1024'th character of
832 @file{foo}, and then four more characters starting with the 1028'th
833 character.
835 @comment sys/types.h
836 @comment POSIX.1
837 @deftp {Data Type} off_t
838 This is a signed integer type used to represent file sizes.  In
839 @theglibc{}, this type is no narrower than @code{int}.
841 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
842 is transparently replaced by @code{off64_t}.
843 @end deftp
845 @comment sys/types.h
846 @comment Unix98
847 @deftp {Data Type} off64_t
848 This type is used similar to @code{off_t}.  The difference is that even
849 on 32 bit machines, where the @code{off_t} type would have 32 bits,
850 @code{off64_t} has 64 bits and so is able to address files up to
851 @twoexp{63} bytes in length.
853 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
854 available under the name @code{off_t}.
855 @end deftp
857 These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
858 of compatibility with older BSD systems.  They are defined in two
859 different header files: @file{fcntl.h} and @file{sys/file.h}.
861 @table @code
862 @item L_SET
863 An alias for @code{SEEK_SET}.
865 @item L_INCR
866 An alias for @code{SEEK_CUR}.
868 @item L_XTND
869 An alias for @code{SEEK_END}.
870 @end table
872 @node Descriptors and Streams
873 @section Descriptors and Streams
874 @cindex streams, and file descriptors
875 @cindex converting file descriptor to stream
876 @cindex extracting file descriptor from stream
878 Given an open file descriptor, you can create a stream for it with the
879 @code{fdopen} function.  You can get the underlying file descriptor for
880 an existing stream with the @code{fileno} function.  These functions are
881 declared in the header file @file{stdio.h}.
882 @pindex stdio.h
884 @comment stdio.h
885 @comment POSIX.1
886 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
887 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
888 The @code{fdopen} function returns a new stream for the file descriptor
889 @var{filedes}.
891 The @var{opentype} argument is interpreted in the same way as for the
892 @code{fopen} function (@pxref{Opening Streams}), except that
893 the @samp{b} option is not permitted; this is because @gnusystems{} make no
894 distinction between text and binary files.  Also, @code{"w"} and
895 @code{"w+"} do not cause truncation of the file; these have an effect only
896 when opening a file, and in this case the file has already been opened.
897 You must make sure that the @var{opentype} argument matches the actual
898 mode of the open file descriptor.
900 The return value is the new stream.  If the stream cannot be created
901 (for example, if the modes for the file indicated by the file descriptor
902 do not permit the access specified by the @var{opentype} argument), a
903 null pointer is returned instead.
905 In some other systems, @code{fdopen} may fail to detect that the modes
906 for file descriptor do not permit the access specified by
907 @code{opentype}.  @Theglibc{} always checks for this.
908 @end deftypefun
910 For an example showing the use of the @code{fdopen} function,
911 see @ref{Creating a Pipe}.
913 @comment stdio.h
914 @comment POSIX.1
915 @deftypefun int fileno (FILE *@var{stream})
916 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
917 This function returns the file descriptor associated with the stream
918 @var{stream}.  If an error is detected (for example, if the @var{stream}
919 is not valid) or if @var{stream} does not do I/O to a file,
920 @code{fileno} returns @math{-1}.
921 @end deftypefun
923 @comment stdio.h
924 @comment GNU
925 @deftypefun int fileno_unlocked (FILE *@var{stream})
926 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
927 The @code{fileno_unlocked} function is equivalent to the @code{fileno}
928 function except that it does not implicitly lock the stream if the state
929 is @code{FSETLOCKING_INTERNAL}.
931 This function is a GNU extension.
932 @end deftypefun
934 @cindex standard file descriptors
935 @cindex file descriptors, standard
936 There are also symbolic constants defined in @file{unistd.h} for the
937 file descriptors belonging to the standard streams @code{stdin},
938 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
939 @pindex unistd.h
941 @comment unistd.h
942 @comment POSIX.1
943 @table @code
944 @item STDIN_FILENO
945 @vindex STDIN_FILENO
946 This macro has value @code{0}, which is the file descriptor for
947 standard input.
948 @cindex standard input file descriptor
950 @comment unistd.h
951 @comment POSIX.1
952 @item STDOUT_FILENO
953 @vindex STDOUT_FILENO
954 This macro has value @code{1}, which is the file descriptor for
955 standard output.
956 @cindex standard output file descriptor
958 @comment unistd.h
959 @comment POSIX.1
960 @item STDERR_FILENO
961 @vindex STDERR_FILENO
962 This macro has value @code{2}, which is the file descriptor for
963 standard error output.
964 @end table
965 @cindex standard error file descriptor
967 @node Stream/Descriptor Precautions
968 @section Dangers of Mixing Streams and Descriptors
969 @cindex channels
970 @cindex streams and descriptors
971 @cindex descriptors and streams
972 @cindex mixing descriptors and streams
974 You can have multiple file descriptors and streams (let's call both
975 streams and descriptors ``channels'' for short) connected to the same
976 file, but you must take care to avoid confusion between channels.  There
977 are two cases to consider: @dfn{linked} channels that share a single
978 file position value, and @dfn{independent} channels that have their own
979 file positions.
981 It's best to use just one channel in your program for actual data
982 transfer to any given file, except when all the access is for input.
983 For example, if you open a pipe (something you can only do at the file
984 descriptor level), either do all I/O with the descriptor, or construct a
985 stream from the descriptor with @code{fdopen} and then do all I/O with
986 the stream.
988 @menu
989 * Linked Channels::        Dealing with channels sharing a file position.
990 * Independent Channels::   Dealing with separately opened, unlinked channels.
991 * Cleaning Streams::       Cleaning a stream makes it safe to use
992                             another channel.
993 @end menu
995 @node Linked Channels
996 @subsection Linked Channels
997 @cindex linked channels
999 Channels that come from a single opening share the same file position;
1000 we call them @dfn{linked} channels.  Linked channels result when you
1001 make a stream from a descriptor using @code{fdopen}, when you get a
1002 descriptor from a stream with @code{fileno}, when you copy a descriptor
1003 with @code{dup} or @code{dup2}, and when descriptors are inherited
1004 during @code{fork}.  For files that don't support random access, such as
1005 terminals and pipes, @emph{all} channels are effectively linked.  On
1006 random-access files, all append-type output streams are effectively
1007 linked to each other.
1009 @cindex cleaning up a stream
1010 If you have been using a stream for I/O (or have just opened the stream),
1011 and you want to do I/O using
1012 another channel (either a stream or a descriptor) that is linked to it,
1013 you must first @dfn{clean up} the stream that you have been using.
1014 @xref{Cleaning Streams}.
1016 Terminating a process, or executing a new program in the process,
1017 destroys all the streams in the process.  If descriptors linked to these
1018 streams persist in other processes, their file positions become
1019 undefined as a result.  To prevent this, you must clean up the streams
1020 before destroying them.
1022 @node Independent Channels
1023 @subsection Independent Channels
1024 @cindex independent channels
1026 When you open channels (streams or descriptors) separately on a seekable
1027 file, each channel has its own file position.  These are called
1028 @dfn{independent channels}.
1030 The system handles each channel independently.  Most of the time, this
1031 is quite predictable and natural (especially for input): each channel
1032 can read or write sequentially at its own place in the file.  However,
1033 if some of the channels are streams, you must take these precautions:
1035 @itemize @bullet
1036 @item
1037 You should clean an output stream after use, before doing anything else
1038 that might read or write from the same part of the file.
1040 @item
1041 You should clean an input stream before reading data that may have been
1042 modified using an independent channel.  Otherwise, you might read
1043 obsolete data that had been in the stream's buffer.
1044 @end itemize
1046 If you do output to one channel at the end of the file, this will
1047 certainly leave the other independent channels positioned somewhere
1048 before the new end.  You cannot reliably set their file positions to the
1049 new end of file before writing, because the file can always be extended
1050 by another process between when you set the file position and when you
1051 write the data.  Instead, use an append-type descriptor or stream; they
1052 always output at the current end of the file.  In order to make the
1053 end-of-file position accurate, you must clean the output channel you
1054 were using, if it is a stream.
1056 It's impossible for two channels to have separate file pointers for a
1057 file that doesn't support random access.  Thus, channels for reading or
1058 writing such files are always linked, never independent.  Append-type
1059 channels are also always linked.  For these channels, follow the rules
1060 for linked channels; see @ref{Linked Channels}.
1062 @node Cleaning Streams
1063 @subsection Cleaning Streams
1065 You can use @code{fflush} to clean a stream in most
1066 cases.
1068 You can skip the @code{fflush} if you know the stream
1069 is already clean.  A stream is clean whenever its buffer is empty.  For
1070 example, an unbuffered stream is always clean.  An input stream that is
1071 at end-of-file is clean.  A line-buffered stream is clean when the last
1072 character output was a newline.  However, a just-opened input stream
1073 might not be clean, as its input buffer might not be empty.
1075 There is one case in which cleaning a stream is impossible on most
1076 systems.  This is when the stream is doing input from a file that is not
1077 random-access.  Such streams typically read ahead, and when the file is
1078 not random access, there is no way to give back the excess data already
1079 read.  When an input stream reads from a random-access file,
1080 @code{fflush} does clean the stream, but leaves the file pointer at an
1081 unpredictable place; you must set the file pointer before doing any
1082 further I/O.
1084 Closing an output-only stream also does @code{fflush}, so this is a
1085 valid way of cleaning an output stream.
1087 You need not clean a stream before using its descriptor for control
1088 operations such as setting terminal modes; these operations don't affect
1089 the file position and are not affected by it.  You can use any
1090 descriptor for these operations, and all channels are affected
1091 simultaneously.  However, text already ``output'' to a stream but still
1092 buffered by the stream will be subject to the new terminal modes when
1093 subsequently flushed.  To make sure ``past'' output is covered by the
1094 terminal settings that were in effect at the time, flush the output
1095 streams for that terminal before setting the modes.  @xref{Terminal
1096 Modes}.
1098 @node Scatter-Gather
1099 @section Fast Scatter-Gather I/O
1100 @cindex scatter-gather
1102 Some applications may need to read or write data to multiple buffers,
1103 which are separated in memory.  Although this can be done easily enough
1104 with multiple calls to @code{read} and @code{write}, it is inefficient
1105 because there is overhead associated with each kernel call.
1107 Instead, many platforms provide special high-speed primitives to perform
1108 these @dfn{scatter-gather} operations in a single kernel call.  @Theglibc{}
1109 will provide an emulation on any system that lacks these
1110 primitives, so they are not a portability threat.  They are defined in
1111 @code{sys/uio.h}.
1113 These functions are controlled with arrays of @code{iovec} structures,
1114 which describe the location and size of each buffer.
1116 @comment sys/uio.h
1117 @comment BSD
1118 @deftp {Data Type} {struct iovec}
1120 The @code{iovec} structure describes a buffer.  It contains two fields:
1122 @table @code
1124 @item void *iov_base
1125 Contains the address of a buffer.
1127 @item size_t iov_len
1128 Contains the length of the buffer.
1130 @end table
1131 @end deftp
1133 @comment sys/uio.h
1134 @comment BSD
1135 @deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
1136 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
1137 @c The fallback sysdeps/posix implementation, used even on GNU/Linux
1138 @c with old kernels that lack a full readv/writev implementation, may
1139 @c malloc the buffer into which data is read, if the total read size is
1140 @c too large for alloca.
1142 The @code{readv} function reads data from @var{filedes} and scatters it
1143 into the buffers described in @var{vector}, which is taken to be
1144 @var{count} structures long.  As each buffer is filled, data is sent to the
1145 next.
1147 Note that @code{readv} is not guaranteed to fill all the buffers.
1148 It may stop at any point, for the same reasons @code{read} would.
1150 The return value is a count of bytes (@emph{not} buffers) read, @math{0}
1151 indicating end-of-file, or @math{-1} indicating an error.  The possible
1152 errors are the same as in @code{read}.
1154 @end deftypefun
1156 @comment sys/uio.h
1157 @comment BSD
1158 @deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
1159 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
1160 @c The fallback sysdeps/posix implementation, used even on GNU/Linux
1161 @c with old kernels that lack a full readv/writev implementation, may
1162 @c malloc the buffer from which data is written, if the total write size
1163 @c is too large for alloca.
1165 The @code{writev} function gathers data from the buffers described in
1166 @var{vector}, which is taken to be @var{count} structures long, and writes
1167 them to @code{filedes}.  As each buffer is written, it moves on to the
1168 next.
1170 Like @code{readv}, @code{writev} may stop midstream under the same
1171 conditions @code{write} would.
1173 The return value is a count of bytes written, or @math{-1} indicating an
1174 error.  The possible errors are the same as in @code{write}.
1176 @end deftypefun
1178 @c Note - I haven't read this anywhere.  I surmised it from my knowledge
1179 @c of computer science.  Thus, there could be subtleties I'm missing.
1181 Note that if the buffers are small (under about 1kB), high-level streams
1182 may be easier to use than these functions.  However, @code{readv} and
1183 @code{writev} are more efficient when the individual buffers themselves
1184 (as opposed to the total output), are large.  In that case, a high-level
1185 stream would not be able to cache the data effectively.
1187 @node Memory-mapped I/O
1188 @section Memory-mapped I/O
1190 On modern operating systems, it is possible to @dfn{mmap} (pronounced
1191 ``em-map'') a file to a region of memory.  When this is done, the file can
1192 be accessed just like an array in the program.
1194 This is more efficient than @code{read} or @code{write}, as only the regions
1195 of the file that a program actually accesses are loaded.  Accesses to
1196 not-yet-loaded parts of the mmapped region are handled in the same way as
1197 swapped out pages.
1199 Since mmapped pages can be stored back to their file when physical
1200 memory is low, it is possible to mmap files orders of magnitude larger
1201 than both the physical memory @emph{and} swap space.  The only limit is
1202 address space.  The theoretical limit is 4GB on a 32-bit machine -
1203 however, the actual limit will be smaller since some areas will be
1204 reserved for other purposes.  If the LFS interface is used the file size
1205 on 32-bit systems is not limited to 2GB (offsets are signed which
1206 reduces the addressable area of 4GB by half); the full 64-bit are
1207 available.
1209 Memory mapping only works on entire pages of memory.  Thus, addresses
1210 for mapping must be page-aligned, and length values will be rounded up.
1211 To determine the size of a page the machine uses one should use
1213 @vindex _SC_PAGESIZE
1214 @smallexample
1215 size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
1216 @end smallexample
1218 @noindent
1219 These functions are declared in @file{sys/mman.h}.
1221 @comment sys/mman.h
1222 @comment POSIX
1223 @deftypefun {void *} mmap (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset})
1224 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1226 The @code{mmap} function creates a new mapping, connected to bytes
1227 (@var{offset}) to (@var{offset} + @var{length} - 1) in the file open on
1228 @var{filedes}.  A new reference for the file specified by @var{filedes}
1229 is created, which is not removed by closing the file.
1231 @var{address} gives a preferred starting address for the mapping.
1232 @code{NULL} expresses no preference.  Any previous mapping at that
1233 address is automatically removed.  The address you give may still be
1234 changed, unless you use the @code{MAP_FIXED} flag.
1236 @vindex PROT_READ
1237 @vindex PROT_WRITE
1238 @vindex PROT_EXEC
1239 @var{protect} contains flags that control what kind of access is
1240 permitted.  They include @code{PROT_READ}, @code{PROT_WRITE}, and
1241 @code{PROT_EXEC}, which permit reading, writing, and execution,
1242 respectively.  Inappropriate access will cause a segfault (@pxref{Program
1243 Error Signals}).
1245 Note that most hardware designs cannot support write permission without
1246 read permission, and many do not distinguish read and execute permission.
1247 Thus, you may receive wider permissions than you ask for, and mappings of
1248 write-only files may be denied even if you do not use @code{PROT_READ}.
1250 @var{flags} contains flags that control the nature of the map.
1251 One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified.
1253 They include:
1255 @vtable @code
1256 @item MAP_PRIVATE
1257 This specifies that writes to the region should never be written back
1258 to the attached file.  Instead, a copy is made for the process, and the
1259 region will be swapped normally if memory runs low.  No other process will
1260 see the changes.
1262 Since private mappings effectively revert to ordinary memory
1263 when written to, you must have enough virtual memory for a copy of
1264 the entire mmapped region if you use this mode with @code{PROT_WRITE}.
1266 @item MAP_SHARED
1267 This specifies that writes to the region will be written back to the
1268 file.  Changes made will be shared immediately with other processes
1269 mmaping the same file.
1271 Note that actual writing may take place at any time.  You need to use
1272 @code{msync}, described below, if it is important that other processes
1273 using conventional I/O get a consistent view of the file.
1275 @item MAP_FIXED
1276 This forces the system to use the exact mapping address specified in
1277 @var{address} and fail if it can't.
1279 @c One of these is official - the other is obviously an obsolete synonym
1280 @c Which is which?
1281 @item MAP_ANONYMOUS
1282 @itemx MAP_ANON
1283 This flag tells the system to create an anonymous mapping, not connected
1284 to a file.  @var{filedes} and @var{off} are ignored, and the region is
1285 initialized with zeros.
1287 Anonymous maps are used as the basic primitive to extend the heap on some
1288 systems.  They are also useful to share data between multiple tasks
1289 without creating a file.
1291 On some systems using private anonymous mmaps is more efficient than using
1292 @code{malloc} for large blocks.  This is not an issue with @theglibc{},
1293 as the included @code{malloc} automatically uses @code{mmap} where appropriate.
1295 @c Linux has some other MAP_ options, which I have not discussed here.
1296 @c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to
1297 @c user programs (and I don't understand the last two).  MAP_LOCKED does
1298 @c not appear to be implemented.
1300 @end vtable
1302 @code{mmap} returns the address of the new mapping, or
1303 @code{MAP_FAILED} for an error.
1305 Possible errors include:
1307 @table @code
1309 @item EINVAL
1311 Either @var{address} was unusable, or inconsistent @var{flags} were
1312 given.
1314 @item EACCES
1316 @var{filedes} was not open for the type of access specified in @var{protect}.
1318 @item ENOMEM
1320 Either there is not enough memory for the operation, or the process is
1321 out of address space.
1323 @item ENODEV
1325 This file is of a type that doesn't support mapping.
1327 @item ENOEXEC
1329 The file is on a filesystem that doesn't support mapping.
1331 @c On Linux, EAGAIN will appear if the file has a conflicting mandatory lock.
1332 @c However mandatory locks are not discussed in this manual.
1334 @c Similarly, ETXTBSY will occur if the MAP_DENYWRITE flag (not documented
1335 @c here) is used and the file is already open for writing.
1337 @end table
1339 @end deftypefun
1341 @comment sys/mman.h
1342 @comment LFS
1343 @deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset})
1344 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1345 @c The page_shift auto detection when MMAP2_PAGE_SHIFT is -1 (it never
1346 @c is) would be thread-unsafe.
1347 The @code{mmap64} function is equivalent to the @code{mmap} function but
1348 the @var{offset} parameter is of type @code{off64_t}.  On 32-bit systems
1349 this allows the file associated with the @var{filedes} descriptor to be
1350 larger than 2GB.  @var{filedes} must be a descriptor returned from a
1351 call to @code{open64} or @code{fopen64} and @code{freopen64} where the
1352 descriptor is retrieved with @code{fileno}.
1354 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
1355 function is actually available under the name @code{mmap}.  I.e., the
1356 new, extended API using 64 bit file sizes and offsets transparently
1357 replaces the old API.
1358 @end deftypefun
1360 @comment sys/mman.h
1361 @comment POSIX
1362 @deftypefun int munmap (void *@var{addr}, size_t @var{length})
1363 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1365 @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} +
1366 @var{length}).  @var{length} should be the length of the mapping.
1368 It is safe to unmap multiple mappings in one command, or include unmapped
1369 space in the range.  It is also possible to unmap only part of an existing
1370 mapping.  However, only entire pages can be removed.  If @var{length} is not
1371 an even number of pages, it will be rounded up.
1373 It returns @math{0} for success and @math{-1} for an error.
1375 One error is possible:
1377 @table @code
1379 @item EINVAL
1380 The memory range given was outside the user mmap range or wasn't page
1381 aligned.
1383 @end table
1385 @end deftypefun
1387 @comment sys/mman.h
1388 @comment POSIX
1389 @deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags})
1390 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1392 When using shared mappings, the kernel can write the file at any time
1393 before the mapping is removed.  To be certain data has actually been
1394 written to the file and will be accessible to non-memory-mapped I/O, it
1395 is necessary to use this function.
1397 It operates on the region @var{address} to (@var{address} + @var{length}).
1398 It may be used on part of a mapping or multiple mappings, however the
1399 region given should not contain any unmapped space.
1401 @var{flags} can contain some options:
1403 @vtable @code
1405 @item MS_SYNC
1407 This flag makes sure the data is actually written @emph{to disk}.
1408 Normally @code{msync} only makes sure that accesses to a file with
1409 conventional I/O reflect the recent changes.
1411 @item MS_ASYNC
1413 This tells @code{msync} to begin the synchronization, but not to wait for
1414 it to complete.
1416 @c Linux also has MS_INVALIDATE, which I don't understand.
1418 @end vtable
1420 @code{msync} returns @math{0} for success and @math{-1} for
1421 error.  Errors include:
1423 @table @code
1425 @item EINVAL
1426 An invalid region was given, or the @var{flags} were invalid.
1428 @item EFAULT
1429 There is no existing mapping in at least part of the given region.
1431 @end table
1433 @end deftypefun
1435 @comment sys/mman.h
1436 @comment GNU
1437 @deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag})
1438 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1440 This function can be used to change the size of an existing memory
1441 area. @var{address} and @var{length} must cover a region entirely mapped
1442 in the same @code{mmap} statement.  A new mapping with the same
1443 characteristics will be returned with the length @var{new_length}.
1445 One option is possible, @code{MREMAP_MAYMOVE}.  If it is given in
1446 @var{flags}, the system may remove the existing mapping and create a new
1447 one of the desired length in another location.
1449 The address of the resulting mapping is returned, or @math{-1}.  Possible
1450 error codes include:
1452 @table @code
1454 @item EFAULT
1455 There is no existing mapping in at least part of the original region, or
1456 the region covers two or more distinct mappings.
1458 @item EINVAL
1459 The address given is misaligned or inappropriate.
1461 @item EAGAIN
1462 The region has pages locked, and if extended it would exceed the
1463 process's resource limit for locked pages.  @xref{Limits on Resources}.
1465 @item ENOMEM
1466 The region is private writable, and insufficient virtual memory is
1467 available to extend it.  Also, this error will occur if
1468 @code{MREMAP_MAYMOVE} is not given and the extension would collide with
1469 another mapped region.
1471 @end table
1472 @end deftypefun
1474 This function is only available on a few systems.  Except for performing
1475 optional optimizations one should not rely on this function.
1477 Not all file descriptors may be mapped.  Sockets, pipes, and most devices
1478 only allow sequential access and do not fit into the mapping abstraction.
1479 In addition, some regular files may not be mmapable, and older kernels may
1480 not support mapping at all.  Thus, programs using @code{mmap} should
1481 have a fallback method to use should it fail. @xref{Mmap,,,standards,GNU
1482 Coding Standards}.
1484 @comment sys/mman.h
1485 @comment POSIX
1486 @deftypefun int madvise (void *@var{addr}, size_t @var{length}, int @var{advice})
1487 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1489 This function can be used to provide the system with @var{advice} about
1490 the intended usage patterns of the memory region starting at @var{addr}
1491 and extending @var{length} bytes.
1493 The valid BSD values for @var{advice} are:
1495 @table @code
1497 @item MADV_NORMAL
1498 The region should receive no further special treatment.
1500 @item MADV_RANDOM
1501 The region will be accessed via random page references.  The kernel
1502 should page-in the minimal number of pages for each page fault.
1504 @item MADV_SEQUENTIAL
1505 The region will be accessed via sequential page references.  This
1506 may cause the kernel to aggressively read-ahead, expecting further
1507 sequential references after any page fault within this region.
1509 @item MADV_WILLNEED
1510 The region will be needed.  The pages within this region may
1511 be pre-faulted in by the kernel.
1513 @item MADV_DONTNEED
1514 The region is no longer needed.  The kernel may free these pages,
1515 causing any changes to the pages to be lost, as well as swapped
1516 out pages to be discarded.
1518 @end table
1520 The POSIX names are slightly different, but with the same meanings:
1522 @table @code
1524 @item POSIX_MADV_NORMAL
1525 This corresponds with BSD's @code{MADV_NORMAL}.
1527 @item POSIX_MADV_RANDOM
1528 This corresponds with BSD's @code{MADV_RANDOM}.
1530 @item POSIX_MADV_SEQUENTIAL
1531 This corresponds with BSD's @code{MADV_SEQUENTIAL}.
1533 @item POSIX_MADV_WILLNEED
1534 This corresponds with BSD's @code{MADV_WILLNEED}.
1536 @item POSIX_MADV_DONTNEED
1537 This corresponds with BSD's @code{MADV_DONTNEED}.
1539 @end table
1541 @code{madvise} returns @math{0} for success and @math{-1} for
1542 error.  Errors include:
1543 @table @code
1545 @item EINVAL
1546 An invalid region was given, or the @var{advice} was invalid.
1548 @item EFAULT
1549 There is no existing mapping in at least part of the given region.
1551 @end table
1552 @end deftypefun
1554 @comment sys/mman.h
1555 @comment POSIX
1556 @deftypefn Function int shm_open (const char *@var{name}, int @var{oflag}, mode_t @var{mode})
1557 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1558 @c shm_open @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1559 @c  libc_once(where_is_shmfs) @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1560 @c   where_is_shmfs @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1561 @c    statfs dup ok
1562 @c    setmntent dup @ascuheap @asulock @acsmem @acsfd @aculock
1563 @c    getmntent_r dup @mtslocale @ascuheap @aculock @acsmem [no @asucorrupt @acucorrupt; exclusive stream]
1564 @c    strcmp dup ok
1565 @c    strlen dup ok
1566 @c    malloc dup @ascuheap @acsmem
1567 @c    mempcpy dup ok
1568 @c    endmntent dup @ascuheap @asulock @aculock @acsmem @acsfd
1569 @c  strlen dup ok
1570 @c  strchr dup ok
1571 @c  mempcpy dup ok
1572 @c  open dup @acsfd
1573 @c  fcntl dup ok
1574 @c  close dup @acsfd
1576 This function returns a file descriptor that can be used to allocate shared
1577 memory via mmap.  Unrelated processes can use same @var{name} to create or
1578 open existing shared memory objects.
1580 A @var{name} argument specifies the shared memory object to be opened.
1581 In @theglibc{} it must be a string smaller than @code{NAME_MAX} bytes starting
1582 with an optional slash but containing no other slashes.
1584 The semantics of @var{oflag} and @var{mode} arguments is same as in @code{open}.
1586 @code{shm_open} returns the file descriptor on success or @math{-1} on error.
1587 On failure @code{errno} is set.
1588 @end deftypefn
1590 @deftypefn Function int shm_unlink (const char *@var{name})
1591 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1592 @c shm_unlink @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1593 @c  libc_once(where_is_shmfs) dup @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1594 @c  strlen dup ok
1595 @c  strchr dup ok
1596 @c  mempcpy dup ok
1597 @c  unlink dup ok
1599 This function is inverse of @code{shm_open} and removes the object with
1600 the given @var{name} previously created by @code{shm_open}.
1602 @code{shm_unlink} returns @math{0} on success or @math{-1} on error.
1603 On failure @code{errno} is set.
1604 @end deftypefn
1606 @node Waiting for I/O
1607 @section Waiting for Input or Output
1608 @cindex waiting for input or output
1609 @cindex multiplexing input
1610 @cindex input from multiple files
1612 Sometimes a program needs to accept input on multiple input channels
1613 whenever input arrives.  For example, some workstations may have devices
1614 such as a digitizing tablet, function button box, or dial box that are
1615 connected via normal asynchronous serial interfaces; good user interface
1616 style requires responding immediately to input on any device.  Another
1617 example is a program that acts as a server to several other processes
1618 via pipes or sockets.
1620 You cannot normally use @code{read} for this purpose, because this
1621 blocks the program until input is available on one particular file
1622 descriptor; input on other channels won't wake it up.  You could set
1623 nonblocking mode and poll each file descriptor in turn, but this is very
1624 inefficient.
1626 A better solution is to use the @code{select} function.  This blocks the
1627 program until input or output is ready on a specified set of file
1628 descriptors, or until a timer expires, whichever comes first.  This
1629 facility is declared in the header file @file{sys/types.h}.
1630 @pindex sys/types.h
1632 In the case of a server socket (@pxref{Listening}), we say that
1633 ``input'' is available when there are pending connections that could be
1634 accepted (@pxref{Accepting Connections}).  @code{accept} for server
1635 sockets blocks and interacts with @code{select} just as @code{read} does
1636 for normal input.
1638 @cindex file descriptor sets, for @code{select}
1639 The file descriptor sets for the @code{select} function are specified
1640 as @code{fd_set} objects.  Here is the description of the data type
1641 and some macros for manipulating these objects.
1643 @comment sys/types.h
1644 @comment BSD
1645 @deftp {Data Type} fd_set
1646 The @code{fd_set} data type represents file descriptor sets for the
1647 @code{select} function.  It is actually a bit array.
1648 @end deftp
1650 @comment sys/types.h
1651 @comment BSD
1652 @deftypevr Macro int FD_SETSIZE
1653 The value of this macro is the maximum number of file descriptors that a
1654 @code{fd_set} object can hold information about.  On systems with a
1655 fixed maximum number, @code{FD_SETSIZE} is at least that number.  On
1656 some systems, including GNU, there is no absolute limit on the number of
1657 descriptors open, but this macro still has a constant value which
1658 controls the number of bits in an @code{fd_set}; if you get a file
1659 descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
1660 that descriptor into an @code{fd_set}.
1661 @end deftypevr
1663 @comment sys/types.h
1664 @comment BSD
1665 @deftypefn Macro void FD_ZERO (fd_set *@var{set})
1666 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
1667 This macro initializes the file descriptor set @var{set} to be the
1668 empty set.
1669 @end deftypefn
1671 @comment sys/types.h
1672 @comment BSD
1673 @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
1674 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
1675 @c Setting a bit isn't necessarily atomic, so there's a potential race
1676 @c here if set is not used exclusively.
1677 This macro adds @var{filedes} to the file descriptor set @var{set}.
1679 The @var{filedes} parameter must not have side effects since it is
1680 evaluated more than once.
1681 @end deftypefn
1683 @comment sys/types.h
1684 @comment BSD
1685 @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
1686 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
1687 @c Setting a bit isn't necessarily atomic, so there's a potential race
1688 @c here if set is not used exclusively.
1689 This macro removes @var{filedes} from the file descriptor set @var{set}.
1691 The @var{filedes} parameter must not have side effects since it is
1692 evaluated more than once.
1693 @end deftypefn
1695 @comment sys/types.h
1696 @comment BSD
1697 @deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set})
1698 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
1699 This macro returns a nonzero value (true) if @var{filedes} is a member
1700 of the file descriptor set @var{set}, and zero (false) otherwise.
1702 The @var{filedes} parameter must not have side effects since it is
1703 evaluated more than once.
1704 @end deftypefn
1706 Next, here is the description of the @code{select} function itself.
1708 @comment sys/types.h
1709 @comment BSD
1710 @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})
1711 @safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}}
1712 @c The select syscall is preferred, but pselect6 may be used instead,
1713 @c which requires converting timeout to a timespec and back.  The
1714 @c conversions are not atomic.
1715 The @code{select} function blocks the calling process until there is
1716 activity on any of the specified sets of file descriptors, or until the
1717 timeout period has expired.
1719 The file descriptors specified by the @var{read-fds} argument are
1720 checked to see if they are ready for reading; the @var{write-fds} file
1721 descriptors are checked to see if they are ready for writing; and the
1722 @var{except-fds} file descriptors are checked for exceptional
1723 conditions.  You can pass a null pointer for any of these arguments if
1724 you are not interested in checking for that kind of condition.
1726 A file descriptor is considered ready for reading if a @code{read}
1727 call will not block.  This usually includes the read offset being at
1728 the end of the file or there is an error to report.  A server socket
1729 is considered ready for reading if there is a pending connection which
1730 can be accepted with @code{accept}; @pxref{Accepting Connections}.  A
1731 client socket is ready for writing when its connection is fully
1732 established; @pxref{Connecting}.
1734 ``Exceptional conditions'' does not mean errors---errors are reported
1735 immediately when an erroneous system call is executed, and do not
1736 constitute a state of the descriptor.  Rather, they include conditions
1737 such as the presence of an urgent message on a socket.  (@xref{Sockets},
1738 for information on urgent messages.)
1740 The @code{select} function checks only the first @var{nfds} file
1741 descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
1742 of this argument.
1744 The @var{timeout} specifies the maximum time to wait.  If you pass a
1745 null pointer for this argument, it means to block indefinitely until one
1746 of the file descriptors is ready.  Otherwise, you should provide the
1747 time in @code{struct timeval} format; see @ref{High-Resolution
1748 Calendar}.  Specify zero as the time (a @code{struct timeval} containing
1749 all zeros) if you want to find out which descriptors are ready without
1750 waiting if none are ready.
1752 The normal return value from @code{select} is the total number of ready file
1753 descriptors in all of the sets.  Each of the argument sets is overwritten
1754 with information about the descriptors that are ready for the corresponding
1755 operation.  Thus, to see if a particular descriptor @var{desc} has input,
1756 use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
1758 If @code{select} returns because the timeout period expires, it returns
1759 a value of zero.
1761 Any signal will cause @code{select} to return immediately.  So if your
1762 program uses signals, you can't rely on @code{select} to keep waiting
1763 for the full time specified.  If you want to be sure of waiting for a
1764 particular amount of time, you must check for @code{EINTR} and repeat
1765 the @code{select} with a newly calculated timeout based on the current
1766 time.  See the example below.  See also @ref{Interrupted Primitives}.
1768 If an error occurs, @code{select} returns @code{-1} and does not modify
1769 the argument file descriptor sets.  The following @code{errno} error
1770 conditions are defined for this function:
1772 @table @code
1773 @item EBADF
1774 One of the file descriptor sets specified an invalid file descriptor.
1776 @item EINTR
1777 The operation was interrupted by a signal.  @xref{Interrupted Primitives}.
1779 @item EINVAL
1780 The @var{timeout} argument is invalid; one of the components is negative
1781 or too large.
1782 @end table
1783 @end deftypefun
1785 @strong{Portability Note:}  The @code{select} function is a BSD Unix
1786 feature.
1788 Here is an example showing how you can use @code{select} to establish a
1789 timeout period for reading from a file descriptor.  The @code{input_timeout}
1790 function blocks the calling process until input is available on the
1791 file descriptor, or until the timeout period expires.
1793 @smallexample
1794 @include select.c.texi
1795 @end smallexample
1797 There is another example showing the use of @code{select} to multiplex
1798 input from multiple sockets in @ref{Server Example}.
1801 @node Synchronizing I/O
1802 @section Synchronizing I/O operations
1804 @cindex synchronizing
1805 In most modern operating systems, the normal I/O operations are not
1806 executed synchronously.  I.e., even if a @code{write} system call
1807 returns, this does not mean the data is actually written to the media,
1808 e.g., the disk.
1810 In situations where synchronization points are necessary, you can use
1811 special functions which ensure that all operations finish before
1812 they return.
1814 @comment unistd.h
1815 @comment X/Open
1816 @deftypefun void sync (void)
1817 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1818 A call to this function will not return as long as there is data which
1819 has not been written to the device.  All dirty buffers in the kernel will
1820 be written and so an overall consistent system can be achieved (if no
1821 other process in parallel writes data).
1823 A prototype for @code{sync} can be found in @file{unistd.h}.
1824 @end deftypefun
1826 Programs more often want to ensure that data written to a given file is
1827 committed, rather than all data in the system.  For this, @code{sync} is overkill.
1830 @comment unistd.h
1831 @comment POSIX
1832 @deftypefun int fsync (int @var{fildes})
1833 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1834 The @code{fsync} function can be used to make sure all data associated with
1835 the open file @var{fildes} is written to the device associated with the
1836 descriptor.  The function call does not return unless all actions have
1837 finished.
1839 A prototype for @code{fsync} can be found in @file{unistd.h}.
1841 This function is a cancellation point in multi-threaded programs.  This
1842 is a problem if the thread allocates some resources (like memory, file
1843 descriptors, semaphores or whatever) at the time @code{fsync} is
1844 called.  If the thread gets canceled these resources stay allocated
1845 until the program ends.  To avoid this, calls to @code{fsync} should be
1846 protected using cancellation handlers.
1847 @c ref pthread_cleanup_push / pthread_cleanup_pop
1849 The return value of the function is zero if no error occurred.  Otherwise
1850 it is @math{-1} and the global variable @var{errno} is set to the
1851 following values:
1852 @table @code
1853 @item EBADF
1854 The descriptor @var{fildes} is not valid.
1856 @item EINVAL
1857 No synchronization is possible since the system does not implement this.
1858 @end table
1859 @end deftypefun
1861 Sometimes it is not even necessary to write all data associated with a
1862 file descriptor.  E.g., in database files which do not change in size it
1863 is enough to write all the file content data to the device.
1864 Meta-information, like the modification time etc., are not that important
1865 and leaving such information uncommitted does not prevent a successful
1866 recovering of the file in case of a problem.
1868 @comment unistd.h
1869 @comment POSIX
1870 @deftypefun int fdatasync (int @var{fildes})
1871 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1872 When a call to the @code{fdatasync} function returns, it is ensured
1873 that all of the file data is written to the device.  For all pending I/O
1874 operations, the parts guaranteeing data integrity finished.
1876 Not all systems implement the @code{fdatasync} operation.  On systems
1877 missing this functionality @code{fdatasync} is emulated by a call to
1878 @code{fsync} since the performed actions are a superset of those
1879 required by @code{fdatasync}.
1881 The prototype for @code{fdatasync} is in @file{unistd.h}.
1883 The return value of the function is zero if no error occurred.  Otherwise
1884 it is @math{-1} and the global variable @var{errno} is set to the
1885 following values:
1886 @table @code
1887 @item EBADF
1888 The descriptor @var{fildes} is not valid.
1890 @item EINVAL
1891 No synchronization is possible since the system does not implement this.
1892 @end table
1893 @end deftypefun
1896 @node Asynchronous I/O
1897 @section Perform I/O Operations in Parallel
1899 The POSIX.1b standard defines a new set of I/O operations which can
1900 significantly reduce the time an application spends waiting at I/O.  The
1901 new functions allow a program to initiate one or more I/O operations and
1902 then immediately resume normal work while the I/O operations are
1903 executed in parallel.  This functionality is available if the
1904 @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
1906 These functions are part of the library with realtime functions named
1907 @file{librt}.  They are not actually part of the @file{libc} binary.
1908 The implementation of these functions can be done using support in the
1909 kernel (if available) or using an implementation based on threads at
1910 userlevel.  In the latter case it might be necessary to link applications
1911 with the thread library @file{libpthread} in addition to @file{librt}.
1913 All AIO operations operate on files which were opened previously.  There
1914 might be arbitrarily many operations running for one file.  The
1915 asynchronous I/O operations are controlled using a data structure named
1916 @code{struct aiocb} (@dfn{AIO control block}).  It is defined in
1917 @file{aio.h} as follows.
1919 @comment aio.h
1920 @comment POSIX.1b
1921 @deftp {Data Type} {struct aiocb}
1922 The POSIX.1b standard mandates that the @code{struct aiocb} structure
1923 contains at least the members described in the following table.  There
1924 might be more elements which are used by the implementation, but
1925 depending upon these elements is not portable and is highly deprecated.
1927 @table @code
1928 @item int aio_fildes
1929 This element specifies the file descriptor to be used for the
1930 operation.  It must be a legal descriptor, otherwise the operation will
1931 fail.
1933 The device on which the file is opened must allow the seek operation.
1934 I.e., it is not possible to use any of the AIO operations on devices
1935 like terminals where an @code{lseek} call would lead to an error.
1937 @item off_t aio_offset
1938 This element specifies the offset in the file at which the operation (input
1939 or output) is performed.  Since the operations are carried out in arbitrary
1940 order and more than one operation for one file descriptor can be
1941 started, one cannot expect a current read/write position of the file
1942 descriptor.
1944 @item volatile void *aio_buf
1945 This is a pointer to the buffer with the data to be written or the place
1946 where the read data is stored.
1948 @item size_t aio_nbytes
1949 This element specifies the length of the buffer pointed to by @code{aio_buf}.
1951 @item int aio_reqprio
1952 If the platform has defined @code{_POSIX_PRIORITIZED_IO} and
1953 @code{_POSIX_PRIORITY_SCHEDULING}, the AIO requests are
1954 processed based on the current scheduling priority.  The
1955 @code{aio_reqprio} element can then be used to lower the priority of the
1956 AIO operation.
1958 @item struct sigevent aio_sigevent
1959 This element specifies how the calling process is notified once the
1960 operation terminates.  If the @code{sigev_notify} element is
1961 @code{SIGEV_NONE}, no notification is sent.  If it is @code{SIGEV_SIGNAL},
1962 the signal determined by @code{sigev_signo} is sent.  Otherwise,
1963 @code{sigev_notify} must be @code{SIGEV_THREAD}.  In this case, a thread
1964 is created which starts executing the function pointed to by
1965 @code{sigev_notify_function}.
1967 @item int aio_lio_opcode
1968 This element is only used by the @code{lio_listio} and
1969 @code{lio_listio64} functions.  Since these functions allow an
1970 arbitrary number of operations to start at once, and each operation can be
1971 input or output (or nothing), the information must be stored in the
1972 control block.  The possible values are:
1974 @vtable @code
1975 @item LIO_READ
1976 Start a read operation.  Read from the file at position
1977 @code{aio_offset} and store the next @code{aio_nbytes} bytes in the
1978 buffer pointed to by @code{aio_buf}.
1980 @item LIO_WRITE
1981 Start a write operation.  Write @code{aio_nbytes} bytes starting at
1982 @code{aio_buf} into the file starting at position @code{aio_offset}.
1984 @item LIO_NOP
1985 Do nothing for this control block.  This value is useful sometimes when
1986 an array of @code{struct aiocb} values contains holes, i.e., some of the
1987 values must not be handled although the whole array is presented to the
1988 @code{lio_listio} function.
1989 @end vtable
1990 @end table
1992 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
1993 32 bit machine, this type is in fact @code{struct aiocb64}, since the LFS
1994 interface transparently replaces the @code{struct aiocb} definition.
1995 @end deftp
1997 For use with the AIO functions defined in the LFS, there is a similar type
1998 defined which replaces the types of the appropriate members with larger
1999 types but otherwise is equivalent to @code{struct aiocb}.  Particularly,
2000 all member names are the same.
2002 @comment aio.h
2003 @comment POSIX.1b
2004 @deftp {Data Type} {struct aiocb64}
2005 @table @code
2006 @item int aio_fildes
2007 This element specifies the file descriptor which is used for the
2008 operation.  It must be a legal descriptor since otherwise the operation
2009 fails for obvious reasons.
2011 The device on which the file is opened must allow the seek operation.
2012 I.e., it is not possible to use any of the AIO operations on devices
2013 like terminals where an @code{lseek} call would lead to an error.
2015 @item off64_t aio_offset
2016 This element specifies at which offset in the file the operation (input
2017 or output) is performed.  Since the operation are carried in arbitrary
2018 order and more than one operation for one file descriptor can be
2019 started, one cannot expect a current read/write position of the file
2020 descriptor.
2022 @item volatile void *aio_buf
2023 This is a pointer to the buffer with the data to be written or the place
2024 where the read data is stored.
2026 @item size_t aio_nbytes
2027 This element specifies the length of the buffer pointed to by @code{aio_buf}.
2029 @item int aio_reqprio
2030 If for the platform @code{_POSIX_PRIORITIZED_IO} and
2031 @code{_POSIX_PRIORITY_SCHEDULING} are defined the AIO requests are
2032 processed based on the current scheduling priority.  The
2033 @code{aio_reqprio} element can then be used to lower the priority of the
2034 AIO operation.
2036 @item struct sigevent aio_sigevent
2037 This element specifies how the calling process is notified once the
2038 operation terminates.  If the @code{sigev_notify}, element is
2039 @code{SIGEV_NONE} no notification is sent.  If it is @code{SIGEV_SIGNAL},
2040 the signal determined by @code{sigev_signo} is sent.  Otherwise,
2041 @code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
2042 which starts executing the function pointed to by
2043 @code{sigev_notify_function}.
2045 @item int aio_lio_opcode
2046 This element is only used by the @code{lio_listio} and
2047 @code{[lio_listio64} functions.  Since these functions allow an
2048 arbitrary number of operations to start at once, and since each operation can be
2049 input or output (or nothing), the information must be stored in the
2050 control block.  See the description of @code{struct aiocb} for a description
2051 of the possible values.
2052 @end table
2054 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
2055 32 bit machine, this type is available under the name @code{struct
2056 aiocb64}, since the LFS transparently replaces the old interface.
2057 @end deftp
2059 @menu
2060 * Asynchronous Reads/Writes::    Asynchronous Read and Write Operations.
2061 * Status of AIO Operations::     Getting the Status of AIO Operations.
2062 * Synchronizing AIO Operations:: Getting into a consistent state.
2063 * Cancel AIO Operations::        Cancellation of AIO Operations.
2064 * Configuration of AIO::         How to optimize the AIO implementation.
2065 @end menu
2067 @node Asynchronous Reads/Writes
2068 @subsection Asynchronous Read and Write Operations
2070 @comment aio.h
2071 @comment POSIX.1b
2072 @deftypefun int aio_read (struct aiocb *@var{aiocbp})
2073 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2074 @c Calls aio_enqueue_request.
2075 @c aio_enqueue_request @asulock @ascuheap @aculock @acsmem
2076 @c  pthread_self ok
2077 @c  pthread_getschedparam @asulock @aculock
2078 @c   lll_lock (pthread descriptor's lock) @asulock @aculock
2079 @c   sched_getparam ok
2080 @c   sched_getscheduler ok
2081 @c   lll_unlock @aculock
2082 @c  pthread_mutex_lock (aio_requests_mutex) @asulock @aculock
2083 @c  get_elem @ascuheap @acsmem [@asucorrupt @acucorrupt]
2084 @c   realloc @ascuheap @acsmem
2085 @c   calloc @ascuheap @acsmem
2086 @c  aio_create_helper_thread @asulock @ascuheap @aculock @acsmem
2087 @c   pthread_attr_init ok
2088 @c   pthread_attr_setdetachstate ok
2089 @c   pthread_get_minstack ok
2090 @c   pthread_attr_setstacksize ok
2091 @c   sigfillset ok
2092 @c    memset ok
2093 @c    sigdelset ok
2094 @c   SYSCALL rt_sigprocmask ok
2095 @c   pthread_create @asulock @ascuheap @aculock @acsmem
2096 @c    lll_lock (default_pthread_attr_lock) @asulock @aculock
2097 @c    alloca/malloc @ascuheap @acsmem
2098 @c    lll_unlock @aculock
2099 @c    allocate_stack @asulock @ascuheap @aculock @acsmem
2100 @c     getpagesize dup
2101 @c     lll_lock (default_pthread_attr_lock) @asulock @aculock
2102 @c     lll_unlock @aculock
2103 @c     _dl_allocate_tls @ascuheap @acsmem
2104 @c      _dl_allocate_tls_storage @ascuheap @acsmem
2105 @c       memalign @ascuheap @acsmem
2106 @c       memset ok
2107 @c       allocate_dtv dup
2108 @c       free @ascuheap @acsmem
2109 @c      allocate_dtv @ascuheap @acsmem
2110 @c       calloc @ascuheap @acsmem
2111 @c       INSTALL_DTV ok
2112 @c     list_add dup
2113 @c     get_cached_stack
2114 @c      lll_lock (stack_cache_lock) @asulock @aculock
2115 @c      list_for_each ok
2116 @c      list_entry dup
2117 @c      FREE_P dup
2118 @c      stack_list_del dup
2119 @c      stack_list_add dup
2120 @c      lll_unlock @aculock
2121 @c      _dl_allocate_tls_init ok
2122 @c       GET_DTV ok
2123 @c     mmap ok
2124 @c     atomic_increment_val ok
2125 @c     munmap ok
2126 @c     change_stack_perm ok
2127 @c      mprotect ok
2128 @c     mprotect ok
2129 @c     stack_list_del dup
2130 @c     _dl_deallocate_tls dup
2131 @c     munmap ok
2132 @c    THREAD_COPY_STACK_GUARD ok
2133 @c    THREAD_COPY_POINTER_GUARD ok
2134 @c    atomic_exchange_acq ok
2135 @c    lll_futex_wake ok
2136 @c    deallocate_stack @asulock @ascuheap @aculock @acsmem
2137 @c     lll_lock (state_cache_lock) @asulock @aculock
2138 @c     stack_list_del ok
2139 @c      atomic_write_barrier ok
2140 @c      list_del ok
2141 @c      atomic_write_barrier ok
2142 @c     queue_stack @ascuheap @acsmem
2143 @c      stack_list_add ok
2144 @c       atomic_write_barrier ok
2145 @c       list_add ok
2146 @c       atomic_write_barrier ok
2147 @c      free_stacks @ascuheap @acsmem
2148 @c       list_for_each_prev_safe ok
2149 @c       list_entry ok
2150 @c       FREE_P ok
2151 @c       stack_list_del dup
2152 @c       _dl_deallocate_tls dup
2153 @c       munmap ok
2154 @c     _dl_deallocate_tls @ascuheap @acsmem
2155 @c      free @ascuheap @acsmem
2156 @c     lll_unlock @aculock
2157 @c    create_thread @asulock @ascuheap @aculock @acsmem
2158 @c     td_eventword
2159 @c     td_eventmask
2160 @c     do_clone @asulock @ascuheap @aculock @acsmem
2161 @c      PREPARE_CREATE ok
2162 @c      lll_lock (pd->lock) @asulock @aculock
2163 @c      atomic_increment ok
2164 @c      clone ok
2165 @c      atomic_decrement ok
2166 @c      atomic_exchange_acq ok
2167 @c      lll_futex_wake ok
2168 @c      deallocate_stack dup
2169 @c      sched_setaffinity ok
2170 @c      tgkill ok
2171 @c      sched_setscheduler ok
2172 @c     atomic_compare_and_exchange_bool_acq ok
2173 @c     nptl_create_event ok
2174 @c     lll_unlock (pd->lock) @aculock
2175 @c    free @ascuheap @acsmem
2176 @c   pthread_attr_destroy ok (cpuset won't be set, so free isn't called)
2177 @c  add_request_to_runlist ok
2178 @c  pthread_cond_signal ok
2179 @c  aio_free_request ok
2180 @c  pthread_mutex_unlock @aculock
2182 @c (in the new thread, initiated with clone)
2183 @c    start_thread ok
2184 @c     HP_TIMING_NOW ok
2185 @c     ctype_init @mtslocale
2186 @c     atomic_exchange_acq ok
2187 @c     lll_futex_wake ok
2188 @c     sigemptyset ok
2189 @c     sigaddset ok
2190 @c     setjmp ok
2191 @c     CANCEL_ASYNC -> pthread_enable_asynccancel ok
2192 @c      do_cancel ok
2193 @c       pthread_unwind ok
2194 @c        Unwind_ForcedUnwind or longjmp ok [@ascuheap @acsmem?]
2195 @c     lll_lock @asulock @aculock
2196 @c     lll_unlock @asulock @aculock
2197 @c     CANCEL_RESET -> pthread_disable_asynccancel ok
2198 @c      lll_futex_wait ok
2199 @c     ->start_routine ok -----
2200 @c     call_tls_dtors @asulock @ascuheap @aculock @acsmem
2201 @c      user-supplied dtor
2202 @c      rtld_lock_lock_recursive (dl_load_lock) @asulock @aculock
2203 @c      rtld_lock_unlock_recursive @aculock
2204 @c      free @ascuheap @acsmem
2205 @c     nptl_deallocate_tsd @ascuheap @acsmem
2206 @c      tsd user-supplied dtors ok
2207 @c      free @ascuheap @acsmem
2208 @c     libc_thread_freeres
2209 @c      libc_thread_subfreeres ok
2210 @c     atomic_decrement_and_test ok
2211 @c     td_eventword ok
2212 @c     td_eventmask ok
2213 @c     atomic_compare_exchange_bool_acq ok
2214 @c     nptl_death_event ok
2215 @c     lll_robust_dead ok
2216 @c     getpagesize ok
2217 @c     madvise ok
2218 @c     free_tcb @asulock @ascuheap @aculock @acsmem
2219 @c      free @ascuheap @acsmem
2220 @c      deallocate_stack @asulock @ascuheap @aculock @acsmem
2221 @c     lll_futex_wait ok
2222 @c     exit_thread_inline ok
2223 @c      syscall(exit) ok
2225 This function initiates an asynchronous read operation.  It
2226 immediately returns after the operation was enqueued or when an
2227 error was encountered.
2229 The first @code{aiocbp->aio_nbytes} bytes of the file for which
2230 @code{aiocbp->aio_fildes} is a descriptor are written to the buffer
2231 starting at @code{aiocbp->aio_buf}.  Reading starts at the absolute
2232 position @code{aiocbp->aio_offset} in the file.
2234 If prioritized I/O is supported by the platform the
2235 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
2236 the request is actually enqueued.
2238 The calling process is notified about the termination of the read
2239 request according to the @code{aiocbp->aio_sigevent} value.
2241 When @code{aio_read} returns, the return value is zero if no error
2242 occurred that can be found before the process is enqueued.  If such an
2243 early error is found, the function returns @math{-1} and sets
2244 @code{errno} to one of the following values:
2246 @table @code
2247 @item EAGAIN
2248 The request was not enqueued due to (temporarily) exceeded resource
2249 limitations.
2250 @item ENOSYS
2251 The @code{aio_read} function is not implemented.
2252 @item EBADF
2253 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
2254 need not be recognized before enqueueing the request and so this error
2255 might also be signaled asynchronously.
2256 @item EINVAL
2257 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
2258 invalid.  This condition need not be recognized before enqueueing the
2259 request and so this error might also be signaled asynchronously.
2260 @end table
2262 If @code{aio_read} returns zero, the current status of the request
2263 can be queried using @code{aio_error} and @code{aio_return} functions.
2264 As long as the value returned by @code{aio_error} is @code{EINPROGRESS}
2265 the operation has not yet completed.  If @code{aio_error} returns zero,
2266 the operation successfully terminated, otherwise the value is to be
2267 interpreted as an error code.  If the function terminated, the result of
2268 the operation can be obtained using a call to @code{aio_return}.  The
2269 returned value is the same as an equivalent call to @code{read} would
2270 have returned.  Possible error codes returned by @code{aio_error} are:
2272 @table @code
2273 @item EBADF
2274 The @code{aiocbp->aio_fildes} descriptor is not valid.
2275 @item ECANCELED
2276 The operation was canceled before the operation was finished
2277 (@pxref{Cancel AIO Operations})
2278 @item EINVAL
2279 The @code{aiocbp->aio_offset} value is invalid.
2280 @end table
2282 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2283 function is in fact @code{aio_read64} since the LFS interface transparently
2284 replaces the normal implementation.
2285 @end deftypefun
2287 @comment aio.h
2288 @comment Unix98
2289 @deftypefun int aio_read64 (struct aiocb64 *@var{aiocbp})
2290 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2291 This function is similar to the @code{aio_read} function.  The only
2292 difference is that on @w{32 bit} machines, the file descriptor should
2293 be opened in the large file mode.  Internally, @code{aio_read64} uses
2294 functionality equivalent to @code{lseek64} (@pxref{File Position
2295 Primitive}) to position the file descriptor correctly for the reading,
2296 as opposed to @code{lseek} functionality used in @code{aio_read}.
2298 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2299 function is available under the name @code{aio_read} and so transparently
2300 replaces the interface for small files on 32 bit machines.
2301 @end deftypefun
2303 To write data asynchronously to a file, there exists an equivalent pair
2304 of functions with a very similar interface.
2306 @comment aio.h
2307 @comment POSIX.1b
2308 @deftypefun int aio_write (struct aiocb *@var{aiocbp})
2309 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2310 This function initiates an asynchronous write operation.  The function
2311 call immediately returns after the operation was enqueued or if before
2312 this happens an error was encountered.
2314 The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at
2315 @code{aiocbp->aio_buf} are written to the file for which
2316 @code{aiocbp->aio_fildes} is a descriptor, starting at the absolute
2317 position @code{aiocbp->aio_offset} in the file.
2319 If prioritized I/O is supported by the platform, the
2320 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
2321 the request is actually enqueued.
2323 The calling process is notified about the termination of the read
2324 request according to the @code{aiocbp->aio_sigevent} value.
2326 When @code{aio_write} returns, the return value is zero if no error
2327 occurred that can be found before the process is enqueued.  If such an
2328 early error is found the function returns @math{-1} and sets
2329 @code{errno} to one of the following values.
2331 @table @code
2332 @item EAGAIN
2333 The request was not enqueued due to (temporarily) exceeded resource
2334 limitations.
2335 @item ENOSYS
2336 The @code{aio_write} function is not implemented.
2337 @item EBADF
2338 The @code{aiocbp->aio_fildes} descriptor is not valid.  This condition
2339 may not be recognized before enqueueing the request, and so this error
2340 might also be signaled asynchronously.
2341 @item EINVAL
2342 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqprio} value is
2343 invalid.  This condition may not be recognized before enqueueing the
2344 request and so this error might also be signaled asynchronously.
2345 @end table
2347 In the case @code{aio_write} returns zero, the current status of the
2348 request can be queried using @code{aio_error} and @code{aio_return}
2349 functions.  As long as the value returned by @code{aio_error} is
2350 @code{EINPROGRESS} the operation has not yet completed.  If
2351 @code{aio_error} returns zero, the operation successfully terminated,
2352 otherwise the value is to be interpreted as an error code.  If the
2353 function terminated, the result of the operation can be get using a call
2354 to @code{aio_return}.  The returned value is the same as an equivalent
2355 call to @code{read} would have returned.  Possible error codes returned
2356 by @code{aio_error} are:
2358 @table @code
2359 @item EBADF
2360 The @code{aiocbp->aio_fildes} descriptor is not valid.
2361 @item ECANCELED
2362 The operation was canceled before the operation was finished.
2363 (@pxref{Cancel AIO Operations})
2364 @item EINVAL
2365 The @code{aiocbp->aio_offset} value is invalid.
2366 @end table
2368 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2369 function is in fact @code{aio_write64} since the LFS interface transparently
2370 replaces the normal implementation.
2371 @end deftypefun
2373 @comment aio.h
2374 @comment Unix98
2375 @deftypefun int aio_write64 (struct aiocb64 *@var{aiocbp})
2376 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2377 This function is similar to the @code{aio_write} function.  The only
2378 difference is that on @w{32 bit} machines the file descriptor should
2379 be opened in the large file mode.  Internally @code{aio_write64} uses
2380 functionality equivalent to @code{lseek64} (@pxref{File Position
2381 Primitive}) to position the file descriptor correctly for the writing,
2382 as opposed to @code{lseek} functionality used in @code{aio_write}.
2384 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2385 function is available under the name @code{aio_write} and so transparently
2386 replaces the interface for small files on 32 bit machines.
2387 @end deftypefun
2389 Besides these functions with the more or less traditional interface,
2390 POSIX.1b also defines a function which can initiate more than one
2391 operation at a time, and which can handle freely mixed read and write
2392 operations.  It is therefore similar to a combination of @code{readv} and
2393 @code{writev}.
2395 @comment aio.h
2396 @comment POSIX.1b
2397 @deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
2398 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2399 @c Call lio_listio_internal, that takes the aio_requests_mutex lock and
2400 @c enqueues each request.  Then, it waits for notification or prepares
2401 @c for it before releasing the lock.  Even though it performs memory
2402 @c allocation and locking of its own, it doesn't add any classes of
2403 @c safety issues that aren't already covered by aio_enqueue_request.
2404 The @code{lio_listio} function can be used to enqueue an arbitrary
2405 number of read and write requests at one time.  The requests can all be
2406 meant for the same file, all for different files or every solution in
2407 between.
2409 @code{lio_listio} gets the @var{nent} requests from the array pointed to
2410 by @var{list}.  The operation to be performed is determined by the
2411 @code{aio_lio_opcode} member in each element of @var{list}.  If this
2412 field is @code{LIO_READ} a read operation is enqueued, similar to a call
2413 of @code{aio_read} for this element of the array (except that the way
2414 the termination is signalled is different, as we will see below).  If
2415 the @code{aio_lio_opcode} member is @code{LIO_WRITE} a write operation
2416 is enqueued.  Otherwise the @code{aio_lio_opcode} must be @code{LIO_NOP}
2417 in which case this element of @var{list} is simply ignored.  This
2418 ``operation'' is useful in situations where one has a fixed array of
2419 @code{struct aiocb} elements from which only a few need to be handled at
2420 a time.  Another situation is where the @code{lio_listio} call was
2421 canceled before all requests are processed (@pxref{Cancel AIO
2422 Operations}) and the remaining requests have to be reissued.
2424 The other members of each element of the array pointed to by
2425 @code{list} must have values suitable for the operation as described in
2426 the documentation for @code{aio_read} and @code{aio_write} above.
2428 The @var{mode} argument determines how @code{lio_listio} behaves after
2429 having enqueued all the requests.  If @var{mode} is @code{LIO_WAIT} it
2430 waits until all requests terminated.  Otherwise @var{mode} must be
2431 @code{LIO_NOWAIT} and in this case the function returns immediately after
2432 having enqueued all the requests.  In this case the caller gets a
2433 notification of the termination of all requests according to the
2434 @var{sig} parameter.  If @var{sig} is @code{NULL} no notification is
2435 send.  Otherwise a signal is sent or a thread is started, just as
2436 described in the description for @code{aio_read} or @code{aio_write}.
2438 If @var{mode} is @code{LIO_WAIT}, the return value of @code{lio_listio}
2439 is @math{0} when all requests completed successfully.  Otherwise the
2440 function return @math{-1} and @code{errno} is set accordingly.  To find
2441 out which request or requests failed one has to use the @code{aio_error}
2442 function on all the elements of the array @var{list}.
2444 In case @var{mode} is @code{LIO_NOWAIT}, the function returns @math{0} if
2445 all requests were enqueued correctly.  The current state of the requests
2446 can be found using @code{aio_error} and @code{aio_return} as described
2447 above.  If @code{lio_listio} returns @math{-1} in this mode, the
2448 global variable @code{errno} is set accordingly.  If a request did not
2449 yet terminate, a call to @code{aio_error} returns @code{EINPROGRESS}.  If
2450 the value is different, the request is finished and the error value (or
2451 @math{0}) is returned and the result of the operation can be retrieved
2452 using @code{aio_return}.
2454 Possible values for @code{errno} are:
2456 @table @code
2457 @item EAGAIN
2458 The resources necessary to queue all the requests are not available at
2459 the moment.  The error status for each element of @var{list} must be
2460 checked to determine which request failed.
2462 Another reason could be that the system wide limit of AIO requests is
2463 exceeded.  This cannot be the case for the implementation on @gnusystems{}
2464 since no arbitrary limits exist.
2465 @item EINVAL
2466 The @var{mode} parameter is invalid or @var{nent} is larger than
2467 @code{AIO_LISTIO_MAX}.
2468 @item EIO
2469 One or more of the request's I/O operations failed.  The error status of
2470 each request should be checked to determine which one failed.
2471 @item ENOSYS
2472 The @code{lio_listio} function is not supported.
2473 @end table
2475 If the @var{mode} parameter is @code{LIO_NOWAIT} and the caller cancels
2476 a request, the error status for this request returned by
2477 @code{aio_error} is @code{ECANCELED}.
2479 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2480 function is in fact @code{lio_listio64} since the LFS interface
2481 transparently replaces the normal implementation.
2482 @end deftypefun
2484 @comment aio.h
2485 @comment Unix98
2486 @deftypefun int lio_listio64 (int @var{mode}, struct aiocb64 *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
2487 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2488 This function is similar to the @code{lio_listio} function.  The only
2489 difference is that on @w{32 bit} machines, the file descriptor should
2490 be opened in the large file mode.  Internally, @code{lio_listio64} uses
2491 functionality equivalent to @code{lseek64} (@pxref{File Position
2492 Primitive}) to position the file descriptor correctly for the reading or
2493 writing, as opposed to @code{lseek} functionality used in
2494 @code{lio_listio}.
2496 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2497 function is available under the name @code{lio_listio} and so
2498 transparently replaces the interface for small files on 32 bit
2499 machines.
2500 @end deftypefun
2502 @node Status of AIO Operations
2503 @subsection Getting the Status of AIO Operations
2505 As already described in the documentation of the functions in the last
2506 section, it must be possible to get information about the status of an I/O
2507 request.  When the operation is performed truly asynchronously (as with
2508 @code{aio_read} and @code{aio_write} and with @code{lio_listio} when the
2509 mode is @code{LIO_NOWAIT}), one sometimes needs to know whether a
2510 specific request already terminated and if so, what the result was.
2511 The following two functions allow you to get this kind of information.
2513 @comment aio.h
2514 @comment POSIX.1b
2515 @deftypefun int aio_error (const struct aiocb *@var{aiocbp})
2516 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2517 This function determines the error state of the request described by the
2518 @code{struct aiocb} variable pointed to by @var{aiocbp}.  If the
2519 request has not yet terminated the value returned is always
2520 @code{EINPROGRESS}.  Once the request has terminated the value
2521 @code{aio_error} returns is either @math{0} if the request completed
2522 successfully or it returns the value which would be stored in the
2523 @code{errno} variable if the request would have been done using
2524 @code{read}, @code{write}, or @code{fsync}.
2526 The function can return @code{ENOSYS} if it is not implemented.  It
2527 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2528 refer to an asynchronous operation whose return status is not yet known.
2530 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2531 function is in fact @code{aio_error64} since the LFS interface
2532 transparently replaces the normal implementation.
2533 @end deftypefun
2535 @comment aio.h
2536 @comment Unix98
2537 @deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp})
2538 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2539 This function is similar to @code{aio_error} with the only difference
2540 that the argument is a reference to a variable of type @code{struct
2541 aiocb64}.
2543 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2544 function is available under the name @code{aio_error} and so
2545 transparently replaces the interface for small files on 32 bit
2546 machines.
2547 @end deftypefun
2549 @comment aio.h
2550 @comment POSIX.1b
2551 @deftypefun ssize_t aio_return (struct aiocb *@var{aiocbp})
2552 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2553 This function can be used to retrieve the return status of the operation
2554 carried out by the request described in the variable pointed to by
2555 @var{aiocbp}.  As long as the error status of this request as returned
2556 by @code{aio_error} is @code{EINPROGRESS} the return of this function is
2557 undefined.
2559 Once the request is finished this function can be used exactly once to
2560 retrieve the return value.  Following calls might lead to undefined
2561 behavior.  The return value itself is the value which would have been
2562 returned by the @code{read}, @code{write}, or @code{fsync} call.
2564 The function can return @code{ENOSYS} if it is not implemented.  It
2565 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2566 refer to an asynchronous operation whose return status is not yet known.
2568 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2569 function is in fact @code{aio_return64} since the LFS interface
2570 transparently replaces the normal implementation.
2571 @end deftypefun
2573 @comment aio.h
2574 @comment Unix98
2575 @deftypefun ssize_t aio_return64 (struct aiocb64 *@var{aiocbp})
2576 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2577 This function is similar to @code{aio_return} with the only difference
2578 that the argument is a reference to a variable of type @code{struct
2579 aiocb64}.
2581 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2582 function is available under the name @code{aio_return} and so
2583 transparently replaces the interface for small files on 32 bit
2584 machines.
2585 @end deftypefun
2587 @node Synchronizing AIO Operations
2588 @subsection Getting into a Consistent State
2590 When dealing with asynchronous operations it is sometimes necessary to
2591 get into a consistent state.  This would mean for AIO that one wants to
2592 know whether a certain request or a group of request were processed.
2593 This could be done by waiting for the notification sent by the system
2594 after the operation terminated, but this sometimes would mean wasting
2595 resources (mainly computation time).  Instead POSIX.1b defines two
2596 functions which will help with most kinds of consistency.
2598 The @code{aio_fsync} and @code{aio_fsync64} functions are only available
2599 if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}.
2601 @cindex synchronizing
2602 @comment aio.h
2603 @comment POSIX.1b
2604 @deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp})
2605 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2606 @c After fcntl to check that the FD is open, it calls
2607 @c aio_enqueue_request.
2608 Calling this function forces all I/O operations operating queued at the
2609 time of the function call operating on the file descriptor
2610 @code{aiocbp->aio_fildes} into the synchronized I/O completion state
2611 (@pxref{Synchronizing I/O}).  The @code{aio_fsync} function returns
2612 immediately but the notification through the method described in
2613 @code{aiocbp->aio_sigevent} will happen only after all requests for this
2614 file descriptor have terminated and the file is synchronized.  This also
2615 means that requests for this very same file descriptor which are queued
2616 after the synchronization request are not affected.
2618 If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
2619 to @code{fdatasync}.  Otherwise @var{op} should be @code{O_SYNC} and
2620 the synchronization happens as with @code{fsync}.
2622 As long as the synchronization has not happened, a call to
2623 @code{aio_error} with the reference to the object pointed to by
2624 @var{aiocbp} returns @code{EINPROGRESS}.  Once the synchronization is
2625 done @code{aio_error} return @math{0} if the synchronization was not
2626 successful.  Otherwise the value returned is the value to which the
2627 @code{fsync} or @code{fdatasync} function would have set the
2628 @code{errno} variable.  In this case nothing can be assumed about the
2629 consistency for the data written to this file descriptor.
2631 The return value of this function is @math{0} if the request was
2632 successfully enqueued.  Otherwise the return value is @math{-1} and
2633 @code{errno} is set to one of the following values:
2635 @table @code
2636 @item EAGAIN
2637 The request could not be enqueued due to temporary lack of resources.
2638 @item EBADF
2639 The file descriptor @code{@var{aiocbp}->aio_fildes} is not valid.
2640 @item EINVAL
2641 The implementation does not support I/O synchronization or the @var{op}
2642 parameter is other than @code{O_DSYNC} and @code{O_SYNC}.
2643 @item ENOSYS
2644 This function is not implemented.
2645 @end table
2647 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2648 function is in fact @code{aio_fsync64} since the LFS interface
2649 transparently replaces the normal implementation.
2650 @end deftypefun
2652 @comment aio.h
2653 @comment Unix98
2654 @deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp})
2655 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2656 This function is similar to @code{aio_fsync} with the only difference
2657 that the argument is a reference to a variable of type @code{struct
2658 aiocb64}.
2660 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2661 function is available under the name @code{aio_fsync} and so
2662 transparently replaces the interface for small files on 32 bit
2663 machines.
2664 @end deftypefun
2666 Another method of synchronization is to wait until one or more requests of a
2667 specific set terminated.  This could be achieved by the @code{aio_*}
2668 functions to notify the initiating process about the termination but in
2669 some situations this is not the ideal solution.  In a program which
2670 constantly updates clients somehow connected to the server it is not
2671 always the best solution to go round robin since some connections might
2672 be slow.  On the other hand letting the @code{aio_*} function notify the
2673 caller might also be not the best solution since whenever the process
2674 works on preparing data for on client it makes no sense to be
2675 interrupted by a notification since the new client will not be handled
2676 before the current client is served.  For situations like this
2677 @code{aio_suspend} should be used.
2679 @comment aio.h
2680 @comment POSIX.1b
2681 @deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
2682 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
2683 @c Take aio_requests_mutex, set up waitlist and requestlist, wait
2684 @c for completion or timeout, and release the mutex.
2685 When calling this function, the calling thread is suspended until at
2686 least one of the requests pointed to by the @var{nent} elements of the
2687 array @var{list} has completed.  If any of the requests has already
2688 completed at the time @code{aio_suspend} is called, the function returns
2689 immediately.  Whether a request has terminated or not is determined by
2690 comparing the error status of the request with @code{EINPROGRESS}.  If
2691 an element of @var{list} is @code{NULL}, the entry is simply ignored.
2693 If no request has finished, the calling process is suspended.  If
2694 @var{timeout} is @code{NULL}, the process is not woken until a request
2695 has finished.  If @var{timeout} is not @code{NULL}, the process remains
2696 suspended at least as long as specified in @var{timeout}.  In this case,
2697 @code{aio_suspend} returns with an error.
2699 The return value of the function is @math{0} if one or more requests
2700 from the @var{list} have terminated.  Otherwise the function returns
2701 @math{-1} and @code{errno} is set to one of the following values:
2703 @table @code
2704 @item EAGAIN
2705 None of the requests from the @var{list} completed in the time specified
2706 by @var{timeout}.
2707 @item EINTR
2708 A signal interrupted the @code{aio_suspend} function.  This signal might
2709 also be sent by the AIO implementation while signalling the termination
2710 of one of the requests.
2711 @item ENOSYS
2712 The @code{aio_suspend} function is not implemented.
2713 @end table
2715 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2716 function is in fact @code{aio_suspend64} since the LFS interface
2717 transparently replaces the normal implementation.
2718 @end deftypefun
2720 @comment aio.h
2721 @comment Unix98
2722 @deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
2723 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
2724 This function is similar to @code{aio_suspend} with the only difference
2725 that the argument is a reference to a variable of type @code{struct
2726 aiocb64}.
2728 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2729 function is available under the name @code{aio_suspend} and so
2730 transparently replaces the interface for small files on 32 bit
2731 machines.
2732 @end deftypefun
2734 @node Cancel AIO Operations
2735 @subsection Cancellation of AIO Operations
2737 When one or more requests are asynchronously processed, it might be
2738 useful in some situations to cancel a selected operation, e.g., if it
2739 becomes obvious that the written data is no longer accurate and would
2740 have to be overwritten soon.  As an example, assume an application, which
2741 writes data in files in a situation where new incoming data would have
2742 to be written in a file which will be updated by an enqueued request.
2743 The POSIX AIO implementation provides such a function, but this function
2744 is not capable of forcing the cancellation of the request.  It is up to the
2745 implementation to decide whether it is possible to cancel the operation
2746 or not.  Therefore using this function is merely a hint.
2748 @comment aio.h
2749 @comment POSIX.1b
2750 @deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp})
2751 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2752 @c After fcntl to check the fd is open, hold aio_requests_mutex, call
2753 @c aio_find_req_fd, aio_remove_request, then aio_notify and
2754 @c aio_free_request each request before releasing the lock.
2755 @c aio_notify calls aio_notify_only and free, besides cond signal or
2756 @c similar.  aio_notify_only calls pthread_attr_init,
2757 @c pthread_attr_setdetachstate, malloc, pthread_create,
2758 @c notify_func_wrapper, aio_sigqueue, getpid, raise.
2759 @c notify_func_wraper calls aio_start_notify_thread, free and then the
2760 @c notifier function.
2761 The @code{aio_cancel} function can be used to cancel one or more
2762 outstanding requests.  If the @var{aiocbp} parameter is @code{NULL}, the
2763 function tries to cancel all of the outstanding requests which would process
2764 the file descriptor @var{fildes} (i.e., whose @code{aio_fildes} member
2765 is @var{fildes}).  If @var{aiocbp} is not @code{NULL}, @code{aio_cancel}
2766 attempts to cancel the specific request pointed to by @var{aiocbp}.
2768 For requests which were successfully canceled, the normal notification
2769 about the termination of the request should take place.  I.e., depending
2770 on the @code{struct sigevent} object which controls this, nothing
2771 happens, a signal is sent or a thread is started.  If the request cannot
2772 be canceled, it terminates the usual way after performing the operation.
2774 After a request is successfully canceled, a call to @code{aio_error} with
2775 a reference to this request as the parameter will return
2776 @code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
2777 If the request wasn't canceled and is still running the error status is
2778 still @code{EINPROGRESS}.
2780 The return value of the function is @code{AIO_CANCELED} if there were
2781 requests which haven't terminated and which were successfully canceled.
2782 If there is one or more requests left which couldn't be canceled, the
2783 return value is @code{AIO_NOTCANCELED}.  In this case @code{aio_error}
2784 must be used to find out which of the, perhaps multiple, requests (in
2785 @var{aiocbp} is @code{NULL}) weren't successfully canceled.  If all
2786 requests already terminated at the time @code{aio_cancel} is called the
2787 return value is @code{AIO_ALLDONE}.
2789 If an error occurred during the execution of @code{aio_cancel} the
2790 function returns @math{-1} and sets @code{errno} to one of the following
2791 values.
2793 @table @code
2794 @item EBADF
2795 The file descriptor @var{fildes} is not valid.
2796 @item ENOSYS
2797 @code{aio_cancel} is not implemented.
2798 @end table
2800 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2801 function is in fact @code{aio_cancel64} since the LFS interface
2802 transparently replaces the normal implementation.
2803 @end deftypefun
2805 @comment aio.h
2806 @comment Unix98
2807 @deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb64 *@var{aiocbp})
2808 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2809 This function is similar to @code{aio_cancel} with the only difference
2810 that the argument is a reference to a variable of type @code{struct
2811 aiocb64}.
2813 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2814 function is available under the name @code{aio_cancel} and so
2815 transparently replaces the interface for small files on 32 bit
2816 machines.
2817 @end deftypefun
2819 @node Configuration of AIO
2820 @subsection How to optimize the AIO implementation
2822 The POSIX standard does not specify how the AIO functions are
2823 implemented.  They could be system calls, but it is also possible to
2824 emulate them at userlevel.
2826 At the point of this writing, the available implementation is a userlevel
2827 implementation which uses threads for handling the enqueued requests.
2828 While this implementation requires making some decisions about
2829 limitations, hard limitations are something which is best avoided
2830 in @theglibc{}.  Therefore, @theglibc{} provides a means
2831 for tuning the AIO implementation according to the individual use.
2833 @comment aio.h
2834 @comment GNU
2835 @deftp {Data Type} {struct aioinit}
2836 This data type is used to pass the configuration or tunable parameters
2837 to the implementation.  The program has to initialize the members of
2838 this struct and pass it to the implementation using the @code{aio_init}
2839 function.
2841 @table @code
2842 @item int aio_threads
2843 This member specifies the maximal number of threads which may be used
2844 at any one time.
2845 @item int aio_num
2846 This number provides an estimate on the maximal number of simultaneously
2847 enqueued requests.
2848 @item int aio_locks
2849 Unused.
2850 @item int aio_usedba
2851 Unused.
2852 @item int aio_debug
2853 Unused.
2854 @item int aio_numusers
2855 Unused.
2856 @item int aio_reserved[2]
2857 Unused.
2858 @end table
2859 @end deftp
2861 @comment aio.h
2862 @comment GNU
2863 @deftypefun void aio_init (const struct aioinit *@var{init})
2864 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
2865 @c All changes to global objects are guarded by aio_requests_mutex.
2866 This function must be called before any other AIO function.  Calling it
2867 is completely voluntary, as it is only meant to help the AIO
2868 implementation perform better.
2870 Before calling the @code{aio_init}, function the members of a variable of
2871 type @code{struct aioinit} must be initialized.  Then a reference to
2872 this variable is passed as the parameter to @code{aio_init} which itself
2873 may or may not pay attention to the hints.
2875 The function has no return value and no error cases are defined.  It is
2876 a extension which follows a proposal from the SGI implementation in
2877 @w{Irix 6}.  It is not covered by POSIX.1b or Unix98.
2878 @end deftypefun
2880 @node Control Operations
2881 @section Control Operations on Files
2883 @cindex control operations on files
2884 @cindex @code{fcntl} function
2885 This section describes how you can perform various other operations on
2886 file descriptors, such as inquiring about or setting flags describing
2887 the status of the file descriptor, manipulating record locks, and the
2888 like.  All of these operations are performed by the function @code{fcntl}.
2890 The second argument to the @code{fcntl} function is a command that
2891 specifies which operation to perform.  The function and macros that name
2892 various flags that are used with it are declared in the header file
2893 @file{fcntl.h}.  Many of these flags are also used by the @code{open}
2894 function; see @ref{Opening and Closing Files}.
2895 @pindex fcntl.h
2897 @comment fcntl.h
2898 @comment POSIX.1
2899 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
2900 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2901 The @code{fcntl} function performs the operation specified by
2902 @var{command} on the file descriptor @var{filedes}.  Some commands
2903 require additional arguments to be supplied.  These additional arguments
2904 and the return value and error conditions are given in the detailed
2905 descriptions of the individual commands.
2907 Briefly, here is a list of what the various commands are.
2909 @table @code
2910 @item F_DUPFD
2911 Duplicate the file descriptor (return another file descriptor pointing
2912 to the same open file).  @xref{Duplicating Descriptors}.
2914 @item F_GETFD
2915 Get flags associated with the file descriptor.  @xref{Descriptor Flags}.
2917 @item F_SETFD
2918 Set flags associated with the file descriptor.  @xref{Descriptor Flags}.
2920 @item F_GETFL
2921 Get flags associated with the open file.  @xref{File Status Flags}.
2923 @item F_SETFL
2924 Set flags associated with the open file.  @xref{File Status Flags}.
2926 @item F_GETLK
2927 Test a file lock.  @xref{File Locks}.
2929 @item F_SETLK
2930 Set or clear a file lock.  @xref{File Locks}.
2932 @item F_SETLKW
2933 Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.
2935 @item F_OFD_GETLK
2936 Test an open file description lock.  @xref{Open File Description Locks}.
2937 Specific to Linux.
2939 @item F_OFD_SETLK
2940 Set or clear an open file description lock.  @xref{Open File Description Locks}.
2941 Specific to Linux.
2943 @item F_OFD_SETLKW
2944 Like @code{F_OFD_SETLK}, but block until lock is acquired.
2945 @xref{Open File Description Locks}.  Specific to Linux.
2947 @item F_GETOWN
2948 Get process or process group ID to receive @code{SIGIO} signals.
2949 @xref{Interrupt Input}.
2951 @item F_SETOWN
2952 Set process or process group ID to receive @code{SIGIO} signals.
2953 @xref{Interrupt Input}.
2954 @end table
2956 This function is a cancellation point in multi-threaded programs.  This
2957 is a problem if the thread allocates some resources (like memory, file
2958 descriptors, semaphores or whatever) at the time @code{fcntl} is
2959 called.  If the thread gets canceled these resources stay allocated
2960 until the program ends.  To avoid this calls to @code{fcntl} should be
2961 protected using cancellation handlers.
2962 @c ref pthread_cleanup_push / pthread_cleanup_pop
2963 @end deftypefun
2966 @node Duplicating Descriptors
2967 @section Duplicating Descriptors
2969 @cindex duplicating file descriptors
2970 @cindex redirecting input and output
2972 You can @dfn{duplicate} a file descriptor, or allocate another file
2973 descriptor that refers to the same open file as the original.  Duplicate
2974 descriptors share one file position and one set of file status flags
2975 (@pxref{File Status Flags}), but each has its own set of file descriptor
2976 flags (@pxref{Descriptor Flags}).
2978 The major use of duplicating a file descriptor is to implement
2979 @dfn{redirection} of input or output:  that is, to change the
2980 file or pipe that a particular file descriptor corresponds to.
2982 You can perform this operation using the @code{fcntl} function with the
2983 @code{F_DUPFD} command, but there are also convenient functions
2984 @code{dup} and @code{dup2} for duplicating descriptors.
2986 @pindex unistd.h
2987 @pindex fcntl.h
2988 The @code{fcntl} function and flags are declared in @file{fcntl.h},
2989 while prototypes for @code{dup} and @code{dup2} are in the header file
2990 @file{unistd.h}.
2992 @comment unistd.h
2993 @comment POSIX.1
2994 @deftypefun int dup (int @var{old})
2995 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2996 This function copies descriptor @var{old} to the first available
2997 descriptor number (the first number not currently open).  It is
2998 equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
2999 @end deftypefun
3001 @comment unistd.h
3002 @comment POSIX.1
3003 @deftypefun int dup2 (int @var{old}, int @var{new})
3004 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3005 This function copies the descriptor @var{old} to descriptor number
3006 @var{new}.
3008 If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
3009 does not close @var{new}.  Otherwise, the new duplicate of @var{old}
3010 replaces any previous meaning of descriptor @var{new}, as if @var{new}
3011 were closed first.
3013 If @var{old} and @var{new} are different numbers, and @var{old} is a
3014 valid descriptor number, then @code{dup2} is equivalent to:
3016 @smallexample
3017 close (@var{new});
3018 fcntl (@var{old}, F_DUPFD, @var{new})
3019 @end smallexample
3021 However, @code{dup2} does this atomically; there is no instant in the
3022 middle of calling @code{dup2} at which @var{new} is closed and not yet a
3023 duplicate of @var{old}.
3024 @end deftypefun
3026 @comment fcntl.h
3027 @comment POSIX.1
3028 @deftypevr Macro int F_DUPFD
3029 This macro is used as the @var{command} argument to @code{fcntl}, to
3030 copy the file descriptor given as the first argument.
3032 The form of the call in this case is:
3034 @smallexample
3035 fcntl (@var{old}, F_DUPFD, @var{next-filedes})
3036 @end smallexample
3038 The @var{next-filedes} argument is of type @code{int} and specifies that
3039 the file descriptor returned should be the next available one greater
3040 than or equal to this value.
3042 The return value from @code{fcntl} with this command is normally the value
3043 of the new file descriptor.  A return value of @math{-1} indicates an
3044 error.  The following @code{errno} error conditions are defined for
3045 this command:
3047 @table @code
3048 @item EBADF
3049 The @var{old} argument is invalid.
3051 @item EINVAL
3052 The @var{next-filedes} argument is invalid.
3054 @item EMFILE
3055 There are no more file descriptors available---your program is already
3056 using the maximum.  In BSD and GNU, the maximum is controlled by a
3057 resource limit that can be changed; @pxref{Limits on Resources}, for
3058 more information about the @code{RLIMIT_NOFILE} limit.
3059 @end table
3061 @code{ENFILE} is not a possible error code for @code{dup2} because
3062 @code{dup2} does not create a new opening of a file; duplicate
3063 descriptors do not count toward the limit which @code{ENFILE}
3064 indicates.  @code{EMFILE} is possible because it refers to the limit on
3065 distinct descriptor numbers in use in one process.
3066 @end deftypevr
3068 Here is an example showing how to use @code{dup2} to do redirection.
3069 Typically, redirection of the standard streams (like @code{stdin}) is
3070 done by a shell or shell-like program before calling one of the
3071 @code{exec} functions (@pxref{Executing a File}) to execute a new
3072 program in a child process.  When the new program is executed, it
3073 creates and initializes the standard streams to point to the
3074 corresponding file descriptors, before its @code{main} function is
3075 invoked.
3077 So, to redirect standard input to a file, the shell could do something
3078 like:
3080 @smallexample
3081 pid = fork ();
3082 if (pid == 0)
3083   @{
3084     char *filename;
3085     char *program;
3086     int file;
3087     @dots{}
3088     file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
3089     dup2 (file, STDIN_FILENO);
3090     TEMP_FAILURE_RETRY (close (file));
3091     execv (program, NULL);
3092   @}
3093 @end smallexample
3095 There is also a more detailed example showing how to implement redirection
3096 in the context of a pipeline of processes in @ref{Launching Jobs}.
3099 @node Descriptor Flags
3100 @section File Descriptor Flags
3101 @cindex file descriptor flags
3103 @dfn{File descriptor flags} are miscellaneous attributes of a file
3104 descriptor.  These flags are associated with particular file
3105 descriptors, so that if you have created duplicate file descriptors
3106 from a single opening of a file, each descriptor has its own set of flags.
3108 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
3109 which causes the descriptor to be closed if you use any of the
3110 @code{exec@dots{}} functions (@pxref{Executing a File}).
3112 The symbols in this section are defined in the header file
3113 @file{fcntl.h}.
3114 @pindex fcntl.h
3116 @comment fcntl.h
3117 @comment POSIX.1
3118 @deftypevr Macro int F_GETFD
3119 This macro is used as the @var{command} argument to @code{fcntl}, to
3120 specify that it should return the file descriptor flags associated
3121 with the @var{filedes} argument.
3123 The normal return value from @code{fcntl} with this command is a
3124 nonnegative number which can be interpreted as the bitwise OR of the
3125 individual flags (except that currently there is only one flag to use).
3127 In case of an error, @code{fcntl} returns @math{-1}.  The following
3128 @code{errno} error conditions are defined for this command:
3130 @table @code
3131 @item EBADF
3132 The @var{filedes} argument is invalid.
3133 @end table
3134 @end deftypevr
3137 @comment fcntl.h
3138 @comment POSIX.1
3139 @deftypevr Macro int F_SETFD
3140 This macro is used as the @var{command} argument to @code{fcntl}, to
3141 specify that it should set the file descriptor flags associated with the
3142 @var{filedes} argument.  This requires a third @code{int} argument to
3143 specify the new flags, so the form of the call is:
3145 @smallexample
3146 fcntl (@var{filedes}, F_SETFD, @var{new-flags})
3147 @end smallexample
3149 The normal return value from @code{fcntl} with this command is an
3150 unspecified value other than @math{-1}, which indicates an error.
3151 The flags and error conditions are the same as for the @code{F_GETFD}
3152 command.
3153 @end deftypevr
3155 The following macro is defined for use as a file descriptor flag with
3156 the @code{fcntl} function.  The value is an integer constant usable
3157 as a bit mask value.
3159 @comment fcntl.h
3160 @comment POSIX.1
3161 @deftypevr Macro int FD_CLOEXEC
3162 @cindex close-on-exec (file descriptor flag)
3163 This flag specifies that the file descriptor should be closed when
3164 an @code{exec} function is invoked; see @ref{Executing a File}.  When
3165 a file descriptor is allocated (as with @code{open} or @code{dup}),
3166 this bit is initially cleared on the new file descriptor, meaning that
3167 descriptor will survive into the new program after @code{exec}.
3168 @end deftypevr
3170 If you want to modify the file descriptor flags, you should get the
3171 current flags with @code{F_GETFD} and modify the value.  Don't assume
3172 that the flags listed here are the only ones that are implemented; your
3173 program may be run years from now and more flags may exist then.  For
3174 example, here is a function to set or clear the flag @code{FD_CLOEXEC}
3175 without altering any other flags:
3177 @smallexample
3178 /* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
3179    @r{or clear the flag if @var{value} is 0.}
3180    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
3183 set_cloexec_flag (int desc, int value)
3185   int oldflags = fcntl (desc, F_GETFD, 0);
3186   /* @r{If reading the flags failed, return error indication now.} */
3187   if (oldflags < 0)
3188     return oldflags;
3189   /* @r{Set just the flag we want to set.} */
3190   if (value != 0)
3191     oldflags |= FD_CLOEXEC;
3192   else
3193     oldflags &= ~FD_CLOEXEC;
3194   /* @r{Store modified flag word in the descriptor.} */
3195   return fcntl (desc, F_SETFD, oldflags);
3197 @end smallexample
3199 @node File Status Flags
3200 @section File Status Flags
3201 @cindex file status flags
3203 @dfn{File status flags} are used to specify attributes of the opening of a
3204 file.  Unlike the file descriptor flags discussed in @ref{Descriptor
3205 Flags}, the file status flags are shared by duplicated file descriptors
3206 resulting from a single opening of the file.  The file status flags are
3207 specified with the @var{flags} argument to @code{open};
3208 @pxref{Opening and Closing Files}.
3210 File status flags fall into three categories, which are described in the
3211 following sections.
3213 @itemize @bullet
3214 @item
3215 @ref{Access Modes}, specify what type of access is allowed to the
3216 file: reading, writing, or both.  They are set by @code{open} and are
3217 returned by @code{fcntl}, but cannot be changed.
3219 @item
3220 @ref{Open-time Flags}, control details of what @code{open} will do.
3221 These flags are not preserved after the @code{open} call.
3223 @item
3224 @ref{Operating Modes}, affect how operations such as @code{read} and
3225 @code{write} are done.  They are set by @code{open}, and can be fetched or
3226 changed with @code{fcntl}.
3227 @end itemize
3229 The symbols in this section are defined in the header file
3230 @file{fcntl.h}.
3231 @pindex fcntl.h
3233 @menu
3234 * Access Modes::                Whether the descriptor can read or write.
3235 * Open-time Flags::             Details of @code{open}.
3236 * Operating Modes::             Special modes to control I/O operations.
3237 * Getting File Status Flags::   Fetching and changing these flags.
3238 @end menu
3240 @node Access Modes
3241 @subsection File Access Modes
3243 The file access modes allow a file descriptor to be used for reading,
3244 writing, or both.  (On @gnuhurdsystems{}, they can also allow none of these,
3245 and allow execution of the file as a program.)  The access modes are chosen
3246 when the file is opened, and never change.
3248 @comment fcntl.h
3249 @comment POSIX.1
3250 @deftypevr Macro int O_RDONLY
3251 Open the file for read access.
3252 @end deftypevr
3254 @comment fcntl.h
3255 @comment POSIX.1
3256 @deftypevr Macro int O_WRONLY
3257 Open the file for write access.
3258 @end deftypevr
3260 @comment fcntl.h
3261 @comment POSIX.1
3262 @deftypevr Macro int O_RDWR
3263 Open the file for both reading and writing.
3264 @end deftypevr
3266 On @gnuhurdsystems{} (and not on other systems), @code{O_RDONLY} and
3267 @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
3268 and it is valid for either bit to be set or clear.  This means that
3269 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}.  A file access
3270 mode of zero is permissible; it allows no operations that do input or
3271 output to the file, but does allow other operations such as
3272 @code{fchmod}.  On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
3273 is a misnomer, @file{fcntl.h} defines additional names for the file
3274 access modes.  These names are preferred when writing GNU-specific code.
3275 But most programs will want to be portable to other POSIX.1 systems and
3276 should use the POSIX.1 names above instead.
3278 @comment fcntl.h (optional)
3279 @comment GNU
3280 @deftypevr Macro int O_READ
3281 Open the file for reading.  Same as @code{O_RDONLY}; only defined on GNU.
3282 @end deftypevr
3284 @comment fcntl.h (optional)
3285 @comment GNU
3286 @deftypevr Macro int O_WRITE
3287 Open the file for writing.  Same as @code{O_WRONLY}; only defined on GNU.
3288 @end deftypevr
3290 @comment fcntl.h (optional)
3291 @comment GNU
3292 @deftypevr Macro int O_EXEC
3293 Open the file for executing.  Only defined on GNU.
3294 @end deftypevr
3296 To determine the file access mode with @code{fcntl}, you must extract
3297 the access mode bits from the retrieved file status flags.  On
3298 @gnuhurdsystems{},
3299 you can just test the @code{O_READ} and @code{O_WRITE} bits in
3300 the flags word.  But in other POSIX.1 systems, reading and writing
3301 access modes are not stored as distinct bit flags.  The portable way to
3302 extract the file access mode bits is with @code{O_ACCMODE}.
3304 @comment fcntl.h
3305 @comment POSIX.1
3306 @deftypevr Macro int O_ACCMODE
3307 This macro stands for a mask that can be bitwise-ANDed with the file
3308 status flag value to produce a value representing the file access mode.
3309 The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
3310 (On @gnuhurdsystems{} it could also be zero, and it never includes the
3311 @code{O_EXEC} bit.)
3312 @end deftypevr
3314 @node Open-time Flags
3315 @subsection Open-time Flags
3317 The open-time flags specify options affecting how @code{open} will behave.
3318 These options are not preserved once the file is open.  The exception to
3319 this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
3320 @emph{is} saved.  @xref{Opening and Closing Files}, for how to call
3321 @code{open}.
3323 There are two sorts of options specified by open-time flags.
3325 @itemize @bullet
3326 @item
3327 @dfn{File name translation flags} affect how @code{open} looks up the
3328 file name to locate the file, and whether the file can be created.
3329 @cindex file name translation flags
3330 @cindex flags, file name translation
3332 @item
3333 @dfn{Open-time action flags} specify extra operations that @code{open} will
3334 perform on the file once it is open.
3335 @cindex open-time action flags
3336 @cindex flags, open-time action
3337 @end itemize
3339 Here are the file name translation flags.
3341 @comment fcntl.h
3342 @comment POSIX.1
3343 @deftypevr Macro int O_CREAT
3344 If set, the file will be created if it doesn't already exist.
3345 @c !!! mode arg, umask
3346 @cindex create on open (file status flag)
3347 @end deftypevr
3349 @comment fcntl.h
3350 @comment POSIX.1
3351 @deftypevr Macro int O_EXCL
3352 If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
3353 if the specified file already exists.  This is guaranteed to never
3354 clobber an existing file.
3355 @end deftypevr
3357 @comment fcntl.h
3358 @comment POSIX.1
3359 @deftypevr Macro int O_NONBLOCK
3360 @cindex non-blocking open
3361 This prevents @code{open} from blocking for a ``long time'' to open the
3362 file.  This is only meaningful for some kinds of files, usually devices
3363 such as serial ports; when it is not meaningful, it is harmless and
3364 ignored.  Often opening a port to a modem blocks until the modem reports
3365 carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
3366 return immediately without a carrier.
3368 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
3369 mode and a file name translation flag.  This means that specifying
3370 @code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
3371 @pxref{Operating Modes}.  To open the file without blocking but do normal
3372 I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
3373 then call @code{fcntl} to turn the bit off.
3374 @end deftypevr
3376 @comment fcntl.h
3377 @comment POSIX.1
3378 @deftypevr Macro int O_NOCTTY
3379 If the named file is a terminal device, don't make it the controlling
3380 terminal for the process.  @xref{Job Control}, for information about
3381 what it means to be the controlling terminal.
3383 On @gnuhurdsystems{} and 4.4 BSD, opening a file never makes it the
3384 controlling terminal and @code{O_NOCTTY} is zero.  However, @gnulinuxsystems{}
3385 and some other systems use a nonzero value for @code{O_NOCTTY} and set the
3386 controlling terminal when you open a file that is a terminal device; so
3387 to be portable, use @code{O_NOCTTY} when it is important to avoid this.
3388 @cindex controlling terminal, setting
3389 @end deftypevr
3391 The following three file name translation flags exist only on
3392 @gnuhurdsystems{}.
3394 @comment fcntl.h (optional)
3395 @comment GNU
3396 @deftypevr Macro int O_IGNORE_CTTY
3397 Do not recognize the named file as the controlling terminal, even if it
3398 refers to the process's existing controlling terminal device.  Operations
3399 on the new file descriptor will never induce job control signals.
3400 @xref{Job Control}.
3401 @end deftypevr
3403 @comment fcntl.h (optional)
3404 @comment GNU
3405 @deftypevr Macro int O_NOLINK
3406 If the named file is a symbolic link, open the link itself instead of
3407 the file it refers to.  (@code{fstat} on the new file descriptor will
3408 return the information returned by @code{lstat} on the link's name.)
3409 @cindex symbolic link, opening
3410 @end deftypevr
3412 @comment fcntl.h (optional)
3413 @comment GNU
3414 @deftypevr Macro int O_NOTRANS
3415 If the named file is specially translated, do not invoke the translator.
3416 Open the bare file the translator itself sees.
3417 @end deftypevr
3420 The open-time action flags tell @code{open} to do additional operations
3421 which are not really related to opening the file.  The reason to do them
3422 as part of @code{open} instead of in separate calls is that @code{open}
3423 can do them @i{atomically}.
3425 @comment fcntl.h
3426 @comment POSIX.1
3427 @deftypevr Macro int O_TRUNC
3428 Truncate the file to zero length.  This option is only useful for
3429 regular files, not special files such as directories or FIFOs.  POSIX.1
3430 requires that you open the file for writing to use @code{O_TRUNC}.  In
3431 BSD and GNU you must have permission to write the file to truncate it,
3432 but you need not open for write access.
3434 This is the only open-time action flag specified by POSIX.1.  There is
3435 no good reason for truncation to be done by @code{open}, instead of by
3436 calling @code{ftruncate} afterwards.  The @code{O_TRUNC} flag existed in
3437 Unix before @code{ftruncate} was invented, and is retained for backward
3438 compatibility.
3439 @end deftypevr
3441 The remaining operating modes are BSD extensions.  They exist only
3442 on some systems.  On other systems, these macros are not defined.
3444 @comment fcntl.h (optional)
3445 @comment BSD
3446 @deftypevr Macro int O_SHLOCK
3447 Acquire a shared lock on the file, as with @code{flock}.
3448 @xref{File Locks}.
3450 If @code{O_CREAT} is specified, the locking is done atomically when
3451 creating the file.  You are guaranteed that no other process will get
3452 the lock on the new file first.
3453 @end deftypevr
3455 @comment fcntl.h (optional)
3456 @comment BSD
3457 @deftypevr Macro int O_EXLOCK
3458 Acquire an exclusive lock on the file, as with @code{flock}.
3459 @xref{File Locks}.  This is atomic like @code{O_SHLOCK}.
3460 @end deftypevr
3462 @node Operating Modes
3463 @subsection I/O Operating Modes
3465 The operating modes affect how input and output operations using a file
3466 descriptor work.  These flags are set by @code{open} and can be fetched
3467 and changed with @code{fcntl}.
3469 @comment fcntl.h
3470 @comment POSIX.1
3471 @deftypevr Macro int O_APPEND
3472 The bit that enables append mode for the file.  If set, then all
3473 @code{write} operations write the data at the end of the file, extending
3474 it, regardless of the current file position.  This is the only reliable
3475 way to append to a file.  In append mode, you are guaranteed that the
3476 data you write will always go to the current end of the file, regardless
3477 of other processes writing to the file.  Conversely, if you simply set
3478 the file position to the end of file and write, then another process can
3479 extend the file after you set the file position but before you write,
3480 resulting in your data appearing someplace before the real end of file.
3481 @end deftypevr
3483 @comment fcntl.h
3484 @comment POSIX.1
3485 @deftypevr Macro int O_NONBLOCK
3486 The bit that enables nonblocking mode for the file.  If this bit is set,
3487 @code{read} requests on the file can return immediately with a failure
3488 status if there is no input immediately available, instead of blocking.
3489 Likewise, @code{write} requests can also return immediately with a
3490 failure status if the output can't be written immediately.
3492 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
3493 operating mode and a file name translation flag; @pxref{Open-time Flags}.
3494 @end deftypevr
3496 @comment fcntl.h
3497 @comment BSD
3498 @deftypevr Macro int O_NDELAY
3499 This is an obsolete name for @code{O_NONBLOCK}, provided for
3500 compatibility with BSD.  It is not defined by the POSIX.1 standard.
3501 @end deftypevr
3503 The remaining operating modes are BSD and GNU extensions.  They exist only
3504 on some systems.  On other systems, these macros are not defined.
3506 @comment fcntl.h
3507 @comment BSD
3508 @deftypevr Macro int O_ASYNC
3509 The bit that enables asynchronous input mode.  If set, then @code{SIGIO}
3510 signals will be generated when input is available.  @xref{Interrupt Input}.
3512 Asynchronous input mode is a BSD feature.
3513 @end deftypevr
3515 @comment fcntl.h
3516 @comment BSD
3517 @deftypevr Macro int O_FSYNC
3518 The bit that enables synchronous writing for the file.  If set, each
3519 @code{write} call will make sure the data is reliably stored on disk before
3520 returning. @c !!! xref fsync
3522 Synchronous writing is a BSD feature.
3523 @end deftypevr
3525 @comment fcntl.h
3526 @comment BSD
3527 @deftypevr Macro int O_SYNC
3528 This is another name for @code{O_FSYNC}.  They have the same value.
3529 @end deftypevr
3531 @comment fcntl.h
3532 @comment GNU
3533 @deftypevr Macro int O_NOATIME
3534 If this bit is set, @code{read} will not update the access time of the
3535 file.  @xref{File Times}.  This is used by programs that do backups, so
3536 that backing a file up does not count as reading it.
3537 Only the owner of the file or the superuser may use this bit.
3539 This is a GNU extension.
3540 @end deftypevr
3542 @node Getting File Status Flags
3543 @subsection Getting and Setting File Status Flags
3545 The @code{fcntl} function can fetch or change file status flags.
3547 @comment fcntl.h
3548 @comment POSIX.1
3549 @deftypevr Macro int F_GETFL
3550 This macro is used as the @var{command} argument to @code{fcntl}, to
3551 read the file status flags for the open file with descriptor
3552 @var{filedes}.
3554 The normal return value from @code{fcntl} with this command is a
3555 nonnegative number which can be interpreted as the bitwise OR of the
3556 individual flags.  Since the file access modes are not single-bit values,
3557 you can mask off other bits in the returned flags with @code{O_ACCMODE}
3558 to compare them.
3560 In case of an error, @code{fcntl} returns @math{-1}.  The following
3561 @code{errno} error conditions are defined for this command:
3563 @table @code
3564 @item EBADF
3565 The @var{filedes} argument is invalid.
3566 @end table
3567 @end deftypevr
3569 @comment fcntl.h
3570 @comment POSIX.1
3571 @deftypevr Macro int F_SETFL
3572 This macro is used as the @var{command} argument to @code{fcntl}, to set
3573 the file status flags for the open file corresponding to the
3574 @var{filedes} argument.  This command requires a third @code{int}
3575 argument to specify the new flags, so the call looks like this:
3577 @smallexample
3578 fcntl (@var{filedes}, F_SETFL, @var{new-flags})
3579 @end smallexample
3581 You can't change the access mode for the file in this way; that is,
3582 whether the file descriptor was opened for reading or writing.
3584 The normal return value from @code{fcntl} with this command is an
3585 unspecified value other than @math{-1}, which indicates an error.  The
3586 error conditions are the same as for the @code{F_GETFL} command.
3587 @end deftypevr
3589 If you want to modify the file status flags, you should get the current
3590 flags with @code{F_GETFL} and modify the value.  Don't assume that the
3591 flags listed here are the only ones that are implemented; your program
3592 may be run years from now and more flags may exist then.  For example,
3593 here is a function to set or clear the flag @code{O_NONBLOCK} without
3594 altering any other flags:
3596 @smallexample
3597 @group
3598 /* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
3599    @r{or clear the flag if @var{value} is 0.}
3600    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
3603 set_nonblock_flag (int desc, int value)
3605   int oldflags = fcntl (desc, F_GETFL, 0);
3606   /* @r{If reading the flags failed, return error indication now.} */
3607   if (oldflags == -1)
3608     return -1;
3609   /* @r{Set just the flag we want to set.} */
3610   if (value != 0)
3611     oldflags |= O_NONBLOCK;
3612   else
3613     oldflags &= ~O_NONBLOCK;
3614   /* @r{Store modified flag word in the descriptor.} */
3615   return fcntl (desc, F_SETFL, oldflags);
3617 @end group
3618 @end smallexample
3620 @node File Locks
3621 @section File Locks
3623 @cindex file locks
3624 @cindex record locking
3625 This section describes record locks that are associated with the process.
3626 There is also a different type of record lock that is associated with the
3627 open file description instead of the process.  @xref{Open File Description Locks}.
3629 The remaining @code{fcntl} commands are used to support @dfn{record
3630 locking}, which permits multiple cooperating programs to prevent each
3631 other from simultaneously accessing parts of a file in error-prone
3632 ways.
3634 @cindex exclusive lock
3635 @cindex write lock
3636 An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
3637 for writing to the specified part of the file.  While a write lock is in
3638 place, no other process can lock that part of the file.
3640 @cindex shared lock
3641 @cindex read lock
3642 A @dfn{shared} or @dfn{read} lock prohibits any other process from
3643 requesting a write lock on the specified part of the file.  However,
3644 other processes can request read locks.
3646 The @code{read} and @code{write} functions do not actually check to see
3647 whether there are any locks in place.  If you want to implement a
3648 locking protocol for a file shared by multiple processes, your application
3649 must do explicit @code{fcntl} calls to request and clear locks at the
3650 appropriate points.
3652 Locks are associated with processes.  A process can only have one kind
3653 of lock set for each byte of a given file.  When any file descriptor for
3654 that file is closed by the process, all of the locks that process holds
3655 on that file are released, even if the locks were made using other
3656 descriptors that remain open.  Likewise, locks are released when a
3657 process exits, and are not inherited by child processes created using
3658 @code{fork} (@pxref{Creating a Process}).
3660 When making a lock, use a @code{struct flock} to specify what kind of
3661 lock and where.  This data type and the associated macros for the
3662 @code{fcntl} function are declared in the header file @file{fcntl.h}.
3663 @pindex fcntl.h
3665 @comment fcntl.h
3666 @comment POSIX.1
3667 @deftp {Data Type} {struct flock}
3668 This structure is used with the @code{fcntl} function to describe a file
3669 lock.  It has these members:
3671 @table @code
3672 @item short int l_type
3673 Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
3674 @code{F_UNLCK}.
3676 @item short int l_whence
3677 This corresponds to the @var{whence} argument to @code{fseek} or
3678 @code{lseek}, and specifies what the offset is relative to.  Its value
3679 can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
3681 @item off_t l_start
3682 This specifies the offset of the start of the region to which the lock
3683 applies, and is given in bytes relative to the point specified by
3684 @code{l_whence} member.
3686 @item off_t l_len
3687 This specifies the length of the region to be locked.  A value of
3688 @code{0} is treated specially; it means the region extends to the end of
3689 the file.
3691 @item pid_t l_pid
3692 This field is the process ID (@pxref{Process Creation Concepts}) of the
3693 process holding the lock.  It is filled in by calling @code{fcntl} with
3694 the @code{F_GETLK} command, but is ignored when making a lock.  If the
3695 conflicting lock is an open file description lock
3696 (@pxref{Open File Description Locks}), then this field will be set to
3697 @math{-1}.
3698 @end table
3699 @end deftp
3701 @comment fcntl.h
3702 @comment POSIX.1
3703 @deftypevr Macro int F_GETLK
3704 This macro is used as the @var{command} argument to @code{fcntl}, to
3705 specify that it should get information about a lock.  This command
3706 requires a third argument of type @w{@code{struct flock *}} to be passed
3707 to @code{fcntl}, so that the form of the call is:
3709 @smallexample
3710 fcntl (@var{filedes}, F_GETLK, @var{lockp})
3711 @end smallexample
3713 If there is a lock already in place that would block the lock described
3714 by the @var{lockp} argument, information about that lock overwrites
3715 @code{*@var{lockp}}.  Existing locks are not reported if they are
3716 compatible with making a new lock as specified.  Thus, you should
3717 specify a lock type of @code{F_WRLCK} if you want to find out about both
3718 read and write locks, or @code{F_RDLCK} if you want to find out about
3719 write locks only.
3721 There might be more than one lock affecting the region specified by the
3722 @var{lockp} argument, but @code{fcntl} only returns information about
3723 one of them.  The @code{l_whence} member of the @var{lockp} structure is
3724 set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
3725 set to identify the locked region.
3727 If no lock applies, the only change to the @var{lockp} structure is to
3728 update the @code{l_type} to a value of @code{F_UNLCK}.
3730 The normal return value from @code{fcntl} with this command is an
3731 unspecified value other than @math{-1}, which is reserved to indicate an
3732 error.  The following @code{errno} error conditions are defined for
3733 this command:
3735 @table @code
3736 @item EBADF
3737 The @var{filedes} argument is invalid.
3739 @item EINVAL
3740 Either the @var{lockp} argument doesn't specify valid lock information,
3741 or the file associated with @var{filedes} doesn't support locks.
3742 @end table
3743 @end deftypevr
3745 @comment fcntl.h
3746 @comment POSIX.1
3747 @deftypevr Macro int F_SETLK
3748 This macro is used as the @var{command} argument to @code{fcntl}, to
3749 specify that it should set or clear a lock.  This command requires a
3750 third argument of type @w{@code{struct flock *}} to be passed to
3751 @code{fcntl}, so that the form of the call is:
3753 @smallexample
3754 fcntl (@var{filedes}, F_SETLK, @var{lockp})
3755 @end smallexample
3757 If the process already has a lock on any part of the region, the old lock
3758 on that part is replaced with the new lock.  You can remove a lock
3759 by specifying a lock type of @code{F_UNLCK}.
3761 If the lock cannot be set, @code{fcntl} returns immediately with a value
3762 of @math{-1}.  This function does not block waiting for other processes
3763 to release locks.  If @code{fcntl} succeeds, it return a value other
3764 than @math{-1}.
3766 The following @code{errno} error conditions are defined for this
3767 function:
3769 @table @code
3770 @item EAGAIN
3771 @itemx EACCES
3772 The lock cannot be set because it is blocked by an existing lock on the
3773 file.  Some systems use @code{EAGAIN} in this case, and other systems
3774 use @code{EACCES}; your program should treat them alike, after
3775 @code{F_SETLK}.  (@gnulinuxhurdsystems{} always use @code{EAGAIN}.)
3777 @item EBADF
3778 Either: the @var{filedes} argument is invalid; you requested a read lock
3779 but the @var{filedes} is not open for read access; or, you requested a
3780 write lock but the @var{filedes} is not open for write access.
3782 @item EINVAL
3783 Either the @var{lockp} argument doesn't specify valid lock information,
3784 or the file associated with @var{filedes} doesn't support locks.
3786 @item ENOLCK
3787 The system has run out of file lock resources; there are already too
3788 many file locks in place.
3790 Well-designed file systems never report this error, because they have no
3791 limitation on the number of locks.  However, you must still take account
3792 of the possibility of this error, as it could result from network access
3793 to a file system on another machine.
3794 @end table
3795 @end deftypevr
3797 @comment fcntl.h
3798 @comment POSIX.1
3799 @deftypevr Macro int F_SETLKW
3800 This macro is used as the @var{command} argument to @code{fcntl}, to
3801 specify that it should set or clear a lock.  It is just like the
3802 @code{F_SETLK} command, but causes the process to block (or wait)
3803 until the request can be specified.
3805 This command requires a third argument of type @code{struct flock *}, as
3806 for the @code{F_SETLK} command.
3808 The @code{fcntl} return values and errors are the same as for the
3809 @code{F_SETLK} command, but these additional @code{errno} error conditions
3810 are defined for this command:
3812 @table @code
3813 @item EINTR
3814 The function was interrupted by a signal while it was waiting.
3815 @xref{Interrupted Primitives}.
3817 @item EDEADLK
3818 The specified region is being locked by another process.  But that
3819 process is waiting to lock a region which the current process has
3820 locked, so waiting for the lock would result in deadlock.  The system
3821 does not guarantee that it will detect all such conditions, but it lets
3822 you know if it notices one.
3823 @end table
3824 @end deftypevr
3827 The following macros are defined for use as values for the @code{l_type}
3828 member of the @code{flock} structure.  The values are integer constants.
3830 @table @code
3831 @comment fcntl.h
3832 @comment POSIX.1
3833 @vindex F_RDLCK
3834 @item F_RDLCK
3835 This macro is used to specify a read (or shared) lock.
3837 @comment fcntl.h
3838 @comment POSIX.1
3839 @vindex F_WRLCK
3840 @item F_WRLCK
3841 This macro is used to specify a write (or exclusive) lock.
3843 @comment fcntl.h
3844 @comment POSIX.1
3845 @vindex F_UNLCK
3846 @item F_UNLCK
3847 This macro is used to specify that the region is unlocked.
3848 @end table
3850 As an example of a situation where file locking is useful, consider a
3851 program that can be run simultaneously by several different users, that
3852 logs status information to a common file.  One example of such a program
3853 might be a game that uses a file to keep track of high scores.  Another
3854 example might be a program that records usage or accounting information
3855 for billing purposes.
3857 Having multiple copies of the program simultaneously writing to the
3858 file could cause the contents of the file to become mixed up.  But
3859 you can prevent this kind of problem by setting a write lock on the
3860 file before actually writing to the file.
3862 If the program also needs to read the file and wants to make sure that
3863 the contents of the file are in a consistent state, then it can also use
3864 a read lock.  While the read lock is set, no other process can lock
3865 that part of the file for writing.
3867 @c ??? This section could use an example program.
3869 Remember that file locks are only an @emph{advisory} protocol for
3870 controlling access to a file.  There is still potential for access to
3871 the file by programs that don't use the lock protocol.
3873 @node Open File Description Locks
3874 @section Open File Description Locks
3876 In contrast to process-associated record locks (@pxref{File Locks}),
3877 open file description record locks are associated with an open file
3878 description rather than a process.
3880 Using @code{fcntl} to apply an open file description lock on a region that
3881 already has an existing open file description lock that was created via the
3882 same file descriptor will never cause a lock conflict.
3884 Open file description locks are also inherited by child processes across
3885 @code{fork}, or @code{clone} with @code{CLONE_FILES} set
3886 (@pxref{Creating a Process}), along with the file descriptor.
3888 It is important to distinguish between the open file @emph{description} (an
3889 instance of an open file, usually created by a call to @code{open}) and
3890 an open file @emph{descriptor}, which is a numeric value that refers to the
3891 open file description.  The locks described here are associated with the
3892 open file @emph{description} and not the open file @emph{descriptor}.
3894 Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file
3895 descriptor does not give you a new open file description, but rather copies a
3896 reference to an existing open file description and assigns it to a new
3897 file descriptor.  Thus, open file description locks set on a file
3898 descriptor cloned by @code{dup} will never conflict with open file
3899 description locks set on the original descriptor since they refer to the
3900 same open file description.  Depending on the range and type of lock
3901 involved, the original lock may be modified by a @code{F_OFD_SETLK} or
3902 @code{F_OFD_SETLKW} command in this situation however.
3904 Open file description locks always conflict with process-associated locks,
3905 even if acquired by the same process or on the same open file
3906 descriptor.
3908 Open file description locks use the same @code{struct flock} as
3909 process-associated locks as an argument (@pxref{File Locks}) and the
3910 macros for the @code{command} values are also declared in the header file
3911 @file{fcntl.h}. To use them, the macro @code{_GNU_SOURCE} must be
3912 defined prior to including any header file.
3914 In contrast to process-associated locks, any @code{struct flock} used as
3915 an argument to open file description lock commands must have the @code{l_pid}
3916 value set to @math{0}.  Also, when returning information about an
3917 open file description lock in a @code{F_GETLK} or @code{F_OFD_GETLK} request,
3918 the @code{l_pid} field in @code{struct flock} will be set to @math{-1}
3919 to indicate that the lock is not associated with a process.
3921 When the same @code{struct flock} is reused as an argument to a
3922 @code{F_OFD_SETLK} or @code{F_OFD_SETLKW} request after being used for an
3923 @code{F_OFD_GETLK} request, it is necessary to inspect and reset the
3924 @code{l_pid} field to @math{0}.
3926 @pindex fcntl.h.
3928 @deftypevr Macro int F_OFD_GETLK
3929 This macro is used as the @var{command} argument to @code{fcntl}, to
3930 specify that it should get information about a lock.  This command
3931 requires a third argument of type @w{@code{struct flock *}} to be passed
3932 to @code{fcntl}, so that the form of the call is:
3934 @smallexample
3935 fcntl (@var{filedes}, F_OFD_GETLK, @var{lockp})
3936 @end smallexample
3938 If there is a lock already in place that would block the lock described
3939 by the @var{lockp} argument, information about that lock is written to
3940 @code{*@var{lockp}}.  Existing locks are not reported if they are
3941 compatible with making a new lock as specified.  Thus, you should
3942 specify a lock type of @code{F_WRLCK} if you want to find out about both
3943 read and write locks, or @code{F_RDLCK} if you want to find out about
3944 write locks only.
3946 There might be more than one lock affecting the region specified by the
3947 @var{lockp} argument, but @code{fcntl} only returns information about
3948 one of them. Which lock is returned in this situation is undefined.
3950 The @code{l_whence} member of the @var{lockp} structure are set to
3951 @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields are set
3952 to identify the locked region.
3954 If no conflicting lock exists, the only change to the @var{lockp} structure
3955 is to update the @code{l_type} field to the value @code{F_UNLCK}.
3957 The normal return value from @code{fcntl} with this command is either @math{0}
3958 on success or @math{-1}, which indicates an error. The following @code{errno}
3959 error conditions are defined for this command:
3961 @table @code
3962 @item EBADF
3963 The @var{filedes} argument is invalid.
3965 @item EINVAL
3966 Either the @var{lockp} argument doesn't specify valid lock information,
3967 the operating system kernel doesn't support open file description locks, or the file
3968 associated with @var{filedes} doesn't support locks.
3969 @end table
3970 @end deftypevr
3972 @comment fcntl.h
3973 @comment POSIX.1
3974 @deftypevr Macro int F_OFD_SETLK
3975 This macro is used as the @var{command} argument to @code{fcntl}, to
3976 specify that it should set or clear a lock.  This command requires a
3977 third argument of type @w{@code{struct flock *}} to be passed to
3978 @code{fcntl}, so that the form of the call is:
3980 @smallexample
3981 fcntl (@var{filedes}, F_OFD_SETLK, @var{lockp})
3982 @end smallexample
3984 If the open file already has a lock on any part of the
3985 region, the old lock on that part is replaced with the new lock.  You
3986 can remove a lock by specifying a lock type of @code{F_UNLCK}.
3988 If the lock cannot be set, @code{fcntl} returns immediately with a value
3989 of @math{-1}.  This command does not wait for other tasks
3990 to release locks.  If @code{fcntl} succeeds, it returns @math{0}.
3992 The following @code{errno} error conditions are defined for this
3993 command:
3995 @table @code
3996 @item EAGAIN
3997 The lock cannot be set because it is blocked by an existing lock on the
3998 file.
4000 @item EBADF
4001 Either: the @var{filedes} argument is invalid; you requested a read lock
4002 but the @var{filedes} is not open for read access; or, you requested a
4003 write lock but the @var{filedes} is not open for write access.
4005 @item EINVAL
4006 Either the @var{lockp} argument doesn't specify valid lock information,
4007 the operating system kernel doesn't support open file description locks, or the
4008 file associated with @var{filedes} doesn't support locks.
4010 @item ENOLCK
4011 The system has run out of file lock resources; there are already too
4012 many file locks in place.
4014 Well-designed file systems never report this error, because they have no
4015 limitation on the number of locks.  However, you must still take account
4016 of the possibility of this error, as it could result from network access
4017 to a file system on another machine.
4018 @end table
4019 @end deftypevr
4021 @comment fcntl.h
4022 @comment POSIX.1
4023 @deftypevr Macro int F_OFD_SETLKW
4024 This macro is used as the @var{command} argument to @code{fcntl}, to
4025 specify that it should set or clear a lock.  It is just like the
4026 @code{F_OFD_SETLK} command, but causes the process to wait until the request
4027 can be completed.
4029 This command requires a third argument of type @code{struct flock *}, as
4030 for the @code{F_OFD_SETLK} command.
4032 The @code{fcntl} return values and errors are the same as for the
4033 @code{F_OFD_SETLK} command, but these additional @code{errno} error conditions
4034 are defined for this command:
4036 @table @code
4037 @item EINTR
4038 The function was interrupted by a signal while it was waiting.
4039 @xref{Interrupted Primitives}.
4041 @end table
4042 @end deftypevr
4044 Open file description locks are useful in the same sorts of situations as
4045 process-associated locks. They can also be used to synchronize file
4046 access between threads within the same process by having each thread perform
4047 its own @code{open} of the file, to obtain its own open file description.
4049 Because open file description locks are automatically freed only upon
4050 closing the last file descriptor that refers to the open file
4051 description, this locking mechanism avoids the possibility that locks
4052 are inadvertently released due to a library routine opening and closing
4053 a file without the application being aware.
4055 As with process-associated locks, open file description locks are advisory.
4057 @node Open File Description Locks Example
4058 @section Open File Description Locks Example
4060 Here is an example of using open file description locks in a threaded
4061 program. If this program used process-associated locks, then it would be
4062 subject to data corruption because process-associated locks are shared
4063 by the threads inside a process, and thus cannot be used by one thread
4064 to lock out another thread in the same process.
4066 Proper error handling has been omitted in the following program for
4067 brevity.
4069 @smallexample
4070 @include ofdlocks.c.texi
4071 @end smallexample
4073 This example creates three threads each of which loops five times,
4074 appending to the file.  Access to the file is serialized via open file
4075 description locks. If we compile and run the above program, we'll end up
4076 with /tmp/foo that has 15 lines in it.
4078 If we, however, were to replace the @code{F_OFD_SETLK} and
4079 @code{F_OFD_SETLKW} commands with their process-associated lock
4080 equivalents, the locking essentially becomes a noop since it is all done
4081 within the context of the same process. That leads to data corruption
4082 (typically manifested as missing lines) as some threads race in and
4083 overwrite the data written by others.
4085 @node Interrupt Input
4086 @section Interrupt-Driven Input
4088 @cindex interrupt-driven input
4089 If you set the @code{O_ASYNC} status flag on a file descriptor
4090 (@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
4091 input or output becomes possible on that file descriptor.  The process
4092 or process group to receive the signal can be selected by using the
4093 @code{F_SETOWN} command to the @code{fcntl} function.  If the file
4094 descriptor is a socket, this also selects the recipient of @code{SIGURG}
4095 signals that are delivered when out-of-band data arrives on that socket;
4096 see @ref{Out-of-Band Data}.  (@code{SIGURG} is sent in any situation
4097 where @code{select} would report the socket as having an ``exceptional
4098 condition''.  @xref{Waiting for I/O}.)
4100 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
4101 signals are sent to the foreground process group of the terminal.
4102 @xref{Job Control}.
4104 @pindex fcntl.h
4105 The symbols in this section are defined in the header file
4106 @file{fcntl.h}.
4108 @comment fcntl.h
4109 @comment BSD
4110 @deftypevr Macro int F_GETOWN
4111 This macro is used as the @var{command} argument to @code{fcntl}, to
4112 specify that it should get information about the process or process
4113 group to which @code{SIGIO} signals are sent.  (For a terminal, this is
4114 actually the foreground process group ID, which you can get using
4115 @code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
4117 The return value is interpreted as a process ID; if negative, its
4118 absolute value is the process group ID.
4120 The following @code{errno} error condition is defined for this command:
4122 @table @code
4123 @item EBADF
4124 The @var{filedes} argument is invalid.
4125 @end table
4126 @end deftypevr
4128 @comment fcntl.h
4129 @comment BSD
4130 @deftypevr Macro int F_SETOWN
4131 This macro is used as the @var{command} argument to @code{fcntl}, to
4132 specify that it should set the process or process group to which
4133 @code{SIGIO} signals are sent.  This command requires a third argument
4134 of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
4135 the call is:
4137 @smallexample
4138 fcntl (@var{filedes}, F_SETOWN, @var{pid})
4139 @end smallexample
4141 The @var{pid} argument should be a process ID.  You can also pass a
4142 negative number whose absolute value is a process group ID.
4144 The return value from @code{fcntl} with this command is @math{-1}
4145 in case of error and some other value if successful.  The following
4146 @code{errno} error conditions are defined for this command:
4148 @table @code
4149 @item EBADF
4150 The @var{filedes} argument is invalid.
4152 @item ESRCH
4153 There is no process or process group corresponding to @var{pid}.
4154 @end table
4155 @end deftypevr
4157 @c ??? This section could use an example program.
4159 @node IOCTLs
4160 @section Generic I/O Control operations
4161 @cindex generic i/o control operations
4162 @cindex IOCTLs
4164 @gnusystems{} can handle most input/output operations on many different
4165 devices and objects in terms of a few file primitives - @code{read},
4166 @code{write} and @code{lseek}.  However, most devices also have a few
4167 peculiar operations which do not fit into this model.  Such as:
4169 @itemize @bullet
4171 @item
4172 Changing the character font used on a terminal.
4174 @item
4175 Telling a magnetic tape system to rewind or fast forward.  (Since they
4176 cannot move in byte increments, @code{lseek} is inapplicable).
4178 @item
4179 Ejecting a disk from a drive.
4181 @item
4182 Playing an audio track from a CD-ROM drive.
4184 @item
4185 Maintaining routing tables for a network.
4187 @end itemize
4189 Although some such objects such as sockets and terminals
4190 @footnote{Actually, the terminal-specific functions are implemented with
4191 IOCTLs on many platforms.} have special functions of their own, it would
4192 not be practical to create functions for all these cases.
4194 Instead these minor operations, known as @dfn{IOCTL}s, are assigned code
4195 numbers and multiplexed through the @code{ioctl} function, defined in
4196 @code{sys/ioctl.h}.  The code numbers themselves are defined in many
4197 different headers.
4199 @comment sys/ioctl.h
4200 @comment BSD
4201 @deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{})
4202 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4204 The @code{ioctl} function performs the generic I/O operation
4205 @var{command} on @var{filedes}.
4207 A third argument is usually present, either a single number or a pointer
4208 to a structure.  The meaning of this argument, the returned value, and
4209 any error codes depends upon the command used.  Often @math{-1} is
4210 returned for a failure.
4212 @end deftypefun
4214 On some systems, IOCTLs used by different devices share the same numbers.
4215 Thus, although use of an inappropriate IOCTL @emph{usually} only produces
4216 an error, you should not attempt to use device-specific IOCTLs on an
4217 unknown device.
4219 Most IOCTLs are OS-specific and/or only used in special system utilities,
4220 and are thus beyond the scope of this document.  For an example of the use
4221 of an IOCTL, see @ref{Out-of-Band Data}.
4223 @c FIXME this is undocumented:
4224 @c dup3