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