Finish gettext section.
[kopensolaris-gnu/glibc.git] / manual / llio.texi
1 @node Low-Level I/O, File System Interface, I/O on Streams, Top
2 @chapter Low-Level Input/Output
3
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.
9
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:
13
14 @itemize @bullet
15 @item
16 For reading binary files in large chunks.
17
18 @item
19 For reading an entire file into core before parsing it.
20
21 @item
22 To perform operations other than data transfer, which can only be done
23 with a descriptor.  (You can use @code{fileno} to get the descriptor
24 corresponding to a stream.)
25
26 @item
27 To pass descriptors to a child process.  (The child can create its own
28 stream to use a descriptor that it inherits, but cannot inherit a stream
29 directly.)
30 @end itemize
31
32 @menu
33 * Opening and Closing Files::           How to open and close file
34                                          descriptors.
35 * I/O Primitives::                      Reading and writing data.
36 * File Position Primitive::             Setting a descriptor's file
37                                          position.
38 * Descriptors and Streams::             Converting descriptor to stream
39                                          or vice-versa.
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
45                                          descriptors.
46 * Duplicating Descriptors::             Fcntl commands for duplicating
47                                          file descriptors.
48 * Descriptor Flags::                    Fcntl commands for manipulating
49                                          flags associated with file
50                                          descriptors.
51 * File Status Flags::                   Fcntl commands for manipulating
52                                          flags associated with open files.
53 * File Locks::                          Fcntl commands for implementing
54                                          file locking.
55 * Interrupt Input::                     Getting an asynchronous signal when
56                                          input arrives.
57 @end menu
58
59
60 @node Opening and Closing Files
61 @section Opening and Closing Files
62
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}.
69 @pindex unistd.h
70 @pindex fcntl.h
71
72 @comment fcntl.h
73 @comment POSIX.1
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.
80
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.
85
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
90 for this function:
91
92 @table @code
93 @item EACCES
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
96 it cannot be created.
97
98 @item EEXIST
99 Both @code{O_CREAT} and @code{O_EXCL} are set, and the named file already
100 exists.
101
102 @item EINTR
103 The @code{open} operation was interrupted by a signal.
104 @xref{Interrupted Primitives}.
105
106 @item EISDIR
107 The @var{flags} argument specified write access, and the file is a directory.
108
109 @item EMFILE
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}.
113
114 @item ENFILE
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.)
118
119 @item ENOENT
120 The named file does not exist, and @code{O_CREAT} is not specified.
121
122 @item ENOSPC
123 The directory or file system that would contain the new file cannot be
124 extended, because there is no disk space left.
125
126 @item ENXIO
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.
130
131 @item EROFS
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.
135 @end table
136
137 @c !!! umask
138
139 The @code{open} function is the underlying primitive for the @code{fopen}
140 and @code{freopen} functions, that create streams.
141 @end deftypefun
142
143 @comment fcntl.h
144 @comment POSIX.1
145 @deftypefn {Obsolete function} int creat (const char *@var{filename}, mode_t @var{mode})
146 This function is obsolete.  The call:
147
148 @smallexample
149 creat (@var{filename}, @var{mode})
150 @end smallexample
151
152 @noindent
153 is equivalent to:
154
155 @smallexample
156 open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode})
157 @end smallexample
158 @end deftypefn
159
160 @comment unistd.h
161 @comment POSIX.1
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:
165
166 @itemize @bullet
167 @item
168 The file descriptor is deallocated.
169
170 @item
171 Any record locks owned by the process on the file are unlocked.
172
173 @item
174 When all file descriptors associated with a pipe or FIFO have been closed,
175 any unread data is discarded.
176 @end itemize
177
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:
181
182 @table @code
183 @item EBADF
184 The @var{filedes} argument is not a valid file descriptor.
185
186 @item EINTR
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:
190
191 @smallexample
192 TEMP_FAILURE_RETRY (close (desc));
193 @end smallexample
194
195 @item ENOSPC
196 @itemx EIO
197 @itemx EDQUOT
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
200 on their meaning.
201 @end table
202 @end deftypefun
203
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.
208
209 @node I/O Primitives
210 @section Input and Output Primitives
211
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
215 @file{unistd.h}.
216 @pindex unistd.h
217
218 @comment unistd.h
219 @comment POSIX.1
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.
224 @end deftp
225
226 @cindex reading from a file descriptor
227 @comment unistd.h
228 @comment POSIX.1
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.)
234
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.
241
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.
246
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.
250
251 In case of an error, @code{read} returns @code{-1}.  The following
252 @code{errno} error conditions are defined for this function:
253
254 @table @code
255 @item EAGAIN
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.
260
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
264 which name you use.
265
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
272 GNU system.
273
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}.
277
278 @item EBADF
279 The @var{filedes} argument is not a valid file descriptor,
280 or is not open for reading.
281
282 @item EINTR
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.
287
288 @item EIO
289 For many devices, and for disk files, this error code indicates
290 a hardware error.
291
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.
298 @end table
299
300 The @code{read} function is the underlying primitive for all of the
301 functions that read from streams, such as @code{fgetc}.
302 @end deftypefun
303
304 @cindex writing to a file descriptor
305 @comment unistd.h
306 @comment POSIX.1
307 @deftypefun ssize_t write (int @var{filedes}, const void *@var{buffer}, size_t @var{size})
308 The @code{write} function writes up to @var{size} bytes from
309 @var{buffer} to the file with descriptor @var{filedes}.  The data in
310 @var{buffer} is not necessarily a character string and a null character is
311 output like any other character.
312
313 The return value is the number of bytes actually written.  This may be
314 @var{size}, but can always be smaller.  Your program should always call
315 @code{write} in a loop, iterating until all the data is written.
316
317 Once @code{write} returns, the data is enqueued to be written and can be
318 read back right away, but it is not necessarily written out to permanent
319 storage immediately.  You can use @code{fsync} when you need to be sure
320 your data has been permanently stored before continuing.  (It is more
321 efficient for the system to batch up consecutive writes and do them all
322 at once when convenient.  Normally they will always be written to disk
323 within a minute or less.)
324 @c !!! xref fsync
325 You can use the @code{O_FSYNC} open mode to make @code{write} always
326 store the data to disk before returning; @pxref{Operating Modes}.
327
328 In the case of an error, @code{write} returns @code{-1}.  The following
329 @code{errno} error conditions are defined for this function:
330
331 @table @code
332 @item EAGAIN
333 Normally, @code{write} blocks until the write operation is complete.
334 But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control
335 Operations}), it returns immediately without writing any data, and
336 reports this error.  An example of a situation that might cause the
337 process to block on output is writing to a terminal device that supports
338 flow control, where output has been suspended by receipt of a STOP
339 character.
340
341 @strong{Compatibility Note:} Most versions of BSD Unix use a different
342 error code for this: @code{EWOULDBLOCK}.  In the GNU library,
343 @code{EWOULDBLOCK} is an alias for @code{EAGAIN}, so it doesn't matter
344 which name you use.
345
346 On some systems, writing a large amount of data from a character special
347 file can also fail with @code{EAGAIN} if the kernel cannot find enough
348 physical memory to lock down the user's pages.  This is limited to
349 devices that transfer with direct memory access into the user's memory,
350 which means it does not include terminals, since they always use
351 separate buffers inside the kernel.  This problem does not arise in the
352 GNU system.
353
354 @item EBADF
355 The @var{filedes} argument is not a valid file descriptor,
356 or is not open for writing.
357
358 @item EFBIG
359 The size of the file would become larger than the implementation can support.
360
361 @item EINTR
362 The @code{write} operation was interrupted by a signal while it was
363 blocked waiting for completion.  A signal will not necessary cause
364 @code{write} to return @code{EINTR}; it may instead result in a
365 successful @code{write} which writes fewer bytes than requested.
366 @xref{Interrupted Primitives}.
367
368 @item EIO
369 For many devices, and for disk files, this error code indicates
370 a hardware error.
371
372 @item ENOSPC
373 The device containing the file is full.
374
375 @item EPIPE
376 This error is returned when you try to write to a pipe or FIFO that
377 isn't open for reading by any process.  When this happens, a @code{SIGPIPE}
378 signal is also sent to the process; see @ref{Signal Handling}.
379 @end table
380
381 Unless you have arranged to prevent @code{EINTR} failures, you should
382 check @code{errno} after each failing call to @code{write}, and if the
383 error was @code{EINTR}, you should simply repeat the call.
384 @xref{Interrupted Primitives}.  The easy way to do this is with the
385 macro @code{TEMP_FAILURE_RETRY}, as follows:
386
387 @smallexample
388 nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
389 @end smallexample
390
391 The @code{write} function is the underlying primitive for all of the
392 functions that write to streams, such as @code{fputc}.
393 @end deftypefun
394
395 @node File Position Primitive
396 @section Setting the File Position of a Descriptor
397
398 Just as you can set the file position of a stream with @code{fseek}, you
399 can set the file position of a descriptor with @code{lseek}.  This
400 specifies the position in the file for the next @code{read} or
401 @code{write} operation.  @xref{File Positioning}, for more information
402 on the file position and what it means.
403
404 To read the current file position value from a descriptor, use
405 @code{lseek (@var{desc}, 0, SEEK_CUR)}.
406
407 @cindex file positioning on a file descriptor
408 @cindex positioning a file descriptor
409 @cindex seeking on a file descriptor
410 @comment unistd.h
411 @comment POSIX.1
412 @deftypefun off_t lseek (int @var{filedes}, off_t @var{offset}, int @var{whence})
413 The @code{lseek} function is used to change the file position of the
414 file with descriptor @var{filedes}.
415
416 The @var{whence} argument specifies how the @var{offset} should be
417 interpreted in the same way as for the @code{fseek} function, and must be
418 one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or
419 @code{SEEK_END}.
420
421 @table @code
422 @item SEEK_SET
423 Specifies that @var{whence} is a count of characters from the beginning
424 of the file.
425
426 @item SEEK_CUR
427 Specifies that @var{whence} is a count of characters from the current
428 file position.  This count may be positive or negative.
429
430 @item SEEK_END
431 Specifies that @var{whence} is a count of characters from the end of
432 the file.  A negative count specifies a position within the current
433 extent of the file; a positive count specifies a position past the
434 current end.  If you set the position past the current end, and
435 actually write data, you will extend the file with zeros up to that
436 position.@end table
437
438 The return value from @code{lseek} is normally the resulting file
439 position, measured in bytes from the beginning of the file.
440 You can use this feature together with @code{SEEK_CUR} to read the
441 current file position.
442
443 If you want to append to the file, setting the file position to the
444 current end of file with @code{SEEK_END} is not sufficient.  Another
445 process may write more data after you seek but before you write,
446 extending the file so the position you write onto clobbers their data.
447 Instead, use the @code{O_APPEND} operating mode; @pxref{Operating Modes}.
448
449 You can set the file position past the current end of the file.  This
450 does not by itself make the file longer; @code{lseek} never changes the
451 file.  But subsequent output at that position will extend the file.
452 Characters between the previous end of file and the new position are
453 filled with zeros.  Extending the file in this way can create a
454 ``hole'': the blocks of zeros are not actually allocated on disk, so the
455 file takes up less space than it appears so; it is then called a
456 ``sparse file''.
457 @cindex sparse files
458 @cindex holes in files
459
460 If the file position cannot be changed, or the operation is in some way
461 invalid, @code{lseek} returns a value of @code{-1}.  The following
462 @code{errno} error conditions are defined for this function:
463
464 @table @code
465 @item EBADF
466 The @var{filedes} is not a valid file descriptor.
467
468 @item EINVAL
469 The @var{whence} argument value is not valid, or the resulting
470 file offset is not valid.  A file offset is invalid.
471
472 @item ESPIPE
473 The @var{filedes} corresponds to an object that cannot be positioned,
474 such as a pipe, FIFO or terminal device.  (POSIX.1 specifies this error
475 only for pipes and FIFOs, but in the GNU system, you always get
476 @code{ESPIPE} if the object is not seekable.)
477 @end table
478
479 The @code{lseek} function is the underlying primitive for the
480 @code{fseek}, @code{ftell} and @code{rewind} functions, which operate on
481 streams instead of file descriptors.
482 @end deftypefun
483
484 You can have multiple descriptors for the same file if you open the file
485 more than once, or if you duplicate a descriptor with @code{dup}.
486 Descriptors that come from separate calls to @code{open} have independent
487 file positions; using @code{lseek} on one descriptor has no effect on the
488 other.  For example,
489
490 @smallexample
491 @group
492 @{
493   int d1, d2;
494   char buf[4];
495   d1 = open ("foo", O_RDONLY);
496   d2 = open ("foo", O_RDONLY);
497   lseek (d1, 1024, SEEK_SET);
498   read (d2, buf, 4);
499 @}
500 @end group
501 @end smallexample
502
503 @noindent
504 will read the first four characters of the file @file{foo}.  (The
505 error-checking code necessary for a real program has been omitted here
506 for brevity.)
507
508 By contrast, descriptors made by duplication share a common file
509 position with the original descriptor that was duplicated.  Anything
510 which alters the file position of one of the duplicates, including
511 reading or writing data, affects all of them alike.  Thus, for example,
512
513 @smallexample
514 @{
515   int d1, d2, d3;
516   char buf1[4], buf2[4];
517   d1 = open ("foo", O_RDONLY);
518   d2 = dup (d1);
519   d3 = dup (d2);
520   lseek (d3, 1024, SEEK_SET);
521   read (d1, buf1, 4);
522   read (d2, buf2, 4);
523 @}
524 @end smallexample
525
526 @noindent
527 will read four characters starting with the 1024'th character of
528 @file{foo}, and then four more characters starting with the 1028'th
529 character.
530
531 @comment sys/types.h
532 @comment POSIX.1
533 @deftp {Data Type} off_t
534 This is an arithmetic data type used to represent file sizes.
535 In the GNU system, this is equivalent to @code{fpos_t} or @code{long int}.
536 @end deftp
537
538 These aliases for the @samp{SEEK_@dots{}} constants exist for the sake
539 of compatibility with older BSD systems.  They are defined in two
540 different header files: @file{fcntl.h} and @file{sys/file.h}.
541
542 @table @code
543 @item L_SET
544 An alias for @code{SEEK_SET}.
545
546 @item L_INCR
547 An alias for @code{SEEK_CUR}.
548
549 @item L_XTND
550 An alias for @code{SEEK_END}.
551 @end table
552
553 @node Descriptors and Streams
554 @section Descriptors and Streams
555 @cindex streams, and file descriptors
556 @cindex converting file descriptor to stream
557 @cindex extracting file descriptor from stream
558
559 Given an open file descriptor, you can create a stream for it with the
560 @code{fdopen} function.  You can get the underlying file descriptor for
561 an existing stream with the @code{fileno} function.  These functions are
562 declared in the header file @file{stdio.h}.
563 @pindex stdio.h
564
565 @comment stdio.h
566 @comment POSIX.1
567 @deftypefun {FILE *} fdopen (int @var{filedes}, const char *@var{opentype})
568 The @code{fdopen} function returns a new stream for the file descriptor
569 @var{filedes}.
570
571 The @var{opentype} argument is interpreted in the same way as for the
572 @code{fopen} function (@pxref{Opening Streams}), except that
573 the @samp{b} option is not permitted; this is because GNU makes no
574 distinction between text and binary files.  Also, @code{"w"} and
575 @code{"w+"} do not cause truncation of the file; these have affect only
576 when opening a file, and in this case the file has already been opened.
577 You must make sure that the @var{opentype} argument matches the actual
578 mode of the open file descriptor.
579
580 The return value is the new stream.  If the stream cannot be created
581 (for example, if the modes for the file indicated by the file descriptor
582 do not permit the access specified by the @var{opentype} argument), a
583 null pointer is returned instead.
584
585 In some other systems, @code{fdopen} may fail to detect that the modes
586 for file descriptor do not permit the access specified by
587 @code{opentype}.  The GNU C library always checks for this.
588 @end deftypefun
589
590 For an example showing the use of the @code{fdopen} function,
591 see @ref{Creating a Pipe}.
592
593 @comment stdio.h
594 @comment POSIX.1
595 @deftypefun int fileno (FILE *@var{stream})
596 This function returns the file descriptor associated with the stream
597 @var{stream}.  If an error is detected (for example, if the @var{stream}
598 is not valid) or if @var{stream} does not do I/O to a file,
599 @code{fileno} returns @code{-1}.
600 @end deftypefun
601
602 @cindex standard file descriptors
603 @cindex file descriptors, standard
604 There are also symbolic constants defined in @file{unistd.h} for the
605 file descriptors belonging to the standard streams @code{stdin},
606 @code{stdout}, and @code{stderr}; see @ref{Standard Streams}.
607 @pindex unistd.h
608
609 @comment unistd.h
610 @comment POSIX.1
611 @table @code
612 @item STDIN_FILENO
613 @vindex STDIN_FILENO
614 This macro has value @code{0}, which is the file descriptor for
615 standard input.
616 @cindex standard input file descriptor
617
618 @comment unistd.h
619 @comment POSIX.1
620 @item STDOUT_FILENO
621 @vindex STDOUT_FILENO
622 This macro has value @code{1}, which is the file descriptor for
623 standard output.
624 @cindex standard output file descriptor
625
626 @comment unistd.h
627 @comment POSIX.1
628 @item STDERR_FILENO
629 @vindex STDERR_FILENO
630 This macro has value @code{2}, which is the file descriptor for
631 standard error output.
632 @end table
633 @cindex standard error file descriptor
634
635 @node Stream/Descriptor Precautions
636 @section Dangers of Mixing Streams and Descriptors
637 @cindex channels
638 @cindex streams and descriptors
639 @cindex descriptors and streams
640 @cindex mixing descriptors and streams
641
642 You can have multiple file descriptors and streams (let's call both
643 streams and descriptors ``channels'' for short) connected to the same
644 file, but you must take care to avoid confusion between channels.  There
645 are two cases to consider: @dfn{linked} channels that share a single
646 file position value, and @dfn{independent} channels that have their own
647 file positions.
648
649 It's best to use just one channel in your program for actual data
650 transfer to any given file, except when all the access is for input.
651 For example, if you open a pipe (something you can only do at the file
652 descriptor level), either do all I/O with the descriptor, or construct a
653 stream from the descriptor with @code{fdopen} and then do all I/O with
654 the stream.
655
656 @menu
657 * Linked Channels::        Dealing with channels sharing a file position.
658 * Independent Channels::   Dealing with separately opened, unlinked channels.
659 * Cleaning Streams::       Cleaning a stream makes it safe to use
660                             another channel.
661 @end menu
662
663 @node Linked Channels
664 @subsection Linked Channels
665 @cindex linked channels
666
667 Channels that come from a single opening share the same file position;
668 we call them @dfn{linked} channels.  Linked channels result when you
669 make a stream from a descriptor using @code{fdopen}, when you get a
670 descriptor from a stream with @code{fileno}, when you copy a descriptor
671 with @code{dup} or @code{dup2}, and when descriptors are inherited
672 during @code{fork}.  For files that don't support random access, such as
673 terminals and pipes, @emph{all} channels are effectively linked.  On
674 random-access files, all append-type output streams are effectively
675 linked to each other.
676
677 @cindex cleaning up a stream
678 If you have been using a stream for I/O, and you want to do I/O using
679 another channel (either a stream or a descriptor) that is linked to it,
680 you must first @dfn{clean up} the stream that you have been using.
681 @xref{Cleaning Streams}.
682
683 Terminating a process, or executing a new program in the process,
684 destroys all the streams in the process.  If descriptors linked to these
685 streams persist in other processes, their file positions become
686 undefined as a result.  To prevent this, you must clean up the streams
687 before destroying them.
688
689 @node Independent Channels
690 @subsection Independent Channels
691 @cindex independent channels
692
693 When you open channels (streams or descriptors) separately on a seekable
694 file, each channel has its own file position.  These are called
695 @dfn{independent channels}.
696
697 The system handles each channel independently.  Most of the time, this
698 is quite predictable and natural (especially for input): each channel
699 can read or write sequentially at its own place in the file.  However,
700 if some of the channels are streams, you must take these precautions:
701
702 @itemize @bullet
703 @item
704 You should clean an output stream after use, before doing anything else
705 that might read or write from the same part of the file.
706
707 @item
708 You should clean an input stream before reading data that may have been
709 modified using an independent channel.  Otherwise, you might read
710 obsolete data that had been in the stream's buffer.
711 @end itemize
712
713 If you do output to one channel at the end of the file, this will
714 certainly leave the other independent channels positioned somewhere
715 before the new end.  You cannot reliably set their file positions to the
716 new end of file before writing, because the file can always be extended
717 by another process between when you set the file position and when you
718 write the data.  Instead, use an append-type descriptor or stream; they
719 always output at the current end of the file.  In order to make the
720 end-of-file position accurate, you must clean the output channel you
721 were using, if it is a stream.
722
723 It's impossible for two channels to have separate file pointers for a
724 file that doesn't support random access.  Thus, channels for reading or
725 writing such files are always linked, never independent.  Append-type
726 channels are also always linked.  For these channels, follow the rules
727 for linked channels; see @ref{Linked Channels}.
728
729 @node Cleaning Streams
730 @subsection Cleaning Streams
731
732 On the GNU system, you can clean up any stream with @code{fclean}:
733
734 @comment stdio.h
735 @comment GNU
736 @deftypefun int fclean (FILE *@var{stream})
737 Clean up the stream @var{stream} so that its buffer is empty.  If
738 @var{stream} is doing output, force it out.  If @var{stream} is doing
739 input, give the data in the buffer back to the system, arranging to
740 reread it.
741 @end deftypefun
742
743 On other systems, you can use @code{fflush} to clean a stream in most
744 cases.
745
746 You can skip the @code{fclean} or @code{fflush} if you know the stream
747 is already clean.  A stream is clean whenever its buffer is empty.  For
748 example, an unbuffered stream is always clean.  An input stream that is
749 at end-of-file is clean.  A line-buffered stream is clean when the last
750 character output was a newline.
751
752 There is one case in which cleaning a stream is impossible on most
753 systems.  This is when the stream is doing input from a file that is not
754 random-access.  Such streams typically read ahead, and when the file is
755 not random access, there is no way to give back the excess data already
756 read.  When an input stream reads from a random-access file,
757 @code{fflush} does clean the stream, but leaves the file pointer at an
758 unpredictable place; you must set the file pointer before doing any
759 further I/O.  On the GNU system, using @code{fclean} avoids both of
760 these problems.
761
762 Closing an output-only stream also does @code{fflush}, so this is a
763 valid way of cleaning an output stream.  On the GNU system, closing an
764 input stream does @code{fclean}.
765
766 You need not clean a stream before using its descriptor for control
767 operations such as setting terminal modes; these operations don't affect
768 the file position and are not affected by it.  You can use any
769 descriptor for these operations, and all channels are affected
770 simultaneously.  However, text already ``output'' to a stream but still
771 buffered by the stream will be subject to the new terminal modes when
772 subsequently flushed.  To make sure ``past'' output is covered by the
773 terminal settings that were in effect at the time, flush the output
774 streams for that terminal before setting the modes.  @xref{Terminal
775 Modes}.
776
777 @node Waiting for I/O
778 @section Waiting for Input or Output
779 @cindex waiting for input or output
780 @cindex multiplexing input
781 @cindex input from multiple files
782
783 Sometimes a program needs to accept input on multiple input channels
784 whenever input arrives.  For example, some workstations may have devices
785 such as a digitizing tablet, function button box, or dial box that are
786 connected via normal asynchronous serial interfaces; good user interface
787 style requires responding immediately to input on any device.  Another
788 example is a program that acts as a server to several other processes
789 via pipes or sockets.
790
791 You cannot normally use @code{read} for this purpose, because this
792 blocks the program until input is available on one particular file
793 descriptor; input on other channels won't wake it up.  You could set
794 nonblocking mode and poll each file descriptor in turn, but this is very
795 inefficient.
796
797 A better solution is to use the @code{select} function.  This blocks the
798 program until input or output is ready on a specified set of file
799 descriptors, or until a timer expires, whichever comes first.  This
800 facility is declared in the header file @file{sys/types.h}.
801 @pindex sys/types.h
802
803 In the case of a server socket (@pxref{Listening}), we say that
804 ``input'' is available when there are pending connections that could be
805 accepted (@pxref{Accepting Connections}).  @code{accept} for server
806 sockets blocks and interacts with @code{select} just as @code{read} does
807 for normal input.
808
809 @cindex file descriptor sets, for @code{select}
810 The file descriptor sets for the @code{select} function are specified
811 as @code{fd_set} objects.  Here is the description of the data type
812 and some macros for manipulating these objects.
813
814 @comment sys/types.h
815 @comment BSD
816 @deftp {Data Type} fd_set
817 The @code{fd_set} data type represents file descriptor sets for the
818 @code{select} function.  It is actually a bit array.
819 @end deftp
820
821 @comment sys/types.h
822 @comment BSD
823 @deftypevr Macro int FD_SETSIZE
824 The value of this macro is the maximum number of file descriptors that a
825 @code{fd_set} object can hold information about.  On systems with a
826 fixed maximum number, @code{FD_SETSIZE} is at least that number.  On
827 some systems, including GNU, there is no absolute limit on the number of
828 descriptors open, but this macro still has a constant value which
829 controls the number of bits in an @code{fd_set}; if you get a file
830 descriptor with a value as high as @code{FD_SETSIZE}, you cannot put
831 that descriptor into an @code{fd_set}.
832 @end deftypevr
833
834 @comment sys/types.h
835 @comment BSD
836 @deftypefn Macro void FD_ZERO (fd_set *@var{set})
837 This macro initializes the file descriptor set @var{set} to be the
838 empty set.
839 @end deftypefn
840
841 @comment sys/types.h
842 @comment BSD
843 @deftypefn Macro void FD_SET (int @var{filedes}, fd_set *@var{set})
844 This macro adds @var{filedes} to the file descriptor set @var{set}.
845 @end deftypefn
846
847 @comment sys/types.h
848 @comment BSD
849 @deftypefn Macro void FD_CLR (int @var{filedes}, fd_set *@var{set})
850 This macro removes @var{filedes} from the file descriptor set @var{set}.
851 @end deftypefn
852
853 @comment sys/types.h
854 @comment BSD
855 @deftypefn Macro int FD_ISSET (int @var{filedes}, fd_set *@var{set})
856 This macro returns a nonzero value (true) if @var{filedes} is a member
857 of the the file descriptor set @var{set}, and zero (false) otherwise.
858 @end deftypefn
859
860 Next, here is the description of the @code{select} function itself.
861
862 @comment sys/types.h
863 @comment BSD
864 @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})
865 The @code{select} function blocks the calling process until there is
866 activity on any of the specified sets of file descriptors, or until the
867 timeout period has expired.
868
869 The file descriptors specified by the @var{read-fds} argument are
870 checked to see if they are ready for reading; the @var{write-fds} file
871 descriptors are checked to see if they are ready for writing; and the
872 @var{except-fds} file descriptors are checked for exceptional
873 conditions.  You can pass a null pointer for any of these arguments if
874 you are not interested in checking for that kind of condition.
875
876 A file descriptor is considered ready for reading if it is at end of
877 file.  A server socket is considered ready for reading if there is a
878 pending connection which can be accepted with @code{accept};
879 @pxref{Accepting Connections}.  A client socket is ready for writing when
880 its connection is fully established; @pxref{Connecting}.
881
882 ``Exceptional conditions'' does not mean errors---errors are reported
883 immediately when an erroneous system call is executed, and do not
884 constitute a state of the descriptor.  Rather, they include conditions
885 such as the presence of an urgent message on a socket.  (@xref{Sockets},
886 for information on urgent messages.)
887
888 The @code{select} function checks only the first @var{nfds} file
889 descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
890 of this argument.
891
892 The @var{timeout} specifies the maximum time to wait.  If you pass a
893 null pointer for this argument, it means to block indefinitely until one
894 of the file descriptors is ready.  Otherwise, you should provide the
895 time in @code{struct timeval} format; see @ref{High-Resolution
896 Calendar}.  Specify zero as the time (a @code{struct timeval} containing
897 all zeros) if you want to find out which descriptors are ready without
898 waiting if none are ready.
899
900 The normal return value from @code{select} is the total number of ready file
901 descriptors in all of the sets.  Each of the argument sets is overwritten
902 with information about the descriptors that are ready for the corresponding
903 operation.  Thus, to see if a particular descriptor @var{desc} has input,
904 use @code{FD_ISSET (@var{desc}, @var{read-fds})} after @code{select} returns.
905
906 If @code{select} returns because the timeout period expires, it returns
907 a value of zero.
908
909 Any signal will cause @code{select} to return immediately.  So if your
910 program uses signals, you can't rely on @code{select} to keep waiting
911 for the full time specified.  If you want to be sure of waiting for a
912 particular amount of time, you must check for @code{EINTR} and repeat
913 the @code{select} with a newly calculated timeout based on the current
914 time.  See the example below.  See also @ref{Interrupted Primitives}.
915
916 If an error occurs, @code{select} returns @code{-1} and does not modify
917 the argument file descriptor sets.  The following @code{errno} error
918 conditions are defined for this function:
919
920 @table @code
921 @item EBADF
922 One of the file descriptor sets specified an invalid file descriptor.
923
924 @item EINTR
925 The operation was interrupted by a signal.  @xref{Interrupted Primitives}.
926
927 @item EINVAL
928 The @var{timeout} argument is invalid; one of the components is negative
929 or too large.
930 @end table
931 @end deftypefun
932
933 @strong{Portability Note:}  The @code{select} function is a BSD Unix
934 feature.
935
936 Here is an example showing how you can use @code{select} to establish a
937 timeout period for reading from a file descriptor.  The @code{input_timeout}
938 function blocks the calling process until input is available on the
939 file descriptor, or until the timeout period expires.
940
941 @smallexample
942 @include select.c.texi
943 @end smallexample
944
945 There is another example showing the use of @code{select} to multiplex
946 input from multiple sockets in @ref{Server Example}.
947
948
949 @node Control Operations
950 @section Control Operations on Files
951
952 @cindex control operations on files
953 @cindex @code{fcntl} function
954 This section describes how you can perform various other operations on
955 file descriptors, such as inquiring about or setting flags describing
956 the status of the file descriptor, manipulating record locks, and the
957 like.  All of these operations are performed by the function @code{fcntl}.
958
959 The second argument to the @code{fcntl} function is a command that
960 specifies which operation to perform.  The function and macros that name
961 various flags that are used with it are declared in the header file
962 @file{fcntl.h}.  Many of these flags are also used by the @code{open}
963 function; see @ref{Opening and Closing Files}.
964 @pindex fcntl.h
965
966 @comment fcntl.h
967 @comment POSIX.1
968 @deftypefun int fcntl (int @var{filedes}, int @var{command}, @dots{})
969 The @code{fcntl} function performs the operation specified by
970 @var{command} on the file descriptor @var{filedes}.  Some commands
971 require additional arguments to be supplied.  These additional arguments
972 and the return value and error conditions are given in the detailed
973 descriptions of the individual commands.
974
975 Briefly, here is a list of what the various commands are.
976
977 @table @code
978 @item F_DUPFD
979 Duplicate the file descriptor (return another file descriptor pointing
980 to the same open file).  @xref{Duplicating Descriptors}.
981
982 @item F_GETFD
983 Get flags associated with the file descriptor.  @xref{Descriptor Flags}.
984
985 @item F_SETFD
986 Set flags associated with the file descriptor.  @xref{Descriptor Flags}.
987
988 @item F_GETFL
989 Get flags associated with the open file.  @xref{File Status Flags}.
990
991 @item F_SETFL
992 Set flags associated with the open file.  @xref{File Status Flags}.
993
994 @item F_GETLK
995 Get a file lock.  @xref{File Locks}.
996
997 @item F_SETLK
998 Set or clear a file lock.  @xref{File Locks}.
999
1000 @item F_SETLKW
1001 Like @code{F_SETLK}, but wait for completion.  @xref{File Locks}.
1002
1003 @item F_GETOWN
1004 Get process or process group ID to receive @code{SIGIO} signals.
1005 @xref{Interrupt Input}.
1006
1007 @item F_SETOWN
1008 Set process or process group ID to receive @code{SIGIO} signals.
1009 @xref{Interrupt Input}.
1010 @end table
1011 @end deftypefun
1012
1013
1014 @node Duplicating Descriptors
1015 @section Duplicating Descriptors
1016
1017 @cindex duplicating file descriptors
1018 @cindex redirecting input and output
1019
1020 You can @dfn{duplicate} a file descriptor, or allocate another file
1021 descriptor that refers to the same open file as the original.  Duplicate
1022 descriptors share one file position and one set of file status flags
1023 (@pxref{File Status Flags}), but each has its own set of file descriptor
1024 flags (@pxref{Descriptor Flags}).
1025
1026 The major use of duplicating a file descriptor is to implement
1027 @dfn{redirection} of input or output:  that is, to change the
1028 file or pipe that a particular file descriptor corresponds to.
1029
1030 You can perform this operation using the @code{fcntl} function with the
1031 @code{F_DUPFD} command, but there are also convenient functions
1032 @code{dup} and @code{dup2} for duplicating descriptors.
1033
1034 @pindex unistd.h
1035 @pindex fcntl.h
1036 The @code{fcntl} function and flags are declared in @file{fcntl.h},
1037 while prototypes for @code{dup} and @code{dup2} are in the header file
1038 @file{unistd.h}.
1039
1040 @comment unistd.h
1041 @comment POSIX.1
1042 @deftypefun int dup (int @var{old})
1043 This function copies descriptor @var{old} to the first available
1044 descriptor number (the first number not currently open).  It is
1045 equivalent to @code{fcntl (@var{old}, F_DUPFD, 0)}.
1046 @end deftypefun
1047
1048 @comment unistd.h
1049 @comment POSIX.1
1050 @deftypefun int dup2 (int @var{old}, int @var{new})
1051 This function copies the descriptor @var{old} to descriptor number
1052 @var{new}.
1053
1054 If @var{old} is an invalid descriptor, then @code{dup2} does nothing; it
1055 does not close @var{new}.  Otherwise, the new duplicate of @var{old}
1056 replaces any previous meaning of descriptor @var{new}, as if @var{new}
1057 were closed first.
1058
1059 If @var{old} and @var{new} are different numbers, and @var{old} is a
1060 valid descriptor number, then @code{dup2} is equivalent to:
1061
1062 @smallexample
1063 close (@var{new});
1064 fcntl (@var{old}, F_DUPFD, @var{new})
1065 @end smallexample
1066
1067 However, @code{dup2} does this atomically; there is no instant in the
1068 middle of calling @code{dup2} at which @var{new} is closed and not yet a
1069 duplicate of @var{old}.
1070 @end deftypefun
1071
1072 @comment fcntl.h
1073 @comment POSIX.1
1074 @deftypevr Macro int F_DUPFD
1075 This macro is used as the @var{command} argument to @code{fcntl}, to
1076 copy the file descriptor given as the first argument.
1077
1078 The form of the call in this case is:
1079
1080 @smallexample
1081 fcntl (@var{old}, F_DUPFD, @var{next-filedes})
1082 @end smallexample
1083
1084 The @var{next-filedes} argument is of type @code{int} and specifies that
1085 the file descriptor returned should be the next available one greater
1086 than or equal to this value.
1087
1088 The return value from @code{fcntl} with this command is normally the value
1089 of the new file descriptor.  A return value of @code{-1} indicates an
1090 error.  The following @code{errno} error conditions are defined for
1091 this command:
1092
1093 @table @code
1094 @item EBADF
1095 The @var{old} argument is invalid.
1096
1097 @item EINVAL
1098 The @var{next-filedes} argument is invalid.
1099
1100 @item EMFILE
1101 There are no more file descriptors available---your program is already
1102 using the maximum.  In BSD and GNU, the maximum is controlled by a
1103 resource limit that can be changed; @pxref{Limits on Resources}, for
1104 more information about the @code{RLIMIT_NOFILE} limit.
1105 @end table
1106
1107 @code{ENFILE} is not a possible error code for @code{dup2} because
1108 @code{dup2} does not create a new opening of a file; duplicate
1109 descriptors do not count toward the limit which @code{ENFILE}
1110 indicates.  @code{EMFILE} is possible because it refers to the limit on
1111 distinct descriptor numbers in use in one process.
1112 @end deftypevr
1113
1114 Here is an example showing how to use @code{dup2} to do redirection.
1115 Typically, redirection of the standard streams (like @code{stdin}) is
1116 done by a shell or shell-like program before calling one of the
1117 @code{exec} functions (@pxref{Executing a File}) to execute a new
1118 program in a child process.  When the new program is executed, it
1119 creates and initializes the standard streams to point to the
1120 corresponding file descriptors, before its @code{main} function is
1121 invoked.
1122
1123 So, to redirect standard input to a file, the shell could do something
1124 like:
1125
1126 @smallexample
1127 pid = fork ();
1128 if (pid == 0)
1129   @{
1130     char *filename;
1131     char *program;
1132     int file;
1133     @dots{}
1134     file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
1135     dup2 (file, STDIN_FILENO);
1136     TEMP_FAILURE_RETRY (close (file));
1137     execv (program, NULL);
1138   @}
1139 @end smallexample
1140
1141 There is also a more detailed example showing how to implement redirection
1142 in the context of a pipeline of processes in @ref{Launching Jobs}.
1143
1144
1145 @node Descriptor Flags
1146 @section File Descriptor Flags
1147 @cindex file descriptor flags
1148
1149 @dfn{File descriptor flags} are miscellaneous attributes of a file
1150 descriptor.  These flags are associated with particular file
1151 descriptors, so that if you have created duplicate file descriptors
1152 from a single opening of a file, each descriptor has its own set of flags.
1153
1154 Currently there is just one file descriptor flag: @code{FD_CLOEXEC},
1155 which causes the descriptor to be closed if you use any of the
1156 @code{exec@dots{}} functions (@pxref{Executing a File}).
1157
1158 The symbols in this section are defined in the header file
1159 @file{fcntl.h}.
1160 @pindex fcntl.h
1161
1162 @comment fcntl.h
1163 @comment POSIX.1
1164 @deftypevr Macro int F_GETFD
1165 This macro is used as the @var{command} argument to @code{fcntl}, to
1166 specify that it should return the file descriptor flags associated
1167 with the @var{filedes} argument.
1168
1169 The normal return value from @code{fcntl} with this command is a
1170 nonnegative number which can be interpreted as the bitwise OR of the
1171 individual flags (except that currently there is only one flag to use).
1172
1173 In case of an error, @code{fcntl} returns @code{-1}.  The following
1174 @code{errno} error conditions are defined for this command:
1175
1176 @table @code
1177 @item EBADF
1178 The @var{filedes} argument is invalid.
1179 @end table
1180 @end deftypevr
1181
1182
1183 @comment fcntl.h
1184 @comment POSIX.1
1185 @deftypevr Macro int F_SETFD
1186 This macro is used as the @var{command} argument to @code{fcntl}, to
1187 specify that it should set the file descriptor flags associated with the
1188 @var{filedes} argument.  This requires a third @code{int} argument to
1189 specify the new flags, so the form of the call is:
1190
1191 @smallexample
1192 fcntl (@var{filedes}, F_SETFD, @var{new-flags})
1193 @end smallexample
1194
1195 The normal return value from @code{fcntl} with this command is an
1196 unspecified value other than @code{-1}, which indicates an error.
1197 The flags and error conditions are the same as for the @code{F_GETFD}
1198 command.
1199 @end deftypevr
1200
1201 The following macro is defined for use as a file descriptor flag with
1202 the @code{fcntl} function.  The value is an integer constant usable
1203 as a bit mask value.
1204
1205 @comment fcntl.h
1206 @comment POSIX.1
1207 @deftypevr Macro int FD_CLOEXEC
1208 @cindex close-on-exec (file descriptor flag)
1209 This flag specifies that the file descriptor should be closed when
1210 an @code{exec} function is invoked; see @ref{Executing a File}.  When
1211 a file descriptor is allocated (as with @code{open} or @code{dup}),
1212 this bit is initially cleared on the new file descriptor, meaning that
1213 descriptor will survive into the new program after @code{exec}.
1214 @end deftypevr
1215
1216 If you want to modify the file descriptor flags, you should get the
1217 current flags with @code{F_GETFD} and modify the value.  Don't assume
1218 that the flags listed here are the only ones that are implemented; your
1219 program may be run years from now and more flags may exist then.  For
1220 example, here is a function to set or clear the flag @code{FD_CLOEXEC}
1221 without altering any other flags:
1222
1223 @smallexample
1224 /* @r{Set the @code{FD_CLOEXEC} flag of @var{desc} if @var{value} is nonzero,}
1225    @r{or clear the flag if @var{value} is 0.}
1226    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
1227
1228 int
1229 set_cloexec_flag (int desc, int value)
1230 @{
1231   int oldflags = fcntl (desc, F_GETFD, 0);
1232   /* @r{If reading the flags failed, return error indication now.}
1233   if (oldflags < 0)
1234     return oldflags;
1235   /* @r{Set just the flag we want to set.} */
1236   if (value != 0)
1237     oldflags |= FD_CLOEXEC;
1238   else
1239     oldflags &= ~FD_CLOEXEC;
1240   /* @r{Store modified flag word in the descriptor.} */
1241   return fcntl (desc, F_SETFD, oldflags);
1242 @}
1243 @end smallexample
1244
1245 @node File Status Flags
1246 @section File Status Flags
1247 @cindex file status flags
1248
1249 @dfn{File status flags} are used to specify attributes of the opening of a
1250 file.  Unlike the file descriptor flags discussed in @ref{Descriptor
1251 Flags}, the file status flags are shared by duplicated file descriptors
1252 resulting from a single opening of the file.  The file status flags are
1253 specified with the @var{flags} argument to @code{open};
1254 @pxref{Opening and Closing Files}.
1255
1256 File status flags fall into three categories, which are described in the
1257 following sections.
1258
1259 @itemize @bullet
1260 @item
1261 @ref{Access Modes}, specify what type of access is allowed to the
1262 file: reading, writing, or both.  They are set by @code{open} and are
1263 returned by @code{fcntl}, but cannot be changed.
1264
1265 @item
1266 @ref{Open-time Flags}, control details of what @code{open} will do.
1267 These flags are not preserved after the @code{open} call.
1268
1269 @item
1270 @ref{Operating Modes}, affect how operations such as @code{read} and
1271 @code{write} are done.  They are set by @code{open}, and can be fetched or
1272 changed with @code{fcntl}.
1273 @end itemize
1274
1275 The symbols in this section are defined in the header file
1276 @file{fcntl.h}.
1277 @pindex fcntl.h
1278
1279 @menu
1280 * Access Modes::                Whether the descriptor can read or write.
1281 * Open-time Flags::             Details of @code{open}.
1282 * Operating Modes::             Special modes to control I/O operations.
1283 * Getting File Status Flags::   Fetching and changing these flags.
1284 @end menu
1285
1286 @node Access Modes
1287 @subsection File Access Modes
1288
1289 The file access modes allow a file descriptor to be used for reading,
1290 writing, or both.  (In the GNU system, they can also allow none of these,
1291 and allow execution of the file as a program.)  The access modes are chosen
1292 when the file is opened, and never change.
1293
1294 @comment fcntl.h
1295 @comment POSIX.1
1296 @deftypevr Macro int O_RDONLY
1297 Open the file for read access.
1298 @end deftypevr
1299
1300 @comment fcntl.h
1301 @comment POSIX.1
1302 @deftypevr Macro int O_WRONLY
1303 Open the file for write access.
1304 @end deftypevr
1305
1306 @comment fcntl.h
1307 @comment POSIX.1
1308 @deftypevr Macro int O_RDWR
1309 Open the file for both reading and writing.
1310 @end deftypevr
1311
1312 In the GNU system (and not in other systems), @code{O_RDONLY} and
1313 @code{O_WRONLY} are independent bits that can be bitwise-ORed together,
1314 and it is valid for either bit to be set or clear.  This means that
1315 @code{O_RDWR} is the same as @code{O_RDONLY|O_WRONLY}.  A file access
1316 mode of zero is permissible; it allows no operations that do input or
1317 output to the file, but does allow other operations such as
1318 @code{fchmod}.  On the GNU system, since ``read-only'' or ``write-only''
1319 is a misnomer, @file{fcntl.h} defines additional names for the file
1320 access modes.  These names are preferred when writing GNU-specific code.
1321 But most programs will want to be portable to other POSIX.1 systems and
1322 should use the POSIX.1 names above instead.
1323
1324 @comment fcntl.h
1325 @comment GNU
1326 @deftypevr Macro int O_READ
1327 Open the file for reading.  Same as @code{O_RDWR}; only defined on GNU.
1328 @end deftypevr
1329
1330 @comment fcntl.h
1331 @comment GNU
1332 @deftypevr Macro int O_WRITE
1333 Open the file for reading.  Same as @code{O_WRONLY}; only defined on GNU.
1334 @end deftypevr
1335
1336 @comment fcntl.h
1337 @comment GNU
1338 @deftypevr Macro int O_EXEC
1339 Open the file for executing.  Only defined on GNU.
1340 @end deftypevr
1341
1342 To determine the file access mode with @code{fcntl}, you must extract
1343 the access mode bits from the retrieved file status flags.  In the GNU
1344 system, you can just test the @code{O_READ} and @code{O_WRITE} bits in
1345 the flags word.  But in other POSIX.1 systems, reading and writing
1346 access modes are not stored as distinct bit flags.  The portable way to
1347 extract the file access mode bits is with @code{O_ACCMODE}.
1348
1349 @comment fcntl.h
1350 @comment POSIX.1
1351 @deftypevr Macro int O_ACCMODE
1352 This macro stands for a mask that can be bitwise-ANDed with the file
1353 status flag value to produce a value representing the file access mode.
1354 The mode will be @code{O_RDONLY}, @code{O_WRONLY}, or @code{O_RDWR}.
1355 (In the GNU system it could also be zero, and it never includes the
1356 @code{O_EXEC} bit.)
1357 @end deftypevr
1358
1359 @node Open-time Flags
1360 @subsection Open-time Flags
1361
1362 The open-time flags specify options affecting how @code{open} will behave.
1363 These options are not preserved once the file is open.  The exception to
1364 this is @code{O_NONBLOCK}, which is also an I/O operating mode and so it
1365 @emph{is} saved.  @xref{Opening and Closing Files}, for how to call
1366 @code{open}.
1367
1368 There are two sorts of options specified by open-time flags.
1369
1370 @itemize @bullet
1371 @item
1372 @dfn{File name translation flags} affect how @code{open} looks up the
1373 file name to locate the file, and whether the file can be created.
1374 @cindex file name translation flags
1375 @cindex flags, file name translation
1376
1377 @item
1378 @dfn{Open-time action flags} specify extra operations that @code{open} will
1379 perform on the file once it is open.
1380 @cindex open-time action flags
1381 @cindex flags, open-time action
1382 @end itemize
1383
1384 Here are the file name translation flags.
1385
1386 @comment fcntl.h
1387 @comment POSIX.1
1388 @deftypevr Macro int O_CREAT
1389 If set, the file will be created if it doesn't already exist.
1390 @c !!! mode arg, umask
1391 @cindex create on open (file status flag)
1392 @end deftypevr
1393
1394 @comment fcntl.h
1395 @comment POSIX.1
1396 @deftypevr Macro int O_EXCL
1397 If both @code{O_CREAT} and @code{O_EXCL} are set, then @code{open} fails
1398 if the specified file already exists.  This is guaranteed to never
1399 clobber an existing file.
1400 @end deftypevr
1401
1402 @comment fcntl.h
1403 @comment POSIX.1
1404 @deftypevr Macro int O_NONBLOCK
1405 @cindex non-blocking open
1406 This prevents @code{open} from blocking for a ``long time'' to open the
1407 file.  This is only meaningful for some kinds of files, usually devices
1408 such as serial ports; when it is not meaningful, it is harmless and
1409 ignored.  Often opening a port to a modem blocks until the modem reports
1410 carrier detection; if @code{O_NONBLOCK} is specified, @code{open} will
1411 return immediately without a carrier.
1412
1413 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O operating
1414 mode and a file name translation flag.  This means that specifying
1415 @code{O_NONBLOCK} in @code{open} also sets nonblocking I/O mode;
1416 @pxref{Operating Modes}.  To open the file without blocking but do normal
1417 I/O that blocks, you must call @code{open} with @code{O_NONBLOCK} set and
1418 then call @code{fcntl} to turn the bit off.
1419 @end deftypevr
1420
1421 @comment fcntl.h
1422 @comment POSIX.1
1423 @deftypevr Macro int O_NOCTTY
1424 If the named file is a terminal device, don't make it the controlling
1425 terminal for the process.  @xref{Job Control}, for information about
1426 what it means to be the controlling terminal.
1427
1428 In the GNU system and 4.4 BSD, opening a file never makes it the
1429 controlling terminal and @code{O_NOCTTY} is zero.  However, other
1430 systems may use a nonzero value for @code{O_NOCTTY} and set the
1431 controlling terminal when you open a file that is a terminal device; so
1432 to be portable, use @code{O_NOCTTY} when it is important to avoid this.
1433 @cindex controlling terminal, setting
1434 @end deftypevr
1435
1436 The following three file name translation flags exist only in the GNU system.
1437
1438 @comment fcntl.h
1439 @comment GNU
1440 @deftypevr Macro int O_IGNORE_CTTY
1441 Do not recognize the named file as the controlling terminal, even if it
1442 refers to the process's existing controlling terminal device.  Operations
1443 on the new file descriptor will never induce job control signals.
1444 @xref{Job Control}.
1445 @end deftypevr
1446
1447 @comment fcntl.h
1448 @comment GNU
1449 @deftypevr Macro int O_NOLINK
1450 If the named file is a symbolic link, open the link itself instead of
1451 the file it refers to.  (@code{fstat} on the new file descriptor will
1452 return the information returned by @code{lstat} on the link's name.)
1453 @cindex symbolic link, opening
1454 @end deftypevr
1455
1456 @comment fcntl.h
1457 @comment GNU
1458 @deftypevr Macro int O_NOTRANS
1459 If the named file is specially translated, do not invoke the translator.
1460 Open the bare file the translator itself sees.
1461 @end deftypevr
1462
1463
1464 The open-time action flags tell @code{open} to do additional operations
1465 which are not really related to opening the file.  The reason to do them
1466 as part of @code{open} instead of in separate calls is that @code{open}
1467 can do them @i{atomically}.
1468
1469 @comment fcntl.h
1470 @comment POSIX.1
1471 @deftypevr Macro int O_TRUNC
1472 Truncate the file to zero length.  This option is only useful for
1473 regular files, not special files such as directories or FIFOs.  POSIX.1
1474 requires that you open the file for writing to use @code{O_TRUNC}.  In
1475 BSD and GNU you must have permission to write the file to truncate it,
1476 but you need not open for write access.
1477
1478 This is the only open-time action flag specified by POSIX.1.  There is
1479 no good reason for truncation to be done by @code{open}, instead of by
1480 calling @code{ftruncate} afterwards.  The @code{O_TRUNC} flag existed in
1481 Unix before @code{ftruncate} was invented, and is retained for backward
1482 compatibility.
1483 @end deftypevr
1484
1485 @comment fcntl.h
1486 @comment BSD
1487 @deftypevr Macro int O_SHLOCK
1488 Acquire a shared lock on the file, as with @code{flock}.
1489 @xref{File Locks}.
1490
1491 If @code{O_CREAT} is specified, the locking is done atomically when
1492 creating the file.  You are guaranteed that no other process will get
1493 the lock on the new file first.
1494 @end deftypevr
1495
1496 @comment fcntl.h
1497 @comment BSD
1498 @deftypevr Macro int O_EXLOCK
1499 Acquire an exclusive lock on the file, as with @code{flock}.
1500 @xref{File Locks}.  This is atomic like @code{O_SHLOCK}.
1501 @end deftypevr
1502
1503 @node Operating Modes
1504 @subsection I/O Operating Modes
1505
1506 The operating modes affect how input and output operations using a file
1507 descriptor work.  These flags are set by @code{open} and can be fetched
1508 and changed with @code{fcntl}.
1509
1510 @comment fcntl.h
1511 @comment POSIX.1
1512 @deftypevr Macro int O_APPEND
1513 The bit that enables append mode for the file.  If set, then all
1514 @code{write} operations write the data at the end of the file, extending
1515 it, regardless of the current file position.  This is the only reliable
1516 way to append to a file.  In append mode, you are guaranteed that the
1517 data you write will always go to the current end of the file, regardless
1518 of other processes writing to the file.  Conversely, if you simply set
1519 the file position to the end of file and write, then another process can
1520 extend the file after you set the file position but before you write,
1521 resulting in your data appearing someplace before the real end of file.
1522 @end deftypevr
1523
1524 @comment fcntl.h
1525 @comment POSIX.1
1526 @deftypevr Macro int O_NONBLOCK
1527 The bit that enables nonblocking mode for the file.  If this bit is set,
1528 @code{read} requests on the file can return immediately with a failure
1529 status if there is no input immediately available, instead of blocking.
1530 Likewise, @code{write} requests can also return immediately with a
1531 failure status if the output can't be written immediately.
1532
1533 Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
1534 operating mode and a file name translation flag; @pxref{Open-time Flags}.
1535 @end deftypevr
1536
1537 @comment fcntl.h
1538 @comment BSD
1539 @deftypevr Macro int O_NDELAY
1540 This is an obsolete name for @code{O_NONBLOCK}, provided for
1541 compatibility with BSD.  It is not defined by the POSIX.1 standard.
1542 @end deftypevr
1543
1544 The remaining operating modes are BSD and GNU extensions.  They exist only
1545 on some systems.  On other systems, these macros are not defined.
1546
1547 @comment fcntl.h
1548 @comment BSD
1549 @deftypevr Macro int O_ASYNC
1550 The bit that enables asynchronous input mode.  If set, then @code{SIGIO}
1551 signals will be generated when input is available.  @xref{Interrupt Input}.
1552
1553 Asynchronous input mode is a BSD feature.
1554 @end deftypevr
1555
1556 @comment fcntl.h
1557 @comment BSD
1558 @deftypevr Macro int O_FSYNC
1559 The bit that enables synchronous writing for the file.  If set, each
1560 @code{write} call will make sure the data is reliably stored on disk before
1561 returning. @c !!! xref fsync
1562
1563 Synchronous writing is a BSD feature.
1564 @end deftypevr
1565
1566 @comment fcntl.h
1567 @comment BSD
1568 @deftypevr Macro int O_SYNC
1569 This is another name for @code{O_FSYNC}.  They have the same value.
1570 @end deftypevr
1571
1572 @comment fcntl.h
1573 @comment GNU
1574 @deftypevr Macro int O_NOATIME
1575 If this bit is set, @code{read} will not update the access time of the
1576 file.  @xref{File Times}.  This is used by programs that do backups, so
1577 that backing a file up does not count as reading it.
1578 Only the owner of the file or the superuser may use this bit.
1579
1580 This is a GNU extension.
1581 @end deftypevr
1582
1583 @node Getting File Status Flags
1584 @subsection Getting and Setting File Status Flags
1585
1586 The @code{fcntl} function can fetch or change file status flags.
1587
1588 @comment fcntl.h
1589 @comment POSIX.1
1590 @deftypevr Macro int F_GETFL
1591 This macro is used as the @var{command} argument to @code{fcntl}, to
1592 read the file status flags for the open file with descriptor
1593 @var{filedes}.
1594
1595 The normal return value from @code{fcntl} with this command is a
1596 nonnegative number which can be interpreted as the bitwise OR of the
1597 individual flags.  Since the file access modes are not single-bit values,
1598 you can mask off other bits in the returned flags with @code{O_ACCMODE}
1599 to compare them.
1600
1601 In case of an error, @code{fcntl} returns @code{-1}.  The following
1602 @code{errno} error conditions are defined for this command:
1603
1604 @table @code
1605 @item EBADF
1606 The @var{filedes} argument is invalid.
1607 @end table
1608 @end deftypevr
1609
1610 @comment fcntl.h
1611 @comment POSIX.1
1612 @deftypevr Macro int F_SETFL
1613 This macro is used as the @var{command} argument to @code{fcntl}, to set
1614 the file status flags for the open file corresponding to the
1615 @var{filedes} argument.  This command requires a third @code{int}
1616 argument to specify the new flags, so the call looks like this:
1617
1618 @smallexample
1619 fcntl (@var{filedes}, F_SETFL, @var{new-flags})
1620 @end smallexample
1621
1622 You can't change the access mode for the file in this way; that is,
1623 whether the file descriptor was opened for reading or writing.
1624
1625 The normal return value from @code{fcntl} with this command is an
1626 unspecified value other than @code{-1}, which indicates an error.  The
1627 error conditions are the same as for the @code{F_GETFL} command.
1628 @end deftypevr
1629
1630 If you want to modify the file status flags, you should get the current
1631 flags with @code{F_GETFL} and modify the value.  Don't assume that the
1632 flags listed here are the only ones that are implemented; your program
1633 may be run years from now and more flags may exist then.  For example,
1634 here is a function to set or clear the flag @code{O_NONBLOCK} without
1635 altering any other flags:
1636
1637 @smallexample
1638 @group
1639 /* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
1640    @r{or clear the flag if @var{value} is 0.}
1641    @r{Return 0 on success, or -1 on error with @code{errno} set.} */
1642
1643 int
1644 set_nonblock_flag (int desc, int value)
1645 @{
1646   int oldflags = fcntl (desc, F_GETFL, 0);
1647   /* @r{If reading the flags failed, return error indication now.} */
1648   if (oldflags == -1)
1649     return -1;
1650   /* @r{Set just the flag we want to set.} */
1651   if (value != 0)
1652     oldflags |= O_NONBLOCK;
1653   else
1654     oldflags &= ~O_NONBLOCK;
1655   /* @r{Store modified flag word in the descriptor.} */
1656   return fcntl (desc, F_SETFL, oldflags);
1657 @}
1658 @end group
1659 @end smallexample
1660
1661 @node File Locks
1662 @section File Locks
1663
1664 @cindex file locks
1665 @cindex record locking
1666 The remaining @code{fcntl} commands are used to support @dfn{record
1667 locking}, which permits multiple cooperating programs to prevent each
1668 other from simultaneously accessing parts of a file in error-prone
1669 ways.
1670
1671 @cindex exclusive lock
1672 @cindex write lock
1673 An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
1674 for writing to the specified part of the file.  While a write lock is in
1675 place, no other process can lock that part of the file.
1676
1677 @cindex shared lock
1678 @cindex read lock
1679 A @dfn{shared} or @dfn{read} lock prohibits any other process from
1680 requesting a write lock on the specified part of the file.  However,
1681 other processes can request read locks.
1682
1683 The @code{read} and @code{write} functions do not actually check to see
1684 whether there are any locks in place.  If you want to implement a
1685 locking protocol for a file shared by multiple processes, your application
1686 must do explicit @code{fcntl} calls to request and clear locks at the
1687 appropriate points.
1688
1689 Locks are associated with processes.  A process can only have one kind
1690 of lock set for each byte of a given file.  When any file descriptor for
1691 that file is closed by the process, all of the locks that process holds
1692 on that file are released, even if the locks were made using other
1693 descriptors that remain open.  Likewise, locks are released when a
1694 process exits, and are not inherited by child processes created using
1695 @code{fork} (@pxref{Creating a Process}).
1696
1697 When making a lock, use a @code{struct flock} to specify what kind of
1698 lock and where.  This data type and the associated macros for the
1699 @code{fcntl} function are declared in the header file @file{fcntl.h}.
1700 @pindex fcntl.h
1701
1702 @comment fcntl.h
1703 @comment POSIX.1
1704 @deftp {Data Type} {struct flock}
1705 This structure is used with the @code{fcntl} function to describe a file
1706 lock.  It has these members:
1707
1708 @table @code
1709 @item short int l_type
1710 Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
1711 @code{F_UNLCK}.
1712
1713 @item short int l_whence
1714 This corresponds to the @var{whence} argument to @code{fseek} or
1715 @code{lseek}, and specifies what the offset is relative to.  Its value
1716 can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.
1717
1718 @item off_t l_start
1719 This specifies the offset of the start of the region to which the lock
1720 applies, and is given in bytes relative to the point specified by
1721 @code{l_whence} member.
1722
1723 @item off_t l_len
1724 This specifies the length of the region to be locked.  A value of
1725 @code{0} is treated specially; it means the region extends to the end of
1726 the file.
1727
1728 @item pid_t l_pid
1729 This field is the process ID (@pxref{Process Creation Concepts}) of the
1730 process holding the lock.  It is filled in by calling @code{fcntl} with
1731 the @code{F_GETLK} command, but is ignored when making a lock.
1732 @end table
1733 @end deftp
1734
1735 @comment fcntl.h
1736 @comment POSIX.1
1737 @deftypevr Macro int F_GETLK
1738 This macro is used as the @var{command} argument to @code{fcntl}, to
1739 specify that it should get information about a lock.  This command
1740 requires a third argument of type @w{@code{struct flock *}} to be passed
1741 to @code{fcntl}, so that the form of the call is:
1742
1743 @smallexample
1744 fcntl (@var{filedes}, F_GETLK, @var{lockp})
1745 @end smallexample
1746
1747 If there is a lock already in place that would block the lock described
1748 by the @var{lockp} argument, information about that lock overwrites
1749 @code{*@var{lockp}}.  Existing locks are not reported if they are
1750 compatible with making a new lock as specified.  Thus, you should
1751 specify a lock type of @code{F_WRLCK} if you want to find out about both
1752 read and write locks, or @code{F_RDLCK} if you want to find out about
1753 write locks only.
1754
1755 There might be more than one lock affecting the region specified by the
1756 @var{lockp} argument, but @code{fcntl} only returns information about
1757 one of them.  The @code{l_whence} member of the @var{lockp} structure is
1758 set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
1759 set to identify the locked region.
1760
1761 If no lock applies, the only change to the @var{lockp} structure is to
1762 update the @code{l_type} to a value of @code{F_UNLCK}.
1763
1764 The normal return value from @code{fcntl} with this command is an
1765 unspecified value other than @code{-1}, which is reserved to indicate an
1766 error.  The following @code{errno} error conditions are defined for
1767 this command:
1768
1769 @table @code
1770 @item EBADF
1771 The @var{filedes} argument is invalid.
1772
1773 @item EINVAL
1774 Either the @var{lockp} argument doesn't specify valid lock information,
1775 or the file associated with @var{filedes} doesn't support locks.
1776 @end table
1777 @end deftypevr
1778
1779 @comment fcntl.h
1780 @comment POSIX.1
1781 @deftypevr Macro int F_SETLK
1782 This macro is used as the @var{command} argument to @code{fcntl}, to
1783 specify that it should set or clear a lock.  This command requires a
1784 third argument of type @w{@code{struct flock *}} to be passed to
1785 @code{fcntl}, so that the form of the call is:
1786
1787 @smallexample
1788 fcntl (@var{filedes}, F_SETLK, @var{lockp})
1789 @end smallexample
1790
1791 If the process already has a lock on any part of the region, the old lock
1792 on that part is replaced with the new lock.  You can remove a lock
1793 by specifying a lock type of @code{F_UNLCK}.
1794
1795 If the lock cannot be set, @code{fcntl} returns immediately with a value
1796 of @code{-1}.  This function does not block waiting for other processes
1797 to release locks.  If @code{fcntl} succeeds, it return a value other
1798 than @code{-1}.
1799
1800 The following @code{errno} error conditions are defined for this
1801 function:
1802
1803 @table @code
1804 @item EAGAIN
1805 @itemx EACCES
1806 The lock cannot be set because it is blocked by an existing lock on the
1807 file.  Some systems use @code{EAGAIN} in this case, and other systems
1808 use @code{EACCES}; your program should treat them alike, after
1809 @code{F_SETLK}.  (The GNU system always uses @code{EAGAIN}.)
1810
1811 @item EBADF
1812 Either: the @var{filedes} argument is invalid; you requested a read lock
1813 but the @var{filedes} is not open for read access; or, you requested a
1814 write lock but the @var{filedes} is not open for write access.
1815
1816 @item EINVAL
1817 Either the @var{lockp} argument doesn't specify valid lock information,
1818 or the file associated with @var{filedes} doesn't support locks.
1819
1820 @item ENOLCK
1821 The system has run out of file lock resources; there are already too
1822 many file locks in place.
1823
1824 Well-designed file systems never report this error, because they have no
1825 limitation on the number of locks.  However, you must still take account
1826 of the possibility of this error, as it could result from network access
1827 to a file system on another machine.
1828 @end table
1829 @end deftypevr
1830
1831 @comment fcntl.h
1832 @comment POSIX.1
1833 @deftypevr Macro int F_SETLKW
1834 This macro is used as the @var{command} argument to @code{fcntl}, to
1835 specify that it should set or clear a lock.  It is just like the
1836 @code{F_SETLK} command, but causes the process to block (or wait)
1837 until the request can be specified.
1838
1839 This command requires a third argument of type @code{struct flock *}, as
1840 for the @code{F_SETLK} command.
1841
1842 The @code{fcntl} return values and errors are the same as for the
1843 @code{F_SETLK} command, but these additional @code{errno} error conditions
1844 are defined for this command:
1845
1846 @table @code
1847 @item EINTR
1848 The function was interrupted by a signal while it was waiting.
1849 @xref{Interrupted Primitives}.
1850
1851 @item EDEADLK
1852 The specified region is being locked by another process.  But that
1853 process is waiting to lock a region which the current process has
1854 locked, so waiting for the lock would result in deadlock.  The system
1855 does not guarantee that it will detect all such conditions, but it lets
1856 you know if it notices one.
1857 @end table
1858 @end deftypevr
1859
1860
1861 The following macros are defined for use as values for the @code{l_type}
1862 member of the @code{flock} structure.  The values are integer constants.
1863
1864 @table @code
1865 @comment fcntl.h
1866 @comment POSIX.1
1867 @vindex F_RDLCK
1868 @item F_RDLCK
1869 This macro is used to specify a read (or shared) lock.
1870
1871 @comment fcntl.h
1872 @comment POSIX.1
1873 @vindex F_WRLCK
1874 @item F_WRLCK
1875 This macro is used to specify a write (or exclusive) lock.
1876
1877 @comment fcntl.h
1878 @comment POSIX.1
1879 @vindex F_UNLCK
1880 @item F_UNLCK
1881 This macro is used to specify that the region is unlocked.
1882 @end table
1883
1884 As an example of a situation where file locking is useful, consider a
1885 program that can be run simultaneously by several different users, that
1886 logs status information to a common file.  One example of such a program
1887 might be a game that uses a file to keep track of high scores.  Another
1888 example might be a program that records usage or accounting information
1889 for billing purposes.
1890
1891 Having multiple copies of the program simultaneously writing to the
1892 file could cause the contents of the file to become mixed up.  But
1893 you can prevent this kind of problem by setting a write lock on the
1894 file before actually writing to the file.
1895
1896 If the program also needs to read the file and wants to make sure that
1897 the contents of the file are in a consistent state, then it can also use
1898 a read lock.  While the read lock is set, no other process can lock
1899 that part of the file for writing.
1900
1901 @c ??? This section could use an example program.
1902
1903 Remember that file locks are only a @emph{voluntary} protocol for
1904 controlling access to a file.  There is still potential for access to
1905 the file by programs that don't use the lock protocol.
1906
1907 @node Interrupt Input
1908 @section Interrupt-Driven Input
1909
1910 @cindex interrupt-driven input
1911 If you set the @code{O_ASYNC} status flag on a file descriptor
1912 (@pxref{File Status Flags}), a @code{SIGIO} signal is sent whenever
1913 input or output becomes possible on that file descriptor.  The process
1914 or process group to receive the signal can be selected by using the
1915 @code{F_SETOWN} command to the @code{fcntl} function.  If the file
1916 descriptor is a socket, this also selects the recipient of @code{SIGURG}
1917 signals that are delivered when out-of-band data arrives on that socket;
1918 see @ref{Out-of-Band Data}.  (@code{SIGURG} is sent in any situation
1919 where @code{select} would report the socket as having an ``exceptional
1920 condition''.  @xref{Waiting for I/O}.)
1921
1922 If the file descriptor corresponds to a terminal device, then @code{SIGIO}
1923 signals are sent to the foreground process group of the terminal.
1924 @xref{Job Control}.
1925
1926 @pindex fcntl.h
1927 The symbols in this section are defined in the header file
1928 @file{fcntl.h}.
1929
1930 @comment fcntl.h
1931 @comment BSD
1932 @deftypevr Macro int F_GETOWN
1933 This macro is used as the @var{command} argument to @code{fcntl}, to
1934 specify that it should get information about the process or process
1935 group to which @code{SIGIO} signals are sent.  (For a terminal, this is
1936 actually the foreground process group ID, which you can get using
1937 @code{tcgetpgrp}; see @ref{Terminal Access Functions}.)
1938
1939 The return value is interpreted as a process ID; if negative, its
1940 absolute value is the process group ID.
1941
1942 The following @code{errno} error condition is defined for this command:
1943
1944 @table @code
1945 @item EBADF
1946 The @var{filedes} argument is invalid.
1947 @end table
1948 @end deftypevr
1949
1950 @comment fcntl.h
1951 @comment BSD
1952 @deftypevr Macro int F_SETOWN
1953 This macro is used as the @var{command} argument to @code{fcntl}, to
1954 specify that it should set the process or process group to which
1955 @code{SIGIO} signals are sent.  This command requires a third argument
1956 of type @code{pid_t} to be passed to @code{fcntl}, so that the form of
1957 the call is:
1958
1959 @smallexample
1960 fcntl (@var{filedes}, F_SETOWN, @var{pid})
1961 @end smallexample
1962
1963 The @var{pid} argument should be a process ID.  You can also pass a
1964 negative number whose absolute value is a process group ID.
1965
1966 The return value from @code{fcntl} with this command is @code{-1}
1967 in case of error and some other value if successful.  The following
1968 @code{errno} error conditions are defined for this command:
1969
1970 @table @code
1971 @item EBADF
1972 The @var{filedes} argument is invalid.
1973
1974 @item ESRCH
1975 There is no process or process group corresponding to @var{pid}.
1976 @end table
1977 @end deftypevr
1978
1979 @c ??? This section could use an example program.