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:
17 For reading binary files in large chunks.
20 For reading an entire file into core before parsing it.
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.)
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
34 * Opening and Closing Files:: How to open and close file
36 * I/O Primitives:: Reading and writing data.
37 * File Position Primitive:: Setting a descriptor's file
39 * Descriptors and Streams:: Converting descriptor to stream
41 * Stream/Descriptor Precautions:: Precautions needed if you use both
42 descriptors and streams.
43 * Scatter-Gather:: Fast I/O to discontinuous buffers.
44 * Copying File Data:: Copying data between files.
45 * Memory-mapped I/O:: Using files like memory.
46 * Waiting for I/O:: How to check for input or output
47 on multiple file descriptors.
48 * Synchronizing I/O:: Making sure all I/O actions completed.
49 * Asynchronous I/O:: Perform I/O in parallel.
50 * Control Operations:: Various other operations on file
52 * Duplicating Descriptors:: Fcntl commands for duplicating
54 * Descriptor Flags:: Fcntl commands for manipulating
55 flags associated with file
57 * File Status Flags:: Fcntl commands for manipulating
58 flags associated with open files.
59 * File Locks:: Fcntl commands for implementing
61 * Open File Description Locks:: Fcntl commands for implementing
62 open file description locking.
63 * Open File Description Locks Example:: An example of open file description lock
65 * Interrupt Input:: Getting an asynchronous signal when
67 * IOCTLs:: Generic I/O Control operations.
71 @node Opening and Closing Files
72 @section Opening and Closing Files
74 @cindex opening a file descriptor
75 @cindex closing a file descriptor
76 This section describes the primitives for opening and closing files
77 using file descriptors. The @code{open} and @code{creat} functions are
78 declared in the header file @file{fcntl.h}, while @code{close} is
79 declared in @file{unistd.h}.
83 @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
84 @standards{POSIX.1, fcntl.h}
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
105 The file exists but is not readable/writable as requested by the @var{flags}
106 argument, or the file does not exist and the directory is unwritable so
107 it cannot be created.
110 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
114 The @code{open} operation was interrupted by a signal.
115 @xref{Interrupted Primitives}.
118 The @var{flags} argument specified write access, and the file is a directory.
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}.
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{}.)
131 The named file does not exist, and @code{O_CREAT} is not specified.
134 The directory or file system that would contain the new file cannot be
135 extended, because there is no disk space left.
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.
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.
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 low-level 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.
169 @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
170 @standards{Unix98, fcntl.h}
171 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
172 This function is similar to @code{open}. It returns a file descriptor
173 which can be used to access the file named by @var{filename}. The only
174 difference is that on 32 bit systems the file is opened in the
175 large file mode. I.e., file length and file offsets can exceed 31 bits.
177 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
178 function is actually available under the name @code{open}. I.e., the
179 new, extended API using 64 bit file sizes and offsets transparently
180 replaces the old API.
183 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
184 @standards{POSIX.1, fcntl.h}
185 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
186 This function is obsolete. The call:
189 creat (@var{filename}, @var{mode})
196 open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
199 If on a 32 bit machine the sources are translated with
200 @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file
201 descriptor opened in the large file mode which enables the file handling
202 functions to use files up to @twoexp{63} in size and offset from
203 @minus{}@twoexp{63} to @twoexp{63}. This happens transparently for the user
204 since all of the low-level file handling functions are equally replaced.
207 @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode})
208 @standards{Unix98, fcntl.h}
209 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
210 This function is similar to @code{creat}. It returns a file descriptor
211 which can be used to access the file named by @var{filename}. The only
212 difference is that on 32 bit systems the file is opened in the
213 large file mode. I.e., file length and file offsets can exceed 31 bits.
215 To use this file descriptor one must not use the normal operations but
216 instead the counterparts named @code{*64}, e.g., @code{read64}.
218 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
219 function is actually available under the name @code{open}. I.e., the
220 new, extended API using 64 bit file sizes and offsets transparently
221 replaces the old API.
224 @deftypefun int close (int @var{filedes})
225 @standards{POSIX.1, unistd.h}
226 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
227 The function @code{close} closes the file descriptor @var{filedes}.
228 Closing a file has the following consequences:
232 The file descriptor is deallocated.
235 Any record locks owned by the process on the file are unlocked.
238 When all file descriptors associated with a pipe or FIFO have been closed,
239 any unread data is discarded.
242 This function is a cancellation point in multi-threaded programs. This
243 is a problem if the thread allocates some resources (like memory, file
244 descriptors, semaphores or whatever) at the time @code{close} is
245 called. If the thread gets canceled these resources stay allocated
246 until the program ends. To avoid this, calls to @code{close} should be
247 protected using cancellation handlers.
248 @c ref pthread_cleanup_push / pthread_cleanup_pop
250 The normal return value from @code{close} is @math{0}; a value of @math{-1}
251 is returned in case of failure. The following @code{errno} error
252 conditions are defined for this function:
256 The @var{filedes} argument is not a valid file descriptor.
259 The @code{close} call was interrupted by a signal.
260 @xref{Interrupted Primitives}.
261 Here is an example of how to handle @code{EINTR} properly:
264 TEMP_FAILURE_RETRY (close (desc));
270 When the file is accessed by NFS, these errors from @code{write} can sometimes
271 not be detected until @code{close}. @xref{I/O Primitives}, for details
275 Please note that there is @emph{no} separate @code{close64} function.
276 This is not necessary since this function does not determine nor depend
277 on the mode of the file. The kernel which performs the @code{close}
278 operation knows which mode the descriptor is used for and can handle
282 To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
283 of trying to close its underlying file descriptor with @code{close}.
284 This flushes any buffered output and updates the stream object to
285 indicate that it is closed.
288 @section Input and Output Primitives
290 This section describes the functions for performing primitive input and
291 output operations on file descriptors: @code{read}, @code{write}, and
292 @code{lseek}. These functions are declared in the header file
296 @deftp {Data Type} ssize_t
297 @standards{POSIX.1, unistd.h}
298 This data type is used to represent the sizes of blocks that can be
299 read or written in a single operation. It is similar to @code{size_t},
300 but must be a signed type.
303 @cindex reading from a file descriptor
304 @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
305 @standards{POSIX.1, unistd.h}
306 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
307 The @code{read} function reads up to @var{size} bytes from the file
308 with descriptor @var{filedes}, storing the results in the @var{buffer}.
309 (This is not necessarily a character string, and no terminating null
312 @cindex end-of-file, on a file descriptor
313 The return value is the number of bytes actually read. This might be
314 less than @var{size}; for example, if there aren't that many bytes left
315 in the file or if there aren't that many bytes immediately available.
316 The exact behavior depends on what kind of file it is. Note that
317 reading less than @var{size} bytes is not an error.
319 A value of zero indicates end-of-file (except if the value of the
320 @var{size} argument is also zero). This is not considered an error.
321 If you keep calling @code{read} while at end-of-file, it will keep
322 returning zero and doing nothing else.
324 If @code{read} returns at least one character, there is no way you can
325 tell whether end-of-file was reached. But if you did reach the end, the
326 next read will return zero.
328 In case of an error, @code{read} returns @math{-1}. The following
329 @code{errno} error conditions are defined for this function:
333 Normally, when no input is immediately available, @code{read} waits for
334 some input. But if the @code{O_NONBLOCK} flag is set for the file
335 (@pxref{File Status Flags}), @code{read} returns immediately without
336 reading any data, and reports this error.
338 @strong{Compatibility Note:} Most versions of BSD Unix use a different
339 error code for this: @code{EWOULDBLOCK}. In @theglibc{},
340 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
343 On some systems, reading a large amount of data from a character special
344 file can also fail with @code{EAGAIN} if the kernel cannot find enough
345 physical memory to lock down the user's pages. This is limited to
346 devices that transfer with direct memory access into the user's memory,
347 which means it does not include terminals, since they always use
348 separate buffers inside the kernel. This problem never happens on
351 Any condition that could result in @code{EAGAIN} can instead result in a
352 successful @code{read} which returns fewer bytes than requested.
353 Calling @code{read} again immediately would result in @code{EAGAIN}.
356 The @var{filedes} argument is not a valid file descriptor,
357 or is not open for reading.
360 @code{read} was interrupted by a signal while it was waiting for input.
361 @xref{Interrupted Primitives}. A signal will not necessarily cause
362 @code{read} to return @code{EINTR}; it may instead result in a
363 successful @code{read} which returns fewer bytes than requested.
366 For many devices, and for disk files, this error code indicates
369 @code{EIO} also occurs when a background process tries to read from the
370 controlling terminal, and the normal action of stopping the process by
371 sending it a @code{SIGTTIN} signal isn't working. This might happen if
372 the signal is being blocked or ignored, or because the process group is
373 orphaned. @xref{Job Control}, for more information about job control,
374 and @ref{Signal Handling}, for information about signals.
377 In some systems, when reading from a character or block device, position
378 and size offsets must be aligned to a particular block size. This error
379 indicates that the offsets were not properly aligned.
382 Please note that there is no function named @code{read64}. This is not
383 necessary since this function does not directly modify or handle the
384 possibly wide file offset. Since the kernel handles this state
385 internally, the @code{read} function can be used for all cases.
387 This function is a cancellation point in multi-threaded programs. This
388 is a problem if the thread allocates some resources (like memory, file
389 descriptors, semaphores or whatever) at the time @code{read} is
390 called. If the thread gets canceled these resources stay allocated
391 until the program ends. To avoid this, calls to @code{read} should be
392 protected using cancellation handlers.
393 @c ref pthread_cleanup_push / pthread_cleanup_pop
395 The @code{read} function is the underlying primitive for all of the
396 functions that read from streams, such as @code{fgetc}.
399 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
400 @standards{Unix98, unistd.h}
401 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
402 @c This is usually a safe syscall. The sysdeps/posix fallback emulation
403 @c is not MT-Safe because it uses lseek, read and lseek back, but is it
405 The @code{pread} function is similar to the @code{read} function. The
406 first three arguments are identical, and the return values and error
407 codes also correspond.
409 The difference is the fourth argument and its handling. The data block
410 is not read from the current position of the file descriptor
411 @code{filedes}. Instead the data is read from the file starting at
412 position @var{offset}. The position of the file descriptor itself is
413 not affected by the operation. The value is the same as before the call.
415 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
416 @code{pread} function is in fact @code{pread64} and the type
417 @code{off_t} has 64 bits, which makes it possible to handle files up to
418 @twoexp{63} bytes in length.
420 The return value of @code{pread} describes the number of bytes read.
421 In the error case it returns @math{-1} like @code{read} does and the
422 error codes are also the same, with these additions:
426 The value given for @var{offset} is negative and therefore illegal.
429 The file descriptor @var{filedes} is associated with a pipe or a FIFO and
430 this device does not allow positioning of the file pointer.
433 The function is an extension defined in the Unix Single Specification
437 @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
438 @standards{Unix98, unistd.h}
439 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
440 @c This is usually a safe syscall. The sysdeps/posix fallback emulation
441 @c is not MT-Safe because it uses lseek64, read and lseek64 back, but is
443 This function is similar to the @code{pread} function. The difference
444 is that the @var{offset} parameter is of type @code{off64_t} instead of
445 @code{off_t} which makes it possible on 32 bit machines to address
446 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
447 file descriptor @code{filedes} must be opened using @code{open64} since
448 otherwise the large offsets possible with @code{off64_t} will lead to
449 errors with a descriptor in small file mode.
451 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
452 32 bit machine this function is actually available under the name
453 @code{pread} and so transparently replaces the 32 bit interface.
456 @cindex writing to a file descriptor
457 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
458 @standards{POSIX.1, unistd.h}
459 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
460 @c Some say write is thread-unsafe on Linux without O_APPEND. In the VFS layer
461 @c the vfs_write() does no locking around the acquisition of a file offset and
462 @c therefore multiple threads / kernel tasks may race and get the same offset
463 @c resulting in data loss.
466 @c http://thread.gmane.org/gmane.linux.kernel/397980
467 @c http://lwn.net/Articles/180387/
469 @c The counter argument is that POSIX only says that the write starts at the
470 @c file position and that the file position is updated *before* the function
471 @c returns. What that really means is that any expectation of atomic writes is
472 @c strictly an invention of the interpretation of the reader. Data loss could
473 @c happen if two threads start the write at the same time. Only writes that
474 @c come after the return of another write are guaranteed to follow the other
477 @c The other side of the coin is that POSIX goes on further to say in
478 @c "2.9.7 Thread Interactions with Regular File Operations" that threads
479 @c should never see interleaving sets of file operations, but it is insane
480 @c to do anything like that because it kills performance, so you don't get
481 @c those guarantees in Linux.
483 @c So we mark it thread safe, it doesn't blow up, but you might loose
484 @c data, and we don't strictly meet the POSIX requirements.
486 @c The fix for file offsets racing was merged in 3.14, the commits were:
487 @c 9c225f2655e36a470c4f58dbbc99244c5fc7f2d4, and
488 @c d7a15f8d0777955986a2ab00ab181795cab14b01. Therefore after Linux 3.14 you
489 @c should get mostly MT-safe writes.
490 The @code{write} function writes up to @var{size} bytes from
491 @var{buffer} to the file with descriptor @var{filedes}. The data in
492 @var{buffer} is not necessarily a character string and a null character is
493 output like any other character.
495 The return value is the number of bytes actually written. This may be
496 @var{size}, but can always be smaller. Your program should always call
497 @code{write} in a loop, iterating until all the data is written.
499 Once @code{write} returns, the data is enqueued to be written and can be
500 read back right away, but it is not necessarily written out to permanent
501 storage immediately. You can use @code{fsync} when you need to be sure
502 your data has been permanently stored before continuing. (It is more
503 efficient for the system to batch up consecutive writes and do them all
504 at once when convenient. Normally they will always be written to disk
505 within a minute or less.) Modern systems provide another function
506 @code{fdatasync} which guarantees integrity only for the file data and
508 @c !!! xref fsync, fdatasync
509 You can use the @code{O_FSYNC} open mode to make @code{write} always
510 store the data to disk before returning; @pxref{Operating Modes}.
512 In the case of an error, @code{write} returns @math{-1}. The following
513 @code{errno} error conditions are defined for this function:
517 Normally, @code{write} blocks until the write operation is complete.
518 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
519 Operations}), it returns immediately without writing any data and
520 reports this error. An example of a situation that might cause the
521 process to block on output is writing to a terminal device that supports
522 flow control, where output has been suspended by receipt of a STOP
525 @strong{Compatibility Note:} Most versions of BSD Unix use a different
526 error code for this: @code{EWOULDBLOCK}. In @theglibc{},
527 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
530 On some systems, writing a large amount of data from a character special
531 file can also fail with @code{EAGAIN} if the kernel cannot find enough
532 physical memory to lock down the user's pages. This is limited to
533 devices that transfer with direct memory access into the user's memory,
534 which means it does not include terminals, since they always use
535 separate buffers inside the kernel. This problem does not arise on
539 The @var{filedes} argument is not a valid file descriptor,
540 or is not open for writing.
543 The size of the file would become larger than the implementation can support.
546 The @code{write} operation was interrupted by a signal while it was
547 blocked waiting for completion. A signal will not necessarily cause
548 @code{write} to return @code{EINTR}; it may instead result in a
549 successful @code{write} which writes fewer bytes than requested.
550 @xref{Interrupted Primitives}.
553 For many devices, and for disk files, this error code indicates
557 The device containing the file is full.
560 This error is returned when you try to write to a pipe or FIFO that
561 isn't open for reading by any process. When this happens, a @code{SIGPIPE}
562 signal is also sent to the process; see @ref{Signal Handling}.
565 In some systems, when writing to a character or block device, position
566 and size offsets must be aligned to a particular block size. This error
567 indicates that the offsets were not properly aligned.
570 Unless you have arranged to prevent @code{EINTR} failures, you should
571 check @code{errno} after each failing call to @code{write}, and if the
572 error was @code{EINTR}, you should simply repeat the call.
573 @xref{Interrupted Primitives}. The easy way to do this is with the
574 macro @code{TEMP_FAILURE_RETRY}, as follows:
577 nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
580 Please note that there is no function named @code{write64}. This is not
581 necessary since this function does not directly modify or handle the
582 possibly wide file offset. Since the kernel handles this state
583 internally the @code{write} function can be used for all cases.
585 This function is a cancellation point in multi-threaded programs. This
586 is a problem if the thread allocates some resources (like memory, file
587 descriptors, semaphores or whatever) at the time @code{write} is
588 called. If the thread gets canceled these resources stay allocated
589 until the program ends. To avoid this, calls to @code{write} should be
590 protected using cancellation handlers.
591 @c ref pthread_cleanup_push / pthread_cleanup_pop
593 The @code{write} function is the underlying primitive for all of the
594 functions that write to streams, such as @code{fputc}.
597 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
598 @standards{Unix98, unistd.h}
599 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
600 @c This is usually a safe syscall. The sysdeps/posix fallback emulation
601 @c is not MT-Safe because it uses lseek, write and lseek back, but is it
603 The @code{pwrite} function is similar to the @code{write} function. The
604 first three arguments are identical, and the return values and error codes
607 The difference is the fourth argument and its handling. The data block
608 is not written to the current position of the file descriptor
609 @code{filedes}. Instead the data is written to the file starting at
610 position @var{offset}. The position of the file descriptor itself is
611 not affected by the operation. The value is the same as before the call.
613 However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite}
614 appends data to the end of the file, regardless of the value of
617 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
618 @code{pwrite} function is in fact @code{pwrite64} and the type
619 @code{off_t} has 64 bits, which makes it possible to handle files up to
620 @twoexp{63} bytes in length.
622 The return value of @code{pwrite} describes the number of written bytes.
623 In the error case it returns @math{-1} like @code{write} does and the
624 error codes are also the same, with these additions:
628 The value given for @var{offset} is negative and therefore illegal.
631 The file descriptor @var{filedes} is associated with a pipe or a FIFO and
632 this device does not allow positioning of the file pointer.
635 The function is an extension defined in the Unix Single Specification
639 @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset})
640 @standards{Unix98, unistd.h}
641 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
642 @c This is usually a safe syscall. The sysdeps/posix fallback emulation
643 @c is not MT-Safe because it uses lseek64, write and lseek64 back, but
644 @c is it used anywhere?
645 This function is similar to the @code{pwrite} function. The difference
646 is that the @var{offset} parameter is of type @code{off64_t} instead of
647 @code{off_t} which makes it possible on 32 bit machines to address
648 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
649 file descriptor @code{filedes} must be opened using @code{open64} since
650 otherwise the large offsets possible with @code{off64_t} will lead to
651 errors with a descriptor in small file mode.
653 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
654 32 bit machine this function is actually available under the name
655 @code{pwrite} and so transparently replaces the 32 bit interface.
658 @node File Position Primitive
659 @section Setting the File Position of a Descriptor
661 Just as you can set the file position of a stream with @code{fseek}, you
662 can set the file position of a descriptor with @code{lseek}. This
663 specifies the position in the file for the next @code{read} or
664 @code{write} operation. @xref{File Positioning}, for more information
665 on the file position and what it means.
667 To read the current file position value from a descriptor, use
668 @code{lseek (@var{desc}, 0, SEEK_CUR)}.
670 @cindex file positioning on a file descriptor
671 @cindex positioning a file descriptor
672 @cindex seeking on a file descriptor
673 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
674 @standards{POSIX.1, unistd.h}
675 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
676 The @code{lseek} function is used to change the file position of the
677 file with descriptor @var{filedes}.
679 The @var{whence} argument specifies how the @var{offset} should be
680 interpreted, in the same way as for the @code{fseek} function, and it must
681 be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
686 Specifies that @var{offset} is a count of characters from the beginning
690 Specifies that @var{offset} is a count of characters from the current
691 file position. This count may be positive or negative.
694 Specifies that @var{offset} is a count of characters from the end of
695 the file. A negative count specifies a position within the current
696 extent of the file; a positive count specifies a position past the
697 current end. If you set the position past the current end, and
698 actually write data, you will extend the file with zeros up to that
702 The return value from @code{lseek} is normally the resulting file
703 position, measured in bytes from the beginning of the file.
704 You can use this feature together with @code{SEEK_CUR} to read the
705 current file position.
707 If you want to append to the file, setting the file position to the
708 current end of file with @code{SEEK_END} is not sufficient. Another
709 process may write more data after you seek but before you write,
710 extending the file so the position you write onto clobbers their data.
711 Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
713 You can set the file position past the current end of the file. This
714 does not by itself make the file longer; @code{lseek} never changes the
715 file. But subsequent output at that position will extend the file.
716 Characters between the previous end of file and the new position are
717 filled with zeros. Extending the file in this way can create a
718 ``hole'': the blocks of zeros are not actually allocated on disk, so the
719 file takes up less space than it appears to; it is then called a
722 @cindex holes in files
724 If the file position cannot be changed, or the operation is in some way
725 invalid, @code{lseek} returns a value of @math{-1}. The following
726 @code{errno} error conditions are defined for this function:
730 The @var{filedes} is not a valid file descriptor.
733 The @var{whence} argument value is not valid, or the resulting
734 file offset is not valid. A file offset is invalid.
737 The @var{filedes} corresponds to an object that cannot be positioned,
738 such as a pipe, FIFO or terminal device. (POSIX.1 specifies this error
739 only for pipes and FIFOs, but on @gnusystems{}, you always get
740 @code{ESPIPE} if the object is not seekable.)
743 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
744 @code{lseek} function is in fact @code{lseek64} and the type
745 @code{off_t} has 64 bits which makes it possible to handle files up to
746 @twoexp{63} bytes in length.
748 This function is a cancellation point in multi-threaded programs. This
749 is a problem if the thread allocates some resources (like memory, file
750 descriptors, semaphores or whatever) at the time @code{lseek} is
751 called. If the thread gets canceled these resources stay allocated
752 until the program ends. To avoid this calls to @code{lseek} should be
753 protected using cancellation handlers.
754 @c ref pthread_cleanup_push / pthread_cleanup_pop
756 The @code{lseek} function is the underlying primitive for the
757 @code{fseek}, @code{fseeko}, @code{ftell}, @code{ftello} and
758 @code{rewind} functions, which operate on streams instead of file
762 @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence})
763 @standards{Unix98, unistd.h}
764 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
765 This function is similar to the @code{lseek} function. The difference
766 is that the @var{offset} parameter is of type @code{off64_t} instead of
767 @code{off_t} which makes it possible on 32 bit machines to address
768 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
769 file descriptor @code{filedes} must be opened using @code{open64} since
770 otherwise the large offsets possible with @code{off64_t} will lead to
771 errors with a descriptor in small file mode.
773 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
774 32 bits machine this function is actually available under the name
775 @code{lseek} and so transparently replaces the 32 bit interface.
778 You can have multiple descriptors for the same file if you open the file
779 more than once, or if you duplicate a descriptor with @code{dup}.
780 Descriptors that come from separate calls to @code{open} have independent
781 file positions; using @code{lseek} on one descriptor has no effect on the
789 d1 = open ("foo", O_RDONLY);
790 d2 = open ("foo", O_RDONLY);
791 lseek (d1, 1024, SEEK_SET);
798 will read the first four characters of the file @file{foo}. (The
799 error-checking code necessary for a real program has been omitted here
802 By contrast, descriptors made by duplication share a common file
803 position with the original descriptor that was duplicated. Anything
804 which alters the file position of one of the duplicates, including
805 reading or writing data, affects all of them alike. Thus, for example,
810 char buf1[4], buf2[4];
811 d1 = open ("foo", O_RDONLY);
814 lseek (d3, 1024, SEEK_SET);
821 will read four characters starting with the 1024'th character of
822 @file{foo}, and then four more characters starting with the 1028'th
825 @deftp {Data Type} off_t
826 @standards{POSIX.1, sys/types.h}
827 This is a signed integer type used to represent file sizes. In
828 @theglibc{}, this type is no narrower than @code{int}.
830 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
831 is transparently replaced by @code{off64_t}.
834 @deftp {Data Type} off64_t
835 @standards{Unix98, sys/types.h}
836 This type is used similar to @code{off_t}. The difference is that even
837 on 32 bit machines, where the @code{off_t} type would have 32 bits,
838 @code{off64_t} has 64 bits and so is able to address files up to
839 @twoexp{63} bytes in length.
841 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
842 available under the name @code{off_t}.
845 These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
846 of compatibility with older BSD systems. They are defined in two
847 different header files: @file{fcntl.h} and @file{sys/file.h}.
851 An alias for @code{SEEK_SET}.
854 An alias for @code{SEEK_CUR}.
857 An alias for @code{SEEK_END}.
860 @node Descriptors and Streams
861 @section Descriptors and Streams
862 @cindex streams, and file descriptors
863 @cindex converting file descriptor to stream
864 @cindex extracting file descriptor from stream
866 Given an open file descriptor, you can create a stream for it with the
867 @code{fdopen} function. You can get the underlying file descriptor for
868 an existing stream with the @code{fileno} function. These functions are
869 declared in the header file @file{stdio.h}.
872 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
873 @standards{POSIX.1, stdio.h}
874 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @aculock{}}}
875 The @code{fdopen} function returns a new stream for the file descriptor
878 The @var{opentype} argument is interpreted in the same way as for the
879 @code{fopen} function (@pxref{Opening Streams}), except that
880 the @samp{b} option is not permitted; this is because @gnusystems{} make no
881 distinction between text and binary files. Also, @code{"w"} and
882 @code{"w+"} do not cause truncation of the file; these have an effect only
883 when opening a file, and in this case the file has already been opened.
884 You must make sure that the @var{opentype} argument matches the actual
885 mode of the open file descriptor.
887 The return value is the new stream. If the stream cannot be created
888 (for example, if the modes for the file indicated by the file descriptor
889 do not permit the access specified by the @var{opentype} argument), a
890 null pointer is returned instead.
892 In some other systems, @code{fdopen} may fail to detect that the modes
893 for file descriptors do not permit the access specified by
894 @code{opentype}. @Theglibc{} always checks for this.
897 For an example showing the use of the @code{fdopen} function,
898 see @ref{Creating a Pipe}.
900 @deftypefun int fileno (FILE *@var{stream})
901 @standards{POSIX.1, stdio.h}
902 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
903 This function returns the file descriptor associated with the stream
904 @var{stream}. If an error is detected (for example, if the @var{stream}
905 is not valid) or if @var{stream} does not do I/O to a file,
906 @code{fileno} returns @math{-1}.
909 @deftypefun int fileno_unlocked (FILE *@var{stream})
910 @standards{GNU, stdio.h}
911 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
912 The @code{fileno_unlocked} function is equivalent to the @code{fileno}
913 function except that it does not implicitly lock the stream if the state
914 is @code{FSETLOCKING_INTERNAL}.
916 This function is a GNU extension.
919 @cindex standard file descriptors
920 @cindex file descriptors, standard
921 There are also symbolic constants defined in @file{unistd.h} for the
922 file descriptors belonging to the standard streams @code{stdin},
923 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
928 @standards{POSIX.1, unistd.h}
929 This macro has value @code{0}, which is the file descriptor for
931 @cindex standard input file descriptor
934 @standards{POSIX.1, unistd.h}
935 This macro has value @code{1}, which is the file descriptor for
937 @cindex standard output file descriptor
940 @standards{POSIX.1, unistd.h}
941 This macro has value @code{2}, which is the file descriptor for
942 standard error output.
944 @cindex standard error file descriptor
946 @node Stream/Descriptor Precautions
947 @section Dangers of Mixing Streams and Descriptors
949 @cindex streams and descriptors
950 @cindex descriptors and streams
951 @cindex mixing descriptors and streams
953 You can have multiple file descriptors and streams (let's call both
954 streams and descriptors ``channels'' for short) connected to the same
955 file, but you must take care to avoid confusion between channels. There
956 are two cases to consider: @dfn{linked} channels that share a single
957 file position value, and @dfn{independent} channels that have their own
960 It's best to use just one channel in your program for actual data
961 transfer to any given file, except when all the access is for input.
962 For example, if you open a pipe (something you can only do at the file
963 descriptor level), either do all I/O with the descriptor, or construct a
964 stream from the descriptor with @code{fdopen} and then do all I/O with
968 * Linked Channels:: Dealing with channels sharing a file position.
969 * Independent Channels:: Dealing with separately opened, unlinked channels.
970 * Cleaning Streams:: Cleaning a stream makes it safe to use
974 @node Linked Channels
975 @subsection Linked Channels
976 @cindex linked channels
978 Channels that come from a single opening share the same file position;
979 we call them @dfn{linked} channels. Linked channels result when you
980 make a stream from a descriptor using @code{fdopen}, when you get a
981 descriptor from a stream with @code{fileno}, when you copy a descriptor
982 with @code{dup} or @code{dup2}, and when descriptors are inherited
983 during @code{fork}. For files that don't support random access, such as
984 terminals and pipes, @emph{all} channels are effectively linked. On
985 random-access files, all append-type output streams are effectively
986 linked to each other.
988 @cindex cleaning up a stream
989 If you have been using a stream for I/O (or have just opened the stream),
990 and you want to do I/O using
991 another channel (either a stream or a descriptor) that is linked to it,
992 you must first @dfn{clean up} the stream that you have been using.
993 @xref{Cleaning Streams}.
995 Terminating a process, or executing a new program in the process,
996 destroys all the streams in the process. If descriptors linked to these
997 streams persist in other processes, their file positions become
998 undefined as a result. To prevent this, you must clean up the streams
999 before destroying them.
1001 @node Independent Channels
1002 @subsection Independent Channels
1003 @cindex independent channels
1005 When you open channels (streams or descriptors) separately on a seekable
1006 file, each channel has its own file position. These are called
1007 @dfn{independent channels}.
1009 The system handles each channel independently. Most of the time, this
1010 is quite predictable and natural (especially for input): each channel
1011 can read or write sequentially at its own place in the file. However,
1012 if some of the channels are streams, you must take these precautions:
1016 You should clean an output stream after use, before doing anything else
1017 that might read or write from the same part of the file.
1020 You should clean an input stream before reading data that may have been
1021 modified using an independent channel. Otherwise, you might read
1022 obsolete data that had been in the stream's buffer.
1025 If you do output to one channel at the end of the file, this will
1026 certainly leave the other independent channels positioned somewhere
1027 before the new end. You cannot reliably set their file positions to the
1028 new end of file before writing, because the file can always be extended
1029 by another process between when you set the file position and when you
1030 write the data. Instead, use an append-type descriptor or stream; they
1031 always output at the current end of the file. In order to make the
1032 end-of-file position accurate, you must clean the output channel you
1033 were using, if it is a stream.
1035 It's impossible for two channels to have separate file pointers for a
1036 file that doesn't support random access. Thus, channels for reading or
1037 writing such files are always linked, never independent. Append-type
1038 channels are also always linked. For these channels, follow the rules
1039 for linked channels; see @ref{Linked Channels}.
1041 @node Cleaning Streams
1042 @subsection Cleaning Streams
1044 You can use @code{fflush} to clean a stream in most
1047 You can skip the @code{fflush} if you know the stream
1048 is already clean. A stream is clean whenever its buffer is empty. For
1049 example, an unbuffered stream is always clean. An input stream that is
1050 at end-of-file is clean. A line-buffered stream is clean when the last
1051 character output was a newline. However, a just-opened input stream
1052 might not be clean, as its input buffer might not be empty.
1054 There is one case in which cleaning a stream is impossible on most
1055 systems. This is when the stream is doing input from a file that is not
1056 random-access. Such streams typically read ahead, and when the file is
1057 not random access, there is no way to give back the excess data already
1058 read. When an input stream reads from a random-access file,
1059 @code{fflush} does clean the stream, but leaves the file pointer at an
1060 unpredictable place; you must set the file pointer before doing any
1063 Closing an output-only stream also does @code{fflush}, so this is a
1064 valid way of cleaning an output stream.
1066 You need not clean a stream before using its descriptor for control
1067 operations such as setting terminal modes; these operations don't affect
1068 the file position and are not affected by it. You can use any
1069 descriptor for these operations, and all channels are affected
1070 simultaneously. However, text already ``output'' to a stream but still
1071 buffered by the stream will be subject to the new terminal modes when
1072 subsequently flushed. To make sure ``past'' output is covered by the
1073 terminal settings that were in effect at the time, flush the output
1074 streams for that terminal before setting the modes. @xref{Terminal
1077 @node Scatter-Gather
1078 @section Fast Scatter-Gather I/O
1079 @cindex scatter-gather
1081 Some applications may need to read or write data to multiple buffers,
1082 which are separated in memory. Although this can be done easily enough
1083 with multiple calls to @code{read} and @code{write}, it is inefficient
1084 because there is overhead associated with each kernel call.
1086 Instead, many platforms provide special high-speed primitives to perform
1087 these @dfn{scatter-gather} operations in a single kernel call. @Theglibc{}
1088 will provide an emulation on any system that lacks these
1089 primitives, so they are not a portability threat. They are defined in
1092 These functions are controlled with arrays of @code{iovec} structures,
1093 which describe the location and size of each buffer.
1095 @deftp {Data Type} {struct iovec}
1096 @standards{BSD, sys/uio.h}
1098 The @code{iovec} structure describes a buffer. It contains two fields:
1102 @item void *iov_base
1103 Contains the address of a buffer.
1105 @item size_t iov_len
1106 Contains the length of the buffer.
1111 @deftypefun ssize_t readv (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
1112 @standards{BSD, sys/uio.h}
1113 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
1114 @c The fallback sysdeps/posix implementation, used even on GNU/Linux
1115 @c with old kernels that lack a full readv/writev implementation, may
1116 @c malloc the buffer into which data is read, if the total read size is
1117 @c too large for alloca.
1119 The @code{readv} function reads data from @var{filedes} and scatters it
1120 into the buffers described in @var{vector}, which is taken to be
1121 @var{count} structures long. As each buffer is filled, data is sent to the
1124 Note that @code{readv} is not guaranteed to fill all the buffers.
1125 It may stop at any point, for the same reasons @code{read} would.
1127 The return value is a count of bytes (@emph{not} buffers) read, @math{0}
1128 indicating end-of-file, or @math{-1} indicating an error. The possible
1129 errors are the same as in @code{read}.
1133 @deftypefun ssize_t writev (int @var{filedes}, const struct iovec *@var{vector}, int @var{count})
1134 @standards{BSD, sys/uio.h}
1135 @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
1136 @c The fallback sysdeps/posix implementation, used even on GNU/Linux
1137 @c with old kernels that lack a full readv/writev implementation, may
1138 @c malloc the buffer from which data is written, if the total write size
1139 @c is too large for alloca.
1141 The @code{writev} function gathers data from the buffers described in
1142 @var{vector}, which is taken to be @var{count} structures long, and writes
1143 them to @code{filedes}. As each buffer is written, it moves on to the
1146 Like @code{readv}, @code{writev} may stop midstream under the same
1147 conditions @code{write} would.
1149 The return value is a count of bytes written, or @math{-1} indicating an
1150 error. The possible errors are the same as in @code{write}.
1154 @deftypefun ssize_t preadv (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
1155 @standards{BSD, sys/uio.h}
1156 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1157 @c This is a syscall for Linux 3.2 for all architectures but microblaze
1158 @c (which was added on 3.15). The sysdeps/posix fallback emulation
1159 @c is also MT-Safe since it calls pread, and it is now a syscall on all
1162 This function is similar to the @code{readv} function, with the difference
1163 it adds an extra @var{offset} parameter of type @code{off_t} similar to
1164 @code{pread}. The data is written to the file starting at position
1165 @var{offset}. The position of the file descriptor itself is not affected
1166 by the operation. The value is the same as before the call.
1168 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1169 @code{preadv} function is in fact @code{preadv64} and the type
1170 @code{off_t} has 64 bits, which makes it possible to handle files up to
1171 @twoexp{63} bytes in length.
1173 The return value is a count of bytes (@emph{not} buffers) read, @math{0}
1174 indicating end-of-file, or @math{-1} indicating an error. The possible
1175 errors are the same as in @code{readv} and @code{pread}.
1178 @deftypefun ssize_t preadv64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
1179 @standards{BSD, unistd.h}
1180 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1181 @c This is a syscall for Linux 3.2 for all architectures but microblaze
1182 @c (which was added on 3.15). The sysdeps/posix fallback emulation
1183 @c is also MT-Safe since it calls pread64, and it is now a syscall on all
1186 This function is similar to the @code{preadv} function with the difference
1187 is that the @var{offset} parameter is of type @code{off64_t} instead of
1188 @code{off_t}. It makes it possible on 32 bit machines to address
1189 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
1190 file descriptor @code{filedes} must be opened using @code{open64} since
1191 otherwise the large offsets possible with @code{off64_t} will lead to
1192 errors with a descriptor in small file mode.
1194 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1195 32 bit machine this function is actually available under the name
1196 @code{preadv} and so transparently replaces the 32 bit interface.
1199 @deftypefun ssize_t pwritev (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset})
1200 @standards{BSD, sys/uio.h}
1201 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1202 @c This is a syscall for Linux 3.2 for all architectures but microblaze
1203 @c (which was added on 3.15). The sysdeps/posix fallback emulation
1204 @c is also MT-Safe since it calls pwrite, and it is now a syscall on all
1207 This function is similar to the @code{writev} function, with the difference
1208 it adds an extra @var{offset} parameter of type @code{off_t} similar to
1209 @code{pwrite}. The data is written to the file starting at position
1210 @var{offset}. The position of the file descriptor itself is not affected
1211 by the operation. The value is the same as before the call.
1213 However, on Linux, if a file is opened with @code{O_APPEND}, @code{pwrite}
1214 appends data to the end of the file, regardless of the value of
1217 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1218 @code{pwritev} function is in fact @code{pwritev64} and the type
1219 @code{off_t} has 64 bits, which makes it possible to handle files up to
1220 @twoexp{63} bytes in length.
1222 The return value is a count of bytes (@emph{not} buffers) written, @math{0}
1223 indicating end-of-file, or @math{-1} indicating an error. The possible
1224 errors are the same as in @code{writev} and @code{pwrite}.
1227 @deftypefun ssize_t pwritev64 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset})
1228 @standards{BSD, unistd.h}
1229 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1230 @c This is a syscall for Linux 3.2 for all architectures but microblaze
1231 @c (which was added on 3.15). The sysdeps/posix fallback emulation
1232 @c is also MT-Safe since it calls pwrite64, and it is now a syscall on all
1235 This function is similar to the @code{pwritev} function with the difference
1236 is that the @var{offset} parameter is of type @code{off64_t} instead of
1237 @code{off_t}. It makes it possible on 32 bit machines to address
1238 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
1239 file descriptor @code{filedes} must be opened using @code{open64} since
1240 otherwise the large offsets possible with @code{off64_t} will lead to
1241 errors with a descriptor in small file mode.
1243 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1244 32 bit machine this function is actually available under the name
1245 @code{pwritev} and so transparently replaces the 32 bit interface.
1248 @deftypefun ssize_t preadv2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
1249 @standards{GNU, sys/uio.h}
1250 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1251 @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
1252 @c is also MT-Safe since it calls preadv.
1254 This function is similar to the @code{preadv} function, with the
1255 difference it adds an extra @var{flags} parameter of type @code{int}.
1256 Additionally, if @var{offset} is @math{-1}, the current file position
1257 is used and updated (like the @code{readv} function).
1259 The supported @var{flags} are dependent of the underlying system. For
1264 High priority request. This adds a flag that tells the file system that
1265 this is a high priority request for which it is worth to poll the hardware.
1266 The flag is purely advisory and can be ignored if not supported. The
1267 @var{fd} must be opened using @code{O_DIRECT}.
1270 Per-IO synchronization as if the file was opened with @code{O_DSYNC} flag.
1273 Per-IO synchronization as if the file was opened with @code{O_SYNC} flag.
1276 Use nonblocking mode for this operation; that is, this call to @code{preadv2}
1277 will fail and set @code{errno} to @code{EAGAIN} if the operation would block.
1280 Per-IO synchronization as if the file was opened with @code{O_APPEND} flag.
1283 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1284 @code{preadv2} function is in fact @code{preadv64v2} and the type
1285 @code{off_t} has 64 bits, which makes it possible to handle files up to
1286 @twoexp{63} bytes in length.
1288 The return value is a count of bytes (@emph{not} buffers) read, @math{0}
1289 indicating end-of-file, or @math{-1} indicating an error. The possible
1290 errors are the same as in @code{preadv} with the addition of:
1296 @c The default sysdeps/posix code will return it for any flags value
1297 @c different than 0.
1298 An unsupported @var{flags} was used.
1304 @deftypefun ssize_t preadv64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
1305 @standards{GNU, unistd.h}
1306 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1307 @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
1308 @c is also MT-Safe since it calls preadv.
1310 This function is similar to the @code{preadv2} function with the difference
1311 is that the @var{offset} parameter is of type @code{off64_t} instead of
1312 @code{off_t}. It makes it possible on 32 bit machines to address
1313 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
1314 file descriptor @code{filedes} must be opened using @code{open64} since
1315 otherwise the large offsets possible with @code{off64_t} will lead to
1316 errors with a descriptor in small file mode.
1318 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1319 32 bit machine this function is actually available under the name
1320 @code{preadv2} and so transparently replaces the 32 bit interface.
1324 @deftypefun ssize_t pwritev2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off_t @var{offset}, int @var{flags})
1325 @standards{GNU, sys/uio.h}
1326 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1327 @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
1328 @c is also MT-Safe since it calls pwritev.
1330 This function is similar to the @code{pwritev} function, with the
1331 difference it adds an extra @var{flags} parameter of type @code{int}.
1332 Additionally, if @var{offset} is @math{-1}, the current file position
1333 should is used and updated (like the @code{writev} function).
1335 The supported @var{flags} are dependent of the underlying system. For
1336 Linux, the supported flags are the same as those for @code{preadv2}.
1338 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
1339 @code{pwritev2} function is in fact @code{pwritev64v2} and the type
1340 @code{off_t} has 64 bits, which makes it possible to handle files up to
1341 @twoexp{63} bytes in length.
1343 The return value is a count of bytes (@emph{not} buffers) write, @math{0}
1344 indicating end-of-file, or @math{-1} indicating an error. The possible
1345 errors are the same as in @code{preadv2}.
1348 @deftypefun ssize_t pwritev64v2 (int @var{fd}, const struct iovec *@var{iov}, int @var{iovcnt}, off64_t @var{offset}, int @var{flags})
1349 @standards{GNU, unistd.h}
1350 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1351 @c This is a syscall for Linux v4.6. The sysdeps/posix fallback emulation
1352 @c is also MT-Safe since it calls pwritev.
1354 This function is similar to the @code{pwritev2} function with the difference
1355 is that the @var{offset} parameter is of type @code{off64_t} instead of
1356 @code{off_t}. It makes it possible on 32 bit machines to address
1357 files larger than @twoexp{31} bytes and up to @twoexp{63} bytes. The
1358 file descriptor @code{filedes} must be opened using @code{open64} since
1359 otherwise the large offsets possible with @code{off64_t} will lead to
1360 errors with a descriptor in small file mode.
1362 When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a
1363 32 bit machine this function is actually available under the name
1364 @code{pwritev2} and so transparently replaces the 32 bit interface.
1367 @node Copying File Data
1368 @section Copying data between two files
1369 @cindex copying files
1372 A special function is provided to copy data between two files on the
1373 same file system. The system can optimize such copy operations. This
1374 is particularly important on network file systems, where the data would
1375 otherwise have to be transferred twice over the network.
1377 Note that this function only copies file data, but not metadata such as
1378 file permissions or extended attributes.
1380 @deftypefun ssize_t copy_file_range (int @var{inputfd}, off64_t *@var{inputpos}, int @var{outputfd}, off64_t *@var{outputpos}, ssize_t @var{length}, unsigned int @var{flags})
1381 @standards{GNU, unistd.h}
1382 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1384 This function copies up to @var{length} bytes from the file descriptor
1385 @var{inputfd} to the file descriptor @var{outputfd}.
1387 The function can operate on both the current file position (like
1388 @code{read} and @code{write}) and an explicit offset (like @code{pread}
1389 and @code{pwrite}). If the @var{inputpos} pointer is null, the file
1390 position of @var{inputfd} is used as the starting point of the copy
1391 operation, and the file position is advanced during it. If
1392 @var{inputpos} is not null, then @code{*@var{inputpos}} is used as the
1393 starting point of the copy operation, and @code{*@var{inputpos}} is
1394 incremented by the number of copied bytes, but the file position remains
1395 unchanged. Similar rules apply to @var{outputfd} and @var{outputpos}
1396 for the output file position.
1398 The @var{flags} argument is currently reserved and must be zero.
1400 The @code{copy_file_range} function returns the number of bytes copied.
1401 This can be less than the specified @var{length} in case the input file
1402 contains fewer remaining bytes than @var{length}, or if a read or write
1403 failure occurs. The return value is zero if the end of the input file
1404 is encountered immediately.
1406 If no bytes can be copied, to report an error, @code{copy_file_range}
1407 returns the value @math{-1} and sets @code{errno}. The table below
1408 lists some of the error conditions for this function.
1412 The kernel does not implement the required functionality.
1415 At least one of the descriptors @var{inputfd} or @var{outputfd} refers
1419 At least one of the descriptors @var{inputfd} or @var{outputfd} refers
1420 to a non-regular, non-directory file (such as a socket or a FIFO).
1422 The input or output positions before are after the copy operations are
1423 outside of an implementation-defined limit.
1425 The @var{flags} argument is not zero.
1428 The new file size would exceed the process file size limit.
1429 @xref{Limits on Resources}.
1431 The input or output positions before are after the copy operations are
1432 outside of an implementation-defined limit. This can happen if the file
1433 was not opened with large file support (LFS) on 32-bit machines, and the
1434 copy operation would create a file which is larger than what
1435 @code{off_t} could represent.
1438 The argument @var{inputfd} is not a valid file descriptor open for
1441 The argument @var{outputfd} is not a valid file descriptor open for
1442 writing, or @var{outputfd} has been opened with @code{O_APPEND}.
1445 In addition, @code{copy_file_range} can fail with the error codes
1446 which are used by @code{read}, @code{pread}, @code{write}, and
1449 The @code{copy_file_range} function is a cancellation point. In case of
1450 cancellation, the input location (the file position or the value at
1451 @code{*@var{inputpos}}) is indeterminate.
1454 @node Memory-mapped I/O
1455 @section Memory-mapped I/O
1457 On modern operating systems, it is possible to @dfn{mmap} (pronounced
1458 ``em-map'') a file to a region of memory. When this is done, the file can
1459 be accessed just like an array in the program.
1461 This is more efficient than @code{read} or @code{write}, as only the regions
1462 of the file that a program actually accesses are loaded. Accesses to
1463 not-yet-loaded parts of the mmapped region are handled in the same way as
1466 Since mmapped pages can be stored back to their file when physical
1467 memory is low, it is possible to mmap files orders of magnitude larger
1468 than both the physical memory @emph{and} swap space. The only limit is
1469 address space. The theoretical limit is 4GB on a 32-bit machine -
1470 however, the actual limit will be smaller since some areas will be
1471 reserved for other purposes. If the LFS interface is used the file size
1472 on 32-bit systems is not limited to 2GB (offsets are signed which
1473 reduces the addressable area of 4GB by half); the full 64-bit are
1476 Memory mapping only works on entire pages of memory. Thus, addresses
1477 for mapping must be page-aligned, and length values will be rounded up.
1478 To determine the default size of a page the machine uses one should use:
1480 @vindex _SC_PAGESIZE
1482 size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
1485 On some systems, mappings can use larger page sizes
1486 for certain files, and applications can request larger page sizes for
1487 anonymous mappings as well (see the @code{MAP_HUGETLB} flag below).
1489 The following functions are declared in @file{sys/mman.h}:
1491 @deftypefun {void *} mmap (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off_t @var{offset})
1492 @standards{POSIX, sys/mman.h}
1493 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1495 The @code{mmap} function creates a new mapping, connected to bytes
1496 (@var{offset}) to (@var{offset} + @var{length} - 1) in the file open on
1497 @var{filedes}. A new reference for the file specified by @var{filedes}
1498 is created, which is not removed by closing the file.
1500 @var{address} gives a preferred starting address for the mapping.
1501 @code{NULL} expresses no preference. Any previous mapping at that
1502 address is automatically removed. The address you give may still be
1503 changed, unless you use the @code{MAP_FIXED} flag.
1505 @var{protect} contains flags that control what kind of access is
1506 permitted. They include @code{PROT_READ}, @code{PROT_WRITE}, and
1507 @code{PROT_EXEC}. The special flag @code{PROT_NONE} reserves a region
1508 of address space for future use. The @code{mprotect} function can be
1509 used to change the protection flags. @xref{Memory Protection}.
1511 @var{flags} contains flags that control the nature of the map.
1512 One of @code{MAP_SHARED} or @code{MAP_PRIVATE} must be specified.
1518 This specifies that writes to the region should never be written back
1519 to the attached file. Instead, a copy is made for the process, and the
1520 region will be swapped normally if memory runs low. No other process will
1523 Since private mappings effectively revert to ordinary memory
1524 when written to, you must have enough virtual memory for a copy of
1525 the entire mmapped region if you use this mode with @code{PROT_WRITE}.
1528 This specifies that writes to the region will be written back to the
1529 file. Changes made will be shared immediately with other processes
1530 mmaping the same file.
1532 Note that actual writing may take place at any time. You need to use
1533 @code{msync}, described below, if it is important that other processes
1534 using conventional I/O get a consistent view of the file.
1537 This forces the system to use the exact mapping address specified in
1538 @var{address} and fail if it can't.
1540 @c One of these is official - the other is obviously an obsolete synonym
1544 This flag tells the system to create an anonymous mapping, not connected
1545 to a file. @var{filedes} and @var{offset} are ignored, and the region is
1546 initialized with zeros.
1548 Anonymous maps are used as the basic primitive to extend the heap on some
1549 systems. They are also useful to share data between multiple tasks
1550 without creating a file.
1552 On some systems using private anonymous mmaps is more efficient than using
1553 @code{malloc} for large blocks. This is not an issue with @theglibc{},
1554 as the included @code{malloc} automatically uses @code{mmap} where appropriate.
1557 @standards{Linux, sys/mman.h}
1558 This requests that the system uses an alternative page size which is
1559 larger than the default page size for the mapping. For some workloads,
1560 increasing the page size for large mappings improves performance because
1561 the system needs to handle far fewer pages. For other workloads which
1562 require frequent transfer of pages between storage or different nodes,
1563 the decreased page granularity may cause performance problems due to the
1564 increased page size and larger transfers.
1566 In order to create the mapping, the system needs physically contiguous
1567 memory of the size of the increased page size. As a result,
1568 @code{MAP_HUGETLB} mappings are affected by memory fragmentation, and
1569 their creation can fail even if plenty of memory is available in the
1572 Not all file systems support mappings with an increased page size.
1574 The @code{MAP_HUGETLB} flag is specific to Linux.
1576 @c There is a mechanism to select different hugepage sizes; see
1577 @c include/uapi/asm-generic/hugetlb_encode.h in the kernel sources.
1579 @c Linux has some other MAP_ options, which I have not discussed here.
1580 @c MAP_DENYWRITE, MAP_EXECUTABLE and MAP_GROWSDOWN don't seem applicable to
1581 @c user programs (and I don't understand the last two). MAP_LOCKED does
1582 @c not appear to be implemented.
1586 @code{mmap} returns the address of the new mapping, or
1587 @code{MAP_FAILED} for an error.
1589 Possible errors include:
1595 Either @var{address} was unusable (because it is not a multiple of the
1596 applicable page size), or inconsistent @var{flags} were given.
1598 If @code{MAP_HUGETLB} was specified, the file or system does not support
1603 @var{filedes} was not open for the type of access specified in @var{protect}.
1607 Either there is not enough memory for the operation, or the process is
1608 out of address space.
1612 This file is of a type that doesn't support mapping.
1616 The file is on a filesystem that doesn't support mapping.
1618 @c On Linux, EAGAIN will appear if the file has a conflicting mandatory lock.
1619 @c However mandatory locks are not discussed in this manual.
1621 @c Similarly, ETXTBSY will occur if the MAP_DENYWRITE flag (not documented
1622 @c here) is used and the file is already open for writing.
1628 @deftypefun {void *} mmap64 (void *@var{address}, size_t @var{length}, int @var{protect}, int @var{flags}, int @var{filedes}, off64_t @var{offset})
1629 @standards{LFS, sys/mman.h}
1630 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1631 @c The page_shift auto detection when MMAP2_PAGE_SHIFT is -1 (it never
1632 @c is) would be thread-unsafe.
1633 The @code{mmap64} function is equivalent to the @code{mmap} function but
1634 the @var{offset} parameter is of type @code{off64_t}. On 32-bit systems
1635 this allows the file associated with the @var{filedes} descriptor to be
1636 larger than 2GB. @var{filedes} must be a descriptor returned from a
1637 call to @code{open64} or @code{fopen64} and @code{freopen64} where the
1638 descriptor is retrieved with @code{fileno}.
1640 When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this
1641 function is actually available under the name @code{mmap}. I.e., the
1642 new, extended API using 64 bit file sizes and offsets transparently
1643 replaces the old API.
1646 @deftypefun int munmap (void *@var{addr}, size_t @var{length})
1647 @standards{POSIX, sys/mman.h}
1648 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1650 @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} +
1651 @var{length}). @var{length} should be the length of the mapping.
1653 It is safe to unmap multiple mappings in one command, or include unmapped
1654 space in the range. It is also possible to unmap only part of an existing
1655 mapping. However, only entire pages can be removed. If @var{length} is not
1656 an even number of pages, it will be rounded up.
1658 It returns @math{0} for success and @math{-1} for an error.
1660 One error is possible:
1665 The memory range given was outside the user mmap range or wasn't page
1672 @deftypefun int msync (void *@var{address}, size_t @var{length}, int @var{flags})
1673 @standards{POSIX, sys/mman.h}
1674 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1676 When using shared mappings, the kernel can write the file at any time
1677 before the mapping is removed. To be certain data has actually been
1678 written to the file and will be accessible to non-memory-mapped I/O, it
1679 is necessary to use this function.
1681 It operates on the region @var{address} to (@var{address} + @var{length}).
1682 It may be used on part of a mapping or multiple mappings, however the
1683 region given should not contain any unmapped space.
1685 @var{flags} can contain some options:
1691 This flag makes sure the data is actually written @emph{to disk}.
1692 Normally @code{msync} only makes sure that accesses to a file with
1693 conventional I/O reflect the recent changes.
1697 This tells @code{msync} to begin the synchronization, but not to wait for
1700 @c Linux also has MS_INVALIDATE, which I don't understand.
1704 @code{msync} returns @math{0} for success and @math{-1} for
1705 error. Errors include:
1710 An invalid region was given, or the @var{flags} were invalid.
1713 There is no existing mapping in at least part of the given region.
1719 @deftypefun {void *} mremap (void *@var{address}, size_t @var{length}, size_t @var{new_length}, int @var{flag})
1720 @standards{GNU, sys/mman.h}
1721 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1723 This function can be used to change the size of an existing memory
1724 area. @var{address} and @var{length} must cover a region entirely mapped
1725 in the same @code{mmap} statement. A new mapping with the same
1726 characteristics will be returned with the length @var{new_length}.
1728 One option is possible, @code{MREMAP_MAYMOVE}. If it is given in
1729 @var{flags}, the system may remove the existing mapping and create a new
1730 one of the desired length in another location.
1732 The address of the resulting mapping is returned, or @math{-1}. Possible
1733 error codes include:
1738 There is no existing mapping in at least part of the original region, or
1739 the region covers two or more distinct mappings.
1742 The address given is misaligned or inappropriate.
1745 The region has pages locked, and if extended it would exceed the
1746 process's resource limit for locked pages. @xref{Limits on Resources}.
1749 The region is private writable, and insufficient virtual memory is
1750 available to extend it. Also, this error will occur if
1751 @code{MREMAP_MAYMOVE} is not given and the extension would collide with
1752 another mapped region.
1757 This function is only available on a few systems. Except for performing
1758 optional optimizations one should not rely on this function.
1760 Not all file descriptors may be mapped. Sockets, pipes, and most devices
1761 only allow sequential access and do not fit into the mapping abstraction.
1762 In addition, some regular files may not be mmapable, and older kernels may
1763 not support mapping at all. Thus, programs using @code{mmap} should
1764 have a fallback method to use should it fail. @xref{Mmap,,,standards,GNU
1767 @deftypefun int madvise (void *@var{addr}, size_t @var{length}, int @var{advice})
1768 @standards{POSIX, sys/mman.h}
1769 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1771 This function can be used to provide the system with @var{advice} about
1772 the intended usage patterns of the memory region starting at @var{addr}
1773 and extending @var{length} bytes.
1775 The valid BSD values for @var{advice} are:
1780 The region should receive no further special treatment.
1783 The region will be accessed via random page references. The kernel
1784 should page-in the minimal number of pages for each page fault.
1786 @item MADV_SEQUENTIAL
1787 The region will be accessed via sequential page references. This
1788 may cause the kernel to aggressively read-ahead, expecting further
1789 sequential references after any page fault within this region.
1792 The region will be needed. The pages within this region may
1793 be pre-faulted in by the kernel.
1796 The region is no longer needed. The kernel may free these pages,
1797 causing any changes to the pages to be lost, as well as swapped
1798 out pages to be discarded.
1801 @standards{Linux, sys/mman.h}
1802 Indicate that it is beneficial to increase the page size for this
1803 mapping. This can improve performance for larger mappings because the
1804 system needs to handle far fewer pages. However, if parts of the
1805 mapping are frequently transferred between storage or different nodes,
1806 performance may suffer because individual transfers can become
1807 substantially larger due to the increased page size.
1809 This flag is specific to Linux.
1811 @item MADV_NOHUGEPAGE
1812 Undo the effect of a previous @code{MADV_HUGEPAGE} advice. This flag
1813 is specific to Linux.
1817 The POSIX names are slightly different, but with the same meanings:
1821 @item POSIX_MADV_NORMAL
1822 This corresponds with BSD's @code{MADV_NORMAL}.
1824 @item POSIX_MADV_RANDOM
1825 This corresponds with BSD's @code{MADV_RANDOM}.
1827 @item POSIX_MADV_SEQUENTIAL
1828 This corresponds with BSD's @code{MADV_SEQUENTIAL}.
1830 @item POSIX_MADV_WILLNEED
1831 This corresponds with BSD's @code{MADV_WILLNEED}.
1833 @item POSIX_MADV_DONTNEED
1834 This corresponds with BSD's @code{MADV_DONTNEED}.
1838 @code{madvise} returns @math{0} for success and @math{-1} for
1839 error. Errors include:
1843 An invalid region was given, or the @var{advice} was invalid.
1846 There is no existing mapping in at least part of the given region.
1851 @deftypefn Function int shm_open (const char *@var{name}, int @var{oflag}, mode_t @var{mode})
1852 @standards{POSIX, sys/mman.h}
1853 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1854 @c shm_open @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1855 @c libc_once(where_is_shmfs) @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1856 @c where_is_shmfs @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
1858 @c setmntent dup @ascuheap @asulock @acsmem @acsfd @aculock
1859 @c getmntent_r dup @mtslocale @ascuheap @aculock @acsmem [no @asucorrupt @acucorrupt; exclusive stream]
1862 @c malloc dup @ascuheap @acsmem
1864 @c endmntent dup @ascuheap @asulock @aculock @acsmem @acsfd
1872 This function returns a file descriptor that can be used to allocate shared
1873 memory via mmap. Unrelated processes can use same @var{name} to create or
1874 open existing shared memory objects.
1876 A @var{name} argument specifies the shared memory object to be opened.
1877 In @theglibc{} it must be a string smaller than @code{NAME_MAX} bytes starting
1878 with an optional slash but containing no other slashes.
1880 The semantics of @var{oflag} and @var{mode} arguments is same as in @code{open}.
1882 @code{shm_open} returns the file descriptor on success or @math{-1} on error.
1883 On failure @code{errno} is set.
1886 @deftypefn Function int shm_unlink (const char *@var{name})
1887 @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asuinit{} @ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
1888 @c shm_unlink @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1889 @c libc_once(where_is_shmfs) dup @mtslocale @asuinit @ascuheap @asulock @aculock @acsmem @acsfd
1895 This function is the inverse of @code{shm_open} and removes the object with
1896 the given @var{name} previously created by @code{shm_open}.
1898 @code{shm_unlink} returns @math{0} on success or @math{-1} on error.
1899 On failure @code{errno} is set.
1902 @deftypefun int memfd_create (const char *@var{name}, unsigned int @var{flags})
1903 @standards{Linux, sys/mman.h}
1904 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
1905 The @code{memfd_create} function returns a file descriptor which can be
1906 used to create memory mappings using the @code{mmap} function. It is
1907 similar to the @code{shm_open} function in the sense that these mappings
1908 are not backed by actual files. However, the descriptor returned by
1909 @code{memfd_create} does not correspond to a named object; the
1910 @var{name} argument is used for debugging purposes only (e.g., will
1911 appear in @file{/proc}), and separate invocations of @code{memfd_create}
1912 with the same @var{name} will not return descriptors for the same region
1913 of memory. The descriptor can also be used to create alias mappings
1914 within the same process.
1916 The descriptor initially refers to a zero-length file. Before mappings
1917 can be created which are backed by memory, the file size needs to be
1918 increased with the @code{ftruncate} function. @xref{File Size}.
1920 The @var{flags} argument can be a combination of the following flags:
1924 @standards{Linux, sys/mman.h}
1925 The descriptor is created with the @code{O_CLOEXEC} flag.
1927 @item MFD_ALLOW_SEALING
1928 @standards{Linux, sys/mman.h}
1929 The descriptor supports the addition of seals using the @code{fcntl}
1933 @standards{Linux, sys/mman.h}
1934 This requests that mappings created using the returned file descriptor
1935 use a larger page size. See @code{MAP_HUGETLB} above for details.
1937 This flag is incompatible with @code{MFD_ALLOW_SEALING}.
1940 @code{memfd_create} returns a file descriptor on success, and @math{-1}
1943 The following @code{errno} error conditions are defined for this
1948 An invalid combination is specified in @var{flags}, or @var{name} is
1952 The @var{name} argument does not point to a string.
1955 The operation would exceed the file descriptor limit for this process.
1958 The operation would exceed the system-wide file descriptor limit.
1961 There is not enough memory for the operation.
1965 @node Waiting for I/O
1966 @section Waiting for Input or Output
1967 @cindex waiting for input or output
1968 @cindex multiplexing input
1969 @cindex input from multiple files
1971 Sometimes a program needs to accept input on multiple input channels
1972 whenever input arrives. For example, some workstations may have devices
1973 such as a digitizing tablet, function button box, or dial box that are
1974 connected via normal asynchronous serial interfaces; good user interface
1975 style requires responding immediately to input on any device. Another
1976 example is a program that acts as a server to several other processes
1977 via pipes or sockets.
1979 You cannot normally use @code{read} for this purpose, because this
1980 blocks the program until input is available on one particular file
1981 descriptor; input on other channels won't wake it up. You could set
1982 nonblocking mode and poll each file descriptor in turn, but this is very
1985 A better solution is to use the @code{select} function. This blocks the
1986 program until input or output is ready on a specified set of file
1987 descriptors, or until a timer expires, whichever comes first. This
1988 facility is declared in the header file @file{sys/types.h}.
1991 In the case of a server socket (@pxref{Listening}), we say that
1992 ``input'' is available when there are pending connections that could be
1993 accepted (@pxref{Accepting Connections}). @code{accept} for server
1994 sockets blocks and interacts with @code{select} just as @code{read} does
1997 @cindex file descriptor sets, for @code{select}
1998 The file descriptor sets for the @code{select} function are specified
1999 as @code{fd_set} objects. Here is the description of the data type
2000 and some macros for manipulating these objects.
2002 @deftp {Data Type} fd_set
2003 @standards{BSD, sys/types.h}
2004 The @code{fd_set} data type represents file descriptor sets for the
2005 @code{select} function. It is actually a bit array.
2008 @deftypevr Macro int FD_SETSIZE
2009 @standards{BSD, sys/types.h}
2010 The value of this macro is the maximum number of file descriptors that a
2011 @code{fd_set} object can hold information about. On systems with a
2012 fixed maximum number, @code{FD_SETSIZE} is at least that number. On
2013 some systems, including GNU, there is no absolute limit on the number of
2014 descriptors open, but this macro still has a constant value which
2015 controls the number of bits in an @code{fd_set}; if you get a file
2016 descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
2017 that descriptor into an @code{fd_set}.
2020 @deftypefn Macro void FD_ZERO (fd_set *@var{set})
2021 @standards{BSD, sys/types.h}
2022 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
2023 This macro initializes the file descriptor set @var{set} to be the
2027 @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
2028 @standards{BSD, sys/types.h}
2029 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
2030 @c Setting a bit isn't necessarily atomic, so there's a potential race
2031 @c here if set is not used exclusively.
2032 This macro adds @var{filedes} to the file descriptor set @var{set}.
2034 The @var{filedes} parameter must not have side effects since it is
2035 evaluated more than once.
2038 @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
2039 @standards{BSD, sys/types.h}
2040 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
2041 @c Setting a bit isn't necessarily atomic, so there's a potential race
2042 @c here if set is not used exclusively.
2043 This macro removes @var{filedes} from the file descriptor set @var{set}.
2045 The @var{filedes} parameter must not have side effects since it is
2046 evaluated more than once.
2049 @deftypefn Macro int FD_ISSET (int @var{filedes}, const fd_set *@var{set})
2050 @standards{BSD, sys/types.h}
2051 @safety{@prelim{}@mtsafe{@mtsrace{:set}}@assafe{}@acsafe{}}
2052 This macro returns a nonzero value (true) if @var{filedes} is a member
2053 of the file descriptor set @var{set}, and zero (false) otherwise.
2055 The @var{filedes} parameter must not have side effects since it is
2056 evaluated more than once.
2059 Next, here is the description of the @code{select} function itself.
2061 @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})
2062 @standards{BSD, sys/types.h}
2063 @safety{@prelim{}@mtsafe{@mtsrace{:read-fds} @mtsrace{:write-fds} @mtsrace{:except-fds}}@assafe{}@acsafe{}}
2064 @c The select syscall is preferred, but pselect6 may be used instead,
2065 @c which requires converting timeout to a timespec and back. The
2066 @c conversions are not atomic.
2067 The @code{select} function blocks the calling process until there is
2068 activity on any of the specified sets of file descriptors, or until the
2069 timeout period has expired.
2071 The file descriptors specified by the @var{read-fds} argument are
2072 checked to see if they are ready for reading; the @var{write-fds} file
2073 descriptors are checked to see if they are ready for writing; and the
2074 @var{except-fds} file descriptors are checked for exceptional
2075 conditions. You can pass a null pointer for any of these arguments if
2076 you are not interested in checking for that kind of condition.
2078 A file descriptor is considered ready for reading if a @code{read}
2079 call will not block. This usually includes the read offset being at
2080 the end of the file or there is an error to report. A server socket
2081 is considered ready for reading if there is a pending connection which
2082 can be accepted with @code{accept}; @pxref{Accepting Connections}. A
2083 client socket is ready for writing when its connection is fully
2084 established; @pxref{Connecting}.
2086 ``Exceptional conditions'' does not mean errors---errors are reported
2087 immediately when an erroneous system call is executed, and do not
2088 constitute a state of the descriptor. Rather, they include conditions
2089 such as the presence of an urgent message on a socket. (@xref{Sockets},
2090 for information on urgent messages.)
2092 The @code{select} function checks only the first @var{nfds} file
2093 descriptors. The usual thing is to pass @code{FD_SETSIZE} as the value
2096 The @var{timeout} specifies the maximum time to wait. If you pass a
2097 null pointer for this argument, it means to block indefinitely until
2098 one of the file descriptors is ready. Otherwise, you should provide
2099 the time in @code{struct timeval} format; see @ref{Time Types}.
2100 Specify zero as the time (a @code{struct timeval} containing all
2101 zeros) if you want to find out which descriptors are ready without
2102 waiting if none are ready.
2104 The normal return value from @code{select} is the total number of ready file
2105 descriptors in all of the sets. Each of the argument sets is overwritten
2106 with information about the descriptors that are ready for the corresponding
2107 operation. Thus, to see if a particular descriptor @var{desc} has input,
2108 use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
2110 If @code{select} returns because the timeout period expires, it returns
2113 Any signal will cause @code{select} to return immediately. So if your
2114 program uses signals, you can't rely on @code{select} to keep waiting
2115 for the full time specified. If you want to be sure of waiting for a
2116 particular amount of time, you must check for @code{EINTR} and repeat
2117 the @code{select} with a newly calculated timeout based on the current
2118 time. See the example below. See also @ref{Interrupted Primitives}.
2120 If an error occurs, @code{select} returns @code{-1} and does not modify
2121 the argument file descriptor sets. The following @code{errno} error
2122 conditions are defined for this function:
2126 One of the file descriptor sets specified an invalid file descriptor.
2129 The operation was interrupted by a signal. @xref{Interrupted Primitives}.
2132 The @var{timeout} argument is invalid; one of the components is negative
2137 @strong{Portability Note:} The @code{select} function is a BSD Unix
2140 Here is an example showing how you can use @code{select} to establish a
2141 timeout period for reading from a file descriptor. The @code{input_timeout}
2142 function blocks the calling process until input is available on the
2143 file descriptor, or until the timeout period expires.
2146 @include select.c.texi
2149 There is another example showing the use of @code{select} to multiplex
2150 input from multiple sockets in @ref{Server Example}.
2153 @node Synchronizing I/O
2154 @section Synchronizing I/O operations
2156 @cindex synchronizing
2157 In most modern operating systems, the normal I/O operations are not
2158 executed synchronously. I.e., even if a @code{write} system call
2159 returns, this does not mean the data is actually written to the media,
2162 In situations where synchronization points are necessary, you can use
2163 special functions which ensure that all operations finish before
2166 @deftypefun void sync (void)
2167 @standards{X/Open, unistd.h}
2168 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2169 A call to this function will not return as long as there is data which
2170 has not been written to the device. All dirty buffers in the kernel will
2171 be written and so an overall consistent system can be achieved (if no
2172 other process in parallel writes data).
2174 A prototype for @code{sync} can be found in @file{unistd.h}.
2177 Programs more often want to ensure that data written to a given file is
2178 committed, rather than all data in the system. For this, @code{sync} is overkill.
2181 @deftypefun int fsync (int @var{fildes})
2182 @standards{POSIX, unistd.h}
2183 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2184 The @code{fsync} function can be used to make sure all data associated with
2185 the open file @var{fildes} is written to the device associated with the
2186 descriptor. The function call does not return unless all actions have
2189 A prototype for @code{fsync} can be found in @file{unistd.h}.
2191 This function is a cancellation point in multi-threaded programs. This
2192 is a problem if the thread allocates some resources (like memory, file
2193 descriptors, semaphores or whatever) at the time @code{fsync} is
2194 called. If the thread gets canceled these resources stay allocated
2195 until the program ends. To avoid this, calls to @code{fsync} should be
2196 protected using cancellation handlers.
2197 @c ref pthread_cleanup_push / pthread_cleanup_pop
2199 The return value of the function is zero if no error occurred. Otherwise
2200 it is @math{-1} and the global variable @code{errno} is set to the
2204 The descriptor @var{fildes} is not valid.
2207 No synchronization is possible since the system does not implement this.
2211 Sometimes it is not even necessary to write all data associated with a
2212 file descriptor. E.g., in database files which do not change in size it
2213 is enough to write all the file content data to the device.
2214 Meta-information, like the modification time etc., are not that important
2215 and leaving such information uncommitted does not prevent a successful
2216 recovery of the file in case of a problem.
2218 @deftypefun int fdatasync (int @var{fildes})
2219 @standards{POSIX, unistd.h}
2220 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2221 When a call to the @code{fdatasync} function returns, it is ensured
2222 that all of the file data is written to the device. For all pending I/O
2223 operations, the parts guaranteeing data integrity finished.
2225 Not all systems implement the @code{fdatasync} operation. On systems
2226 missing this functionality @code{fdatasync} is emulated by a call to
2227 @code{fsync} since the performed actions are a superset of those
2228 required by @code{fdatasync}.
2230 The prototype for @code{fdatasync} is in @file{unistd.h}.
2232 The return value of the function is zero if no error occurred. Otherwise
2233 it is @math{-1} and the global variable @code{errno} is set to the
2237 The descriptor @var{fildes} is not valid.
2240 No synchronization is possible since the system does not implement this.
2245 @node Asynchronous I/O
2246 @section Perform I/O Operations in Parallel
2248 The POSIX.1b standard defines a new set of I/O operations which can
2249 significantly reduce the time an application spends waiting for I/O. The
2250 new functions allow a program to initiate one or more I/O operations and
2251 then immediately resume normal work while the I/O operations are
2252 executed in parallel. This functionality is available if the
2253 @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}.
2255 These functions are part of the library with realtime functions named
2256 @file{librt}. They are not actually part of the @file{libc} binary.
2257 The implementation of these functions can be done using support in the
2258 kernel (if available) or using an implementation based on threads at
2259 userlevel. In the latter case it might be necessary to link applications
2260 with the thread library @file{libpthread} in addition to @file{librt}.
2262 All AIO operations operate on files which were opened previously. There
2263 might be arbitrarily many operations running for one file. The
2264 asynchronous I/O operations are controlled using a data structure named
2265 @code{struct aiocb} (@dfn{AIO control block}). It is defined in
2266 @file{aio.h} as follows.
2268 @deftp {Data Type} {struct aiocb}
2269 @standards{POSIX.1b, aio.h}
2270 The POSIX.1b standard mandates that the @code{struct aiocb} structure
2271 contains at least the members described in the following table. There
2272 might be more elements which are used by the implementation, but
2273 depending upon these elements is not portable and is highly deprecated.
2276 @item int aio_fildes
2277 This element specifies the file descriptor to be used for the
2278 operation. It must be a legal descriptor, otherwise the operation will
2281 The device on which the file is opened must allow the seek operation.
2282 I.e., it is not possible to use any of the AIO operations on devices
2283 like terminals where an @code{lseek} call would lead to an error.
2285 @item off_t aio_offset
2286 This element specifies the offset in the file at which the operation (input
2287 or output) is performed. Since the operations are carried out in arbitrary
2288 order and more than one operation for one file descriptor can be
2289 started, one cannot expect a current read/write position of the file
2292 @item volatile void *aio_buf
2293 This is a pointer to the buffer with the data to be written or the place
2294 where the read data is stored.
2296 @item size_t aio_nbytes
2297 This element specifies the length of the buffer pointed to by @code{aio_buf}.
2299 @item int aio_reqprio
2300 If the platform has defined @code{_POSIX_PRIORITIZED_IO} and
2301 @code{_POSIX_PRIORITY_SCHEDULING}, the AIO requests are
2302 processed based on the current scheduling priority. The
2303 @code{aio_reqprio} element can then be used to lower the priority of the
2306 @item struct sigevent aio_sigevent
2307 This element specifies how the calling process is notified once the
2308 operation terminates. If the @code{sigev_notify} element is
2309 @code{SIGEV_NONE}, no notification is sent. If it is @code{SIGEV_SIGNAL},
2310 the signal determined by @code{sigev_signo} is sent. Otherwise,
2311 @code{sigev_notify} must be @code{SIGEV_THREAD}. In this case, a thread
2312 is created which starts executing the function pointed to by
2313 @code{sigev_notify_function}.
2315 @item int aio_lio_opcode
2316 This element is only used by the @code{lio_listio} and
2317 @code{lio_listio64} functions. Since these functions allow an
2318 arbitrary number of operations to start at once, and each operation can be
2319 input or output (or nothing), the information must be stored in the
2320 control block. The possible values are:
2324 Start a read operation. Read from the file at position
2325 @code{aio_offset} and store the next @code{aio_nbytes} bytes in the
2326 buffer pointed to by @code{aio_buf}.
2329 Start a write operation. Write @code{aio_nbytes} bytes starting at
2330 @code{aio_buf} into the file starting at position @code{aio_offset}.
2333 Do nothing for this control block. This value is useful sometimes when
2334 an array of @code{struct aiocb} values contains holes, i.e., some of the
2335 values must not be handled although the whole array is presented to the
2336 @code{lio_listio} function.
2340 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
2341 32 bit machine, this type is in fact @code{struct aiocb64}, since the LFS
2342 interface transparently replaces the @code{struct aiocb} definition.
2345 For use with the AIO functions defined in the LFS, there is a similar type
2346 defined which replaces the types of the appropriate members with larger
2347 types but otherwise is equivalent to @code{struct aiocb}. Particularly,
2348 all member names are the same.
2350 @deftp {Data Type} {struct aiocb64}
2351 @standards{POSIX.1b, aio.h}
2353 @item int aio_fildes
2354 This element specifies the file descriptor which is used for the
2355 operation. It must be a legal descriptor since otherwise the operation
2356 fails for obvious reasons.
2358 The device on which the file is opened must allow the seek operation.
2359 I.e., it is not possible to use any of the AIO operations on devices
2360 like terminals where an @code{lseek} call would lead to an error.
2362 @item off64_t aio_offset
2363 This element specifies at which offset in the file the operation (input
2364 or output) is performed. Since the operation are carried in arbitrary
2365 order and more than one operation for one file descriptor can be
2366 started, one cannot expect a current read/write position of the file
2369 @item volatile void *aio_buf
2370 This is a pointer to the buffer with the data to be written or the place
2371 where the read data is stored.
2373 @item size_t aio_nbytes
2374 This element specifies the length of the buffer pointed to by @code{aio_buf}.
2376 @item int aio_reqprio
2377 If for the platform @code{_POSIX_PRIORITIZED_IO} and
2378 @code{_POSIX_PRIORITY_SCHEDULING} are defined the AIO requests are
2379 processed based on the current scheduling priority. The
2380 @code{aio_reqprio} element can then be used to lower the priority of the
2383 @item struct sigevent aio_sigevent
2384 This element specifies how the calling process is notified once the
2385 operation terminates. If the @code{sigev_notify} element is
2386 @code{SIGEV_NONE} no notification is sent. If it is @code{SIGEV_SIGNAL},
2387 the signal determined by @code{sigev_signo} is sent. Otherwise,
2388 @code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread
2389 is created which starts executing the function pointed to by
2390 @code{sigev_notify_function}.
2392 @item int aio_lio_opcode
2393 This element is only used by the @code{lio_listio} and
2394 @code{lio_listio64} functions. Since these functions allow an
2395 arbitrary number of operations to start at once, and since each operation can be
2396 input or output (or nothing), the information must be stored in the
2397 control block. See the description of @code{struct aiocb} for a description
2398 of the possible values.
2401 When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a
2402 32 bit machine, this type is available under the name @code{struct
2403 aiocb64}, since the LFS transparently replaces the old interface.
2407 * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
2408 * Status of AIO Operations:: Getting the Status of AIO Operations.
2409 * Synchronizing AIO Operations:: Getting into a consistent state.
2410 * Cancel AIO Operations:: Cancellation of AIO Operations.
2411 * Configuration of AIO:: How to optimize the AIO implementation.
2414 @node Asynchronous Reads/Writes
2415 @subsection Asynchronous Read and Write Operations
2417 @deftypefun int aio_read (struct aiocb *@var{aiocbp})
2418 @standards{POSIX.1b, aio.h}
2419 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2420 @c Calls aio_enqueue_request.
2421 @c aio_enqueue_request @asulock @ascuheap @aculock @acsmem
2423 @c pthread_getschedparam @asulock @aculock
2424 @c lll_lock (pthread descriptor's lock) @asulock @aculock
2425 @c sched_getparam ok
2426 @c sched_getscheduler ok
2427 @c lll_unlock @aculock
2428 @c pthread_mutex_lock (aio_requests_mutex) @asulock @aculock
2429 @c get_elem @ascuheap @acsmem [@asucorrupt @acucorrupt]
2430 @c realloc @ascuheap @acsmem
2431 @c calloc @ascuheap @acsmem
2432 @c aio_create_helper_thread @asulock @ascuheap @aculock @acsmem
2433 @c pthread_attr_init ok
2434 @c pthread_attr_setdetachstate ok
2435 @c pthread_get_minstack ok
2436 @c pthread_attr_setstacksize ok
2440 @c SYSCALL rt_sigprocmask ok
2441 @c pthread_create @asulock @ascuheap @aculock @acsmem
2442 @c lll_lock (default_pthread_attr_lock) @asulock @aculock
2443 @c alloca/malloc @ascuheap @acsmem
2444 @c lll_unlock @aculock
2445 @c allocate_stack @asulock @ascuheap @aculock @acsmem
2447 @c lll_lock (default_pthread_attr_lock) @asulock @aculock
2448 @c lll_unlock @aculock
2449 @c _dl_allocate_tls @ascuheap @acsmem
2450 @c _dl_allocate_tls_storage @ascuheap @acsmem
2451 @c memalign @ascuheap @acsmem
2454 @c free @ascuheap @acsmem
2455 @c allocate_dtv @ascuheap @acsmem
2456 @c calloc @ascuheap @acsmem
2460 @c lll_lock (stack_cache_lock) @asulock @aculock
2464 @c stack_list_del dup
2465 @c stack_list_add dup
2466 @c lll_unlock @aculock
2467 @c _dl_allocate_tls_init ok
2470 @c atomic_increment_val ok
2472 @c change_stack_perm ok
2475 @c stack_list_del dup
2476 @c _dl_deallocate_tls dup
2478 @c THREAD_COPY_STACK_GUARD ok
2479 @c THREAD_COPY_POINTER_GUARD ok
2480 @c atomic_exchange_acq ok
2481 @c lll_futex_wake ok
2482 @c deallocate_stack @asulock @ascuheap @aculock @acsmem
2483 @c lll_lock (state_cache_lock) @asulock @aculock
2484 @c stack_list_del ok
2485 @c atomic_write_barrier ok
2487 @c atomic_write_barrier ok
2488 @c queue_stack @ascuheap @acsmem
2489 @c stack_list_add ok
2490 @c atomic_write_barrier ok
2492 @c atomic_write_barrier ok
2493 @c free_stacks @ascuheap @acsmem
2494 @c list_for_each_prev_safe ok
2497 @c stack_list_del dup
2498 @c _dl_deallocate_tls dup
2500 @c _dl_deallocate_tls @ascuheap @acsmem
2501 @c free @ascuheap @acsmem
2502 @c lll_unlock @aculock
2503 @c create_thread @asulock @ascuheap @aculock @acsmem
2506 @c do_clone @asulock @ascuheap @aculock @acsmem
2507 @c PREPARE_CREATE ok
2508 @c lll_lock (pd->lock) @asulock @aculock
2509 @c atomic_increment ok
2511 @c atomic_decrement ok
2512 @c atomic_exchange_acq ok
2513 @c lll_futex_wake ok
2514 @c deallocate_stack dup
2515 @c sched_setaffinity ok
2517 @c sched_setscheduler ok
2518 @c atomic_compare_and_exchange_bool_acq ok
2519 @c nptl_create_event ok
2520 @c lll_unlock (pd->lock) @aculock
2521 @c free @ascuheap @acsmem
2522 @c pthread_attr_destroy ok (cpuset won't be set, so free isn't called)
2523 @c add_request_to_runlist ok
2524 @c pthread_cond_signal ok
2525 @c aio_free_request ok
2526 @c pthread_mutex_unlock @aculock
2528 @c (in the new thread, initiated with clone)
2531 @c ctype_init @mtslocale
2532 @c atomic_exchange_acq ok
2533 @c lll_futex_wake ok
2537 @c CANCEL_ASYNC -> pthread_enable_asynccancel ok
2539 @c pthread_unwind ok
2540 @c Unwind_ForcedUnwind or longjmp ok [@ascuheap @acsmem?]
2541 @c lll_lock @asulock @aculock
2542 @c lll_unlock @asulock @aculock
2543 @c CANCEL_RESET -> pthread_disable_asynccancel ok
2544 @c lll_futex_wait ok
2545 @c ->start_routine ok -----
2546 @c call_tls_dtors @asulock @ascuheap @aculock @acsmem
2547 @c user-supplied dtor
2548 @c rtld_lock_lock_recursive (dl_load_lock) @asulock @aculock
2549 @c rtld_lock_unlock_recursive @aculock
2550 @c free @ascuheap @acsmem
2551 @c nptl_deallocate_tsd @ascuheap @acsmem
2552 @c tsd user-supplied dtors ok
2553 @c free @ascuheap @acsmem
2554 @c libc_thread_freeres
2555 @c libc_thread_subfreeres ok
2556 @c atomic_decrement_and_test ok
2559 @c atomic_compare_exchange_bool_acq ok
2560 @c nptl_death_event ok
2561 @c lll_robust_dead ok
2564 @c free_tcb @asulock @ascuheap @aculock @acsmem
2565 @c free @ascuheap @acsmem
2566 @c deallocate_stack @asulock @ascuheap @aculock @acsmem
2567 @c lll_futex_wait ok
2568 @c exit_thread_inline ok
2571 This function initiates an asynchronous read operation. It
2572 immediately returns after the operation was enqueued or when an
2573 error was encountered.
2575 The first @code{aiocbp->aio_nbytes} bytes of the file for which
2576 @code{aiocbp->aio_fildes} is a descriptor are written to the buffer
2577 starting at @code{aiocbp->aio_buf}. Reading starts at the absolute
2578 position @code{aiocbp->aio_offset} in the file.
2580 If prioritized I/O is supported by the platform the
2581 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
2582 the request is actually enqueued.
2584 The calling process is notified about the termination of the read
2585 request according to the @code{aiocbp->aio_sigevent} value.
2587 When @code{aio_read} returns, the return value is zero if no error
2588 occurred that can be found before the process is enqueued. If such an
2589 early error is found, the function returns @math{-1} and sets
2590 @code{errno} to one of the following values:
2594 The request was not enqueued due to (temporarily) exceeded resource
2597 The @code{aio_read} function is not implemented.
2599 The @code{aiocbp->aio_fildes} descriptor is not valid. This condition
2600 need not be recognized before enqueueing the request and so this error
2601 might also be signaled asynchronously.
2603 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is
2604 invalid. This condition need not be recognized before enqueueing the
2605 request and so this error might also be signaled asynchronously.
2608 If @code{aio_read} returns zero, the current status of the request
2609 can be queried using @code{aio_error} and @code{aio_return} functions.
2610 As long as the value returned by @code{aio_error} is @code{EINPROGRESS}
2611 the operation has not yet completed. If @code{aio_error} returns zero,
2612 the operation successfully terminated, otherwise the value is to be
2613 interpreted as an error code. If the function terminated, the result of
2614 the operation can be obtained using a call to @code{aio_return}. The
2615 returned value is the same as an equivalent call to @code{read} would
2616 have returned. Possible error codes returned by @code{aio_error} are:
2620 The @code{aiocbp->aio_fildes} descriptor is not valid.
2622 The operation was canceled before the operation was finished
2623 (@pxref{Cancel AIO Operations})
2625 The @code{aiocbp->aio_offset} value is invalid.
2628 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2629 function is in fact @code{aio_read64} since the LFS interface transparently
2630 replaces the normal implementation.
2633 @deftypefun int aio_read64 (struct aiocb64 *@var{aiocbp})
2634 @standards{Unix98, aio.h}
2635 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2636 This function is similar to the @code{aio_read} function. The only
2637 difference is that on @w{32 bit} machines, the file descriptor should
2638 be opened in the large file mode. Internally, @code{aio_read64} uses
2639 functionality equivalent to @code{lseek64} (@pxref{File Position
2640 Primitive}) to position the file descriptor correctly for the reading,
2641 as opposed to the @code{lseek} functionality used in @code{aio_read}.
2643 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2644 function is available under the name @code{aio_read} and so transparently
2645 replaces the interface for small files on 32 bit machines.
2648 To write data asynchronously to a file, there exists an equivalent pair
2649 of functions with a very similar interface.
2651 @deftypefun int aio_write (struct aiocb *@var{aiocbp})
2652 @standards{POSIX.1b, aio.h}
2653 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2654 This function initiates an asynchronous write operation. The function
2655 call immediately returns after the operation was enqueued or if before
2656 this happens an error was encountered.
2658 The first @code{aiocbp->aio_nbytes} bytes from the buffer starting at
2659 @code{aiocbp->aio_buf} are written to the file for which
2660 @code{aiocbp->aio_fildes} is a descriptor, starting at the absolute
2661 position @code{aiocbp->aio_offset} in the file.
2663 If prioritized I/O is supported by the platform, the
2664 @code{aiocbp->aio_reqprio} value is used to adjust the priority before
2665 the request is actually enqueued.
2667 The calling process is notified about the termination of the read
2668 request according to the @code{aiocbp->aio_sigevent} value.
2670 When @code{aio_write} returns, the return value is zero if no error
2671 occurred that can be found before the process is enqueued. If such an
2672 early error is found the function returns @math{-1} and sets
2673 @code{errno} to one of the following values.
2677 The request was not enqueued due to (temporarily) exceeded resource
2680 The @code{aio_write} function is not implemented.
2682 The @code{aiocbp->aio_fildes} descriptor is not valid. This condition
2683 may not be recognized before enqueueing the request, and so this error
2684 might also be signaled asynchronously.
2686 The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqprio} value is
2687 invalid. This condition may not be recognized before enqueueing the
2688 request and so this error might also be signaled asynchronously.
2691 In the case @code{aio_write} returns zero, the current status of the
2692 request can be queried using the @code{aio_error} and @code{aio_return}
2693 functions. As long as the value returned by @code{aio_error} is
2694 @code{EINPROGRESS} the operation has not yet completed. If
2695 @code{aio_error} returns zero, the operation successfully terminated,
2696 otherwise the value is to be interpreted as an error code. If the
2697 function terminated, the result of the operation can be obtained using a call
2698 to @code{aio_return}. The returned value is the same as an equivalent
2699 call to @code{read} would have returned. Possible error codes returned
2700 by @code{aio_error} are:
2704 The @code{aiocbp->aio_fildes} descriptor is not valid.
2706 The operation was canceled before the operation was finished.
2707 (@pxref{Cancel AIO Operations})
2709 The @code{aiocbp->aio_offset} value is invalid.
2712 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2713 function is in fact @code{aio_write64} since the LFS interface transparently
2714 replaces the normal implementation.
2717 @deftypefun int aio_write64 (struct aiocb64 *@var{aiocbp})
2718 @standards{Unix98, aio.h}
2719 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2720 This function is similar to the @code{aio_write} function. The only
2721 difference is that on @w{32 bit} machines the file descriptor should
2722 be opened in the large file mode. Internally @code{aio_write64} uses
2723 functionality equivalent to @code{lseek64} (@pxref{File Position
2724 Primitive}) to position the file descriptor correctly for the writing,
2725 as opposed to the @code{lseek} functionality used in @code{aio_write}.
2727 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2728 function is available under the name @code{aio_write} and so transparently
2729 replaces the interface for small files on 32 bit machines.
2732 Besides these functions with the more or less traditional interface,
2733 POSIX.1b also defines a function which can initiate more than one
2734 operation at a time, and which can handle freely mixed read and write
2735 operations. It is therefore similar to a combination of @code{readv} and
2738 @deftypefun int lio_listio (int @var{mode}, struct aiocb *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
2739 @standards{POSIX.1b, aio.h}
2740 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2741 @c Call lio_listio_internal, that takes the aio_requests_mutex lock and
2742 @c enqueues each request. Then, it waits for notification or prepares
2743 @c for it before releasing the lock. Even though it performs memory
2744 @c allocation and locking of its own, it doesn't add any classes of
2745 @c safety issues that aren't already covered by aio_enqueue_request.
2746 The @code{lio_listio} function can be used to enqueue an arbitrary
2747 number of read and write requests at one time. The requests can all be
2748 meant for the same file, all for different files or every solution in
2751 @code{lio_listio} gets the @var{nent} requests from the array pointed to
2752 by @var{list}. The operation to be performed is determined by the
2753 @code{aio_lio_opcode} member in each element of @var{list}. If this
2754 field is @code{LIO_READ} a read operation is enqueued, similar to a call
2755 of @code{aio_read} for this element of the array (except that the way
2756 the termination is signalled is different, as we will see below). If
2757 the @code{aio_lio_opcode} member is @code{LIO_WRITE} a write operation
2758 is enqueued. Otherwise the @code{aio_lio_opcode} must be @code{LIO_NOP}
2759 in which case this element of @var{list} is simply ignored. This
2760 ``operation'' is useful in situations where one has a fixed array of
2761 @code{struct aiocb} elements from which only a few need to be handled at
2762 a time. Another situation is where the @code{lio_listio} call was
2763 canceled before all requests are processed (@pxref{Cancel AIO
2764 Operations}) and the remaining requests have to be reissued.
2766 The other members of each element of the array pointed to by
2767 @code{list} must have values suitable for the operation as described in
2768 the documentation for @code{aio_read} and @code{aio_write} above.
2770 The @var{mode} argument determines how @code{lio_listio} behaves after
2771 having enqueued all the requests. If @var{mode} is @code{LIO_WAIT} it
2772 waits until all requests terminated. Otherwise @var{mode} must be
2773 @code{LIO_NOWAIT} and in this case the function returns immediately after
2774 having enqueued all the requests. In this case the caller gets a
2775 notification of the termination of all requests according to the
2776 @var{sig} parameter. If @var{sig} is @code{NULL} no notification is
2777 sent. Otherwise a signal is sent or a thread is started, just as
2778 described in the description for @code{aio_read} or @code{aio_write}.
2780 If @var{mode} is @code{LIO_WAIT}, the return value of @code{lio_listio}
2781 is @math{0} when all requests completed successfully. Otherwise the
2782 function returns @math{-1} and @code{errno} is set accordingly. To find
2783 out which request or requests failed one has to use the @code{aio_error}
2784 function on all the elements of the array @var{list}.
2786 In case @var{mode} is @code{LIO_NOWAIT}, the function returns @math{0} if
2787 all requests were enqueued correctly. The current state of the requests
2788 can be found using @code{aio_error} and @code{aio_return} as described
2789 above. If @code{lio_listio} returns @math{-1} in this mode, the
2790 global variable @code{errno} is set accordingly. If a request did not
2791 yet terminate, a call to @code{aio_error} returns @code{EINPROGRESS}. If
2792 the value is different, the request is finished and the error value (or
2793 @math{0}) is returned and the result of the operation can be retrieved
2794 using @code{aio_return}.
2796 Possible values for @code{errno} are:
2800 The resources necessary to queue all the requests are not available at
2801 the moment. The error status for each element of @var{list} must be
2802 checked to determine which request failed.
2804 Another reason could be that the system wide limit of AIO requests is
2805 exceeded. This cannot be the case for the implementation on @gnusystems{}
2806 since no arbitrary limits exist.
2808 The @var{mode} parameter is invalid or @var{nent} is larger than
2809 @code{AIO_LISTIO_MAX}.
2811 One or more of the request's I/O operations failed. The error status of
2812 each request should be checked to determine which one failed.
2814 The @code{lio_listio} function is not supported.
2817 If the @var{mode} parameter is @code{LIO_NOWAIT} and the caller cancels
2818 a request, the error status for this request returned by
2819 @code{aio_error} is @code{ECANCELED}.
2821 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2822 function is in fact @code{lio_listio64} since the LFS interface
2823 transparently replaces the normal implementation.
2826 @deftypefun int lio_listio64 (int @var{mode}, struct aiocb64 *const @var{list}[], int @var{nent}, struct sigevent *@var{sig})
2827 @standards{Unix98, aio.h}
2828 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2829 This function is similar to the @code{lio_listio} function. The only
2830 difference is that on @w{32 bit} machines, the file descriptor should
2831 be opened in the large file mode. Internally, @code{lio_listio64} uses
2832 functionality equivalent to @code{lseek64} (@pxref{File Position
2833 Primitive}) to position the file descriptor correctly for the reading or
2834 writing, as opposed to the @code{lseek} functionality used in
2837 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
2838 function is available under the name @code{lio_listio} and so
2839 transparently replaces the interface for small files on 32 bit
2843 @node Status of AIO Operations
2844 @subsection Getting the Status of AIO Operations
2846 As already described in the documentation of the functions in the last
2847 section, it must be possible to get information about the status of an I/O
2848 request. When the operation is performed truly asynchronously (as with
2849 @code{aio_read} and @code{aio_write} and with @code{lio_listio} when the
2850 mode is @code{LIO_NOWAIT}), one sometimes needs to know whether a
2851 specific request already terminated and if so, what the result was.
2852 The following two functions allow you to get this kind of information.
2854 @deftypefun int aio_error (const struct aiocb *@var{aiocbp})
2855 @standards{POSIX.1b, aio.h}
2856 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2857 This function determines the error state of the request described by the
2858 @code{struct aiocb} variable pointed to by @var{aiocbp}. If the
2859 request has not yet terminated the value returned is always
2860 @code{EINPROGRESS}. Once the request has terminated the value
2861 @code{aio_error} returns is either @math{0} if the request completed
2862 successfully or it returns the value which would be stored in the
2863 @code{errno} variable if the request would have been done using
2864 @code{read}, @code{write}, or @code{fsync}.
2866 The function can return @code{ENOSYS} if it is not implemented. It
2867 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2868 refer to an asynchronous operation whose return status is not yet known.
2870 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2871 function is in fact @code{aio_error64} since the LFS interface
2872 transparently replaces the normal implementation.
2875 @deftypefun int aio_error64 (const struct aiocb64 *@var{aiocbp})
2876 @standards{Unix98, aio.h}
2877 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2878 This function is similar to @code{aio_error} with the only difference
2879 that the argument is a reference to a variable of type @code{struct
2882 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2883 function is available under the name @code{aio_error} and so
2884 transparently replaces the interface for small files on 32 bit
2888 @deftypefun ssize_t aio_return (struct aiocb *@var{aiocbp})
2889 @standards{POSIX.1b, aio.h}
2890 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2891 This function can be used to retrieve the return status of the operation
2892 carried out by the request described in the variable pointed to by
2893 @var{aiocbp}. As long as the error status of this request as returned
2894 by @code{aio_error} is @code{EINPROGRESS} the return value of this function is
2897 Once the request is finished this function can be used exactly once to
2898 retrieve the return value. Following calls might lead to undefined
2899 behavior. The return value itself is the value which would have been
2900 returned by the @code{read}, @code{write}, or @code{fsync} call.
2902 The function can return @code{ENOSYS} if it is not implemented. It
2903 could also return @code{EINVAL} if the @var{aiocbp} parameter does not
2904 refer to an asynchronous operation whose return status is not yet known.
2906 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2907 function is in fact @code{aio_return64} since the LFS interface
2908 transparently replaces the normal implementation.
2911 @deftypefun ssize_t aio_return64 (struct aiocb64 *@var{aiocbp})
2912 @standards{Unix98, aio.h}
2913 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2914 This function is similar to @code{aio_return} with the only difference
2915 that the argument is a reference to a variable of type @code{struct
2918 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2919 function is available under the name @code{aio_return} and so
2920 transparently replaces the interface for small files on 32 bit
2924 @node Synchronizing AIO Operations
2925 @subsection Getting into a Consistent State
2927 When dealing with asynchronous operations it is sometimes necessary to
2928 get into a consistent state. This would mean for AIO that one wants to
2929 know whether a certain request or a group of requests were processed.
2930 This could be done by waiting for the notification sent by the system
2931 after the operation terminated, but this sometimes would mean wasting
2932 resources (mainly computation time). Instead POSIX.1b defines two
2933 functions which will help with most kinds of consistency.
2935 The @code{aio_fsync} and @code{aio_fsync64} functions are only available
2936 if the symbol @code{_POSIX_SYNCHRONIZED_IO} is defined in @file{unistd.h}.
2938 @cindex synchronizing
2939 @deftypefun int aio_fsync (int @var{op}, struct aiocb *@var{aiocbp})
2940 @standards{POSIX.1b, aio.h}
2941 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2942 @c After fcntl to check that the FD is open, it calls
2943 @c aio_enqueue_request.
2944 Calling this function forces all I/O operations queued at the
2945 time of the function call operating on the file descriptor
2946 @code{aiocbp->aio_fildes} into the synchronized I/O completion state
2947 (@pxref{Synchronizing I/O}). The @code{aio_fsync} function returns
2948 immediately but the notification through the method described in
2949 @code{aiocbp->aio_sigevent} will happen only after all requests for this
2950 file descriptor have terminated and the file is synchronized. This also
2951 means that requests for this very same file descriptor which are queued
2952 after the synchronization request are not affected.
2954 If @var{op} is @code{O_DSYNC} the synchronization happens as with a call
2955 to @code{fdatasync}. Otherwise @var{op} should be @code{O_SYNC} and
2956 the synchronization happens as with @code{fsync}.
2958 As long as the synchronization has not happened, a call to
2959 @code{aio_error} with the reference to the object pointed to by
2960 @var{aiocbp} returns @code{EINPROGRESS}. Once the synchronization is
2961 done @code{aio_error} return @math{0} if the synchronization was not
2962 successful. Otherwise the value returned is the value to which the
2963 @code{fsync} or @code{fdatasync} function would have set the
2964 @code{errno} variable. In this case nothing can be assumed about the
2965 consistency of the data written to this file descriptor.
2967 The return value of this function is @math{0} if the request was
2968 successfully enqueued. Otherwise the return value is @math{-1} and
2969 @code{errno} is set to one of the following values:
2973 The request could not be enqueued due to temporary lack of resources.
2975 The file descriptor @code{@var{aiocbp}->aio_fildes} is not valid.
2977 The implementation does not support I/O synchronization or the @var{op}
2978 parameter is other than @code{O_DSYNC} and @code{O_SYNC}.
2980 This function is not implemented.
2983 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2984 function is in fact @code{aio_fsync64} since the LFS interface
2985 transparently replaces the normal implementation.
2988 @deftypefun int aio_fsync64 (int @var{op}, struct aiocb64 *@var{aiocbp})
2989 @standards{Unix98, aio.h}
2990 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
2991 This function is similar to @code{aio_fsync} with the only difference
2992 that the argument is a reference to a variable of type @code{struct
2995 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2996 function is available under the name @code{aio_fsync} and so
2997 transparently replaces the interface for small files on 32 bit
3001 Another method of synchronization is to wait until one or more requests of a
3002 specific set terminated. This could be achieved by the @code{aio_*}
3003 functions to notify the initiating process about the termination but in
3004 some situations this is not the ideal solution. In a program which
3005 constantly updates clients somehow connected to the server it is not
3006 always the best solution to go round robin since some connections might
3007 be slow. On the other hand letting the @code{aio_*} functions notify the
3008 caller might also be not the best solution since whenever the process
3009 works on preparing data for a client it makes no sense to be
3010 interrupted by a notification since the new client will not be handled
3011 before the current client is served. For situations like this
3012 @code{aio_suspend} should be used.
3014 @deftypefun int aio_suspend (const struct aiocb *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
3015 @standards{POSIX.1b, aio.h}
3016 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
3017 @c Take aio_requests_mutex, set up waitlist and requestlist, wait
3018 @c for completion or timeout, and release the mutex.
3019 When calling this function, the calling thread is suspended until at
3020 least one of the requests pointed to by the @var{nent} elements of the
3021 array @var{list} has completed. If any of the requests has already
3022 completed at the time @code{aio_suspend} is called, the function returns
3023 immediately. Whether a request has terminated or not is determined by
3024 comparing the error status of the request with @code{EINPROGRESS}. If
3025 an element of @var{list} is @code{NULL}, the entry is simply ignored.
3027 If no request has finished, the calling process is suspended. If
3028 @var{timeout} is @code{NULL}, the process is not woken until a request
3029 has finished. If @var{timeout} is not @code{NULL}, the process remains
3030 suspended at least as long as specified in @var{timeout}. In this case,
3031 @code{aio_suspend} returns with an error.
3033 The return value of the function is @math{0} if one or more requests
3034 from the @var{list} have terminated. Otherwise the function returns
3035 @math{-1} and @code{errno} is set to one of the following values:
3039 None of the requests from the @var{list} completed in the time specified
3042 A signal interrupted the @code{aio_suspend} function. This signal might
3043 also be sent by the AIO implementation while signalling the termination
3044 of one of the requests.
3046 The @code{aio_suspend} function is not implemented.
3049 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
3050 function is in fact @code{aio_suspend64} since the LFS interface
3051 transparently replaces the normal implementation.
3054 @deftypefun int aio_suspend64 (const struct aiocb64 *const @var{list}[], int @var{nent}, const struct timespec *@var{timeout})
3055 @standards{Unix98, aio.h}
3056 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
3057 This function is similar to @code{aio_suspend} with the only difference
3058 that the argument is a reference to a variable of type @code{struct
3061 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
3062 function is available under the name @code{aio_suspend} and so
3063 transparently replaces the interface for small files on 32 bit
3067 @node Cancel AIO Operations
3068 @subsection Cancellation of AIO Operations
3070 When one or more requests are asynchronously processed, it might be
3071 useful in some situations to cancel a selected operation, e.g., if it
3072 becomes obvious that the written data is no longer accurate and would
3073 have to be overwritten soon. As an example, assume an application, which
3074 writes data in files in a situation where new incoming data would have
3075 to be written in a file which will be updated by an enqueued request.
3076 The POSIX AIO implementation provides such a function, but this function
3077 is not capable of forcing the cancellation of the request. It is up to the
3078 implementation to decide whether it is possible to cancel the operation
3079 or not. Therefore using this function is merely a hint.
3081 @deftypefun int aio_cancel (int @var{fildes}, struct aiocb *@var{aiocbp})
3082 @standards{POSIX.1b, aio.h}
3083 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
3084 @c After fcntl to check the fd is open, hold aio_requests_mutex, call
3085 @c aio_find_req_fd, aio_remove_request, then aio_notify and
3086 @c aio_free_request each request before releasing the lock.
3087 @c aio_notify calls aio_notify_only and free, besides cond signal or
3088 @c similar. aio_notify_only calls pthread_attr_init,
3089 @c pthread_attr_setdetachstate, malloc, pthread_create,
3090 @c notify_func_wrapper, aio_sigqueue, getpid, raise.
3091 @c notify_func_wraper calls aio_start_notify_thread, free and then the
3092 @c notifier function.
3093 The @code{aio_cancel} function can be used to cancel one or more
3094 outstanding requests. If the @var{aiocbp} parameter is @code{NULL}, the
3095 function tries to cancel all of the outstanding requests which would process
3096 the file descriptor @var{fildes} (i.e., whose @code{aio_fildes} member
3097 is @var{fildes}). If @var{aiocbp} is not @code{NULL}, @code{aio_cancel}
3098 attempts to cancel the specific request pointed to by @var{aiocbp}.
3100 For requests which were successfully canceled, the normal notification
3101 about the termination of the request should take place. I.e., depending
3102 on the @code{struct sigevent} object which controls this, nothing
3103 happens, a signal is sent or a thread is started. If the request cannot
3104 be canceled, it terminates the usual way after performing the operation.
3106 After a request is successfully canceled, a call to @code{aio_error} with
3107 a reference to this request as the parameter will return
3108 @code{ECANCELED} and a call to @code{aio_return} will return @math{-1}.
3109 If the request wasn't canceled and is still running the error status is
3110 still @code{EINPROGRESS}.
3112 The return value of the function is @code{AIO_CANCELED} if there were
3113 requests which haven't terminated and which were successfully canceled.
3114 If there is one or more requests left which couldn't be canceled, the
3115 return value is @code{AIO_NOTCANCELED}. In this case @code{aio_error}
3116 must be used to find out which of the, perhaps multiple, requests (if
3117 @var{aiocbp} is @code{NULL}) weren't successfully canceled. If all
3118 requests already terminated at the time @code{aio_cancel} is called the
3119 return value is @code{AIO_ALLDONE}.
3121 If an error occurred during the execution of @code{aio_cancel} the
3122 function returns @math{-1} and sets @code{errno} to one of the following
3127 The file descriptor @var{fildes} is not valid.
3129 @code{aio_cancel} is not implemented.
3132 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
3133 function is in fact @code{aio_cancel64} since the LFS interface
3134 transparently replaces the normal implementation.
3137 @deftypefun int aio_cancel64 (int @var{fildes}, struct aiocb64 *@var{aiocbp})
3138 @standards{Unix98, aio.h}
3139 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
3140 This function is similar to @code{aio_cancel} with the only difference
3141 that the argument is a reference to a variable of type @code{struct
3144 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64}, this
3145 function is available under the name @code{aio_cancel} and so
3146 transparently replaces the interface for small files on 32 bit
3150 @node Configuration of AIO
3151 @subsection How to optimize the AIO implementation
3153 The POSIX standard does not specify how the AIO functions are
3154 implemented. They could be system calls, but it is also possible to
3155 emulate them at userlevel.
3157 At the time of writing, the available implementation is a user-level
3158 implementation which uses threads for handling the enqueued requests.
3159 While this implementation requires making some decisions about
3160 limitations, hard limitations are something best avoided
3161 in @theglibc{}. Therefore, @theglibc{} provides a means
3162 for tuning the AIO implementation according to the individual use.
3164 @deftp {Data Type} {struct aioinit}
3165 @standards{GNU, aio.h}
3166 This data type is used to pass the configuration or tunable parameters
3167 to the implementation. The program has to initialize the members of
3168 this struct and pass it to the implementation using the @code{aio_init}
3172 @item int aio_threads
3173 This member specifies the maximal number of threads which may be used
3176 This number provides an estimate on the maximal number of simultaneously
3180 @item int aio_usedba
3184 @item int aio_numusers
3186 @item int aio_reserved[2]
3191 @deftypefun void aio_init (const struct aioinit *@var{init})
3192 @standards{GNU, aio.h}
3193 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
3194 @c All changes to global objects are guarded by aio_requests_mutex.
3195 This function must be called before any other AIO function. Calling it
3196 is completely voluntary, as it is only meant to help the AIO
3197 implementation perform better.
3199 Before calling @code{aio_init}, the members of a variable of
3200 type @code{struct aioinit} must be initialized. Then a reference to
3201 this variable is passed as the parameter to @code{aio_init} which itself
3202 may or may not pay attention to the hints.
3204 The function has no return value and no error cases are defined. It is
3205 an extension which follows a proposal from the SGI implementation in
3206 @w{Irix 6}. It is not covered by POSIX.1b or Unix98.
3209 @node Control Operations
3210 @section Control Operations on Files
3212 @cindex control operations on files
3213 @cindex @code{fcntl} function
3214 This section describes how you can perform various other operations on
3215 file descriptors, such as inquiring about or setting flags describing
3216 the status of the file descriptor, manipulating record locks, and the
3217 like. All of these operations are performed by the function @code{fcntl}.
3219 The second argument to the @code{fcntl} function is a command that
3220 specifies which operation to perform. The function and macros that name
3221 various flags that are used with it are declared in the header file
3222 @file{fcntl.h}. Many of these flags are also used by the @code{open}
3223 function; see @ref{Opening and Closing Files}.
3226 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
3227 @standards{POSIX.1, fcntl.h}
3228 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3229 The @code{fcntl} function performs the operation specified by
3230 @var{command} on the file descriptor @var{filedes}. Some commands
3231 require additional arguments to be supplied. These additional arguments
3232 and the return value and error conditions are given in the detailed
3233 descriptions of the individual commands.
3235 Briefly, here is a list of what the various commands are.
3239 Duplicate the file descriptor (return another file descriptor pointing
3240 to the same open file). @xref{Duplicating Descriptors}.
3243 Get flags associated with the file descriptor. @xref{Descriptor Flags}.
3246 Set flags associated with the file descriptor. @xref{Descriptor Flags}.
3249 Get flags associated with the open file. @xref{File Status Flags}.
3252 Set flags associated with the open file. @xref{File Status Flags}.
3255 Test a file lock. @xref{File Locks}.
3258 Set or clear a file lock. @xref{File Locks}.
3261 Like @code{F_SETLK}, but wait for completion. @xref{File Locks}.
3264 Test an open file description lock. @xref{Open File Description Locks}.
3268 Set or clear an open file description lock. @xref{Open File Description Locks}.
3272 Like @code{F_OFD_SETLK}, but block until lock is acquired.
3273 @xref{Open File Description Locks}. Specific to Linux.
3276 Get process or process group ID to receive @code{SIGIO} signals.
3277 @xref{Interrupt Input}.
3280 Set process or process group ID to receive @code{SIGIO} signals.
3281 @xref{Interrupt Input}.
3284 This function is a cancellation point in multi-threaded programs for the
3285 commands @code{F_SETLKW} (and the LFS analogous @code{F_SETLKW64}) and
3286 @code{F_OFD_SETLKW}. This is a problem if the thread allocates some
3287 resources (like memory, file descriptors, semaphores or whatever) at the time
3288 @code{fcntl} is called. If the thread gets canceled these resources stay
3289 allocated until the program ends. To avoid this calls to @code{fcntl} should
3290 be protected using cancellation handlers.
3291 @c ref pthread_cleanup_push / pthread_cleanup_pop
3295 @node Duplicating Descriptors
3296 @section Duplicating Descriptors
3298 @cindex duplicating file descriptors
3299 @cindex redirecting input and output
3301 You can @dfn{duplicate} a file descriptor, or allocate another file
3302 descriptor that refers to the same open file as the original. Duplicate
3303 descriptors share one file position and one set of file status flags
3304 (@pxref{File Status Flags}), but each has its own set of file descriptor
3305 flags (@pxref{Descriptor Flags}).
3307 The major use of duplicating a file descriptor is to implement
3308 @dfn{redirection} of input or output: that is, to change the
3309 file or pipe that a particular file descriptor corresponds to.
3311 You can perform this operation using the @code{fcntl} function with the
3312 @code{F_DUPFD} command, but there are also convenient functions
3313 @code{dup} and @code{dup2} for duplicating descriptors.
3317 The @code{fcntl} function and flags are declared in @file{fcntl.h},
3318 while prototypes for @code{dup} and @code{dup2} are in the header file
3321 @deftypefun int dup (int @var{old})
3322 @standards{POSIX.1, unistd.h}
3323 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3324 This function copies descriptor @var{old} to the first available
3325 descriptor number (the first number not currently open). It is
3326 equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
3329 @deftypefun int dup2 (int @var{old}, int @var{new})
3330 @standards{POSIX.1, unistd.h}
3331 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3332 This function copies the descriptor @var{old} to descriptor number
3335 If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
3336 does not close @var{new}. Otherwise, the new duplicate of @var{old}
3337 replaces any previous meaning of descriptor @var{new}, as if @var{new}
3340 If @var{old} and @var{new} are different numbers, and @var{old} is a
3341 valid descriptor number, then @code{dup2} is equivalent to:
3345 fcntl (@var{old}, F_DUPFD, @var{new})
3348 However, @code{dup2} does this atomically; there is no instant in the
3349 middle of calling @code{dup2} at which @var{new} is closed and not yet a
3350 duplicate of @var{old}.
3353 @deftypevr Macro int F_DUPFD
3354 @standards{POSIX.1, fcntl.h}
3355 This macro is used as the @var{command} argument to @code{fcntl}, to
3356 copy the file descriptor given as the first argument.
3358 The form of the call in this case is:
3361 fcntl (@var{old}, F_DUPFD, @var{next-filedes})
3364 The @var{next-filedes} argument is of type @code{int} and specifies that
3365 the file descriptor returned should be the next available one greater
3366 than or equal to this value.
3368 The return value from @code{fcntl} with this command is normally the value
3369 of the new file descriptor. A return value of @math{-1} indicates an
3370 error. The following @code{errno} error conditions are defined for
3375 The @var{old} argument is invalid.
3378 The @var{next-filedes} argument is invalid.
3381 There are no more file descriptors available---your program is already
3382 using the maximum. In BSD and GNU, the maximum is controlled by a
3383 resource limit that can be changed; @pxref{Limits on Resources}, for
3384 more information about the @code{RLIMIT_NOFILE} limit.
3387 @code{ENFILE} is not a possible error code for @code{dup2} because
3388 @code{dup2} does not create a new opening of a file; duplicate
3389 descriptors do not count toward the limit which @code{ENFILE}
3390 indicates. @code{EMFILE} is possible because it refers to the limit on
3391 distinct descriptor numbers in use in one process.
3394 Here is an example showing how to use @code{dup2} to do redirection.
3395 Typically, redirection of the standard streams (like @code{stdin}) is
3396 done by a shell or shell-like program before calling one of the
3397 @code{exec} functions (@pxref{Executing a File}) to execute a new
3398 program in a child process. When the new program is executed, it
3399 creates and initializes the standard streams to point to the
3400 corresponding file descriptors, before its @code{main} function is
3403 So, to redirect standard input to a file, the shell could do something
3414 file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
3415 dup2 (file, STDIN_FILENO);
3416 TEMP_FAILURE_RETRY (close (file));
3417 execv (program, NULL);
3421 There is also a more detailed example showing how to implement redirection
3422 in the context of a pipeline of processes in @ref{Launching Jobs}.
3425 @node Descriptor Flags
3426 @section File Descriptor Flags
3427 @cindex file descriptor flags
3429 @dfn{File descriptor flags} are miscellaneous attributes of a file
3430 descriptor. These flags are associated with particular file
3431 descriptors, so that if you have created duplicate file descriptors
3432 from a single opening of a file, each descriptor has its own set of flags.
3434 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
3435 which causes the descriptor to be closed if you use any of the
3436 @code{exec@dots{}} functions (@pxref{Executing a File}).
3438 The symbols in this section are defined in the header file
3442 @deftypevr Macro int F_GETFD
3443 @standards{POSIX.1, fcntl.h}
3444 This macro is used as the @var{command} argument to @code{fcntl}, to
3445 specify that it should return the file descriptor flags associated
3446 with the @var{filedes} argument.
3448 The normal return value from @code{fcntl} with this command is a
3449 nonnegative number which can be interpreted as the bitwise OR of the
3450 individual flags (except that currently there is only one flag to use).
3452 In case of an error, @code{fcntl} returns @math{-1}. The following
3453 @code{errno} error conditions are defined for this command:
3457 The @var{filedes} argument is invalid.
3462 @deftypevr Macro int F_SETFD
3463 @standards{POSIX.1, fcntl.h}
3464 This macro is used as the @var{command} argument to @code{fcntl}, to
3465 specify that it should set the file descriptor flags associated with the
3466 @var{filedes} argument. This requires a third @code{int} argument to
3467 specify the new flags, so the form of the call is:
3470 fcntl (@var{filedes}, F_SETFD, @var{new-flags})
3473 The normal return value from @code{fcntl} with this command is an
3474 unspecified value other than @math{-1}, which indicates an error.
3475 The flags and error conditions are the same as for the @code{F_GETFD}
3479 The following macro is defined for use as a file descriptor flag with
3480 the @code{fcntl} function. The value is an integer constant usable
3481 as a bit mask value.
3483 @deftypevr Macro int FD_CLOEXEC
3484 @standards{POSIX.1, fcntl.h}
3485 @cindex close-on-exec (file descriptor flag)
3486 This flag specifies that the file descriptor should be closed when
3487 an @code{exec} function is invoked; see @ref{Executing a File}. When
3488 a file descriptor is allocated (as with @code{open} or @code{dup}),
3489 this bit is initially cleared on the new file descriptor, meaning that
3490 descriptor will survive into the new program after @code{exec}.
3493 If you want to modify the file descriptor flags, you should get the
3494 current flags with @code{F_GETFD} and modify the value. Don't assume
3495 that the flags listed here are the only ones that are implemented; your
3496 program may be run years from now and more flags may exist then. For
3497 example, here is a function to set or clear the flag @code{FD_CLOEXEC}
3498 without altering any other flags:
3501 /* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
3502 @r{or clear the flag if @var{value} is 0.}
3503 @r{Return 0 on success, or -1 on error with @code{errno} set.} */
3506 set_cloexec_flag (int desc, int value)
3508 int oldflags = fcntl (desc, F_GETFD, 0);
3509 /* @r{If reading the flags failed, return error indication now.} */
3512 /* @r{Set just the flag we want to set.} */
3514 oldflags |= FD_CLOEXEC;
3516 oldflags &= ~FD_CLOEXEC;
3517 /* @r{Store modified flag word in the descriptor.} */
3518 return fcntl (desc, F_SETFD, oldflags);
3522 @node File Status Flags
3523 @section File Status Flags
3524 @cindex file status flags
3526 @dfn{File status flags} are used to specify attributes of the opening of a
3527 file. Unlike the file descriptor flags discussed in @ref{Descriptor
3528 Flags}, the file status flags are shared by duplicated file descriptors
3529 resulting from a single opening of the file. The file status flags are
3530 specified with the @var{flags} argument to @code{open};
3531 @pxref{Opening and Closing Files}.
3533 File status flags fall into three categories, which are described in the
3538 @ref{Access Modes}, specify what type of access is allowed to the
3539 file: reading, writing, or both. They are set by @code{open} and are
3540 returned by @code{fcntl}, but cannot be changed.
3543 @ref{Open-time Flags}, control details of what @code{open} will do.
3544 These flags are not preserved after the @code{open} call.
3547 @ref{Operating Modes}, affect how operations such as @code{read} and
3548 @code{write} are done. They are set by @code{open}, and can be fetched or
3549 changed with @code{fcntl}.
3552 The symbols in this section are defined in the header file
3557 * Access Modes:: Whether the descriptor can read or write.
3558 * Open-time Flags:: Details of @code{open}.
3559 * Operating Modes:: Special modes to control I/O operations.
3560 * Getting File Status Flags:: Fetching and changing these flags.
3564 @subsection File Access Modes
3566 The file access modes allow a file descriptor to be used for reading,
3567 writing, or both. (On @gnuhurdsystems{}, they can also allow none of these,
3568 and allow execution of the file as a program.) The access modes are chosen
3569 when the file is opened, and never change.
3571 @deftypevr Macro int O_RDONLY
3572 @standards{POSIX.1, fcntl.h}
3573 Open the file for read access.
3576 @deftypevr Macro int O_WRONLY
3577 @standards{POSIX.1, fcntl.h}
3578 Open the file for write access.
3581 @deftypevr Macro int O_RDWR
3582 @standards{POSIX.1, fcntl.h}
3583 Open the file for both reading and writing.
3586 On @gnuhurdsystems{} (and not on other systems), @code{O_RDONLY} and
3587 @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
3588 and it is valid for either bit to be set or clear. This means that
3589 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}. A file access
3590 mode of zero is permissible; it allows no operations that do input or
3591 output to the file, but does allow other operations such as
3592 @code{fchmod}. On @gnuhurdsystems{}, since ``read-only'' or ``write-only''
3593 is a misnomer, @file{fcntl.h} defines additional names for the file
3594 access modes. These names are preferred when writing GNU-specific code.
3595 But most programs will want to be portable to other POSIX.1 systems and
3596 should use the POSIX.1 names above instead.
3598 @deftypevr Macro int O_READ
3599 @standards{GNU, fcntl.h (optional)}
3600 Open the file for reading. Same as @code{O_RDONLY}; only defined on GNU.
3603 @deftypevr Macro int O_WRITE
3604 @standards{GNU, fcntl.h (optional)}
3605 Open the file for writing. Same as @code{O_WRONLY}; only defined on GNU.
3608 @deftypevr Macro int O_EXEC
3609 @standards{GNU, fcntl.h (optional)}
3610 Open the file for executing. Only defined on GNU.
3613 To determine the file access mode with @code{fcntl}, you must extract
3614 the access mode bits from the retrieved file status flags. On
3616 you can just test the @code{O_READ} and @code{O_WRITE} bits in
3617 the flags word. But in other POSIX.1 systems, reading and writing
3618 access modes are not stored as distinct bit flags. The portable way to
3619 extract the file access mode bits is with @code{O_ACCMODE}.
3621 @deftypevr Macro int O_ACCMODE
3622 @standards{POSIX.1, fcntl.h}
3623 This macro stands for a mask that can be bitwise-ANDed with the file
3624 status flag value to produce a value representing the file access mode.
3625 The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
3626 (On @gnuhurdsystems{} it could also be zero, and it never includes the
3630 @node Open-time Flags
3631 @subsection Open-time Flags
3633 The open-time flags specify options affecting how @code{open} will behave.
3634 These options are not preserved once the file is open. The exception to
3635 this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
3636 @emph{is} saved. @xref{Opening and Closing Files}, for how to call
3639 There are two sorts of options specified by open-time flags.
3643 @dfn{File name translation flags} affect how @code{open} looks up the
3644 file name to locate the file, and whether the file can be created.
3645 @cindex file name translation flags
3646 @cindex flags, file name translation
3649 @dfn{Open-time action flags} specify extra operations that @code{open} will
3650 perform on the file once it is open.
3651 @cindex open-time action flags
3652 @cindex flags, open-time action
3655 Here are the file name translation flags.
3657 @deftypevr Macro int O_CREAT
3658 @standards{POSIX.1, fcntl.h}
3659 If set, the file will be created if it doesn't already exist.
3660 @c !!! mode arg, umask
3661 @cindex create on open (file status flag)
3664 @deftypevr Macro int O_EXCL
3665 @standards{POSIX.1, fcntl.h}
3666 If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
3667 if the specified file already exists. This is guaranteed to never
3668 clobber an existing file.
3670 The @code{O_EXCL} flag has a special meaning in combination with
3671 @code{O_TMPFILE}; see below.
3674 @deftypevr Macro int O_DIRECTORY
3675 @standards{POSIX.1, fcntl.h}
3676 If set, the open operation fails if the given name is not the name of
3677 a directory. The @code{errno} variable is set to @code{ENOTDIR} for
3678 this error condition.
3681 @deftypevr Macro int O_NOFOLLOW
3682 @standards{POSIX.1, fcntl.h}
3683 If set, the open operation fails if the final component of the file name
3684 refers to a symbolic link. The @code{errno} variable is set to
3685 @code{ELOOP} for this error condition.
3688 @deftypevr Macro int O_TMPFILE
3689 @standards{GNU, fcntl.h}
3690 If this flag is specified, functions in the @code{open} family create an
3691 unnamed temporary file. In this case, the pathname argument to the
3692 @code{open} family of functions (@pxref{Opening and Closing Files}) is
3693 interpreted as the directory in which the temporary file is created
3694 (thus determining the file system which provides the storage for the
3695 file). The @code{O_TMPFILE} flag must be combined with @code{O_WRONLY}
3696 or @code{O_RDWR}, and the @var{mode} argument is required.
3698 The temporary file can later be given a name using @code{linkat},
3699 turning it into a regular file. This allows the atomic creation of a
3700 file with the specific file attributes (mode and extended attributes)
3701 and file contents. If, for security reasons, it is not desirable that a
3702 name can be given to the file, the @code{O_EXCL} flag can be specified
3703 along with @code{O_TMPFILE}.
3705 Not all kernels support this open flag. If this flag is unsupported, an
3706 attempt to create an unnamed temporary file fails with an error of
3707 @code{EINVAL}. If the underlying file system does not support the
3708 @code{O_TMPFILE} flag, an @code{EOPNOTSUPP} error is the result.
3710 The @code{O_TMPFILE} flag is a GNU extension.
3713 @deftypevr Macro int O_NONBLOCK
3714 @standards{POSIX.1, fcntl.h}
3715 @cindex non-blocking open
3716 This prevents @code{open} from blocking for a ``long time'' to open the
3717 file. This is only meaningful for some kinds of files, usually devices
3718 such as serial ports; when it is not meaningful, it is harmless and
3719 ignored. Often, opening a port to a modem blocks until the modem reports
3720 carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
3721 return immediately without a carrier.
3723 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
3724 mode and a file name translation flag. This means that specifying
3725 @code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
3726 @pxref{Operating Modes}. To open the file without blocking but do normal
3727 I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
3728 then call @code{fcntl} to turn the bit off.
3731 @deftypevr Macro int O_NOCTTY
3732 @standards{POSIX.1, fcntl.h}
3733 If the named file is a terminal device, don't make it the controlling
3734 terminal for the process. @xref{Job Control}, for information about
3735 what it means to be the controlling terminal.
3737 On @gnuhurdsystems{} and 4.4 BSD, opening a file never makes it the
3738 controlling terminal and @code{O_NOCTTY} is zero. However, @gnulinuxsystems{}
3739 and some other systems use a nonzero value for @code{O_NOCTTY} and set the
3740 controlling terminal when you open a file that is a terminal device; so
3741 to be portable, use @code{O_NOCTTY} when it is important to avoid this.
3742 @cindex controlling terminal, setting
3745 The following three file name translation flags exist only on
3748 @deftypevr Macro int O_IGNORE_CTTY
3749 @standards{GNU, fcntl.h (optional)}
3750 Do not recognize the named file as the controlling terminal, even if it
3751 refers to the process's existing controlling terminal device. Operations
3752 on the new file descriptor will never induce job control signals.
3756 @deftypevr Macro int O_NOLINK
3757 @standards{GNU, fcntl.h (optional)}
3758 If the named file is a symbolic link, open the link itself instead of
3759 the file it refers to. (@code{fstat} on the new file descriptor will
3760 return the information returned by @code{lstat} on the link's name.)
3761 @cindex symbolic link, opening
3764 @deftypevr Macro int O_NOTRANS
3765 @standards{GNU, fcntl.h (optional)}
3766 If the named file is specially translated, do not invoke the translator.
3767 Open the bare file the translator itself sees.
3771 The open-time action flags tell @code{open} to do additional operations
3772 which are not really related to opening the file. The reason to do them
3773 as part of @code{open} instead of in separate calls is that @code{open}
3774 can do them @i{atomically}.
3776 @deftypevr Macro int O_TRUNC
3777 @standards{POSIX.1, fcntl.h}
3778 Truncate the file to zero length. This option is only useful for
3779 regular files, not special files such as directories or FIFOs. POSIX.1
3780 requires that you open the file for writing to use @code{O_TRUNC}. In
3781 BSD and GNU you must have permission to write the file to truncate it,
3782 but you need not open for write access.
3784 This is the only open-time action flag specified by POSIX.1. There is
3785 no good reason for truncation to be done by @code{open}, instead of by
3786 calling @code{ftruncate} afterwards. The @code{O_TRUNC} flag existed in
3787 Unix before @code{ftruncate} was invented, and is retained for backward
3791 The remaining operating modes are BSD extensions. They exist only
3792 on some systems. On other systems, these macros are not defined.
3794 @deftypevr Macro int O_SHLOCK
3795 @standards{BSD, fcntl.h (optional)}
3796 Acquire a shared lock on the file, as with @code{flock}.
3799 If @code{O_CREAT} is specified, the locking is done atomically when
3800 creating the file. You are guaranteed that no other process will get
3801 the lock on the new file first.
3804 @deftypevr Macro int O_EXLOCK
3805 @standards{BSD, fcntl.h (optional)}
3806 Acquire an exclusive lock on the file, as with @code{flock}.
3807 @xref{File Locks}. This is atomic like @code{O_SHLOCK}.
3810 @node Operating Modes
3811 @subsection I/O Operating Modes
3813 The operating modes affect how input and output operations using a file
3814 descriptor work. These flags are set by @code{open} and can be fetched
3815 and changed with @code{fcntl}.
3817 @deftypevr Macro int O_APPEND
3818 @standards{POSIX.1, fcntl.h}
3819 The bit that enables append mode for the file. If set, then all
3820 @code{write} operations write the data at the end of the file, extending
3821 it, regardless of the current file position. This is the only reliable
3822 way to append to a file. In append mode, you are guaranteed that the
3823 data you write will always go to the current end of the file, regardless
3824 of other processes writing to the file. Conversely, if you simply set
3825 the file position to the end of file and write, then another process can
3826 extend the file after you set the file position but before you write,
3827 resulting in your data appearing someplace before the real end of file.
3830 @deftypevr Macro int O_NONBLOCK
3831 @standards{POSIX.1, fcntl.h}
3832 The bit that enables nonblocking mode for the file. If this bit is set,
3833 @code{read} requests on the file can return immediately with a failure
3834 status if there is no input immediately available, instead of blocking.
3835 Likewise, @code{write} requests can also return immediately with a
3836 failure status if the output can't be written immediately.
3838 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
3839 operating mode and a file name translation flag; @pxref{Open-time Flags}.
3842 @deftypevr Macro int O_NDELAY
3843 @standards{BSD, fcntl.h}
3844 This is an obsolete name for @code{O_NONBLOCK}, provided for
3845 compatibility with BSD. It is not defined by the POSIX.1 standard.
3848 The remaining operating modes are BSD and GNU extensions. They exist only
3849 on some systems. On other systems, these macros are not defined.
3851 @deftypevr Macro int O_ASYNC
3852 @standards{BSD, fcntl.h}
3853 The bit that enables asynchronous input mode. If set, then @code{SIGIO}
3854 signals will be generated when input is available. @xref{Interrupt Input}.
3856 Asynchronous input mode is a BSD feature.
3859 @deftypevr Macro int O_FSYNC
3860 @standards{BSD, fcntl.h}
3861 The bit that enables synchronous writing for the file. If set, each
3862 @code{write} call will make sure the data is reliably stored on disk before
3863 returning. @c !!! xref fsync
3865 Synchronous writing is a BSD feature.
3868 @deftypevr Macro int O_SYNC
3869 @standards{BSD, fcntl.h}
3870 This is another name for @code{O_FSYNC}. They have the same value.
3873 @deftypevr Macro int O_NOATIME
3874 @standards{GNU, fcntl.h}
3875 If this bit is set, @code{read} will not update the access time of the
3876 file. @xref{File Times}. This is used by programs that do backups, so
3877 that backing a file up does not count as reading it.
3878 Only the owner of the file or the superuser may use this bit.
3880 This is a GNU extension.
3883 @node Getting File Status Flags
3884 @subsection Getting and Setting File Status Flags
3886 The @code{fcntl} function can fetch or change file status flags.
3888 @deftypevr Macro int F_GETFL
3889 @standards{POSIX.1, fcntl.h}
3890 This macro is used as the @var{command} argument to @code{fcntl}, to
3891 read the file status flags for the open file with descriptor
3894 The normal return value from @code{fcntl} with this command is a
3895 nonnegative number which can be interpreted as the bitwise OR of the
3896 individual flags. Since the file access modes are not single-bit values,
3897 you can mask off other bits in the returned flags with @code{O_ACCMODE}
3900 In case of an error, @code{fcntl} returns @math{-1}. The following
3901 @code{errno} error conditions are defined for this command:
3905 The @var{filedes} argument is invalid.
3909 @deftypevr Macro int F_SETFL
3910 @standards{POSIX.1, fcntl.h}
3911 This macro is used as the @var{command} argument to @code{fcntl}, to set
3912 the file status flags for the open file corresponding to the
3913 @var{filedes} argument. This command requires a third @code{int}
3914 argument to specify the new flags, so the call looks like this:
3917 fcntl (@var{filedes}, F_SETFL, @var{new-flags})
3920 You can't change the access mode for the file in this way; that is,
3921 whether the file descriptor was opened for reading or writing.
3923 The normal return value from @code{fcntl} with this command is an
3924 unspecified value other than @math{-1}, which indicates an error. The
3925 error conditions are the same as for the @code{F_GETFL} command.
3928 If you want to modify the file status flags, you should get the current
3929 flags with @code{F_GETFL} and modify the value. Don't assume that the
3930 flags listed here are the only ones that are implemented; your program
3931 may be run years from now and more flags may exist then. For example,
3932 here is a function to set or clear the flag @code{O_NONBLOCK} without
3933 altering any other flags:
3937 /* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
3938 @r{or clear the flag if @var{value} is 0.}
3939 @r{Return 0 on success, or -1 on error with @code{errno} set.} */
3942 set_nonblock_flag (int desc, int value)
3944 int oldflags = fcntl (desc, F_GETFL, 0);
3945 /* @r{If reading the flags failed, return error indication now.} */
3948 /* @r{Set just the flag we want to set.} */
3950 oldflags |= O_NONBLOCK;
3952 oldflags &= ~O_NONBLOCK;
3953 /* @r{Store modified flag word in the descriptor.} */
3954 return fcntl (desc, F_SETFL, oldflags);
3963 @cindex record locking
3964 This section describes record locks that are associated with the process.
3965 There is also a different type of record lock that is associated with the
3966 open file description instead of the process. @xref{Open File Description Locks}.
3968 The remaining @code{fcntl} commands are used to support @dfn{record
3969 locking}, which permits multiple cooperating programs to prevent each
3970 other from simultaneously accessing parts of a file in error-prone
3973 @cindex exclusive lock
3975 An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
3976 for writing to the specified part of the file. While a write lock is in
3977 place, no other process can lock that part of the file.
3981 A @dfn{shared} or @dfn{read} lock prohibits any other process from
3982 requesting a write lock on the specified part of the file. However,
3983 other processes can request read locks.
3985 The @code{read} and @code{write} functions do not actually check to see
3986 whether there are any locks in place. If you want to implement a
3987 locking protocol for a file shared by multiple processes, your application
3988 must do explicit @code{fcntl} calls to request and clear locks at the
3991 Locks are associated with processes. A process can only have one kind
3992 of lock set for each byte of a given file. When any file descriptor for
3993 that file is closed by the process, all of the locks that process holds
3994 on that file are released, even if the locks were made using other
3995 descriptors that remain open. Likewise, locks are released when a
3996 process exits, and are not inherited by child processes created using
3997 @code{fork} (@pxref{Creating a Process}).
3999 When making a lock, use a @code{struct flock} to specify what kind of
4000 lock and where. This data type and the associated macros for the
4001 @code{fcntl} function are declared in the header file @file{fcntl.h}.
4004 @deftp {Data Type} {struct flock}
4005 @standards{POSIX.1, fcntl.h}
4006 This structure is used with the @code{fcntl} function to describe a file
4007 lock. It has these members:
4010 @item short int l_type
4011 Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
4014 @item short int l_whence
4015 This corresponds to the @var{whence} argument to @code{fseek} or
4016 @code{lseek}, and specifies what the offset is relative to. Its value
4017 can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
4020 This specifies the offset of the start of the region to which the lock
4021 applies, and is given in bytes relative to the point specified by the
4022 @code{l_whence} member.
4025 This specifies the length of the region to be locked. A value of
4026 @code{0} is treated specially; it means the region extends to the end of
4030 This field is the process ID (@pxref{Process Creation Concepts}) of the
4031 process holding the lock. It is filled in by calling @code{fcntl} with
4032 the @code{F_GETLK} command, but is ignored when making a lock. If the
4033 conflicting lock is an open file description lock
4034 (@pxref{Open File Description Locks}), then this field will be set to
4039 @deftypevr Macro int F_GETLK
4040 @standards{POSIX.1, fcntl.h}
4041 This macro is used as the @var{command} argument to @code{fcntl}, to
4042 specify that it should get information about a lock. This command
4043 requires a third argument of type @w{@code{struct flock *}} to be passed
4044 to @code{fcntl}, so that the form of the call is:
4047 fcntl (@var{filedes}, F_GETLK, @var{lockp})
4050 If there is a lock already in place that would block the lock described
4051 by the @var{lockp} argument, information about that lock overwrites
4052 @code{*@var{lockp}}. Existing locks are not reported if they are
4053 compatible with making a new lock as specified. Thus, you should
4054 specify a lock type of @code{F_WRLCK} if you want to find out about both
4055 read and write locks, or @code{F_RDLCK} if you want to find out about
4058 There might be more than one lock affecting the region specified by the
4059 @var{lockp} argument, but @code{fcntl} only returns information about
4060 one of them. The @code{l_whence} member of the @var{lockp} structure is
4061 set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
4062 set to identify the locked region.
4064 If no lock applies, the only change to the @var{lockp} structure is to
4065 update the @code{l_type} to a value of @code{F_UNLCK}.
4067 The normal return value from @code{fcntl} with this command is an
4068 unspecified value other than @math{-1}, which is reserved to indicate an
4069 error. The following @code{errno} error conditions are defined for
4074 The @var{filedes} argument is invalid.
4077 Either the @var{lockp} argument doesn't specify valid lock information,
4078 or the file associated with @var{filedes} doesn't support locks.
4082 @deftypevr Macro int F_SETLK
4083 @standards{POSIX.1, fcntl.h}
4084 This macro is used as the @var{command} argument to @code{fcntl}, to
4085 specify that it should set or clear a lock. This command requires a
4086 third argument of type @w{@code{struct flock *}} to be passed to
4087 @code{fcntl}, so that the form of the call is:
4090 fcntl (@var{filedes}, F_SETLK, @var{lockp})
4093 If the process already has a lock on any part of the region, the old lock
4094 on that part is replaced with the new lock. You can remove a lock
4095 by specifying a lock type of @code{F_UNLCK}.
4097 If the lock cannot be set, @code{fcntl} returns immediately with a value
4098 of @math{-1}. This function does not block while waiting for other processes
4099 to release locks. If @code{fcntl} succeeds, it returns a value other
4102 The following @code{errno} error conditions are defined for this
4108 The lock cannot be set because it is blocked by an existing lock on the
4109 file. Some systems use @code{EAGAIN} in this case, and other systems
4110 use @code{EACCES}; your program should treat them alike, after
4111 @code{F_SETLK}. (@gnulinuxhurdsystems{} always use @code{EAGAIN}.)
4114 Either: the @var{filedes} argument is invalid; you requested a read lock
4115 but the @var{filedes} is not open for read access; or, you requested a
4116 write lock but the @var{filedes} is not open for write access.
4119 Either the @var{lockp} argument doesn't specify valid lock information,
4120 or the file associated with @var{filedes} doesn't support locks.
4123 The system has run out of file lock resources; there are already too
4124 many file locks in place.
4126 Well-designed file systems never report this error, because they have no
4127 limitation on the number of locks. However, you must still take account
4128 of the possibility of this error, as it could result from network access
4129 to a file system on another machine.
4133 @deftypevr Macro int F_SETLKW
4134 @standards{POSIX.1, fcntl.h}
4135 This macro is used as the @var{command} argument to @code{fcntl}, to
4136 specify that it should set or clear a lock. It is just like the
4137 @code{F_SETLK} command, but causes the process to block (or wait)
4138 until the request can be specified.
4140 This command requires a third argument of type @code{struct flock *}, as
4141 for the @code{F_SETLK} command.
4143 The @code{fcntl} return values and errors are the same as for the
4144 @code{F_SETLK} command, but these additional @code{errno} error conditions
4145 are defined for this command:
4149 The function was interrupted by a signal while it was waiting.
4150 @xref{Interrupted Primitives}.
4153 The specified region is being locked by another process. But that
4154 process is waiting to lock a region which the current process has
4155 locked, so waiting for the lock would result in deadlock. The system
4156 does not guarantee that it will detect all such conditions, but it lets
4157 you know if it notices one.
4162 The following macros are defined for use as values for the @code{l_type}
4163 member of the @code{flock} structure. The values are integer constants.
4167 @standards{POSIX.1, fcntl.h}
4168 This macro is used to specify a read (or shared) lock.
4171 @standards{POSIX.1, fcntl.h}
4172 This macro is used to specify a write (or exclusive) lock.
4175 @standards{POSIX.1, fcntl.h}
4176 This macro is used to specify that the region is unlocked.
4179 As an example of a situation where file locking is useful, consider a
4180 program that can be run simultaneously by several different users, that
4181 logs status information to a common file. One example of such a program
4182 might be a game that uses a file to keep track of high scores. Another
4183 example might be a program that records usage or accounting information
4184 for billing purposes.
4186 Having multiple copies of the program simultaneously writing to the
4187 file could cause the contents of the file to become mixed up. But
4188 you can prevent this kind of problem by setting a write lock on the
4189 file before actually writing to the file.
4191 If the program also needs to read the file and wants to make sure that
4192 the contents of the file are in a consistent state, then it can also use
4193 a read lock. While the read lock is set, no other process can lock
4194 that part of the file for writing.
4196 @c ??? This section could use an example program.
4198 Remember that file locks are only an @emph{advisory} protocol for
4199 controlling access to a file. There is still potential for access to
4200 the file by programs that don't use the lock protocol.
4202 @node Open File Description Locks
4203 @section Open File Description Locks
4205 In contrast to process-associated record locks (@pxref{File Locks}),
4206 open file description record locks are associated with an open file
4207 description rather than a process.
4209 Using @code{fcntl} to apply an open file description lock on a region that
4210 already has an existing open file description lock that was created via the
4211 same file descriptor will never cause a lock conflict.
4213 Open file description locks are also inherited by child processes across
4214 @code{fork}, or @code{clone} with @code{CLONE_FILES} set
4215 (@pxref{Creating a Process}), along with the file descriptor.
4217 It is important to distinguish between the open file @emph{description} (an
4218 instance of an open file, usually created by a call to @code{open}) and
4219 an open file @emph{descriptor}, which is a numeric value that refers to the
4220 open file description. The locks described here are associated with the
4221 open file @emph{description} and not the open file @emph{descriptor}.
4223 Using @code{dup} (@pxref{Duplicating Descriptors}) to copy a file
4224 descriptor does not give you a new open file description, but rather copies a
4225 reference to an existing open file description and assigns it to a new
4226 file descriptor. Thus, open file description locks set on a file
4227 descriptor cloned by @code{dup} will never conflict with open file
4228 description locks set on the original descriptor since they refer to the
4229 same open file description. Depending on the range and type of lock
4230 involved, the original lock may be modified by a @code{F_OFD_SETLK} or
4231 @code{F_OFD_SETLKW} command in this situation however.
4233 Open file description locks always conflict with process-associated locks,
4234 even if acquired by the same process or on the same open file
4237 Open file description locks use the same @code{struct flock} as
4238 process-associated locks as an argument (@pxref{File Locks}) and the
4239 macros for the @code{command} values are also declared in the header file
4240 @file{fcntl.h}. To use them, the macro @code{_GNU_SOURCE} must be
4241 defined prior to including any header file.
4243 In contrast to process-associated locks, any @code{struct flock} used as
4244 an argument to open file description lock commands must have the @code{l_pid}
4245 value set to @math{0}. Also, when returning information about an
4246 open file description lock in a @code{F_GETLK} or @code{F_OFD_GETLK} request,
4247 the @code{l_pid} field in @code{struct flock} will be set to @math{-1}
4248 to indicate that the lock is not associated with a process.
4250 When the same @code{struct flock} is reused as an argument to a
4251 @code{F_OFD_SETLK} or @code{F_OFD_SETLKW} request after being used for an
4252 @code{F_OFD_GETLK} request, it is necessary to inspect and reset the
4253 @code{l_pid} field to @math{0}.
4257 @deftypevr Macro int F_OFD_GETLK
4258 This macro is used as the @var{command} argument to @code{fcntl}, to
4259 specify that it should get information about a lock. This command
4260 requires a third argument of type @w{@code{struct flock *}} to be passed
4261 to @code{fcntl}, so that the form of the call is:
4264 fcntl (@var{filedes}, F_OFD_GETLK, @var{lockp})
4267 If there is a lock already in place that would block the lock described
4268 by the @var{lockp} argument, information about that lock is written to
4269 @code{*@var{lockp}}. Existing locks are not reported if they are
4270 compatible with making a new lock as specified. Thus, you should
4271 specify a lock type of @code{F_WRLCK} if you want to find out about both
4272 read and write locks, or @code{F_RDLCK} if you want to find out about
4275 There might be more than one lock affecting the region specified by the
4276 @var{lockp} argument, but @code{fcntl} only returns information about
4277 one of them. Which lock is returned in this situation is undefined.
4279 The @code{l_whence} member of the @var{lockp} structure are set to
4280 @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields are set
4281 to identify the locked region.
4283 If no conflicting lock exists, the only change to the @var{lockp} structure
4284 is to update the @code{l_type} field to the value @code{F_UNLCK}.
4286 The normal return value from @code{fcntl} with this command is either @math{0}
4287 on success or @math{-1}, which indicates an error. The following @code{errno}
4288 error conditions are defined for this command:
4292 The @var{filedes} argument is invalid.
4295 Either the @var{lockp} argument doesn't specify valid lock information,
4296 the operating system kernel doesn't support open file description locks, or the file
4297 associated with @var{filedes} doesn't support locks.
4301 @deftypevr Macro int F_OFD_SETLK
4302 @standards{POSIX.1, fcntl.h}
4303 This macro is used as the @var{command} argument to @code{fcntl}, to
4304 specify that it should set or clear a lock. This command requires a
4305 third argument of type @w{@code{struct flock *}} to be passed to
4306 @code{fcntl}, so that the form of the call is:
4309 fcntl (@var{filedes}, F_OFD_SETLK, @var{lockp})
4312 If the open file already has a lock on any part of the
4313 region, the old lock on that part is replaced with the new lock. You
4314 can remove a lock by specifying a lock type of @code{F_UNLCK}.
4316 If the lock cannot be set, @code{fcntl} returns immediately with a value
4317 of @math{-1}. This command does not wait for other tasks
4318 to release locks. If @code{fcntl} succeeds, it returns @math{0}.
4320 The following @code{errno} error conditions are defined for this
4325 The lock cannot be set because it is blocked by an existing lock on the
4329 Either: the @var{filedes} argument is invalid; you requested a read lock
4330 but the @var{filedes} is not open for read access; or, you requested a
4331 write lock but the @var{filedes} is not open for write access.
4334 Either the @var{lockp} argument doesn't specify valid lock information,
4335 the operating system kernel doesn't support open file description locks, or the
4336 file associated with @var{filedes} doesn't support locks.
4339 The system has run out of file lock resources; there are already too
4340 many file locks in place.
4342 Well-designed file systems never report this error, because they have no
4343 limitation on the number of locks. However, you must still take account
4344 of the possibility of this error, as it could result from network access
4345 to a file system on another machine.
4349 @deftypevr Macro int F_OFD_SETLKW
4350 @standards{POSIX.1, fcntl.h}
4351 This macro is used as the @var{command} argument to @code{fcntl}, to
4352 specify that it should set or clear a lock. It is just like the
4353 @code{F_OFD_SETLK} command, but causes the process to wait until the request
4356 This command requires a third argument of type @code{struct flock *}, as
4357 for the @code{F_OFD_SETLK} command.
4359 The @code{fcntl} return values and errors are the same as for the
4360 @code{F_OFD_SETLK} command, but these additional @code{errno} error conditions
4361 are defined for this command:
4365 The function was interrupted by a signal while it was waiting.
4366 @xref{Interrupted Primitives}.
4371 Open file description locks are useful in the same sorts of situations as
4372 process-associated locks. They can also be used to synchronize file
4373 access between threads within the same process by having each thread perform
4374 its own @code{open} of the file, to obtain its own open file description.
4376 Because open file description locks are automatically freed only upon
4377 closing the last file descriptor that refers to the open file
4378 description, this locking mechanism avoids the possibility that locks
4379 are inadvertently released due to a library routine opening and closing
4380 a file without the application being aware.
4382 As with process-associated locks, open file description locks are advisory.
4384 @node Open File Description Locks Example
4385 @section Open File Description Locks Example
4387 Here is an example of using open file description locks in a threaded
4388 program. If this program used process-associated locks, then it would be
4389 subject to data corruption because process-associated locks are shared
4390 by the threads inside a process, and thus cannot be used by one thread
4391 to lock out another thread in the same process.
4393 Proper error handling has been omitted in the following program for
4397 @include ofdlocks.c.texi
4400 This example creates three threads each of which loops five times,
4401 appending to the file. Access to the file is serialized via open file
4402 description locks. If we compile and run the above program, we'll end up
4403 with /tmp/foo that has 15 lines in it.
4405 If we, however, were to replace the @code{F_OFD_SETLK} and
4406 @code{F_OFD_SETLKW} commands with their process-associated lock
4407 equivalents, the locking essentially becomes a noop since it is all done
4408 within the context of the same process. That leads to data corruption
4409 (typically manifested as missing lines) as some threads race in and
4410 overwrite the data written by others.
4412 @node Interrupt Input
4413 @section Interrupt-Driven Input
4415 @cindex interrupt-driven input
4416 If you set the @code{O_ASYNC} status flag on a file descriptor
4417 (@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
4418 input or output becomes possible on that file descriptor. The process
4419 or process group to receive the signal can be selected by using the
4420 @code{F_SETOWN} command to the @code{fcntl} function. If the file
4421 descriptor is a socket, this also selects the recipient of @code{SIGURG}
4422 signals that are delivered when out-of-band data arrives on that socket;
4423 see @ref{Out-of-Band Data}. (@code{SIGURG} is sent in any situation
4424 where @code{select} would report the socket as having an ``exceptional
4425 condition''. @xref{Waiting for I/O}.)
4427 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
4428 signals are sent to the foreground process group of the terminal.
4432 The symbols in this section are defined in the header file
4435 @deftypevr Macro int F_GETOWN
4436 @standards{BSD, fcntl.h}
4437 This macro is used as the @var{command} argument to @code{fcntl}, to
4438 specify that it should get information about the process or process
4439 group to which @code{SIGIO} signals are sent. (For a terminal, this is
4440 actually the foreground process group ID, which you can get using
4441 @code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
4443 The return value is interpreted as a process ID; if negative, its
4444 absolute value is the process group ID.
4446 The following @code{errno} error condition is defined for this command:
4450 The @var{filedes} argument is invalid.
4454 @deftypevr Macro int F_SETOWN
4455 @standards{BSD, fcntl.h}
4456 This macro is used as the @var{command} argument to @code{fcntl}, to
4457 specify that it should set the process or process group to which
4458 @code{SIGIO} signals are sent. This command requires a third argument
4459 of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
4463 fcntl (@var{filedes}, F_SETOWN, @var{pid})
4466 The @var{pid} argument should be a process ID. You can also pass a
4467 negative number whose absolute value is a process group ID.
4469 The return value from @code{fcntl} with this command is @math{-1}
4470 in case of error and some other value if successful. The following
4471 @code{errno} error conditions are defined for this command:
4475 The @var{filedes} argument is invalid.
4478 There is no process or process group corresponding to @var{pid}.
4482 @c ??? This section could use an example program.
4485 @section Generic I/O Control operations
4486 @cindex generic i/o control operations
4489 @gnusystems{} can handle most input/output operations on many different
4490 devices and objects in terms of a few file primitives - @code{read},
4491 @code{write} and @code{lseek}. However, most devices also have a few
4492 peculiar operations which do not fit into this model. Such as:
4497 Changing the character font used on a terminal.
4500 Telling a magnetic tape system to rewind or fast forward. (Since they
4501 cannot move in byte increments, @code{lseek} is inapplicable).
4504 Ejecting a disk from a drive.
4507 Playing an audio track from a CD-ROM drive.
4510 Maintaining routing tables for a network.
4514 Although some such objects such as sockets and terminals
4515 @footnote{Actually, the terminal-specific functions are implemented with
4516 IOCTLs on many platforms.} have special functions of their own, it would
4517 not be practical to create functions for all these cases.
4519 Instead these minor operations, known as @dfn{IOCTL}s, are assigned code
4520 numbers and multiplexed through the @code{ioctl} function, defined in
4521 @code{sys/ioctl.h}. The code numbers themselves are defined in many
4524 @deftypefun int ioctl (int @var{filedes}, int @var{command}, @dots{})
4525 @standards{BSD, sys/ioctl.h}
4526 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
4528 The @code{ioctl} function performs the generic I/O operation
4529 @var{command} on @var{filedes}.
4531 A third argument is usually present, either a single number or a pointer
4532 to a structure. The meaning of this argument, the returned value, and
4533 any error codes depends upon the command used. Often @math{-1} is
4534 returned for a failure.
4538 On some systems, IOCTLs used by different devices share the same numbers.
4539 Thus, although use of an inappropriate IOCTL @emph{usually} only produces
4540 an error, you should not attempt to use device-specific IOCTLs on an
4543 Most IOCTLs are OS-specific and/or only used in special system utilities,
4544 and are thus beyond the scope of this document. For an example of the use
4545 of an IOCTL, see @ref{Out-of-Band Data}.
4547 @c FIXME this is undocumented: