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