1 @node Low-Level I/O, File System Interface, I/O on Streams, Top
2 @chapter Low-Level Input/Output
4 This chapter describes functions for performing low-level input/output
5 operations on file descriptors. These functions include the primitives
6 for the higher-level I/O functions described in @ref{I/O on Streams}, as
7 well as functions for performing low-level control operations for which
8 there are no equivalents on streams.
10 Stream-level I/O is more flexible and usually more convenient;
11 therefore, programmers generally use the descriptor-level functions only
12 when necessary. These are some of the usual reasons:
16 For reading binary files in large chunks.
19 For reading an entire file into core before parsing it.
22 To perform operations other than data transfer, which can only be done
23 with a descriptor. (You can use @code{fileno} to get the descriptor
24 corresponding to a stream.)
27 To pass descriptors to a child process. (The child can create its own
28 stream to use a descriptor that it inherits, but cannot inherit a stream
33 * Opening and Closing Files:: How to open and close file
35 * I/O Primitives:: Reading and writing data.
36 * File Position Primitive:: Setting a descriptor's file
38 * Descriptors and Streams:: Converting descriptor to stream
40 * Stream/Descriptor Precautions:: Precautions needed if you use both
41 descriptors and streams.
42 * Waiting for I/O:: How to check for input or output
43 on multiple file descriptors.
44 * Control Operations:: Various other operations on file
46 * Duplicating Descriptors:: Fcntl commands for duplicating
48 * Descriptor Flags:: Fcntl commands for manipulating
49 flags associated with file
51 * File Status Flags:: Fcntl commands for manipulating
52 flags associated with open files.
53 * File Locks:: Fcntl commands for implementing
55 * Interrupt Input:: Getting an asynchronous signal when
60 @node Opening and Closing Files
61 @section Opening and Closing Files
63 @cindex opening a file descriptor
64 @cindex closing a file descriptor
65 This section describes the primitives for opening and closing files
66 using file descriptors. The @code{open} and @code{creat} functions are
67 declared in the header file @file{fcntl.h}, while @code{close} is
68 declared in @file{unistd.h}.
74 @deftypefun int open (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}])
75 The @code{open} function creates and returns a new file descriptor
76 for the file named by @var{filename}. Initially, the file position
77 indicator for the file is at the beginning of the file. The argument
78 @var{mode} is used only when a file is created, but it doesn't hurt
79 to supply the argument in any case.
81 The @var{flags} argument controls how the file is to be opened. This is
82 a bit mask; you create the value by the bitwise OR of the appropriate
83 parameters (using the @samp{|} operator in C).
84 @xref{File Status Flags}, for the parameters available.
86 The normal return value from @code{open} is a non-negative integer file
87 descriptor. In the case of an error, a value of @code{-1} is returned
88 instead. In addition to the usual file name errors (@pxref{File
89 Name Errors}), the following @code{errno} error conditions are defined
94 The file exists but is not readable/writable as requested by the @var{flags}
95 argument, the file does not exist and the directory is unwritable so
99 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
103 The @code{open} operation was interrupted by a signal.
104 @xref{Interrupted Primitives}.
107 The @var{flags} argument specified write access, and the file is a directory.
110 The process has too many files open.
111 The maximum number of file descriptors is controlled by the
112 @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
115 The entire system, or perhaps the file system which contains the
116 directory, cannot support any additional open files at the moment.
117 (This problem cannot happen on the GNU system.)
120 The named file does not exist, and @code{O_CREAT} is not specified.
123 The directory or file system that would contain the new file cannot be
124 extended, because there is no disk space left.
127 @code{O_NONBLOCK} and @code{O_WRONLY} are both set in the @var{flags}
128 argument, the file named by @var{filename} is a FIFO (@pxref{Pipes and
129 FIFOs}), and no process has the file open for reading.
132 The file resides on a read-only file system and any of @w{@code{O_WRONLY}},
133 @code{O_RDWR}, and @code{O_TRUNC} are set in the @var{flags} argument,
134 or @code{O_CREAT} is set and the file does not already exist.
139 The @code{open} function is the underlying primitive for the @code{fopen}
140 and @code{freopen} functions, that create streams.
145 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
146 This function is obsolete. The call:
149 creat (@var{filename}, @var{mode})
156 open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
162 @deftypefun int close (int @var{filedes})
163 The function @code{close} closes the file descriptor @var{filedes}.
164 Closing a file has the following consequences:
168 The file descriptor is deallocated.
171 Any record locks owned by the process on the file are unlocked.
174 When all file descriptors associated with a pipe or FIFO have been closed,
175 any unread data is discarded.
178 The normal return value from @code{close} is @code{0}; a value of @code{-1}
179 is returned in case of failure. The following @code{errno} error
180 conditions are defined for this function:
184 The @var{filedes} argument is not a valid file descriptor.
187 The @code{close} call was interrupted by a signal.
188 @xref{Interrupted Primitives}.
189 Here is an example of how to handle @code{EINTR} properly:
192 TEMP_FAILURE_RETRY (close (desc));
198 When the file is accessed by NFS, these errors from @code{write} can sometimes
199 not be detected until @code{close}. @xref{I/O Primitives}, for details
204 To close a stream, call @code{fclose} (@pxref{Closing Streams}) instead
205 of trying to close its underlying file descriptor with @code{close}.
206 This flushes any buffered output and updates the stream object to
207 indicate that it is closed.
210 @section Input and Output Primitives
212 This section describes the functions for performing primitive input and
213 output operations on file descriptors: @code{read}, @code{write}, and
214 @code{lseek}. These functions are declared in the header file
220 @deftp {Data Type} ssize_t
221 This data type is used to represent the sizes of blocks that can be
222 read or written in a single operation. It is similar to @code{size_t},
223 but must be a signed type.
226 @cindex reading from a file descriptor
229 @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size})
230 The @code{read} function reads up to @var{size} bytes from the file
231 with descriptor @var{filedes}, storing the results in the @var{buffer}.
232 (This is not necessarily a character string and there is no terminating
233 null character added.)
235 @cindex end-of-file, on a file descriptor
236 The return value is the number of bytes actually read. This might be
237 less than @var{size}; for example, if there aren't that many bytes left
238 in the file or if there aren't that many bytes immediately available.
239 The exact behavior depends on what kind of file it is. Note that
240 reading less than @var{size} bytes is not an error.
242 A value of zero indicates end-of-file (except if the value of the
243 @var{size} argument is also zero). This is not considered an error.
244 If you keep calling @code{read} while at end-of-file, it will keep
245 returning zero and doing nothing else.
247 If @code{read} returns at least one character, there is no way you can
248 tell whether end-of-file was reached. But if you did reach the end, the
249 next read will return zero.
251 In case of an error, @code{read} returns @code{-1}. The following
252 @code{errno} error conditions are defined for this function:
256 Normally, when no input is immediately available, @code{read} waits for
257 some input. But if the @code{O_NONBLOCK} flag is set for the file
258 (@pxref{File Status Flags}), @code{read} returns immediately without
259 reading any data, and reports this error.
261 @strong{Compatibility Note:} Most versions of BSD Unix use a different
262 error code for this: @code{EWOULDBLOCK}. In the GNU library,
263 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
266 On some systems, reading a large amount of data from a character special
267 file can also fail with @code{EAGAIN} if the kernel cannot find enough
268 physical memory to lock down the user's pages. This is limited to
269 devices that transfer with direct memory access into the user's memory,
270 which means it does not include terminals, since they always use
271 separate buffers inside the kernel. This problem never happens in the
274 Any condition that could result in @code{EAGAIN} can instead result in a
275 successful @code{read} which returns fewer bytes than requested.
276 Calling @code{read} again immediately would result in @code{EAGAIN}.
279 The @var{filedes} argument is not a valid file descriptor,
280 or is not open for reading.
283 @code{read} was interrupted by a signal while it was waiting for input.
284 @xref{Interrupted Primitives}. A signal will not necessary cause
285 @code{read} to return @code{EINTR}; it may instead result in a
286 successful @code{read} which returns fewer bytes than requested.
289 For many devices, and for disk files, this error code indicates
292 @code{EIO} also occurs when a background process tries to read from the
293 controlling terminal, and the normal action of stopping the process by
294 sending it a @code{SIGTTIN} signal isn't working. This might happen if
295 signal is being blocked or ignored, or because the process group is
296 orphaned. @xref{Job Control}, for more information about job control,
297 and @ref{Signal Handling}, for information about signals.
300 The @code{read} function is the underlying primitive for all of the
301 functions that read from streams, such as @code{fgetc}.
306 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset})
307 The @code{pread} function is similar to the @code{read} function. The
308 first three arguments are identical and also the return values and error
311 The difference is the fourth argument and its handling. The data block
312 is not read from the current position of the file descriptor
313 @code{filedes}. Instead the data is read from the file starting at
314 position @var{offset}. The position of the file descriptor itself is
315 not effected by the operation. The value is the same as before the call.
317 The return value of @code{pread} describes the number of bytes read.
318 In the error case it returns @math{-1} like @code{read} does and the
319 error codes are also the same. Only there are a few more error codes:
322 The value given for @var{offset} is negative and therefore illegal.
325 The file descriptor @var{filedes} is associate with a pipe or a FIFO and
326 this device does not allow positioning of the file pointer.
329 The function is an extension defined in the Unix Single Specification
333 @cindex writing to a file descriptor
336 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
337 The @code{write} function writes up to @var{size} bytes from
338 @var{buffer} to the file with descriptor @var{filedes}. The data in
339 @var{buffer} is not necessarily a character string and a null character is
340 output like any other character.
342 The return value is the number of bytes actually written. This may be
343 @var{size}, but can always be smaller. Your program should always call
344 @code{write} in a loop, iterating until all the data is written.
346 Once @code{write} returns, the data is enqueued to be written and can be
347 read back right away, but it is not necessarily written out to permanent
348 storage immediately. You can use @code{fsync} when you need to be sure
349 your data has been permanently stored before continuing. (It is more
350 efficient for the system to batch up consecutive writes and do them all
351 at once when convenient. Normally they will always be written to disk
352 within a minute or less.) Modern systems provide another function
353 @code{fdatasync} which guarantees integrity only for the file data and
355 @c !!! xref fsync, fdatasync
356 You can use the @code{O_FSYNC} open mode to make @code{write} always
357 store the data to disk before returning; @pxref{Operating Modes}.
359 In the case of an error, @code{write} returns @code{-1}. The following
360 @code{errno} error conditions are defined for this function:
364 Normally, @code{write} blocks until the write operation is complete.
365 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
366 Operations}), it returns immediately without writing any data, and
367 reports this error. An example of a situation that might cause the
368 process to block on output is writing to a terminal device that supports
369 flow control, where output has been suspended by receipt of a STOP
372 @strong{Compatibility Note:} Most versions of BSD Unix use a different
373 error code for this: @code{EWOULDBLOCK}. In the GNU library,
374 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
377 On some systems, writing a large amount of data from a character special
378 file can also fail with @code{EAGAIN} if the kernel cannot find enough
379 physical memory to lock down the user's pages. This is limited to
380 devices that transfer with direct memory access into the user's memory,
381 which means it does not include terminals, since they always use
382 separate buffers inside the kernel. This problem does not arise in the
386 The @var{filedes} argument is not a valid file descriptor,
387 or is not open for writing.
390 The size of the file would become larger than the implementation can support.
393 The @code{write} operation was interrupted by a signal while it was
394 blocked waiting for completion. A signal will not necessary cause
395 @code{write} to return @code{EINTR}; it may instead result in a
396 successful @code{write} which writes fewer bytes than requested.
397 @xref{Interrupted Primitives}.
400 For many devices, and for disk files, this error code indicates
404 The device containing the file is full.
407 This error is returned when you try to write to a pipe or FIFO that
408 isn't open for reading by any process. When this happens, a @code{SIGPIPE}
409 signal is also sent to the process; see @ref{Signal Handling}.
412 Unless you have arranged to prevent @code{EINTR} failures, you should
413 check @code{errno} after each failing call to @code{write}, and if the
414 error was @code{EINTR}, you should simply repeat the call.
415 @xref{Interrupted Primitives}. The easy way to do this is with the
416 macro @code{TEMP_FAILURE_RETRY}, as follows:
419 nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
422 The @code{write} function is the underlying primitive for all of the
423 functions that write to streams, such as @code{fputc}.
428 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset})
429 The @code{pwrite} function is similar to the @code{write} function. The
430 first three arguments are identical and also the return values and error
433 The difference is the fourth argument and its handling. The data block
434 is not written to the current position of the file descriptor
435 @code{filedes}. Instead the data is written to the file starting at
436 position @var{offset}. The position of the file descriptor itself is
437 not effected by the operation. The value is the same as before the call.
439 The return value of @code{pwrite} describes the number of written bytes.
440 In the error case it returns @math{-1} like @code{write} does and the
441 error codes are also the same. Only there are a few more error codes:
444 The value given for @var{offset} is negative and therefore illegal.
447 The file descriptor @var{filedes} is associate with a pipe or a FIFO and
448 this device does not allow positioning of the file pointer.
451 The function is an extension defined in the Unix Single Specification
456 @node File Position Primitive
457 @section Setting the File Position of a Descriptor
459 Just as you can set the file position of a stream with @code{fseek}, you
460 can set the file position of a descriptor with @code{lseek}. This
461 specifies the position in the file for the next @code{read} or
462 @code{write} operation. @xref{File Positioning}, for more information
463 on the file position and what it means.
465 To read the current file position value from a descriptor, use
466 @code{lseek (@var{desc}, 0, SEEK_CUR)}.
468 @cindex file positioning on a file descriptor
469 @cindex positioning a file descriptor
470 @cindex seeking on a file descriptor
473 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
474 The @code{lseek} function is used to change the file position of the
475 file with descriptor @var{filedes}.
477 The @var{whence} argument specifies how the @var{offset} should be
478 interpreted in the same way as for the @code{fseek} function, and must be
479 one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
484 Specifies that @var{whence} is a count of characters from the beginning
488 Specifies that @var{whence} is a count of characters from the current
489 file position. This count may be positive or negative.
492 Specifies that @var{whence} is a count of characters from the end of
493 the file. A negative count specifies a position within the current
494 extent of the file; a positive count specifies a position past the
495 current end. If you set the position past the current end, and
496 actually write data, you will extend the file with zeros up to that
499 The return value from @code{lseek} is normally the resulting file
500 position, measured in bytes from the beginning of the file.
501 You can use this feature together with @code{SEEK_CUR} to read the
502 current file position.
504 If you want to append to the file, setting the file position to the
505 current end of file with @code{SEEK_END} is not sufficient. Another
506 process may write more data after you seek but before you write,
507 extending the file so the position you write onto clobbers their data.
508 Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
510 You can set the file position past the current end of the file. This
511 does not by itself make the file longer; @code{lseek} never changes the
512 file. But subsequent output at that position will extend the file.
513 Characters between the previous end of file and the new position are
514 filled with zeros. Extending the file in this way can create a
515 ``hole'': the blocks of zeros are not actually allocated on disk, so the
516 file takes up less space than it appears so; it is then called a
519 @cindex holes in files
521 If the file position cannot be changed, or the operation is in some way
522 invalid, @code{lseek} returns a value of @code{-1}. The following
523 @code{errno} error conditions are defined for this function:
527 The @var{filedes} is not a valid file descriptor.
530 The @var{whence} argument value is not valid, or the resulting
531 file offset is not valid. A file offset is invalid.
534 The @var{filedes} corresponds to an object that cannot be positioned,
535 such as a pipe, FIFO or terminal device. (POSIX.1 specifies this error
536 only for pipes and FIFOs, but in the GNU system, you always get
537 @code{ESPIPE} if the object is not seekable.)
540 The @code{lseek} function is the underlying primitive for the
541 @code{fseek}, @code{ftell} and @code{rewind} functions, which operate on
542 streams instead of file descriptors.
545 You can have multiple descriptors for the same file if you open the file
546 more than once, or if you duplicate a descriptor with @code{dup}.
547 Descriptors that come from separate calls to @code{open} have independent
548 file positions; using @code{lseek} on one descriptor has no effect on the
556 d1 = open ("foo", O_RDONLY);
557 d2 = open ("foo", O_RDONLY);
558 lseek (d1, 1024, SEEK_SET);
565 will read the first four characters of the file @file{foo}. (The
566 error-checking code necessary for a real program has been omitted here
569 By contrast, descriptors made by duplication share a common file
570 position with the original descriptor that was duplicated. Anything
571 which alters the file position of one of the duplicates, including
572 reading or writing data, affects all of them alike. Thus, for example,
577 char buf1[4], buf2[4];
578 d1 = open ("foo", O_RDONLY);
581 lseek (d3, 1024, SEEK_SET);
588 will read four characters starting with the 1024'th character of
589 @file{foo}, and then four more characters starting with the 1028'th
594 @deftp {Data Type} off_t
595 This is an arithmetic data type used to represent file sizes.
596 In the GNU system, this is equivalent to @code{fpos_t} or @code{long int}.
599 These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
600 of compatibility with older BSD systems. They are defined in two
601 different header files: @file{fcntl.h} and @file{sys/file.h}.
605 An alias for @code{SEEK_SET}.
608 An alias for @code{SEEK_CUR}.
611 An alias for @code{SEEK_END}.
614 @node Descriptors and Streams
615 @section Descriptors and Streams
616 @cindex streams, and file descriptors
617 @cindex converting file descriptor to stream
618 @cindex extracting file descriptor from stream
620 Given an open file descriptor, you can create a stream for it with the
621 @code{fdopen} function. You can get the underlying file descriptor for
622 an existing stream with the @code{fileno} function. These functions are
623 declared in the header file @file{stdio.h}.
628 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
629 The @code{fdopen} function returns a new stream for the file descriptor
632 The @var{opentype} argument is interpreted in the same way as for the
633 @code{fopen} function (@pxref{Opening Streams}), except that
634 the @samp{b} option is not permitted; this is because GNU makes no
635 distinction between text and binary files. Also, @code{"w"} and
636 @code{"w+"} do not cause truncation of the file; these have affect only
637 when opening a file, and in this case the file has already been opened.
638 You must make sure that the @var{opentype} argument matches the actual
639 mode of the open file descriptor.
641 The return value is the new stream. If the stream cannot be created
642 (for example, if the modes for the file indicated by the file descriptor
643 do not permit the access specified by the @var{opentype} argument), a
644 null pointer is returned instead.
646 In some other systems, @code{fdopen} may fail to detect that the modes
647 for file descriptor do not permit the access specified by
648 @code{opentype}. The GNU C library always checks for this.
651 For an example showing the use of the @code{fdopen} function,
652 see @ref{Creating a Pipe}.
656 @deftypefun int fileno (FILE *@var{stream})
657 This function returns the file descriptor associated with the stream
658 @var{stream}. If an error is detected (for example, if the @var{stream}
659 is not valid) or if @var{stream} does not do I/O to a file,
660 @code{fileno} returns @code{-1}.
663 @cindex standard file descriptors
664 @cindex file descriptors, standard
665 There are also symbolic constants defined in @file{unistd.h} for the
666 file descriptors belonging to the standard streams @code{stdin},
667 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
675 This macro has value @code{0}, which is the file descriptor for
677 @cindex standard input file descriptor
682 @vindex STDOUT_FILENO
683 This macro has value @code{1}, which is the file descriptor for
685 @cindex standard output file descriptor
690 @vindex STDERR_FILENO
691 This macro has value @code{2}, which is the file descriptor for
692 standard error output.
694 @cindex standard error file descriptor
696 @node Stream/Descriptor Precautions
697 @section Dangers of Mixing Streams and Descriptors
699 @cindex streams and descriptors
700 @cindex descriptors and streams
701 @cindex mixing descriptors and streams
703 You can have multiple file descriptors and streams (let's call both
704 streams and descriptors ``channels'' for short) connected to the same
705 file, but you must take care to avoid confusion between channels. There
706 are two cases to consider: @dfn{linked} channels that share a single
707 file position value, and @dfn{independent} channels that have their own
710 It's best to use just one channel in your program for actual data
711 transfer to any given file, except when all the access is for input.
712 For example, if you open a pipe (something you can only do at the file
713 descriptor level), either do all I/O with the descriptor, or construct a
714 stream from the descriptor with @code{fdopen} and then do all I/O with
718 * Linked Channels:: Dealing with channels sharing a file position.
719 * Independent Channels:: Dealing with separately opened, unlinked channels.
720 * Cleaning Streams:: Cleaning a stream makes it safe to use
724 @node Linked Channels
725 @subsection Linked Channels
726 @cindex linked channels
728 Channels that come from a single opening share the same file position;
729 we call them @dfn{linked} channels. Linked channels result when you
730 make a stream from a descriptor using @code{fdopen}, when you get a
731 descriptor from a stream with @code{fileno}, when you copy a descriptor
732 with @code{dup} or @code{dup2}, and when descriptors are inherited
733 during @code{fork}. For files that don't support random access, such as
734 terminals and pipes, @emph{all} channels are effectively linked. On
735 random-access files, all append-type output streams are effectively
736 linked to each other.
738 @cindex cleaning up a stream
739 If you have been using a stream for I/O, and you want to do I/O using
740 another channel (either a stream or a descriptor) that is linked to it,
741 you must first @dfn{clean up} the stream that you have been using.
742 @xref{Cleaning Streams}.
744 Terminating a process, or executing a new program in the process,
745 destroys all the streams in the process. If descriptors linked to these
746 streams persist in other processes, their file positions become
747 undefined as a result. To prevent this, you must clean up the streams
748 before destroying them.
750 @node Independent Channels
751 @subsection Independent Channels
752 @cindex independent channels
754 When you open channels (streams or descriptors) separately on a seekable
755 file, each channel has its own file position. These are called
756 @dfn{independent channels}.
758 The system handles each channel independently. Most of the time, this
759 is quite predictable and natural (especially for input): each channel
760 can read or write sequentially at its own place in the file. However,
761 if some of the channels are streams, you must take these precautions:
765 You should clean an output stream after use, before doing anything else
766 that might read or write from the same part of the file.
769 You should clean an input stream before reading data that may have been
770 modified using an independent channel. Otherwise, you might read
771 obsolete data that had been in the stream's buffer.
774 If you do output to one channel at the end of the file, this will
775 certainly leave the other independent channels positioned somewhere
776 before the new end. You cannot reliably set their file positions to the
777 new end of file before writing, because the file can always be extended
778 by another process between when you set the file position and when you
779 write the data. Instead, use an append-type descriptor or stream; they
780 always output at the current end of the file. In order to make the
781 end-of-file position accurate, you must clean the output channel you
782 were using, if it is a stream.
784 It's impossible for two channels to have separate file pointers for a
785 file that doesn't support random access. Thus, channels for reading or
786 writing such files are always linked, never independent. Append-type
787 channels are also always linked. For these channels, follow the rules
788 for linked channels; see @ref{Linked Channels}.
790 @node Cleaning Streams
791 @subsection Cleaning Streams
793 On the GNU system, you can clean up any stream with @code{fclean}:
797 @deftypefun int fclean (FILE *@var{stream})
798 Clean up the stream @var{stream} so that its buffer is empty. If
799 @var{stream} is doing output, force it out. If @var{stream} is doing
800 input, give the data in the buffer back to the system, arranging to
804 On other systems, you can use @code{fflush} to clean a stream in most
807 You can skip the @code{fclean} or @code{fflush} if you know the stream
808 is already clean. A stream is clean whenever its buffer is empty. For
809 example, an unbuffered stream is always clean. An input stream that is
810 at end-of-file is clean. A line-buffered stream is clean when the last
811 character output was a newline.
813 There is one case in which cleaning a stream is impossible on most
814 systems. This is when the stream is doing input from a file that is not
815 random-access. Such streams typically read ahead, and when the file is
816 not random access, there is no way to give back the excess data already
817 read. When an input stream reads from a random-access file,
818 @code{fflush} does clean the stream, but leaves the file pointer at an
819 unpredictable place; you must set the file pointer before doing any
820 further I/O. On the GNU system, using @code{fclean} avoids both of
823 Closing an output-only stream also does @code{fflush}, so this is a
824 valid way of cleaning an output stream. On the GNU system, closing an
825 input stream does @code{fclean}.
827 You need not clean a stream before using its descriptor for control
828 operations such as setting terminal modes; these operations don't affect
829 the file position and are not affected by it. You can use any
830 descriptor for these operations, and all channels are affected
831 simultaneously. However, text already ``output'' to a stream but still
832 buffered by the stream will be subject to the new terminal modes when
833 subsequently flushed. To make sure ``past'' output is covered by the
834 terminal settings that were in effect at the time, flush the output
835 streams for that terminal before setting the modes. @xref{Terminal
838 @node Waiting for I/O
839 @section Waiting for Input or Output
840 @cindex waiting for input or output
841 @cindex multiplexing input
842 @cindex input from multiple files
844 Sometimes a program needs to accept input on multiple input channels
845 whenever input arrives. For example, some workstations may have devices
846 such as a digitizing tablet, function button box, or dial box that are
847 connected via normal asynchronous serial interfaces; good user interface
848 style requires responding immediately to input on any device. Another
849 example is a program that acts as a server to several other processes
850 via pipes or sockets.
852 You cannot normally use @code{read} for this purpose, because this
853 blocks the program until input is available on one particular file
854 descriptor; input on other channels won't wake it up. You could set
855 nonblocking mode and poll each file descriptor in turn, but this is very
858 A better solution is to use the @code{select} function. This blocks the
859 program until input or output is ready on a specified set of file
860 descriptors, or until a timer expires, whichever comes first. This
861 facility is declared in the header file @file{sys/types.h}.
864 In the case of a server socket (@pxref{Listening}), we say that
865 ``input'' is available when there are pending connections that could be
866 accepted (@pxref{Accepting Connections}). @code{accept} for server
867 sockets blocks and interacts with @code{select} just as @code{read} does
870 @cindex file descriptor sets, for @code{select}
871 The file descriptor sets for the @code{select} function are specified
872 as @code{fd_set} objects. Here is the description of the data type
873 and some macros for manipulating these objects.
877 @deftp {Data Type} fd_set
878 The @code{fd_set} data type represents file descriptor sets for the
879 @code{select} function. It is actually a bit array.
884 @deftypevr Macro int FD_SETSIZE
885 The value of this macro is the maximum number of file descriptors that a
886 @code{fd_set} object can hold information about. On systems with a
887 fixed maximum number, @code{FD_SETSIZE} is at least that number. On
888 some systems, including GNU, there is no absolute limit on the number of
889 descriptors open, but this macro still has a constant value which
890 controls the number of bits in an @code{fd_set}; if you get a file
891 descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
892 that descriptor into an @code{fd_set}.
897 @deftypefn Macro void FD_ZERO (fd_set *@var{set})
898 This macro initializes the file descriptor set @var{set} to be the
904 @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
905 This macro adds @var{filedes} to the file descriptor set @var{set}.
910 @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
911 This macro removes @var{filedes} from the file descriptor set @var{set}.
916 @deftypefn Macro int FD_ISSET (int @var{filedes}, fd_set *@var{set})
917 This macro returns a nonzero value (true) if @var{filedes} is a member
918 of the the file descriptor set @var{set}, and zero (false) otherwise.
921 Next, here is the description of the @code{select} function itself.
925 @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})
926 The @code{select} function blocks the calling process until there is
927 activity on any of the specified sets of file descriptors, or until the
928 timeout period has expired.
930 The file descriptors specified by the @var{read-fds} argument are
931 checked to see if they are ready for reading; the @var{write-fds} file
932 descriptors are checked to see if they are ready for writing; and the
933 @var{except-fds} file descriptors are checked for exceptional
934 conditions. You can pass a null pointer for any of these arguments if
935 you are not interested in checking for that kind of condition.
937 A file descriptor is considered ready for reading if it is at end of
938 file. A server socket is considered ready for reading if there is a
939 pending connection which can be accepted with @code{accept};
940 @pxref{Accepting Connections}. A client socket is ready for writing when
941 its connection is fully established; @pxref{Connecting}.
943 ``Exceptional conditions'' does not mean errors---errors are reported
944 immediately when an erroneous system call is executed, and do not
945 constitute a state of the descriptor. Rather, they include conditions
946 such as the presence of an urgent message on a socket. (@xref{Sockets},
947 for information on urgent messages.)
949 The @code{select} function checks only the first @var{nfds} file
950 descriptors. The usual thing is to pass @code{FD_SETSIZE} as the value
953 The @var{timeout} specifies the maximum time to wait. If you pass a
954 null pointer for this argument, it means to block indefinitely until one
955 of the file descriptors is ready. Otherwise, you should provide the
956 time in @code{struct timeval} format; see @ref{High-Resolution
957 Calendar}. Specify zero as the time (a @code{struct timeval} containing
958 all zeros) if you want to find out which descriptors are ready without
959 waiting if none are ready.
961 The normal return value from @code{select} is the total number of ready file
962 descriptors in all of the sets. Each of the argument sets is overwritten
963 with information about the descriptors that are ready for the corresponding
964 operation. Thus, to see if a particular descriptor @var{desc} has input,
965 use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
967 If @code{select} returns because the timeout period expires, it returns
970 Any signal will cause @code{select} to return immediately. So if your
971 program uses signals, you can't rely on @code{select} to keep waiting
972 for the full time specified. If you want to be sure of waiting for a
973 particular amount of time, you must check for @code{EINTR} and repeat
974 the @code{select} with a newly calculated timeout based on the current
975 time. See the example below. See also @ref{Interrupted Primitives}.
977 If an error occurs, @code{select} returns @code{-1} and does not modify
978 the argument file descriptor sets. The following @code{errno} error
979 conditions are defined for this function:
983 One of the file descriptor sets specified an invalid file descriptor.
986 The operation was interrupted by a signal. @xref{Interrupted Primitives}.
989 The @var{timeout} argument is invalid; one of the components is negative
994 @strong{Portability Note:} The @code{select} function is a BSD Unix
997 Here is an example showing how you can use @code{select} to establish a
998 timeout period for reading from a file descriptor. The @code{input_timeout}
999 function blocks the calling process until input is available on the
1000 file descriptor, or until the timeout period expires.
1003 @include select.c.texi
1006 There is another example showing the use of @code{select} to multiplex
1007 input from multiple sockets in @ref{Server Example}.
1010 @node Control Operations
1011 @section Control Operations on Files
1013 @cindex control operations on files
1014 @cindex @code{fcntl} function
1015 This section describes how you can perform various other operations on
1016 file descriptors, such as inquiring about or setting flags describing
1017 the status of the file descriptor, manipulating record locks, and the
1018 like. All of these operations are performed by the function @code{fcntl}.
1020 The second argument to the @code{fcntl} function is a command that
1021 specifies which operation to perform. The function and macros that name
1022 various flags that are used with it are declared in the header file
1023 @file{fcntl.h}. Many of these flags are also used by the @code{open}
1024 function; see @ref{Opening and Closing Files}.
1029 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
1030 The @code{fcntl} function performs the operation specified by
1031 @var{command} on the file descriptor @var{filedes}. Some commands
1032 require additional arguments to be supplied. These additional arguments
1033 and the return value and error conditions are given in the detailed
1034 descriptions of the individual commands.
1036 Briefly, here is a list of what the various commands are.
1040 Duplicate the file descriptor (return another file descriptor pointing
1041 to the same open file). @xref{Duplicating Descriptors}.
1044 Get flags associated with the file descriptor. @xref{Descriptor Flags}.
1047 Set flags associated with the file descriptor. @xref{Descriptor Flags}.
1050 Get flags associated with the open file. @xref{File Status Flags}.
1053 Set flags associated with the open file. @xref{File Status Flags}.
1056 Get a file lock. @xref{File Locks}.
1059 Set or clear a file lock. @xref{File Locks}.
1062 Like @code{F_SETLK}, but wait for completion. @xref{File Locks}.
1065 Get process or process group ID to receive @code{SIGIO} signals.
1066 @xref{Interrupt Input}.
1069 Set process or process group ID to receive @code{SIGIO} signals.
1070 @xref{Interrupt Input}.
1075 @node Duplicating Descriptors
1076 @section Duplicating Descriptors
1078 @cindex duplicating file descriptors
1079 @cindex redirecting input and output
1081 You can @dfn{duplicate} a file descriptor, or allocate another file
1082 descriptor that refers to the same open file as the original. Duplicate
1083 descriptors share one file position and one set of file status flags
1084 (@pxref{File Status Flags}), but each has its own set of file descriptor
1085 flags (@pxref{Descriptor Flags}).
1087 The major use of duplicating a file descriptor is to implement
1088 @dfn{redirection} of input or output: that is, to change the
1089 file or pipe that a particular file descriptor corresponds to.
1091 You can perform this operation using the @code{fcntl} function with the
1092 @code{F_DUPFD} command, but there are also convenient functions
1093 @code{dup} and @code{dup2} for duplicating descriptors.
1097 The @code{fcntl} function and flags are declared in @file{fcntl.h},
1098 while prototypes for @code{dup} and @code{dup2} are in the header file
1103 @deftypefun int dup (int @var{old})
1104 This function copies descriptor @var{old} to the first available
1105 descriptor number (the first number not currently open). It is
1106 equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
1111 @deftypefun int dup2 (int @var{old}, int @var{new})
1112 This function copies the descriptor @var{old} to descriptor number
1115 If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
1116 does not close @var{new}. Otherwise, the new duplicate of @var{old}
1117 replaces any previous meaning of descriptor @var{new}, as if @var{new}
1120 If @var{old} and @var{new} are different numbers, and @var{old} is a
1121 valid descriptor number, then @code{dup2} is equivalent to:
1125 fcntl (@var{old}, F_DUPFD, @var{new})
1128 However, @code{dup2} does this atomically; there is no instant in the
1129 middle of calling @code{dup2} at which @var{new} is closed and not yet a
1130 duplicate of @var{old}.
1135 @deftypevr Macro int F_DUPFD
1136 This macro is used as the @var{command} argument to @code{fcntl}, to
1137 copy the file descriptor given as the first argument.
1139 The form of the call in this case is:
1142 fcntl (@var{old}, F_DUPFD, @var{next-filedes})
1145 The @var{next-filedes} argument is of type @code{int} and specifies that
1146 the file descriptor returned should be the next available one greater
1147 than or equal to this value.
1149 The return value from @code{fcntl} with this command is normally the value
1150 of the new file descriptor. A return value of @code{-1} indicates an
1151 error. The following @code{errno} error conditions are defined for
1156 The @var{old} argument is invalid.
1159 The @var{next-filedes} argument is invalid.
1162 There are no more file descriptors available---your program is already
1163 using the maximum. In BSD and GNU, the maximum is controlled by a
1164 resource limit that can be changed; @pxref{Limits on Resources}, for
1165 more information about the @code{RLIMIT_NOFILE} limit.
1168 @code{ENFILE} is not a possible error code for @code{dup2} because
1169 @code{dup2} does not create a new opening of a file; duplicate
1170 descriptors do not count toward the limit which @code{ENFILE}
1171 indicates. @code{EMFILE} is possible because it refers to the limit on
1172 distinct descriptor numbers in use in one process.
1175 Here is an example showing how to use @code{dup2} to do redirection.
1176 Typically, redirection of the standard streams (like @code{stdin}) is
1177 done by a shell or shell-like program before calling one of the
1178 @code{exec} functions (@pxref{Executing a File}) to execute a new
1179 program in a child process. When the new program is executed, it
1180 creates and initializes the standard streams to point to the
1181 corresponding file descriptors, before its @code{main} function is
1184 So, to redirect standard input to a file, the shell could do something
1195 file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
1196 dup2 (file, STDIN_FILENO);
1197 TEMP_FAILURE_RETRY (close (file));
1198 execv (program, NULL);
1202 There is also a more detailed example showing how to implement redirection
1203 in the context of a pipeline of processes in @ref{Launching Jobs}.
1206 @node Descriptor Flags
1207 @section File Descriptor Flags
1208 @cindex file descriptor flags
1210 @dfn{File descriptor flags} are miscellaneous attributes of a file
1211 descriptor. These flags are associated with particular file
1212 descriptors, so that if you have created duplicate file descriptors
1213 from a single opening of a file, each descriptor has its own set of flags.
1215 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
1216 which causes the descriptor to be closed if you use any of the
1217 @code{exec@dots{}} functions (@pxref{Executing a File}).
1219 The symbols in this section are defined in the header file
1225 @deftypevr Macro int F_GETFD
1226 This macro is used as the @var{command} argument to @code{fcntl}, to
1227 specify that it should return the file descriptor flags associated
1228 with the @var{filedes} argument.
1230 The normal return value from @code{fcntl} with this command is a
1231 nonnegative number which can be interpreted as the bitwise OR of the
1232 individual flags (except that currently there is only one flag to use).
1234 In case of an error, @code{fcntl} returns @code{-1}. The following
1235 @code{errno} error conditions are defined for this command:
1239 The @var{filedes} argument is invalid.
1246 @deftypevr Macro int F_SETFD
1247 This macro is used as the @var{command} argument to @code{fcntl}, to
1248 specify that it should set the file descriptor flags associated with the
1249 @var{filedes} argument. This requires a third @code{int} argument to
1250 specify the new flags, so the form of the call is:
1253 fcntl (@var{filedes}, F_SETFD, @var{new-flags})
1256 The normal return value from @code{fcntl} with this command is an
1257 unspecified value other than @code{-1}, which indicates an error.
1258 The flags and error conditions are the same as for the @code{F_GETFD}
1262 The following macro is defined for use as a file descriptor flag with
1263 the @code{fcntl} function. The value is an integer constant usable
1264 as a bit mask value.
1268 @deftypevr Macro int FD_CLOEXEC
1269 @cindex close-on-exec (file descriptor flag)
1270 This flag specifies that the file descriptor should be closed when
1271 an @code{exec} function is invoked; see @ref{Executing a File}. When
1272 a file descriptor is allocated (as with @code{open} or @code{dup}),
1273 this bit is initially cleared on the new file descriptor, meaning that
1274 descriptor will survive into the new program after @code{exec}.
1277 If you want to modify the file descriptor flags, you should get the
1278 current flags with @code{F_GETFD} and modify the value. Don't assume
1279 that the flags listed here are the only ones that are implemented; your
1280 program may be run years from now and more flags may exist then. For
1281 example, here is a function to set or clear the flag @code{FD_CLOEXEC}
1282 without altering any other flags:
1285 /* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
1286 @r{or clear the flag if @var{value} is 0.}
1287 @r{Return 0 on success, or -1 on error with @code{errno} set.} */
1290 set_cloexec_flag (int desc, int value)
1292 int oldflags = fcntl (desc, F_GETFD, 0);
1293 /* @r{If reading the flags failed, return error indication now.}
1296 /* @r{Set just the flag we want to set.} */
1298 oldflags |= FD_CLOEXEC;
1300 oldflags &= ~FD_CLOEXEC;
1301 /* @r{Store modified flag word in the descriptor.} */
1302 return fcntl (desc, F_SETFD, oldflags);
1306 @node File Status Flags
1307 @section File Status Flags
1308 @cindex file status flags
1310 @dfn{File status flags} are used to specify attributes of the opening of a
1311 file. Unlike the file descriptor flags discussed in @ref{Descriptor
1312 Flags}, the file status flags are shared by duplicated file descriptors
1313 resulting from a single opening of the file. The file status flags are
1314 specified with the @var{flags} argument to @code{open};
1315 @pxref{Opening and Closing Files}.
1317 File status flags fall into three categories, which are described in the
1322 @ref{Access Modes}, specify what type of access is allowed to the
1323 file: reading, writing, or both. They are set by @code{open} and are
1324 returned by @code{fcntl}, but cannot be changed.
1327 @ref{Open-time Flags}, control details of what @code{open} will do.
1328 These flags are not preserved after the @code{open} call.
1331 @ref{Operating Modes}, affect how operations such as @code{read} and
1332 @code{write} are done. They are set by @code{open}, and can be fetched or
1333 changed with @code{fcntl}.
1336 The symbols in this section are defined in the header file
1341 * Access Modes:: Whether the descriptor can read or write.
1342 * Open-time Flags:: Details of @code{open}.
1343 * Operating Modes:: Special modes to control I/O operations.
1344 * Getting File Status Flags:: Fetching and changing these flags.
1348 @subsection File Access Modes
1350 The file access modes allow a file descriptor to be used for reading,
1351 writing, or both. (In the GNU system, they can also allow none of these,
1352 and allow execution of the file as a program.) The access modes are chosen
1353 when the file is opened, and never change.
1357 @deftypevr Macro int O_RDONLY
1358 Open the file for read access.
1363 @deftypevr Macro int O_WRONLY
1364 Open the file for write access.
1369 @deftypevr Macro int O_RDWR
1370 Open the file for both reading and writing.
1373 In the GNU system (and not in other systems), @code{O_RDONLY} and
1374 @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
1375 and it is valid for either bit to be set or clear. This means that
1376 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}. A file access
1377 mode of zero is permissible; it allows no operations that do input or
1378 output to the file, but does allow other operations such as
1379 @code{fchmod}. On the GNU system, since ``read-only'' or ``write-only''
1380 is a misnomer, @file{fcntl.h} defines additional names for the file
1381 access modes. These names are preferred when writing GNU-specific code.
1382 But most programs will want to be portable to other POSIX.1 systems and
1383 should use the POSIX.1 names above instead.
1387 @deftypevr Macro int O_READ
1388 Open the file for reading. Same as @code{O_RDWR}; only defined on GNU.
1393 @deftypevr Macro int O_WRITE
1394 Open the file for reading. Same as @code{O_WRONLY}; only defined on GNU.
1399 @deftypevr Macro int O_EXEC
1400 Open the file for executing. Only defined on GNU.
1403 To determine the file access mode with @code{fcntl}, you must extract
1404 the access mode bits from the retrieved file status flags. In the GNU
1405 system, you can just test the @code{O_READ} and @code{O_WRITE} bits in
1406 the flags word. But in other POSIX.1 systems, reading and writing
1407 access modes are not stored as distinct bit flags. The portable way to
1408 extract the file access mode bits is with @code{O_ACCMODE}.
1412 @deftypevr Macro int O_ACCMODE
1413 This macro stands for a mask that can be bitwise-ANDed with the file
1414 status flag value to produce a value representing the file access mode.
1415 The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
1416 (In the GNU system it could also be zero, and it never includes the
1420 @node Open-time Flags
1421 @subsection Open-time Flags
1423 The open-time flags specify options affecting how @code{open} will behave.
1424 These options are not preserved once the file is open. The exception to
1425 this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
1426 @emph{is} saved. @xref{Opening and Closing Files}, for how to call
1429 There are two sorts of options specified by open-time flags.
1433 @dfn{File name translation flags} affect how @code{open} looks up the
1434 file name to locate the file, and whether the file can be created.
1435 @cindex file name translation flags
1436 @cindex flags, file name translation
1439 @dfn{Open-time action flags} specify extra operations that @code{open} will
1440 perform on the file once it is open.
1441 @cindex open-time action flags
1442 @cindex flags, open-time action
1445 Here are the file name translation flags.
1449 @deftypevr Macro int O_CREAT
1450 If set, the file will be created if it doesn't already exist.
1451 @c !!! mode arg, umask
1452 @cindex create on open (file status flag)
1457 @deftypevr Macro int O_EXCL
1458 If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
1459 if the specified file already exists. This is guaranteed to never
1460 clobber an existing file.
1465 @deftypevr Macro int O_NONBLOCK
1466 @cindex non-blocking open
1467 This prevents @code{open} from blocking for a ``long time'' to open the
1468 file. This is only meaningful for some kinds of files, usually devices
1469 such as serial ports; when it is not meaningful, it is harmless and
1470 ignored. Often opening a port to a modem blocks until the modem reports
1471 carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
1472 return immediately without a carrier.
1474 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
1475 mode and a file name translation flag. This means that specifying
1476 @code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
1477 @pxref{Operating Modes}. To open the file without blocking but do normal
1478 I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
1479 then call @code{fcntl} to turn the bit off.
1484 @deftypevr Macro int O_NOCTTY
1485 If the named file is a terminal device, don't make it the controlling
1486 terminal for the process. @xref{Job Control}, for information about
1487 what it means to be the controlling terminal.
1489 In the GNU system and 4.4 BSD, opening a file never makes it the
1490 controlling terminal and @code{O_NOCTTY} is zero. However, other
1491 systems may use a nonzero value for @code{O_NOCTTY} and set the
1492 controlling terminal when you open a file that is a terminal device; so
1493 to be portable, use @code{O_NOCTTY} when it is important to avoid this.
1494 @cindex controlling terminal, setting
1497 The following three file name translation flags exist only in the GNU system.
1501 @deftypevr Macro int O_IGNORE_CTTY
1502 Do not recognize the named file as the controlling terminal, even if it
1503 refers to the process's existing controlling terminal device. Operations
1504 on the new file descriptor will never induce job control signals.
1510 @deftypevr Macro int O_NOLINK
1511 If the named file is a symbolic link, open the link itself instead of
1512 the file it refers to. (@code{fstat} on the new file descriptor will
1513 return the information returned by @code{lstat} on the link's name.)
1514 @cindex symbolic link, opening
1519 @deftypevr Macro int O_NOTRANS
1520 If the named file is specially translated, do not invoke the translator.
1521 Open the bare file the translator itself sees.
1525 The open-time action flags tell @code{open} to do additional operations
1526 which are not really related to opening the file. The reason to do them
1527 as part of @code{open} instead of in separate calls is that @code{open}
1528 can do them @i{atomically}.
1532 @deftypevr Macro int O_TRUNC
1533 Truncate the file to zero length. This option is only useful for
1534 regular files, not special files such as directories or FIFOs. POSIX.1
1535 requires that you open the file for writing to use @code{O_TRUNC}. In
1536 BSD and GNU you must have permission to write the file to truncate it,
1537 but you need not open for write access.
1539 This is the only open-time action flag specified by POSIX.1. There is
1540 no good reason for truncation to be done by @code{open}, instead of by
1541 calling @code{ftruncate} afterwards. The @code{O_TRUNC} flag existed in
1542 Unix before @code{ftruncate} was invented, and is retained for backward
1548 @deftypevr Macro int O_SHLOCK
1549 Acquire a shared lock on the file, as with @code{flock}.
1552 If @code{O_CREAT} is specified, the locking is done atomically when
1553 creating the file. You are guaranteed that no other process will get
1554 the lock on the new file first.
1559 @deftypevr Macro int O_EXLOCK
1560 Acquire an exclusive lock on the file, as with @code{flock}.
1561 @xref{File Locks}. This is atomic like @code{O_SHLOCK}.
1564 @node Operating Modes
1565 @subsection I/O Operating Modes
1567 The operating modes affect how input and output operations using a file
1568 descriptor work. These flags are set by @code{open} and can be fetched
1569 and changed with @code{fcntl}.
1573 @deftypevr Macro int O_APPEND
1574 The bit that enables append mode for the file. If set, then all
1575 @code{write} operations write the data at the end of the file, extending
1576 it, regardless of the current file position. This is the only reliable
1577 way to append to a file. In append mode, you are guaranteed that the
1578 data you write will always go to the current end of the file, regardless
1579 of other processes writing to the file. Conversely, if you simply set
1580 the file position to the end of file and write, then another process can
1581 extend the file after you set the file position but before you write,
1582 resulting in your data appearing someplace before the real end of file.
1587 @deftypevr Macro int O_NONBLOCK
1588 The bit that enables nonblocking mode for the file. If this bit is set,
1589 @code{read} requests on the file can return immediately with a failure
1590 status if there is no input immediately available, instead of blocking.
1591 Likewise, @code{write} requests can also return immediately with a
1592 failure status if the output can't be written immediately.
1594 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
1595 operating mode and a file name translation flag; @pxref{Open-time Flags}.
1600 @deftypevr Macro int O_NDELAY
1601 This is an obsolete name for @code{O_NONBLOCK}, provided for
1602 compatibility with BSD. It is not defined by the POSIX.1 standard.
1605 The remaining operating modes are BSD and GNU extensions. They exist only
1606 on some systems. On other systems, these macros are not defined.
1610 @deftypevr Macro int O_ASYNC
1611 The bit that enables asynchronous input mode. If set, then @code{SIGIO}
1612 signals will be generated when input is available. @xref{Interrupt Input}.
1614 Asynchronous input mode is a BSD feature.
1619 @deftypevr Macro int O_FSYNC
1620 The bit that enables synchronous writing for the file. If set, each
1621 @code{write} call will make sure the data is reliably stored on disk before
1622 returning. @c !!! xref fsync
1624 Synchronous writing is a BSD feature.
1629 @deftypevr Macro int O_SYNC
1630 This is another name for @code{O_FSYNC}. They have the same value.
1635 @deftypevr Macro int O_NOATIME
1636 If this bit is set, @code{read} will not update the access time of the
1637 file. @xref{File Times}. This is used by programs that do backups, so
1638 that backing a file up does not count as reading it.
1639 Only the owner of the file or the superuser may use this bit.
1641 This is a GNU extension.
1644 @node Getting File Status Flags
1645 @subsection Getting and Setting File Status Flags
1647 The @code{fcntl} function can fetch or change file status flags.
1651 @deftypevr Macro int F_GETFL
1652 This macro is used as the @var{command} argument to @code{fcntl}, to
1653 read the file status flags for the open file with descriptor
1656 The normal return value from @code{fcntl} with this command is a
1657 nonnegative number which can be interpreted as the bitwise OR of the
1658 individual flags. Since the file access modes are not single-bit values,
1659 you can mask off other bits in the returned flags with @code{O_ACCMODE}
1662 In case of an error, @code{fcntl} returns @code{-1}. The following
1663 @code{errno} error conditions are defined for this command:
1667 The @var{filedes} argument is invalid.
1673 @deftypevr Macro int F_SETFL
1674 This macro is used as the @var{command} argument to @code{fcntl}, to set
1675 the file status flags for the open file corresponding to the
1676 @var{filedes} argument. This command requires a third @code{int}
1677 argument to specify the new flags, so the call looks like this:
1680 fcntl (@var{filedes}, F_SETFL, @var{new-flags})
1683 You can't change the access mode for the file in this way; that is,
1684 whether the file descriptor was opened for reading or writing.
1686 The normal return value from @code{fcntl} with this command is an
1687 unspecified value other than @code{-1}, which indicates an error. The
1688 error conditions are the same as for the @code{F_GETFL} command.
1691 If you want to modify the file status flags, you should get the current
1692 flags with @code{F_GETFL} and modify the value. Don't assume that the
1693 flags listed here are the only ones that are implemented; your program
1694 may be run years from now and more flags may exist then. For example,
1695 here is a function to set or clear the flag @code{O_NONBLOCK} without
1696 altering any other flags:
1700 /* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
1701 @r{or clear the flag if @var{value} is 0.}
1702 @r{Return 0 on success, or -1 on error with @code{errno} set.} */
1705 set_nonblock_flag (int desc, int value)
1707 int oldflags = fcntl (desc, F_GETFL, 0);
1708 /* @r{If reading the flags failed, return error indication now.} */
1711 /* @r{Set just the flag we want to set.} */
1713 oldflags |= O_NONBLOCK;
1715 oldflags &= ~O_NONBLOCK;
1716 /* @r{Store modified flag word in the descriptor.} */
1717 return fcntl (desc, F_SETFL, oldflags);
1726 @cindex record locking
1727 The remaining @code{fcntl} commands are used to support @dfn{record
1728 locking}, which permits multiple cooperating programs to prevent each
1729 other from simultaneously accessing parts of a file in error-prone
1732 @cindex exclusive lock
1734 An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
1735 for writing to the specified part of the file. While a write lock is in
1736 place, no other process can lock that part of the file.
1740 A @dfn{shared} or @dfn{read} lock prohibits any other process from
1741 requesting a write lock on the specified part of the file. However,
1742 other processes can request read locks.
1744 The @code{read} and @code{write} functions do not actually check to see
1745 whether there are any locks in place. If you want to implement a
1746 locking protocol for a file shared by multiple processes, your application
1747 must do explicit @code{fcntl} calls to request and clear locks at the
1750 Locks are associated with processes. A process can only have one kind
1751 of lock set for each byte of a given file. When any file descriptor for
1752 that file is closed by the process, all of the locks that process holds
1753 on that file are released, even if the locks were made using other
1754 descriptors that remain open. Likewise, locks are released when a
1755 process exits, and are not inherited by child processes created using
1756 @code{fork} (@pxref{Creating a Process}).
1758 When making a lock, use a @code{struct flock} to specify what kind of
1759 lock and where. This data type and the associated macros for the
1760 @code{fcntl} function are declared in the header file @file{fcntl.h}.
1765 @deftp {Data Type} {struct flock}
1766 This structure is used with the @code{fcntl} function to describe a file
1767 lock. It has these members:
1770 @item short int l_type
1771 Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
1774 @item short int l_whence
1775 This corresponds to the @var{whence} argument to @code{fseek} or
1776 @code{lseek}, and specifies what the offset is relative to. Its value
1777 can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
1780 This specifies the offset of the start of the region to which the lock
1781 applies, and is given in bytes relative to the point specified by
1782 @code{l_whence} member.
1785 This specifies the length of the region to be locked. A value of
1786 @code{0} is treated specially; it means the region extends to the end of
1790 This field is the process ID (@pxref{Process Creation Concepts}) of the
1791 process holding the lock. It is filled in by calling @code{fcntl} with
1792 the @code{F_GETLK} command, but is ignored when making a lock.
1798 @deftypevr Macro int F_GETLK
1799 This macro is used as the @var{command} argument to @code{fcntl}, to
1800 specify that it should get information about a lock. This command
1801 requires a third argument of type @w{@code{struct flock *}} to be passed
1802 to @code{fcntl}, so that the form of the call is:
1805 fcntl (@var{filedes}, F_GETLK, @var{lockp})
1808 If there is a lock already in place that would block the lock described
1809 by the @var{lockp} argument, information about that lock overwrites
1810 @code{*@var{lockp}}. Existing locks are not reported if they are
1811 compatible with making a new lock as specified. Thus, you should
1812 specify a lock type of @code{F_WRLCK} if you want to find out about both
1813 read and write locks, or @code{F_RDLCK} if you want to find out about
1816 There might be more than one lock affecting the region specified by the
1817 @var{lockp} argument, but @code{fcntl} only returns information about
1818 one of them. The @code{l_whence} member of the @var{lockp} structure is
1819 set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
1820 set to identify the locked region.
1822 If no lock applies, the only change to the @var{lockp} structure is to
1823 update the @code{l_type} to a value of @code{F_UNLCK}.
1825 The normal return value from @code{fcntl} with this command is an
1826 unspecified value other than @code{-1}, which is reserved to indicate an
1827 error. The following @code{errno} error conditions are defined for
1832 The @var{filedes} argument is invalid.
1835 Either the @var{lockp} argument doesn't specify valid lock information,
1836 or the file associated with @var{filedes} doesn't support locks.
1842 @deftypevr Macro int F_SETLK
1843 This macro is used as the @var{command} argument to @code{fcntl}, to
1844 specify that it should set or clear a lock. This command requires a
1845 third argument of type @w{@code{struct flock *}} to be passed to
1846 @code{fcntl}, so that the form of the call is:
1849 fcntl (@var{filedes}, F_SETLK, @var{lockp})
1852 If the process already has a lock on any part of the region, the old lock
1853 on that part is replaced with the new lock. You can remove a lock
1854 by specifying a lock type of @code{F_UNLCK}.
1856 If the lock cannot be set, @code{fcntl} returns immediately with a value
1857 of @code{-1}. This function does not block waiting for other processes
1858 to release locks. If @code{fcntl} succeeds, it return a value other
1861 The following @code{errno} error conditions are defined for this
1867 The lock cannot be set because it is blocked by an existing lock on the
1868 file. Some systems use @code{EAGAIN} in this case, and other systems
1869 use @code{EACCES}; your program should treat them alike, after
1870 @code{F_SETLK}. (The GNU system always uses @code{EAGAIN}.)
1873 Either: the @var{filedes} argument is invalid; you requested a read lock
1874 but the @var{filedes} is not open for read access; or, you requested a
1875 write lock but the @var{filedes} is not open for write access.
1878 Either the @var{lockp} argument doesn't specify valid lock information,
1879 or the file associated with @var{filedes} doesn't support locks.
1882 The system has run out of file lock resources; there are already too
1883 many file locks in place.
1885 Well-designed file systems never report this error, because they have no
1886 limitation on the number of locks. However, you must still take account
1887 of the possibility of this error, as it could result from network access
1888 to a file system on another machine.
1894 @deftypevr Macro int F_SETLKW
1895 This macro is used as the @var{command} argument to @code{fcntl}, to
1896 specify that it should set or clear a lock. It is just like the
1897 @code{F_SETLK} command, but causes the process to block (or wait)
1898 until the request can be specified.
1900 This command requires a third argument of type @code{struct flock *}, as
1901 for the @code{F_SETLK} command.
1903 The @code{fcntl} return values and errors are the same as for the
1904 @code{F_SETLK} command, but these additional @code{errno} error conditions
1905 are defined for this command:
1909 The function was interrupted by a signal while it was waiting.
1910 @xref{Interrupted Primitives}.
1913 The specified region is being locked by another process. But that
1914 process is waiting to lock a region which the current process has
1915 locked, so waiting for the lock would result in deadlock. The system
1916 does not guarantee that it will detect all such conditions, but it lets
1917 you know if it notices one.
1922 The following macros are defined for use as values for the @code{l_type}
1923 member of the @code{flock} structure. The values are integer constants.
1930 This macro is used to specify a read (or shared) lock.
1936 This macro is used to specify a write (or exclusive) lock.
1942 This macro is used to specify that the region is unlocked.
1945 As an example of a situation where file locking is useful, consider a
1946 program that can be run simultaneously by several different users, that
1947 logs status information to a common file. One example of such a program
1948 might be a game that uses a file to keep track of high scores. Another
1949 example might be a program that records usage or accounting information
1950 for billing purposes.
1952 Having multiple copies of the program simultaneously writing to the
1953 file could cause the contents of the file to become mixed up. But
1954 you can prevent this kind of problem by setting a write lock on the
1955 file before actually writing to the file.
1957 If the program also needs to read the file and wants to make sure that
1958 the contents of the file are in a consistent state, then it can also use
1959 a read lock. While the read lock is set, no other process can lock
1960 that part of the file for writing.
1962 @c ??? This section could use an example program.
1964 Remember that file locks are only a @emph{voluntary} protocol for
1965 controlling access to a file. There is still potential for access to
1966 the file by programs that don't use the lock protocol.
1968 @node Interrupt Input
1969 @section Interrupt-Driven Input
1971 @cindex interrupt-driven input
1972 If you set the @code{O_ASYNC} status flag on a file descriptor
1973 (@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
1974 input or output becomes possible on that file descriptor. The process
1975 or process group to receive the signal can be selected by using the
1976 @code{F_SETOWN} command to the @code{fcntl} function. If the file
1977 descriptor is a socket, this also selects the recipient of @code{SIGURG}
1978 signals that are delivered when out-of-band data arrives on that socket;
1979 see @ref{Out-of-Band Data}. (@code{SIGURG} is sent in any situation
1980 where @code{select} would report the socket as having an ``exceptional
1981 condition''. @xref{Waiting for I/O}.)
1983 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
1984 signals are sent to the foreground process group of the terminal.
1988 The symbols in this section are defined in the header file
1993 @deftypevr Macro int F_GETOWN
1994 This macro is used as the @var{command} argument to @code{fcntl}, to
1995 specify that it should get information about the process or process
1996 group to which @code{SIGIO} signals are sent. (For a terminal, this is
1997 actually the foreground process group ID, which you can get using
1998 @code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
2000 The return value is interpreted as a process ID; if negative, its
2001 absolute value is the process group ID.
2003 The following @code{errno} error condition is defined for this command:
2007 The @var{filedes} argument is invalid.
2013 @deftypevr Macro int F_SETOWN
2014 This macro is used as the @var{command} argument to @code{fcntl}, to
2015 specify that it should set the process or process group to which
2016 @code{SIGIO} signals are sent. This command requires a third argument
2017 of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
2021 fcntl (@var{filedes}, F_SETOWN, @var{pid})
2024 The @var{pid} argument should be a process ID. You can also pass a
2025 negative number whose absolute value is a process group ID.
2027 The return value from @code{fcntl} with this command is @code{-1}
2028 in case of error and some other value if successful. The following
2029 @code{errno} error conditions are defined for this command:
2033 The @var{filedes} argument is invalid.
2036 There is no process or process group corresponding to @var{pid}.
2040 @c ??? This section could use an example program.