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