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