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