(Scanning Directory Content): Fix typo.
[kopensolaris-gnu/glibc.git] / manual / filesys.texi
1 @node File System Interface, Pipes and FIFOs, Low-Level I/O, Top
2 @chapter File System Interface
3
4 This chapter describes the GNU C library's functions for manipulating
5 files.  Unlike the input and output functions described in
6 @ref{I/O on Streams} and @ref{Low-Level I/O}, these
7 functions are concerned with operating on the files themselves, rather
8 than on their contents.
9
10 Among the facilities described in this chapter are functions for
11 examining or modifying directories, functions for renaming and deleting
12 files, and functions for examining and setting file attributes such as
13 access permissions and modification times.
14
15 @menu
16 * Working Directory::           This is used to resolve relative
17                                  file names.
18 * Accessing Directories::       Finding out what files a directory
19                                  contains.
20 * Working on Directory Trees::  Apply actions to all files or a selectable
21                                  subset of a directory hierarchy.
22 * Hard Links::                  Adding alternate names to a file.
23 * Symbolic Links::              A file that ``points to'' a file name.
24 * Deleting Files::              How to delete a file, and what that means.
25 * Renaming Files::              Changing a file's name.
26 * Creating Directories::        A system call just for creating a directory.
27 * File Attributes::             Attributes of individual files.
28 * Making Special Files::        How to create special files.
29 * Temporary Files::             Naming and creating temporary files.
30 @end menu
31
32 @node Working Directory
33 @section Working Directory
34
35 @cindex current working directory
36 @cindex working directory
37 @cindex change working directory
38 Each process has associated with it a directory, called its @dfn{current
39 working directory} or simply @dfn{working directory}, that is used in
40 the resolution of relative file names (@pxref{File Name Resolution}).
41
42 When you log in and begin a new session, your working directory is
43 initially set to the home directory associated with your login account
44 in the system user database.  You can find any user's home directory
45 using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User
46 Database}.
47
48 Users can change the working directory using shell commands like
49 @code{cd}.  The functions described in this section are the primitives
50 used by those commands and by other programs for examining and changing
51 the working directory.
52 @pindex cd
53
54 Prototypes for these functions are declared in the header file
55 @file{unistd.h}.
56 @pindex unistd.h
57
58 @comment unistd.h
59 @comment POSIX.1
60 @deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size})
61 The @code{getcwd} function returns an absolute file name representing
62 the current working directory, storing it in the character array
63 @var{buffer} that you provide.  The @var{size} argument is how you tell
64 the system the allocation size of @var{buffer}.
65
66 The GNU library version of this function also permits you to specify a
67 null pointer for the @var{buffer} argument.  Then @code{getcwd}
68 allocates a buffer automatically, as with @code{malloc}
69 (@pxref{Unconstrained Allocation}).  If the @var{size} is greater than
70 zero, then the buffer is that large; otherwise, the buffer is as large
71 as necessary to hold the result.
72
73 The return value is @var{buffer} on success and a null pointer on failure.
74 The following @code{errno} error conditions are defined for this function:
75
76 @table @code
77 @item EINVAL
78 The @var{size} argument is zero and @var{buffer} is not a null pointer.
79
80 @item ERANGE
81 The @var{size} argument is less than the length of the working directory
82 name.  You need to allocate a bigger array and try again.
83
84 @item EACCES
85 Permission to read or search a component of the file name was denied.
86 @end table
87 @end deftypefun
88
89 Here is an example showing how you could implement the behavior of GNU's@*
90 @w{@code{getcwd (NULL, 0)}} using only the standard behavior of
91 @code{getcwd}:
92
93 @smallexample
94 char *
95 gnu_getcwd ()
96 @{
97   int size = 100;
98   char *buffer = (char *) xmalloc (size);
99
100   while (1)
101     @{
102       char *value = getcwd (buffer, size);
103       if (value != 0)
104         return buffer;
105       size *= 2;
106       free (buffer);
107       buffer = (char *) xmalloc (size);
108     @}
109 @}
110 @end smallexample
111
112 @noindent
113 @xref{Malloc Examples}, for information about @code{xmalloc}, which is
114 not a library function but is a customary name used in most GNU
115 software.
116
117 @comment unistd.h
118 @comment BSD
119 @deftypefun {char *} getwd (char *@var{buffer})
120 This is similar to @code{getcwd}, but has no way to specify the size of
121 the buffer.  The GNU library provides @code{getwd} only
122 for backwards compatibility with BSD.
123
124 The @var{buffer} argument should be a pointer to an array at least
125 @code{PATH_MAX} bytes long (@pxref{Limits for Files}).  In the GNU
126 system there is no limit to the size of a file name, so this is not
127 necessarily enough space to contain the directory name.  That is why
128 this function is deprecated.
129 @end deftypefun
130
131 @comment unistd.h
132 @comment POSIX.1
133 @deftypefun int chdir (const char *@var{filename})
134 This function is used to set the process's working directory to
135 @var{filename}.
136
137 The normal, successful return value from @code{chdir} is @code{0}.  A
138 value of @code{-1} is returned to indicate an error.  The @code{errno}
139 error conditions defined for this function are the usual file name
140 syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
141 file @var{filename} is not a directory.
142 @end deftypefun
143
144
145 @node Accessing Directories
146 @section Accessing Directories
147 @cindex accessing directories
148 @cindex reading from a directory
149 @cindex directories, accessing
150
151 The facilities described in this section let you read the contents of a
152 directory file.  This is useful if you want your program to list all the
153 files in a directory, perhaps as part of a menu.
154
155 @cindex directory stream
156 The @code{opendir} function opens a @dfn{directory stream} whose
157 elements are directory entries.  You use the @code{readdir} function on
158 the directory stream to retrieve these entries, represented as
159 @w{@code{struct dirent}} objects.  The name of the file for each entry is
160 stored in the @code{d_name} member of this structure.  There are obvious
161 parallels here to the stream facilities for ordinary files, described in
162 @ref{I/O on Streams}.
163
164 @menu
165 * Directory Entries::           Format of one directory entry.
166 * Opening a Directory::         How to open a directory stream.
167 * Reading/Closing Directory::   How to read directory entries from the stream.
168 * Simple Directory Lister::     A very simple directory listing program.
169 * Random Access Directory::     Rereading part of the directory
170                                  already read with the same stream.
171 * Scanning Directory Content::  Get entries for user selected subset of
172                                  contents in given directory.
173 * Simple Directory Lister Mark II::  Revised version of the program.
174 @end menu
175
176 @node Directory Entries
177 @subsection Format of a Directory Entry
178
179 @pindex dirent.h
180 This section describes what you find in a single directory entry, as you
181 might obtain it from a directory stream.  All the symbols are declared
182 in the header file @file{dirent.h}.
183
184 @comment dirent.h
185 @comment POSIX.1
186 @deftp {Data Type} {struct dirent}
187 This is a structure type used to return information about directory
188 entries.  It contains the following fields:
189
190 @table @code
191 @item char d_name[]
192 This is the null-terminated file name component.  This is the only
193 field you can count on in all POSIX systems.
194
195 @item ino_t d_fileno
196 This is the file serial number.  For BSD compatibility, you can also
197 refer to this member as @code{d_ino}.  In the GNU system and most POSIX
198 systems, for most files this the same as the @code{st_ino} member that
199 @code{stat} will return for the file.  @xref{File Attributes}.
200
201 @item unsigned char d_namlen
202 This is the length of the file name, not including the terminating null
203 character.  Its type is @code{unsigned char} because that is the integer
204 type of the appropriate size
205
206 @item unsigned char d_type
207 This is the type of the file, possibly unknown.  The following constants
208 are defined for its value:
209
210 @table @code
211 @item DT_UNKNOWN
212 The type is unknown.  On some systems this is the only value returned.
213
214 @item DT_REG
215 A regular file.
216
217 @item DT_DIR
218 A directory.
219
220 @item DT_FIFO
221 A named pipe, or FIFO.  @xref{FIFO Special Files}.
222
223 @item DT_SOCK
224 A local-domain socket.  @c !!! @xref{Local Domain}.
225
226 @item DT_CHR
227 A character device.
228
229 @item DT_BLK
230 A block device.
231 @end table
232
233 This member is a BSD extension.  On systems where it is used, it
234 corresponds to the file type bits in the @code{st_mode} member of
235 @code{struct statbuf}.  On other systems it will always be DT_UNKNOWN.
236 These two macros convert between @code{d_type} values and @code{st_mode}
237 values:
238
239 @deftypefun int IFTODT (mode_t @var{mode})
240 This returns the @code{d_type} value corresponding to @var{mode}.
241 @end deftypefun
242
243 @deftypefun mode_t DTTOIF (int @var{dtype})
244 This returns the @code{st_mode} value corresponding to @var{dtype}.
245 @end deftypefun
246 @end table
247
248 This structure may contain additional members in the future.
249
250 When a file has multiple names, each name has its own directory entry.
251 The only way you can tell that the directory entries belong to a
252 single file is that they have the same value for the @code{d_fileno}
253 field.
254
255 File attributes such as size, modification times, and the like are part
256 of the file itself, not any particular directory entry.  @xref{File
257 Attributes}.
258 @end deftp
259
260 @node Opening a Directory
261 @subsection Opening a Directory Stream
262
263 @pindex dirent.h
264 This section describes how to open a directory stream.  All the symbols
265 are declared in the header file @file{dirent.h}.
266
267 @comment dirent.h
268 @comment POSIX.1
269 @deftp {Data Type} DIR
270 The @code{DIR} data type represents a directory stream.
271 @end deftp
272
273 You shouldn't ever allocate objects of the @code{struct dirent} or
274 @code{DIR} data types, since the directory access functions do that for
275 you.  Instead, you refer to these objects using the pointers returned by
276 the following functions.
277
278 @comment dirent.h
279 @comment POSIX.1
280 @deftypefun {DIR *} opendir (const char *@var{dirname})
281 The @code{opendir} function opens and returns a directory stream for
282 reading the directory whose file name is @var{dirname}.  The stream has
283 type @code{DIR *}.
284
285 If unsuccessful, @code{opendir} returns a null pointer.  In addition to
286 the usual file name errors (@pxref{File Name Errors}), the
287 following @code{errno} error conditions are defined for this function:
288
289 @table @code
290 @item EACCES
291 Read permission is denied for the directory named by @code{dirname}.
292
293 @item EMFILE
294 The process has too many files open.
295
296 @item ENFILE
297 The entire system, or perhaps the file system which contains the
298 directory, cannot support any additional open files at the moment.
299 (This problem cannot happen on the GNU system.)
300 @end table
301
302 The @code{DIR} type is typically implemented using a file descriptor,
303 and the @code{opendir} function in terms of the @code{open} function.
304 @xref{Low-Level I/O}.  Directory streams and the underlying
305 file descriptors are closed on @code{exec} (@pxref{Executing a File}).
306 @end deftypefun
307
308 @node Reading/Closing Directory
309 @subsection Reading and Closing a Directory Stream
310
311 @pindex dirent.h
312 This section describes how to read directory entries from a directory
313 stream, and how to close the stream when you are done with it.  All the
314 symbols are declared in the header file @file{dirent.h}.
315
316 @comment dirent.h
317 @comment POSIX.1
318 @deftypefun {struct dirent *} readdir (DIR *@var{dirstream})
319 This function reads the next entry from the directory.  It normally
320 returns a pointer to a structure containing information about the file.
321 This structure is statically allocated and can be rewritten by a
322 subsequent call.
323
324 @strong{Portability Note:} On some systems, @code{readdir} may not
325 return entries for @file{.} and @file{..}, even though these are always
326 valid file names in any directory.  @xref{File Name Resolution}.
327
328 If there are no more entries in the directory or an error is detected,
329 @code{readdir} returns a null pointer.  The following @code{errno} error
330 conditions are defined for this function:
331
332 @table @code
333 @item EBADF
334 The @var{dirstream} argument is not valid.
335 @end table
336
337 @code{readdir} is not thread safe.  Multiple threads using
338 @code{readdir} on the same @var{dirstream} may overwrite the return
339 value.  Use @code{readdir_r} when this is critical.
340 @end deftypefun
341
342 @comment dirent.h
343 @comment GNU
344 @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result})
345 This function is the reentrant version of @code{readdir}.  Like
346 @code{readdir} it returns the next entry from the directory.  But to
347 prevent conflicts for simultaneously running threads the result is not
348 stored in some internal memory.  Instead the argument @var{entry} has to
349 point to a place where the result is stored.
350
351 The return value is @code{0} in case the next entry was read
352 successfully.  In this case a pointer to the result is returned in
353 *@var{result}.  It is not required that *@var{result} is the same as
354 @var{entry}.  If something goes wrong while executing @code{readdir_r}
355 the function returns a value indicating the error (as described for
356 @code{readdir}).
357
358 If there are no more directory entries, @code{readdir_r}'s return value is
359 @code{0}, and *@var{result} is set to @code{NULL}.
360
361 @strong{Portability Note:} On some systems, @code{readdir_r} may not
362 return a terminated string as the file name even if no @code{d_reclen}
363 element is available in @code{struct dirent} and the file name as the
364 maximal allowed size.  Modern systems all have the @code{d_reclen} field
365 and on old systems multi threading is not critical.  In any case, there
366 is no such problem with the @code{readdir} function so that even on
367 systems without @code{d_reclen} field one could use multiple threads by
368 using external locking.
369 @end deftypefun
370
371 @comment dirent.h
372 @comment POSIX.1
373 @deftypefun int closedir (DIR *@var{dirstream})
374 This function closes the directory stream @var{dirstream}.  It returns
375 @code{0} on success and @code{-1} on failure.
376
377 The following @code{errno} error conditions are defined for this
378 function:
379
380 @table @code
381 @item EBADF
382 The @var{dirstream} argument is not valid.
383 @end table
384 @end deftypefun
385
386 @node Simple Directory Lister
387 @subsection Simple Program to List a Directory
388
389 Here's a simple program that prints the names of the files in
390 the current working directory:
391
392 @smallexample
393 @include dir.c.texi
394 @end smallexample
395
396 The order in which files appear in a directory tends to be fairly
397 random.  A more useful program would sort the entries (perhaps by
398 alphabetizing them) before printing them; see
399 @ref{Scanning Directory Content} and @ref{Array Sort Function}.
400
401
402 @node Random Access Directory
403 @subsection Random Access in a Directory Stream
404
405 @pindex dirent.h
406 This section describes how to reread parts of a directory that you have
407 already read from an open directory stream.  All the symbols are
408 declared in the header file @file{dirent.h}.
409
410 @comment dirent.h
411 @comment POSIX.1
412 @deftypefun void rewinddir (DIR *@var{dirstream})
413 The @code{rewinddir} function is used to reinitialize the directory
414 stream @var{dirstream}, so that if you call @code{readdir} it
415 returns information about the first entry in the directory again.  This
416 function also notices if files have been added or removed to the
417 directory since it was opened with @code{opendir}.  (Entries for these
418 files might or might not be returned by @code{readdir} if they were
419 added or removed since you last called @code{opendir} or
420 @code{rewinddir}.)
421 @end deftypefun
422
423 @comment dirent.h
424 @comment BSD
425 @deftypefun off_t telldir (DIR *@var{dirstream})
426 The @code{telldir} function returns the file position of the directory
427 stream @var{dirstream}.  You can use this value with @code{seekdir} to
428 restore the directory stream to that position.
429 @end deftypefun
430
431 @comment dirent.h
432 @comment BSD
433 @deftypefun void seekdir (DIR *@var{dirstream}, off_t @var{pos})
434 The @code{seekdir} function sets the file position of the directory
435 stream @var{dirstream} to @var{pos}.  The value @var{pos} must be the
436 result of a previous call to @code{telldir} on this particular stream;
437 closing and reopening the directory can invalidate values returned by
438 @code{telldir}.
439 @end deftypefun
440
441
442 @node Scanning Directory Content
443 @subsection Scanning the Content of a Directory
444
445 A higher-level interface to the directory handling functions is the
446 @code{scandir} function.  With its help one can select a subset of the
447 entries in a directory, possibly sort them and get as the result a list
448 of names.
449
450 @comment dirent.h
451 @comment BSD/SVID
452 @deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const void *, const void *))
453
454 The @code{scandir} function scans the contents of the directory selected
455 by @var{dir}.  The result in @var{namelist} is an array of pointers to
456 structure of type @code{struct dirent} which describe all selected
457 directory entries and which is allocated using @code{malloc}.  Instead
458 of always getting all directory entries returned, the user supplied
459 function @var{selector} can be used to decide which entries are in the
460 result.  Only the entries for which @var{selector} returns a nonzero
461 value are selected.
462
463 Finally the entries in the @var{namelist} are sorted using the user
464 supplied function @var{cmp}.  The arguments of the @var{cmp} function
465 are of type @code{struct dirent **}.  I.e., one cannot directly use the
466 @code{strcmp} or @code{strcoll} function; see the functions
467 @code{alphasort} and @code{versionsort} below.
468
469 The return value of the function gives the number of entries placed in
470 @var{namelist}.  If it is @code{-1} an error occurred (either the
471 directory could not be opened for reading or the malloc call failed) and
472 the global variable @code{errno} contains more information on the error.
473 @end deftypefun
474
475 As said above the fourth argument to the @code{scandir} function must be
476 a pointer to a sorting function.  For the convenience of the programmer
477 the GNU C library contains implementations of functions which are very
478 helpful for this purpose.
479
480 @comment dirent.h
481 @comment BSD/SVID
482 @deftypefun int alphasort (const void *@var{a}, const void *@var{b})
483 The @code{alphasort} function behaves like the @code{strcoll} function
484 (@pxref{String/Array Comparison}).  The difference is that the arguments
485 are not string pointers but instead they are of type
486 @code{struct dirent **}.
487
488 Return value of @code{alphasort} is less than, equal to, or greater than
489 zero depending on the order of the two entries @var{a} and @var{b}.
490 @end deftypefun
491
492 @comment dirent.h
493 @comment GNU
494 @deftypefun int versionsort (const void *@var{a}, const void *@var{b})
495 The @code{versionsort} function is like @code{alphasort}, excepted that it
496 uses the @code{strverscmp} function internally.
497 @end deftypefun
498
499 If the filesystem supports large files we cannot use the @code{scandir}
500 anymore since the @code{dirent} structure might not able to contain all
501 the information.  The LFS provides the new type @w{@code{struct
502 dirent64}}.  To use this we need a new function.
503
504 @comment dirent.h
505 @comment GNU
506 @deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const void *, const void *))
507 The @code{scandir64} function works like the @code{scandir} function
508 only that the directory entries it returns are described by elements of
509 type @w{@code{struct dirent64}}.  The function pointed to by
510 @var{selector} is again used to select the wanted entries only that
511 @var{selector} now must point to a function which takes a
512 @w{@code{struct dirent64 *}} parameter.
513
514 The @var{cmp} now must be a function which expects its two arguments to
515 be of type @code{struct dirent64 **}.
516 @end deftypefun
517
518 As just said the function expected as the fourth is different from the
519 function expected in @code{scandir}.  Therefore we cannot use the
520 @code{alphasort} and @code{versionsort} functions anymore.  Instead we
521 have two similar functions available.
522
523 @comment dirent.h
524 @comment GNU
525 @deftypefun int alphasort64 (const void *@var{a}, const void *@var{b})
526 The @code{alphasort64} function behaves like the @code{strcoll} function
527 (@pxref{String/Array Comparison}).  The difference is that the arguments
528 are not string pointers but instead they are of type
529 @code{struct dirent64 **}.
530
531 Return value of @code{alphasort64} is less than, equal to, or greater
532 than zero depending on the order of the two entries @var{a} and @var{b}.
533 @end deftypefun
534
535 @comment dirent.h
536 @comment GNU
537 @deftypefun int versionsort64 (const void *@var{a}, const void *@var{b})
538 The @code{versionsort64} function is like @code{alphasort64}, excepted that it
539 uses the @code{strverscmp} function internally.
540 @end deftypefun
541
542 It is important not to mix the use of @code{scandir} and the 64 bits
543 comparison functions or vice versa.  There are systems on which this
544 works but on others it will fail miserably.
545
546 @node Simple Directory Lister Mark II
547 @subsection Simple Program to List a Directory, Mark II
548
549 Here is a revised version of the directory lister found above
550 (@pxref{Simple Directory Lister}).  Using the @code{scandir} function we
551 can avoid using the functions which directly work with the directory
552 contents.  After the call the found entries are available for direct
553 used.
554
555 @smallexample
556 @include dir2.c.texi
557 @end smallexample
558
559 Please note the simple selector function for this example.  Since
560 we want to see all directory entries we always return @code{1}.
561
562
563 @node Working on Directory Trees
564 @section Working on Directory Trees
565 @cindex directory hierarchy
566 @cindex hierarchy, directory
567 @cindex tree, directory
568
569 The functions to handle files in directories described so far allowed to
570 retrieve all the information in small pieces or process all files in a
571 directory (see @code{scandir}).  Sometimes it is useful to process whole
572 hierarchies of directories and the contained files.  The X/Open
573 specification define two functions to do this.  The simpler form is
574 derived from an early definition in @w{System V} systems and therefore
575 this function is available on SVID derived systems.  The prototypes and
576 required definitions can be found in the @file{ftw.h} header.
577
578 Both functions of this @code{ftw} family take as one of the arguments a
579 reference to a callback function.  The functions must be of these types.
580
581 @deftp {Data Type} __ftw_func_t
582
583 @smallexample
584 int (*) (const char *, const struct stat *, int)
585 @end smallexample
586
587 Type for callback functions given to the @code{ftw} function.  The first
588 parameter will contain a pointer to the filename, the second parameter
589 will point to an object of type @code{struct stat} which will be filled
590 for the file named by the first parameter.
591
592 @noindent
593 The last parameter is a flag given more information about the current
594 file.  It can have the following values:
595
596 @vindex FTW_F
597 @vindex FTW_D
598 @vindex FTW_NS
599 @vindex FTW_DNR
600 @vindex FTW_SL
601 @table @code
602 @item FTW_F
603 The current item is a normal file or files which do not fit into one of
604 the following categories.  This means especially special files, sockets
605 etc.
606 @item FTW_D
607 The current item is a directory.
608 @item FTW_NS
609 The @code{stat} call to fill the object pointed to by the second
610 parameter failed and so the information is invalid.
611 @item FTW_DNR
612 The item is a directory which cannot be read.
613 @item FTW_SL
614 The item is a symbolic link.  Since symbolic links are normally followed
615 seeing this value in a @code{ftw} callback function means the referenced
616 file does not exist.  The situation for @code{nftw} is different.
617
618 This value is only available if the program is compiled with
619 @code{_BSD_SOURCE} or @code{_XOPEN_EXTENDED} defined before including
620 the first header.  The original SVID systems do not have symbolic links.
621 @end table
622 @end deftp
623
624 @deftp {Data Type} __nftw_func_t
625
626 @smallexample
627 int (*) (const char *, const struct stat *, int, struct FTW *)
628 @end smallexample
629
630 @vindex FTW_DP
631 @vindex FTW_SLN
632 The first three arguments have the same as for the @code{__ftw_func_t}
633 type.  A difference is that for the third argument some additional
634 values are defined to allow finer differentiation:
635 @table @code
636 @item FTW_DP
637 The current item is a directory and all subdirectories have already been
638 visited and reported.  This flag is returned instead of @code{FTW_D} if
639 the @code{FTW_DEPTH} flag is given to @code{nftw} (see below).
640 @item FTW_SLN
641 The current item is a stale symbolic link.  The file it points to does
642 not exist.
643 @end table
644
645 The last parameter of the callback function is a pointer to a structure
646 with some extra information as described below.
647 @end deftp
648
649 @deftp {Data Type} {struct FTW}
650 The contained information helps to interpret the name parameter and
651 gives some information about current state of the traversal of the
652 directory hierarchy.
653
654 @table @code
655 @item int base
656 The value specifies which part of the filename argument given in the
657 first parameter to the callback function is the name of the file.  The
658 rest of the string is the path to locate the file.  This information is
659 especially important if the @code{FTW_CHDIR} flag for @code{nftw} was
660 set since then the current directory is the one the current item is
661 found in.
662 @item int level
663 While processing the directory the functions tracks how many directories
664 have been examine to find the current item.  This nesting level is
665 @math{0} for the item given starting item (file or directory) and is
666 incremented by one for each entered directory.
667 @end table
668 @end deftp
669
670
671 @comment ftw.h
672 @comment SVID
673 @deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors})
674 The @code{ftw} function calls the callback function given in the
675 parameter @var{func} for every item which is found in the directory
676 specified by @var{filename} and all directories below.  The function
677 follows symbolic links if necessary but does not process an item twice.
678 If @var{filename} names no directory this item is the only object
679 reported by calling the callback function.
680
681 The filename given to the callback function is constructed by taking the
682 @var{filename} parameter and appending the names of all passed
683 directories and then the local file name.  So the callback function can
684 use this parameter to access the file.  Before the callback function is
685 called @code{ftw} calls @code{stat} for this file and passes the
686 information up to the callback function.  If this @code{stat} call was
687 not successful the failure is indicated by setting the falg argument of
688 the callback function to @code{FTW_NS}.  Otherwise the flag is set
689 according to the description given in the description of
690 @code{__ftw_func_t} above.
691
692 The callback function is expected to return @math{0} to indicate that no
693 error occurred and the processing should be continued.  If an error
694 occurred in the callback function or the call to @code{ftw} shall return
695 immediately the callback function can return a value other than
696 @math{0}.  This is the only correct way to stop the function.  The
697 program must not use @code{setjmp} or similar techniques to continue the
698 program in another place.  This would leave the resources allocated in
699 the @code{ftw} function allocated.
700
701 The @var{descriptors} parameter to the @code{ftw} function specifies how
702 many file descriptors the @code{ftw} function is allowed to consume.
703 The more descriptors can be used the faster the function can run.  For
704 each level of directories at most one descriptor is used so that for
705 very deep directory hierarchies the limit on open file descriptors for
706 the process or the system can be exceeded.  Beside this the limit on
707 file descriptors is counted together for all threads in a multi-threaded
708 program and therefore it is always good too limit the maximal number of
709 open descriptors to a reasonable number.
710
711 The return value of the @code{ftw} function is @math{0} if all callback
712 function calls returned @math{0} and all actions performed by the
713 @code{ftw} succeeded.  If some function call failed (other than calling
714 @code{stat} on an item) the function return @math{-1}.  If a callback
715 function returns a value other than @math{0} this value is returned as
716 the return value of @code{ftw}.
717 @end deftypefun
718
719 @comment ftw.h
720 @comment XPG4.2
721 @deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag})
722 The @code{nftw} functions works like the @code{ftw} functions.  It calls
723 the callback function @var{func} for all items it finds in the directory
724 @var{filename} and below.  At most @var{descriptors} file descriptors
725 are consumed during the @code{nftw} call.
726
727 The differences are that for one the callback function is of a different
728 type.  It is of type @w{@code{struct FTW *}} and provides the callback
729 functions the information described above.
730
731 The second difference is that @code{nftw} takes an additional fourth
732 argument which is @math{0} or a combination of any of the following
733 values, combined using bitwise OR.
734
735 @table @code
736 @item FTW_PHYS
737 While traversing the directory symbolic links are not followed.  I.e.,
738 if this flag is given symbolic links are reported using the
739 @code{FTW_SL} value for the type parameter to the callback function.
740 Please note that if this flag is used the appearance of @code{FTW_SL} in
741 a callback function does not mean the referenced file does not exist.
742 To indicate this the extra value @code{FTW_SLN} exists.
743 @item FTW_MOUNT
744 The callback function is only called for items which are on the same
745 mounted filesystem as the directory given as the @var{filename}
746 parameter to @code{nftw}.
747 @item FTW_CHDIR
748 If this flag is given the current working directory is changed to the
749 directory containing the reported object before the callback function is
750 called.
751 @item FTW_DEPTH
752 If this option is given the function visits first all files and
753 subdirectories before the callback function is called for the directory
754 itself (depth-first processing).  This also means the type flag given to
755 the callback function is @code{FTW_DP} and not @code{FTW_D}.
756 @end table
757
758 The return value is computed in the same way as for @code{ftw}.
759 @code{nftw} return @math{0} if no failure occurred in @code{nftw} and
760 all callback function call return values are also @math{0}.  For
761 internal errors such as memory problems @math{-1} is returned and
762 @var{errno} is set accordingly.  If the return value of a callback
763 invocation is nonzero this very same value is returned.
764 @end deftypefun
765
766
767 @node Hard Links
768 @section Hard Links
769 @cindex hard link
770 @cindex link, hard
771 @cindex multiple names for one file
772 @cindex file names, multiple
773
774 In POSIX systems, one file can have many names at the same time.  All of
775 the names are equally real, and no one of them is preferred to the
776 others.
777
778 To add a name to a file, use the @code{link} function.  (The new name is
779 also called a @dfn{hard link} to the file.)  Creating a new link to a
780 file does not copy the contents of the file; it simply makes a new name
781 by which the file can be known, in addition to the file's existing name
782 or names.
783
784 One file can have names in several directories, so the the organization
785 of the file system is not a strict hierarchy or tree.
786
787 In most implementations, it is not possible to have hard links to the
788 same file in multiple file systems.  @code{link} reports an error if you
789 try to make a hard link to the file from another file system when this
790 cannot be done.
791
792 The prototype for the @code{link} function is declared in the header
793 file @file{unistd.h}.
794 @pindex unistd.h
795
796 @comment unistd.h
797 @comment POSIX.1
798 @deftypefun int link (const char *@var{oldname}, const char *@var{newname})
799 The @code{link} function makes a new link to the existing file named by
800 @var{oldname}, under the new name @var{newname}.
801
802 This function returns a value of @code{0} if it is successful and
803 @code{-1} on failure.  In addition to the usual file name errors
804 (@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the
805 following @code{errno} error conditions are defined for this function:
806
807 @table @code
808 @item EACCES
809 You are not allowed to write the directory in which the new link is to
810 be written.
811 @ignore
812 Some implementations also require that the existing file be accessible
813 by the caller, and use this error to report failure for that reason.
814 @end ignore
815
816 @item EEXIST
817 There is already a file named @var{newname}.  If you want to replace
818 this link with a new link, you must remove the old link explicitly first.
819
820 @item EMLINK
821 There are already too many links to the file named by @var{oldname}.
822 (The maximum number of links to a file is @w{@code{LINK_MAX}}; see
823 @ref{Limits for Files}.)
824
825 @item ENOENT
826 The file named by @var{oldname} doesn't exist.  You can't make a link to
827 a file that doesn't exist.
828
829 @item ENOSPC
830 The directory or file system that would contain the new link is full
831 and cannot be extended.
832
833 @item EPERM
834 In the GNU system and some others, you cannot make links to directories.
835 Many systems allow only privileged users to do so.  This error
836 is used to report the problem.
837
838 @item EROFS
839 The directory containing the new link can't be modified because it's on
840 a read-only file system.
841
842 @item EXDEV
843 The directory specified in @var{newname} is on a different file system
844 than the existing file.
845
846 @item EIO
847 A hardware error occurred while trying to read or write the to filesystem.
848 @end table
849 @end deftypefun
850
851 @node Symbolic Links
852 @section Symbolic Links
853 @cindex soft link
854 @cindex link, soft
855 @cindex symbolic link
856 @cindex link, symbolic
857
858 The GNU system supports @dfn{soft links} or @dfn{symbolic links}.  This
859 is a kind of ``file'' that is essentially a pointer to another file
860 name.  Unlike hard links, symbolic links can be made to directories or
861 across file systems with no restrictions.  You can also make a symbolic
862 link to a name which is not the name of any file.  (Opening this link
863 will fail until a file by that name is created.)  Likewise, if the
864 symbolic link points to an existing file which is later deleted, the
865 symbolic link continues to point to the same file name even though the
866 name no longer names any file.
867
868 The reason symbolic links work the way they do is that special things
869 happen when you try to open the link.  The @code{open} function realizes
870 you have specified the name of a link, reads the file name contained in
871 the link, and opens that file name instead.  The @code{stat} function
872 likewise operates on the file that the symbolic link points to, instead
873 of on the link itself.
874
875 By contrast, other operations such as deleting or renaming the file
876 operate on the link itself.  The functions @code{readlink} and
877 @code{lstat} also refrain from following symbolic links, because their
878 purpose is to obtain information about the link.  So does @code{link},
879 the function that makes a hard link---it makes a hard link to the
880 symbolic link, which one rarely wants.
881
882 Prototypes for the functions listed in this section are in
883 @file{unistd.h}.
884 @pindex unistd.h
885
886 @comment unistd.h
887 @comment BSD
888 @deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
889 The @code{symlink} function makes a symbolic link to @var{oldname} named
890 @var{newname}.
891
892 The normal return value from @code{symlink} is @code{0}.  A return value
893 of @code{-1} indicates an error.  In addition to the usual file name
894 syntax errors (@pxref{File Name Errors}), the following @code{errno}
895 error conditions are defined for this function:
896
897 @table @code
898 @item EEXIST
899 There is already an existing file named @var{newname}.
900
901 @item EROFS
902 The file @var{newname} would exist on a read-only file system.
903
904 @item ENOSPC
905 The directory or file system cannot be extended to make the new link.
906
907 @item EIO
908 A hardware error occurred while reading or writing data on the disk.
909
910 @ignore
911 @comment not sure about these
912 @item ELOOP
913 There are too many levels of indirection.  This can be the result of
914 circular symbolic links to directories.
915
916 @item EDQUOT
917 The new link can't be created because the user's disk quota has been
918 exceeded.
919 @end ignore
920 @end table
921 @end deftypefun
922
923 @comment unistd.h
924 @comment BSD
925 @deftypefun int readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size})
926 The @code{readlink} function gets the value of the symbolic link
927 @var{filename}.  The file name that the link points to is copied into
928 @var{buffer}.  This file name string is @emph{not} null-terminated;
929 @code{readlink} normally returns the number of characters copied.  The
930 @var{size} argument specifies the maximum number of characters to copy,
931 usually the allocation size of @var{buffer}.
932
933 If the return value equals @var{size}, you cannot tell whether or not
934 there was room to return the entire name.  So make a bigger buffer and
935 call @code{readlink} again.  Here is an example:
936
937 @smallexample
938 char *
939 readlink_malloc (char *filename)
940 @{
941   int size = 100;
942
943   while (1)
944     @{
945       char *buffer = (char *) xmalloc (size);
946       int nchars = readlink (filename, buffer, size);
947       if (nchars < size)
948         return buffer;
949       free (buffer);
950       size *= 2;
951     @}
952 @}
953 @end smallexample
954
955 @c @group  Invalid outside example.
956 A value of @code{-1} is returned in case of error.  In addition to the
957 usual file name errors (@pxref{File Name Errors}), the following
958 @code{errno} error conditions are defined for this function:
959
960 @table @code
961 @item EINVAL
962 The named file is not a symbolic link.
963
964 @item EIO
965 A hardware error occurred while reading or writing data on the disk.
966 @end table
967 @c @end group
968 @end deftypefun
969
970 @node Deleting Files
971 @section Deleting Files
972 @cindex deleting a file
973 @cindex removing a file
974 @cindex unlinking a file
975
976 You can delete a file with the functions @code{unlink} or @code{remove}.
977
978 Deletion actually deletes a file name.  If this is the file's only name,
979 then the file is deleted as well.  If the file has other names as well
980 (@pxref{Hard Links}), it remains accessible under its other names.
981
982 @comment unistd.h
983 @comment POSIX.1
984 @deftypefun int unlink (const char *@var{filename})
985 The @code{unlink} function deletes the file name @var{filename}.  If
986 this is a file's sole name, the file itself is also deleted.  (Actually,
987 if any process has the file open when this happens, deletion is
988 postponed until all processes have closed the file.)
989
990 @pindex unistd.h
991 The function @code{unlink} is declared in the header file @file{unistd.h}.
992
993 This function returns @code{0} on successful completion, and @code{-1}
994 on error.  In addition to the usual file name errors
995 (@pxref{File Name Errors}), the following @code{errno} error conditions are
996 defined for this function:
997
998 @table @code
999 @item EACCES
1000 Write permission is denied for the directory from which the file is to be
1001 removed, or the directory has the sticky bit set and you do not own the file.
1002
1003 @item EBUSY
1004 This error indicates that the file is being used by the system in such a
1005 way that it can't be unlinked.  For example, you might see this error if
1006 the file name specifies the root directory or a mount point for a file
1007 system.
1008
1009 @item ENOENT
1010 The file name to be deleted doesn't exist.
1011
1012 @item EPERM
1013 On some systems, @code{unlink} cannot be used to delete the name of a
1014 directory, or can only be used this way by a privileged user.
1015 To avoid such problems, use @code{rmdir} to delete directories.
1016 (In the GNU system @code{unlink} can never delete the name of a directory.)
1017
1018 @item EROFS
1019 The directory in which the file name is to be deleted is on a read-only
1020 file system, and can't be modified.
1021 @end table
1022 @end deftypefun
1023
1024 @comment unistd.h
1025 @comment POSIX.1
1026 @deftypefun int rmdir (const char *@var{filename})
1027 @cindex directories, deleting
1028 @cindex deleting a directory
1029 The @code{rmdir} function deletes a directory.  The directory must be
1030 empty before it can be removed; in other words, it can only contain
1031 entries for @file{.} and @file{..}.
1032
1033 In most other respects, @code{rmdir} behaves like @code{unlink}.  There
1034 are two additional @code{errno} error conditions defined for
1035 @code{rmdir}:
1036
1037 @table @code
1038 @item ENOTEMPTY
1039 @itemx EEXIST
1040 The directory to be deleted is not empty.
1041 @end table
1042
1043 These two error codes are synonymous; some systems use one, and some use
1044 the other.  The GNU system always uses @code{ENOTEMPTY}.
1045
1046 The prototype for this function is declared in the header file
1047 @file{unistd.h}.
1048 @pindex unistd.h
1049 @end deftypefun
1050
1051 @comment stdio.h
1052 @comment ISO
1053 @deftypefun int remove (const char *@var{filename})
1054 This is the @w{ISO C} function to remove a file.  It works like
1055 @code{unlink} for files and like @code{rmdir} for directories.
1056 @code{remove} is declared in @file{stdio.h}.
1057 @pindex stdio.h
1058 @end deftypefun
1059
1060 @node Renaming Files
1061 @section Renaming Files
1062
1063 The @code{rename} function is used to change a file's name.
1064
1065 @cindex renaming a file
1066 @comment stdio.h
1067 @comment ISO
1068 @deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
1069 The @code{rename} function renames the file name @var{oldname} with
1070 @var{newname}.  The file formerly accessible under the name
1071 @var{oldname} is afterward accessible as @var{newname} instead.  (If the
1072 file had any other names aside from @var{oldname}, it continues to have
1073 those names.)
1074
1075 The directory containing the name @var{newname} must be on the same
1076 file system as the file (as indicated by the name @var{oldname}).
1077
1078 One special case for @code{rename} is when @var{oldname} and
1079 @var{newname} are two names for the same file.  The consistent way to
1080 handle this case is to delete @var{oldname}.  However, POSIX requires
1081 that in this case @code{rename} do nothing and report success---which is
1082 inconsistent.  We don't know what your operating system will do.
1083
1084 If the @var{oldname} is not a directory, then any existing file named
1085 @var{newname} is removed during the renaming operation.  However, if
1086 @var{newname} is the name of a directory, @code{rename} fails in this
1087 case.
1088
1089 If the @var{oldname} is a directory, then either @var{newname} must not
1090 exist or it must name a directory that is empty.  In the latter case,
1091 the existing directory named @var{newname} is deleted first.  The name
1092 @var{newname} must not specify a subdirectory of the directory
1093 @code{oldname} which is being renamed.
1094
1095 One useful feature of @code{rename} is that the meaning of the name
1096 @var{newname} changes ``atomically'' from any previously existing file
1097 by that name to its new meaning (the file that was called
1098 @var{oldname}).  There is no instant at which @var{newname} is
1099 nonexistent ``in between'' the old meaning and the new meaning.  If
1100 there is a system crash during the operation, it is possible for both
1101 names to still exist; but @var{newname} will always be intact if it
1102 exists at all.
1103
1104 If @code{rename} fails, it returns @code{-1}.  In addition to the usual
1105 file name errors (@pxref{File Name Errors}), the following
1106 @code{errno} error conditions are defined for this function:
1107
1108 @table @code
1109 @item EACCES
1110 One of the directories containing @var{newname} or @var{oldname}
1111 refuses write permission; or @var{newname} and @var{oldname} are
1112 directories and write permission is refused for one of them.
1113
1114 @item EBUSY
1115 A directory named by @var{oldname} or @var{newname} is being used by
1116 the system in a way that prevents the renaming from working.  This includes
1117 directories that are mount points for filesystems, and directories
1118 that are the current working directories of processes.
1119
1120 @item ENOTEMPTY
1121 @itemx EEXIST
1122 The directory @var{newname} isn't empty.  The GNU system always returns
1123 @code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}.
1124
1125 @item EINVAL
1126 The @var{oldname} is a directory that contains @var{newname}.
1127
1128 @item EISDIR
1129 The @var{newname} names a directory, but the @var{oldname} doesn't.
1130
1131 @item EMLINK
1132 The parent directory of @var{newname} would have too many links.
1133
1134 @item ENOENT
1135 The file named by @var{oldname} doesn't exist.
1136
1137 @item ENOSPC
1138 The directory that would contain @var{newname} has no room for another
1139 entry, and there is no space left in the file system to expand it.
1140
1141 @item EROFS
1142 The operation would involve writing to a directory on a read-only file
1143 system.
1144
1145 @item EXDEV
1146 The two file names @var{newname} and @var{oldnames} are on different
1147 file systems.
1148 @end table
1149 @end deftypefun
1150
1151 @node Creating Directories
1152 @section Creating Directories
1153 @cindex creating a directory
1154 @cindex directories, creating
1155
1156 @pindex mkdir
1157 Directories are created with the @code{mkdir} function.  (There is also
1158 a shell command @code{mkdir} which does the same thing.)
1159 @c !!! umask
1160
1161 @comment sys/stat.h
1162 @comment POSIX.1
1163 @deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode})
1164 The @code{mkdir} function creates a new, empty directory whose name is
1165 @var{filename}.
1166
1167 The argument @var{mode} specifies the file permissions for the new
1168 directory file.  @xref{Permission Bits}, for more information about
1169 this.
1170
1171 A return value of @code{0} indicates successful completion, and
1172 @code{-1} indicates failure.  In addition to the usual file name syntax
1173 errors (@pxref{File Name Errors}), the following @code{errno} error
1174 conditions are defined for this function:
1175
1176 @table @code
1177 @item EACCES
1178 Write permission is denied for the parent directory in which the new
1179 directory is to be added.
1180
1181 @item EEXIST
1182 A file named @var{filename} already exists.
1183
1184 @item EMLINK
1185 The parent directory has too many links.
1186
1187 Well-designed file systems never report this error, because they permit
1188 more links than your disk could possibly hold.  However, you must still
1189 take account of the possibility of this error, as it could result from
1190 network access to a file system on another machine.
1191
1192 @item ENOSPC
1193 The file system doesn't have enough room to create the new directory.
1194
1195 @item EROFS
1196 The parent directory of the directory being created is on a read-only
1197 file system, and cannot be modified.
1198 @end table
1199
1200 To use this function, your program should include the header file
1201 @file{sys/stat.h}.
1202 @pindex sys/stat.h
1203 @end deftypefun
1204
1205 @node File Attributes
1206 @section File Attributes
1207
1208 @pindex ls
1209 When you issue an @samp{ls -l} shell command on a file, it gives you
1210 information about the size of the file, who owns it, when it was last
1211 modified, and the like.  This kind of information is called the
1212 @dfn{file attributes}; it is associated with the file itself and not a
1213 particular one of its names.
1214
1215 This section contains information about how you can inquire about and
1216 modify these attributes of files.
1217
1218 @menu
1219 * Attribute Meanings::          The names of the file attributes,
1220                                  and what their values mean.
1221 * Reading Attributes::          How to read the attributes of a file.
1222 * Testing File Type::           Distinguishing ordinary files,
1223                                  directories, links...
1224 * File Owner::                  How ownership for new files is determined,
1225                                  and how to change it.
1226 * Permission Bits::             How information about a file's access
1227                                  mode is stored.
1228 * Access Permission::           How the system decides who can access a file.
1229 * Setting Permissions::         How permissions for new files are assigned,
1230                                  and how to change them.
1231 * Testing File Access::         How to find out if your process can
1232                                  access a file.
1233 * File Times::                  About the time attributes of a file.
1234 @end menu
1235
1236 @node Attribute Meanings
1237 @subsection What the File Attribute Values Mean
1238 @cindex status of a file
1239 @cindex attributes of a file
1240 @cindex file attributes
1241
1242 When you read the attributes of a file, they come back in a structure
1243 called @code{struct stat}.  This section describes the names of the
1244 attributes, their data types, and what they mean.  For the functions
1245 to read the attributes of a file, see @ref{Reading Attributes}.
1246
1247 The header file @file{sys/stat.h} declares all the symbols defined
1248 in this section.
1249 @pindex sys/stat.h
1250
1251 @comment sys/stat.h
1252 @comment POSIX.1
1253 @deftp {Data Type} {struct stat}
1254 The @code{stat} structure type is used to return information about the
1255 attributes of a file.  It contains at least the following members:
1256
1257 @table @code
1258 @item mode_t st_mode
1259 Specifies the mode of the file.  This includes file type information
1260 (@pxref{Testing File Type}) and the file permission bits
1261 (@pxref{Permission Bits}).
1262
1263 @item ino_t st_ino
1264 The file serial number, which distinguishes this file from all other
1265 files on the same device.
1266
1267 @item dev_t st_dev
1268 Identifies the device containing the file.  The @code{st_ino} and
1269 @code{st_dev}, taken together, uniquely identify the file.  The
1270 @code{st_dev} value is not necessarily consistent across reboots or
1271 system crashes, however.
1272
1273 @item nlink_t st_nlink
1274 The number of hard links to the file.  This count keeps track of how
1275 many directories have entries for this file.  If the count is ever
1276 decremented to zero, then the file itself is discarded as soon as no
1277 process still holds it open.  Symbolic links are not counted in the
1278 total.
1279
1280 @item uid_t st_uid
1281 The user ID of the file's owner.  @xref{File Owner}.
1282
1283 @item gid_t st_gid
1284 The group ID of the file.  @xref{File Owner}.
1285
1286 @item off_t st_size
1287 This specifies the size of a regular file in bytes.  For files that
1288 are really devices and the like, this field isn't usually meaningful.
1289 For symbolic links, this specifies the length of the file name the link
1290 refers to.
1291
1292 @item time_t st_atime
1293 This is the last access time for the file.  @xref{File Times}.
1294
1295 @item unsigned long int st_atime_usec
1296 This is the fractional part of the last access time for the file.
1297 @xref{File Times}.
1298
1299 @item time_t st_mtime
1300 This is the time of the last modification to the contents of the file.
1301 @xref{File Times}.
1302
1303 @item unsigned long int st_mtime_usec
1304 This is the fractional part of the time of last modification to the
1305 contents of the file.  @xref{File Times}.
1306
1307 @item time_t st_ctime
1308 This is the time of the last modification to the attributes of the file.
1309 @xref{File Times}.
1310
1311 @item unsigned long int st_ctime_usec
1312 This is the fractional part of the time of last modification to the
1313 attributes of the file.  @xref{File Times}.
1314
1315 @c !!! st_rdev
1316 @item unsigned int st_blocks
1317 This is the amount of disk space that the file occupies, measured in
1318 units of 512-byte blocks.
1319
1320 The number of disk blocks is not strictly proportional to the size of
1321 the file, for two reasons: the file system may use some blocks for
1322 internal record keeping; and the file may be sparse---it may have
1323 ``holes'' which contain zeros but do not actually take up space on the
1324 disk.
1325
1326 You can tell (approximately) whether a file is sparse by comparing this
1327 value with @code{st_size}, like this:
1328
1329 @smallexample
1330 (st.st_blocks * 512 < st.st_size)
1331 @end smallexample
1332
1333 This test is not perfect because a file that is just slightly sparse
1334 might not be detected as sparse at all.  For practical applications,
1335 this is not a problem.
1336
1337 @item unsigned int st_blksize
1338 The optimal block size for reading of writing this file, in bytes.  You
1339 might use this size for allocating the buffer space for reading of
1340 writing the file.  (This is unrelated to @code{st_blocks}.)
1341 @end table
1342 @end deftp
1343
1344   Some of the file attributes have special data type names which exist
1345 specifically for those attributes.  (They are all aliases for well-known
1346 integer types that you know and love.)  These typedef names are defined
1347 in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
1348 Here is a list of them.
1349
1350 @comment sys/types.h
1351 @comment POSIX.1
1352 @deftp {Data Type} mode_t
1353 This is an integer data type used to represent file modes.  In the
1354 GNU system, this is equivalent to @code{unsigned int}.
1355 @end deftp
1356
1357 @cindex inode number
1358 @comment sys/types.h
1359 @comment POSIX.1
1360 @deftp {Data Type} ino_t
1361 This is an arithmetic data type used to represent file serial numbers.
1362 (In Unix jargon, these are sometimes called @dfn{inode numbers}.)
1363 In the GNU system, this type is equivalent to @code{unsigned long int}.
1364 @end deftp
1365
1366 @comment sys/types.h
1367 @comment POSIX.1
1368 @deftp {Data Type} dev_t
1369 This is an arithmetic data type used to represent file device numbers.
1370 In the GNU system, this is equivalent to @code{int}.
1371 @end deftp
1372
1373 @comment sys/types.h
1374 @comment POSIX.1
1375 @deftp {Data Type} nlink_t
1376 This is an arithmetic data type used to represent file link counts.
1377 In the GNU system, this is equivalent to @code{unsigned short int}.
1378 @end deftp
1379
1380 @node Reading Attributes
1381 @subsection Reading the Attributes of a File
1382
1383 To examine the attributes of files, use the functions @code{stat},
1384 @code{fstat} and @code{lstat}.  They return the attribute information in
1385 a @code{struct stat} object.  All three functions are declared in the
1386 header file @file{sys/stat.h}.
1387
1388 @comment sys/stat.h
1389 @comment POSIX.1
1390 @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf})
1391 The @code{stat} function returns information about the attributes of the
1392 file named by @w{@var{filename}} in the structure pointed at by @var{buf}.
1393
1394 If @var{filename} is the name of a symbolic link, the attributes you get
1395 describe the file that the link points to.  If the link points to a
1396 nonexistent file name, then @code{stat} fails, reporting a nonexistent
1397 file.
1398
1399 The return value is @code{0} if the operation is successful, and @code{-1}
1400 on failure.  In addition to the usual file name errors
1401 (@pxref{File Name Errors}, the following @code{errno} error conditions
1402 are defined for this function:
1403
1404 @table @code
1405 @item ENOENT
1406 The file named by @var{filename} doesn't exist.
1407 @end table
1408 @end deftypefun
1409
1410 @comment sys/stat.h
1411 @comment POSIX.1
1412 @deftypefun int fstat (int @var{filedes}, struct stat *@var{buf})
1413 The @code{fstat} function is like @code{stat}, except that it takes an
1414 open file descriptor as an argument instead of a file name.
1415 @xref{Low-Level I/O}.
1416
1417 Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1}
1418 on failure.  The following @code{errno} error conditions are defined for
1419 @code{fstat}:
1420
1421 @table @code
1422 @item EBADF
1423 The @var{filedes} argument is not a valid file descriptor.
1424 @end table
1425 @end deftypefun
1426
1427 @comment sys/stat.h
1428 @comment BSD
1429 @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
1430 The @code{lstat} function is like @code{stat}, except that it does not
1431 follow symbolic links.  If @var{filename} is the name of a symbolic
1432 link, @code{lstat} returns information about the link itself; otherwise,
1433 @code{lstat} works like @code{stat}.  @xref{Symbolic Links}.
1434 @end deftypefun
1435
1436 @node Testing File Type
1437 @subsection Testing the Type of a File
1438
1439 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1440 attributes, contains two kinds of information: the file type code, and
1441 the access permission bits.  This section discusses only the type code,
1442 which you can use to tell whether the file is a directory, whether it is
1443 a socket, and so on.  For information about the access permission,
1444 @ref{Permission Bits}.
1445
1446 There are two predefined ways you can access the file type portion of
1447 the file mode.  First of all, for each type of file, there is a
1448 @dfn{predicate macro} which examines a file mode value and returns
1449 true or false---is the file of that type, or not.  Secondly, you can
1450 mask out the rest of the file mode to get just a file type code.
1451 You can compare this against various constants for the supported file
1452 types.
1453
1454 All of the symbols listed in this section are defined in the header file
1455 @file{sys/stat.h}.
1456 @pindex sys/stat.h
1457
1458 The following predicate macros test the type of a file, given the value
1459 @var{m} which is the @code{st_mode} field returned by @code{stat} on
1460 that file:
1461
1462 @comment sys/stat.h
1463 @comment POSIX
1464 @deftypefn Macro int S_ISDIR (mode_t @var{m})
1465 This macro returns nonzero if the file is a directory.
1466 @end deftypefn
1467
1468 @comment sys/stat.h
1469 @comment POSIX
1470 @deftypefn Macro int S_ISCHR (mode_t @var{m})
1471 This macro returns nonzero if the file is a character special file (a
1472 device like a terminal).
1473 @end deftypefn
1474
1475 @comment sys/stat.h
1476 @comment POSIX
1477 @deftypefn Macro int S_ISBLK (mode_t @var{m})
1478 This macro returns nonzero if the file is a block special file (a device
1479 like a disk).
1480 @end deftypefn
1481
1482 @comment sys/stat.h
1483 @comment POSIX
1484 @deftypefn Macro int S_ISREG (mode_t @var{m})
1485 This macro returns nonzero if the file is a regular file.
1486 @end deftypefn
1487
1488 @comment sys/stat.h
1489 @comment POSIX
1490 @deftypefn Macro int S_ISFIFO (mode_t @var{m})
1491 This macro returns nonzero if the file is a FIFO special file, or a
1492 pipe.  @xref{Pipes and FIFOs}.
1493 @end deftypefn
1494
1495 @comment sys/stat.h
1496 @comment GNU
1497 @deftypefn Macro int S_ISLNK (mode_t @var{m})
1498 This macro returns nonzero if the file is a symbolic link.
1499 @xref{Symbolic Links}.
1500 @end deftypefn
1501
1502 @comment sys/stat.h
1503 @comment GNU
1504 @deftypefn Macro int S_ISSOCK (mode_t @var{m})
1505 This macro returns nonzero if the file is a socket.  @xref{Sockets}.
1506 @end deftypefn
1507
1508 An alternate non-POSIX method of testing the file type is supported for
1509 compatibility with BSD.  The mode can be bitwise ANDed with
1510 @code{S_IFMT} to extract the file type code, and compared to the
1511 appropriate type code constant.  For example,
1512
1513 @smallexample
1514 S_ISCHR (@var{mode})
1515 @end smallexample
1516
1517 @noindent
1518 is equivalent to:
1519
1520 @smallexample
1521 ((@var{mode} & S_IFMT) == S_IFCHR)
1522 @end smallexample
1523
1524 @comment sys/stat.h
1525 @comment BSD
1526 @deftypevr Macro int S_IFMT
1527 This is a bit mask used to extract the file type code portion of a mode
1528 value.
1529 @end deftypevr
1530
1531 These are the symbolic names for the different file type codes:
1532
1533 @table @code
1534 @comment sys/stat.h
1535 @comment BSD
1536 @item S_IFDIR
1537 @vindex S_IFDIR
1538 This macro represents the value of the file type code for a directory file.
1539
1540 @comment sys/stat.h
1541 @comment BSD
1542 @item S_IFCHR
1543 @vindex S_IFCHR
1544 This macro represents the value of the file type code for a
1545 character-oriented device file.
1546
1547 @comment sys/stat.h
1548 @comment BSD
1549 @item S_IFBLK
1550 @vindex S_IFBLK
1551 This macro represents the value of the file type code for a block-oriented
1552 device file.
1553
1554 @comment sys/stat.h
1555 @comment BSD
1556 @item S_IFREG
1557 @vindex S_IFREG
1558 This macro represents the value of the file type code for a regular file.
1559
1560 @comment sys/stat.h
1561 @comment BSD
1562 @item S_IFLNK
1563 @vindex S_IFLNK
1564 This macro represents the value of the file type code for a symbolic link.
1565
1566 @comment sys/stat.h
1567 @comment BSD
1568 @item S_IFSOCK
1569 @vindex S_IFSOCK
1570 This macro represents the value of the file type code for a socket.
1571
1572 @comment sys/stat.h
1573 @comment BSD
1574 @item S_IFIFO
1575 @vindex S_IFIFO
1576 This macro represents the value of the file type code for a FIFO or pipe.
1577 @end table
1578
1579 @node File Owner
1580 @subsection File Owner
1581 @cindex file owner
1582 @cindex owner of a file
1583 @cindex group owner of a file
1584
1585 Every file has an @dfn{owner} which is one of the registered user names
1586 defined on the system.  Each file also has a @dfn{group}, which is one
1587 of the defined groups.  The file owner can often be useful for showing
1588 you who edited the file (especially when you edit with GNU Emacs), but
1589 its main purpose is for access control.
1590
1591 The file owner and group play a role in determining access because the
1592 file has one set of access permission bits for the user that is the
1593 owner, another set that apply to users who belong to the file's group,
1594 and a third set of bits that apply to everyone else.  @xref{Access
1595 Permission}, for the details of how access is decided based on this
1596 data.
1597
1598 When a file is created, its owner is set from the effective user ID of
1599 the process that creates it (@pxref{Process Persona}).  The file's group
1600 ID may be set from either effective group ID of the process, or the
1601 group ID of the directory that contains the file, depending on the
1602 system where the file is stored.  When you access a remote file system,
1603 it behaves according to its own rule, not according to the system your
1604 program is running on.  Thus, your program must be prepared to encounter
1605 either kind of behavior, no matter what kind of system you run it on.
1606
1607 @pindex chown
1608 @pindex chgrp
1609 You can change the owner and/or group owner of an existing file using
1610 the @code{chown} function.  This is the primitive for the @code{chown}
1611 and @code{chgrp} shell commands.
1612
1613 @pindex unistd.h
1614 The prototype for this function is declared in @file{unistd.h}.
1615
1616 @comment unistd.h
1617 @comment POSIX.1
1618 @deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group})
1619 The @code{chown} function changes the owner of the file @var{filename} to
1620 @var{owner}, and its group owner to @var{group}.
1621
1622 Changing the owner of the file on certain systems clears the set-user-ID
1623 and set-group-ID bits of the file's permissions.  (This is because those
1624 bits may not be appropriate for the new owner.)  The other file
1625 permission bits are not changed.
1626
1627 The return value is @code{0} on success and @code{-1} on failure.
1628 In addition to the usual file name errors (@pxref{File Name Errors}),
1629 the following @code{errno} error conditions are defined for this function:
1630
1631 @table @code
1632 @item EPERM
1633 This process lacks permission to make the requested change.
1634
1635 Only privileged users or the file's owner can change the file's group.
1636 On most file systems, only privileged users can change the file owner;
1637 some file systems allow you to change the owner if you are currently the
1638 owner.  When you access a remote file system, the behavior you encounter
1639 is determined by the system that actually holds the file, not by the
1640 system your program is running on.
1641
1642 @xref{Options for Files}, for information about the
1643 @code{_POSIX_CHOWN_RESTRICTED} macro.
1644
1645 @item EROFS
1646 The file is on a read-only file system.
1647 @end table
1648 @end deftypefun
1649
1650 @comment unistd.h
1651 @comment BSD
1652 @deftypefun int fchown (int @var{filedes}, int @var{owner}, int @var{group})
1653 This is like @code{chown}, except that it changes the owner of the file
1654 with open file descriptor @var{filedes}.
1655
1656 The return value from @code{fchown} is @code{0} on success and @code{-1}
1657 on failure.  The following @code{errno} error codes are defined for this
1658 function:
1659
1660 @table @code
1661 @item EBADF
1662 The @var{filedes} argument is not a valid file descriptor.
1663
1664 @item EINVAL
1665 The @var{filedes} argument corresponds to a pipe or socket, not an ordinary
1666 file.
1667
1668 @item EPERM
1669 This process lacks permission to make the requested change.  For
1670 details, see @code{chmod}, above.
1671
1672 @item EROFS
1673 The file resides on a read-only file system.
1674 @end table
1675 @end deftypefun
1676
1677 @node Permission Bits
1678 @subsection The Mode Bits for Access Permission
1679
1680 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1681 attributes, contains two kinds of information: the file type code, and
1682 the access permission bits.  This section discusses only the access
1683 permission bits, which control who can read or write the file.
1684 @xref{Testing File Type}, for information about the file type code.
1685
1686 All of the symbols listed in this section are defined in the header file
1687 @file{sys/stat.h}.
1688 @pindex sys/stat.h
1689
1690 @cindex file permission bits
1691 These symbolic constants are defined for the file mode bits that control
1692 access permission for the file:
1693
1694 @table @code
1695 @comment sys/stat.h
1696 @comment POSIX.1
1697 @item S_IRUSR
1698 @vindex S_IRUSR
1699 @comment sys/stat.h
1700 @comment BSD
1701 @itemx S_IREAD
1702 @vindex S_IREAD
1703 Read permission bit for the owner of the file.  On many systems, this
1704 bit is 0400.  @code{S_IREAD} is an obsolete synonym provided for BSD
1705 compatibility.
1706
1707 @comment sys/stat.h
1708 @comment POSIX.1
1709 @item S_IWUSR
1710 @vindex S_IWUSR
1711 @comment sys/stat.h
1712 @comment BSD
1713 @itemx S_IWRITE
1714 @vindex S_IWRITE
1715 Write permission bit for the owner of the file.  Usually 0200.
1716 @w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility.
1717
1718 @comment sys/stat.h
1719 @comment POSIX.1
1720 @item S_IXUSR
1721 @vindex S_IXUSR
1722 @comment sys/stat.h
1723 @comment BSD
1724 @itemx S_IEXEC
1725 @vindex S_IEXEC
1726 Execute (for ordinary files) or search (for directories) permission bit
1727 for the owner of the file.  Usually 0100.  @code{S_IEXEC} is an obsolete
1728 synonym provided for BSD compatibility.
1729
1730 @comment sys/stat.h
1731 @comment POSIX.1
1732 @item S_IRWXU
1733 @vindex S_IRWXU
1734 This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
1735
1736 @comment sys/stat.h
1737 @comment POSIX.1
1738 @item S_IRGRP
1739 @vindex S_IRGRP
1740 Read permission bit for the group owner of the file.  Usually 040.
1741
1742 @comment sys/stat.h
1743 @comment POSIX.1
1744 @item S_IWGRP
1745 @vindex S_IWGRP
1746 Write permission bit for the group owner of the file.  Usually 020.
1747
1748 @comment sys/stat.h
1749 @comment POSIX.1
1750 @item S_IXGRP
1751 @vindex S_IXGRP
1752 Execute or search permission bit for the group owner of the file.
1753 Usually 010.
1754
1755 @comment sys/stat.h
1756 @comment POSIX.1
1757 @item S_IRWXG
1758 @vindex S_IRWXG
1759 This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
1760
1761 @comment sys/stat.h
1762 @comment POSIX.1
1763 @item S_IROTH
1764 @vindex S_IROTH
1765 Read permission bit for other users.  Usually 04.
1766
1767 @comment sys/stat.h
1768 @comment POSIX.1
1769 @item S_IWOTH
1770 @vindex S_IWOTH
1771 Write permission bit for other users.  Usually 02.
1772
1773 @comment sys/stat.h
1774 @comment POSIX.1
1775 @item S_IXOTH
1776 @vindex S_IXOTH
1777 Execute or search permission bit for other users.  Usually 01.
1778
1779 @comment sys/stat.h
1780 @comment POSIX.1
1781 @item S_IRWXO
1782 @vindex S_IRWXO
1783 This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
1784
1785 @comment sys/stat.h
1786 @comment POSIX
1787 @item S_ISUID
1788 @vindex S_ISUID
1789 This is the set-user-ID on execute bit, usually 04000.
1790 @xref{How Change Persona}.
1791
1792 @comment sys/stat.h
1793 @comment POSIX
1794 @item S_ISGID
1795 @vindex S_ISGID
1796 This is the set-group-ID on execute bit, usually 02000.
1797 @xref{How Change Persona}.
1798
1799 @cindex sticky bit
1800 @comment sys/stat.h
1801 @comment BSD
1802 @item S_ISVTX
1803 @vindex S_ISVTX
1804 This is the @dfn{sticky} bit, usually 01000.
1805
1806 On a directory, it gives permission to delete a file in the directory
1807 only if you own that file.  Ordinarily, a user either can delete all the
1808 files in the directory or cannot delete any of them (based on whether
1809 the user has write permission for the directory).  The same restriction
1810 applies---you must both have write permission for the directory and own
1811 the file you want to delete.  The one exception is that the owner of the
1812 directory can delete any file in the directory, no matter who owns it
1813 (provided the owner has given himself write permission for the
1814 directory).  This is commonly used for the @file{/tmp} directory, where
1815 anyone may create files, but not delete files created by other users.
1816
1817 Originally the sticky bit on an executable file modified the swapping
1818 policies of the system.  Normally, when a program terminated, its pages
1819 in core were immediately freed and reused.  If the sticky bit was set on
1820 the executable file, the system kept the pages in core for a while as if
1821 the program were still running.  This was advantageous for a program
1822 likely to be run many times in succession.  This usage is obsolete in
1823 modern systems.  When a program terminates, its pages always remain in
1824 core as long as there is no shortage of memory in the system.  When the
1825 program is next run, its pages will still be in core if no shortage
1826 arose since the last run.
1827
1828 On some modern systems where the sticky bit has no useful meaning for an
1829 executable file, you cannot set the bit at all for a non-directory.
1830 If you try, @code{chmod} fails with @code{EFTYPE};
1831 @pxref{Setting Permissions}.
1832
1833 Some systems (particularly SunOS) have yet another use for the sticky
1834 bit.  If the sticky bit is set on a file that is @emph{not} executable,
1835 it means the opposite: never cache the pages of this file at all.  The
1836 main use of this is for the files on an NFS server machine which are
1837 used as the swap area of diskless client machines.  The idea is that the
1838 pages of the file will be cached in the client's memory, so it is a
1839 waste of the server's memory to cache them a second time.  In this use
1840 the sticky bit also says that the filesystem may fail to record the
1841 file's modification time onto disk reliably (the idea being that no-one
1842 cares for a swap file).
1843
1844 This bit is only available on BSD systems (and those derived from
1845 them).  Therefore one has to use the @code{_BSD_SOURCE} feature select
1846 macro to get the definition (@pxref{Feature Test Macros}).
1847 @end table
1848
1849 The actual bit values of the symbols are listed in the table above
1850 so you can decode file mode values when debugging your programs.
1851 These bit values are correct for most systems, but they are not
1852 guaranteed.
1853
1854 @strong{Warning:} Writing explicit numbers for file permissions is bad
1855 practice.  It is not only non-portable, it also requires everyone who
1856 reads your program to remember what the bits mean.  To make your
1857 program clean, use the symbolic names.
1858
1859 @node Access Permission
1860 @subsection How Your Access to a File is Decided
1861 @cindex permission to access a file
1862 @cindex access permission for a file
1863 @cindex file access permission
1864
1865 Recall that the operating system normally decides access permission for
1866 a file based on the effective user and group IDs of the process, and its
1867 supplementary group IDs, together with the file's owner, group and
1868 permission bits.  These concepts are discussed in detail in
1869 @ref{Process Persona}.
1870
1871 If the effective user ID of the process matches the owner user ID of the
1872 file, then permissions for read, write, and execute/search are
1873 controlled by the corresponding ``user'' (or ``owner'') bits.  Likewise,
1874 if any of the effective group ID or supplementary group IDs of the
1875 process matches the group owner ID of the file, then permissions are
1876 controlled by the ``group'' bits.  Otherwise, permissions are controlled
1877 by the ``other'' bits.
1878
1879 Privileged users, like @samp{root}, can access any file, regardless of
1880 its file permission bits.  As a special case, for a file to be
1881 executable even for a privileged user, at least one of its execute bits
1882 must be set.
1883
1884 @node Setting Permissions
1885 @subsection Assigning File Permissions
1886
1887 @cindex file creation mask
1888 @cindex umask
1889 The primitive functions for creating files (for example, @code{open} or
1890 @code{mkdir}) take a @var{mode} argument, which specifies the file
1891 permissions for the newly created file.  But the specified mode is
1892 modified by the process's @dfn{file creation mask}, or @dfn{umask},
1893 before it is used.
1894
1895 The bits that are set in the file creation mask identify permissions
1896 that are always to be disabled for newly created files.  For example, if
1897 you set all the ``other'' access bits in the mask, then newly created
1898 files are not accessible at all to processes in the ``other''
1899 category, even if the @var{mode} argument specified to the creation
1900 function would permit such access.  In other words, the file creation
1901 mask is the complement of the ordinary access permissions you want to
1902 grant.
1903
1904 Programs that create files typically specify a @var{mode} argument that
1905 includes all the permissions that make sense for the particular file.
1906 For an ordinary file, this is typically read and write permission for
1907 all classes of users.  These permissions are then restricted as
1908 specified by the individual user's own file creation mask.
1909
1910 @findex chmod
1911 To change the permission of an existing file given its name, call
1912 @code{chmod}.  This function ignores the file creation mask; it uses
1913 exactly the specified permission bits.
1914
1915 @pindex umask
1916 In normal use, the file creation mask is initialized in the user's login
1917 shell (using the @code{umask} shell command), and inherited by all
1918 subprocesses.  Application programs normally don't need to worry about
1919 the file creation mask.  It will do automatically what it is supposed to
1920 do.
1921
1922 When your program should create a file and bypass the umask for its
1923 access permissions, the easiest way to do this is to use @code{fchmod}
1924 after opening the file, rather than changing the umask.
1925
1926 In fact, changing the umask is usually done only by shells.  They use
1927 the @code{umask} function.
1928
1929 The functions in this section are declared in @file{sys/stat.h}.
1930 @pindex sys/stat.h
1931
1932 @comment sys/stat.h
1933 @comment POSIX.1
1934 @deftypefun mode_t umask (mode_t @var{mask})
1935 The @code{umask} function sets the file creation mask of the current
1936 process to @var{mask}, and returns the previous value of the file
1937 creation mask.
1938
1939 Here is an example showing how to read the mask with @code{umask}
1940 without changing it permanently:
1941
1942 @smallexample
1943 mode_t
1944 read_umask (void)
1945 @{
1946   mask = umask (0);
1947   umask (mask);
1948 @}
1949 @end smallexample
1950
1951 @noindent
1952 However, it is better to use @code{getumask} if you just want to read
1953 the mask value, because that is reentrant (at least if you use the GNU
1954 operating system).
1955 @end deftypefun
1956
1957 @comment sys/stat.h
1958 @comment GNU
1959 @deftypefun mode_t getumask (void)
1960 Return the current value of the file creation mask for the current
1961 process.  This function is a GNU extension.
1962 @end deftypefun
1963
1964 @comment sys/stat.h
1965 @comment POSIX.1
1966 @deftypefun int chmod (const char *@var{filename}, mode_t @var{mode})
1967 The @code{chmod} function sets the access permission bits for the file
1968 named by @var{filename} to @var{mode}.
1969
1970 If the @var{filename} names a symbolic link, @code{chmod} changes the
1971 permission of the file pointed to by the link, not those of the link
1972 itself.
1973
1974 This function returns @code{0} if successful and @code{-1} if not.  In
1975 addition to the usual file name errors (@pxref{File Name
1976 Errors}), the following @code{errno} error conditions are defined for
1977 this function:
1978
1979 @table @code
1980 @item ENOENT
1981 The named file doesn't exist.
1982
1983 @item EPERM
1984 This process does not have permission to change the access permission of
1985 this file.  Only the file's owner (as judged by the effective user ID of
1986 the process) or a privileged user can change them.
1987
1988 @item EROFS
1989 The file resides on a read-only file system.
1990
1991 @item EFTYPE
1992 @var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set,
1993 and the named file is not a directory.  Some systems do not allow setting the
1994 sticky bit on non-directory files, and some do (and only some of those
1995 assign a useful meaning to the bit for non-directory files).
1996
1997 You only get @code{EFTYPE} on systems where the sticky bit has no useful
1998 meaning for non-directory files, so it is always safe to just clear the
1999 bit in @var{mode} and call @code{chmod} again.  @xref{Permission Bits},
2000 for full details on the sticky bit.
2001 @end table
2002 @end deftypefun
2003
2004 @comment sys/stat.h
2005 @comment BSD
2006 @deftypefun int fchmod (int @var{filedes}, int @var{mode})
2007 This is like @code{chmod}, except that it changes the permissions of
2008 the file currently open via descriptor @var{filedes}.
2009
2010 The return value from @code{fchmod} is @code{0} on success and @code{-1}
2011 on failure.  The following @code{errno} error codes are defined for this
2012 function:
2013
2014 @table @code
2015 @item EBADF
2016 The @var{filedes} argument is not a valid file descriptor.
2017
2018 @item EINVAL
2019 The @var{filedes} argument corresponds to a pipe or socket, or something
2020 else that doesn't really have access permissions.
2021
2022 @item EPERM
2023 This process does not have permission to change the access permission of
2024 this file.  Only the file's owner (as judged by the effective user ID of
2025 the process) or a privileged user can change them.
2026
2027 @item EROFS
2028 The file resides on a read-only file system.
2029 @end table
2030 @end deftypefun
2031
2032 @node Testing File Access
2033 @subsection Testing Permission to Access a File
2034 @cindex testing access permission
2035 @cindex access, testing for
2036 @cindex setuid programs and file access
2037
2038 When a program runs as a privileged user, this permits it to access
2039 files off-limits to ordinary users---for example, to modify
2040 @file{/etc/passwd}.  Programs designed to be run by ordinary users but
2041 access such files use the setuid bit feature so that they always run
2042 with @code{root} as the effective user ID.
2043
2044 Such a program may also access files specified by the user, files which
2045 conceptually are being accessed explicitly by the user.  Since the
2046 program runs as @code{root}, it has permission to access whatever file
2047 the user specifies---but usually the desired behavior is to permit only
2048 those files which the user could ordinarily access.
2049
2050 The program therefore must explicitly check whether @emph{the user}
2051 would have the necessary access to a file, before it reads or writes the
2052 file.
2053
2054 To do this, use the function @code{access}, which checks for access
2055 permission based on the process's @emph{real} user ID rather than the
2056 effective user ID.  (The setuid feature does not alter the real user ID,
2057 so it reflects the user who actually ran the program.)
2058
2059 There is another way you could check this access, which is easy to
2060 describe, but very hard to use.  This is to examine the file mode bits
2061 and mimic the system's own access computation.  This method is
2062 undesirable because many systems have additional access control
2063 features; your program cannot portably mimic them, and you would not
2064 want to try to keep track of the diverse features that different systems
2065 have.  Using @code{access} is simple and automatically does whatever is
2066 appropriate for the system you are using.
2067
2068 @code{access} is @emph{only} only appropriate to use in setuid programs.
2069 A non-setuid program will always use the effective ID rather than the
2070 real ID.
2071
2072 @pindex unistd.h
2073 The symbols in this section are declared in @file{unistd.h}.
2074
2075 @comment unistd.h
2076 @comment POSIX.1
2077 @deftypefun int access (const char *@var{filename}, int @var{how})
2078 The @code{access} function checks to see whether the file named by
2079 @var{filename} can be accessed in the way specified by the @var{how}
2080 argument.  The @var{how} argument either can be the bitwise OR of the
2081 flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test
2082 @code{F_OK}.
2083
2084 This function uses the @emph{real} user and group ID's of the calling
2085 process, rather than the @emph{effective} ID's, to check for access
2086 permission.  As a result, if you use the function from a @code{setuid}
2087 or @code{setgid} program (@pxref{How Change Persona}), it gives
2088 information relative to the user who actually ran the program.
2089
2090 The return value is @code{0} if the access is permitted, and @code{-1}
2091 otherwise.  (In other words, treated as a predicate function,
2092 @code{access} returns true if the requested access is @emph{denied}.)
2093
2094 In addition to the usual file name errors (@pxref{File Name
2095 Errors}), the following @code{errno} error conditions are defined for
2096 this function:
2097
2098 @table @code
2099 @item EACCES
2100 The access specified by @var{how} is denied.
2101
2102 @item ENOENT
2103 The file doesn't exist.
2104
2105 @item EROFS
2106 Write permission was requested for a file on a read-only file system.
2107 @end table
2108 @end deftypefun
2109
2110 These macros are defined in the header file @file{unistd.h} for use
2111 as the @var{how} argument to the @code{access} function.  The values
2112 are integer constants.
2113 @pindex unistd.h
2114
2115 @comment unistd.h
2116 @comment POSIX.1
2117 @deftypevr Macro int R_OK
2118 Argument that means, test for read permission.
2119 @end deftypevr
2120
2121 @comment unistd.h
2122 @comment POSIX.1
2123 @deftypevr Macro int W_OK
2124 Argument that means, test for write permission.
2125 @end deftypevr
2126
2127 @comment unistd.h
2128 @comment POSIX.1
2129 @deftypevr Macro int X_OK
2130 Argument that means, test for execute/search permission.
2131 @end deftypevr
2132
2133 @comment unistd.h
2134 @comment POSIX.1
2135 @deftypevr Macro int F_OK
2136 Argument that means, test for existence of the file.
2137 @end deftypevr
2138
2139 @node File Times
2140 @subsection File Times
2141
2142 @cindex file access time
2143 @cindex file modification time
2144 @cindex file attribute modification time
2145 Each file has three time stamps associated with it:  its access time,
2146 its modification time, and its attribute modification time.  These
2147 correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime}
2148 members of the @code{stat} structure; see @ref{File Attributes}.
2149
2150 All of these times are represented in calendar time format, as
2151 @code{time_t} objects.  This data type is defined in @file{time.h}.
2152 For more information about representation and manipulation of time
2153 values, see @ref{Calendar Time}.
2154 @pindex time.h
2155
2156 Reading from a file updates its access time attribute, and writing
2157 updates its modification time.  When a file is created, all three
2158 time stamps for that file are set to the current time.  In addition, the
2159 attribute change time and modification time fields of the directory that
2160 contains the new entry are updated.
2161
2162 Adding a new name for a file with the @code{link} function updates the
2163 attribute change time field of the file being linked, and both the
2164 attribute change time and modification time fields of the directory
2165 containing the new name.  These same fields are affected if a file name
2166 is deleted with @code{unlink}, @code{remove}, or @code{rmdir}.  Renaming
2167 a file with @code{rename} affects only the attribute change time and
2168 modification time fields of the two parent directories involved, and not
2169 the times for the file being renamed.
2170
2171 Changing attributes of a file (for example, with @code{chmod}) updates
2172 its attribute change time field.
2173
2174 You can also change some of the time stamps of a file explicitly using
2175 the @code{utime} function---all except the attribute change time.  You
2176 need to include the header file @file{utime.h} to use this facility.
2177 @pindex utime.h
2178
2179 @comment time.h
2180 @comment POSIX.1
2181 @deftp {Data Type} {struct utimbuf}
2182 The @code{utimbuf} structure is used with the @code{utime} function to
2183 specify new access and modification times for a file.  It contains the
2184 following members:
2185
2186 @table @code
2187 @item time_t actime
2188 This is the access time for the file.
2189
2190 @item time_t modtime
2191 This is the modification time for the file.
2192 @end table
2193 @end deftp
2194
2195 @comment time.h
2196 @comment POSIX.1
2197 @deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times})
2198 This function is used to modify the file times associated with the file
2199 named @var{filename}.
2200
2201 If @var{times} is a null pointer, then the access and modification times
2202 of the file are set to the current time.  Otherwise, they are set to the
2203 values from the @code{actime} and @code{modtime} members (respectively)
2204 of the @code{utimbuf} structure pointed at by @var{times}.
2205
2206 The attribute modification time for the file is set to the current time
2207 in either case (since changing the time stamps is itself a modification
2208 of the file attributes).
2209
2210 The @code{utime} function returns @code{0} if successful and @code{-1}
2211 on failure.  In addition to the usual file name errors
2212 (@pxref{File Name Errors}), the following @code{errno} error conditions
2213 are defined for this function:
2214
2215 @table @code
2216 @item EACCES
2217 There is a permission problem in the case where a null pointer was
2218 passed as the @var{times} argument.  In order to update the time stamp on
2219 the file, you must either be the owner of the file, have write
2220 permission on the file, or be a privileged user.
2221
2222 @item ENOENT
2223 The file doesn't exist.
2224
2225 @item EPERM
2226 If the @var{times} argument is not a null pointer, you must either be
2227 the owner of the file or be a privileged user.  This error is used to
2228 report the problem.
2229
2230 @item EROFS
2231 The file lives on a read-only file system.
2232 @end table
2233 @end deftypefun
2234
2235 Each of the three time stamps has a corresponding microsecond part,
2236 which extends its resolution.  These fields are called
2237 @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
2238 each has a value between 0 and 999,999, which indicates the time in
2239 microseconds.  They correspond to the @code{tv_usec} field of a
2240 @code{timeval} structure; see @ref{High-Resolution Calendar}.
2241
2242 The @code{utimes} function is like @code{utime}, but also lets you specify
2243 the fractional part of the file times.  The prototype for this function is
2244 in the header file @file{sys/time.h}.
2245 @pindex sys/time.h
2246
2247 @comment sys/time.h
2248 @comment BSD
2249 @deftypefun int utimes (const char *@var{filename}, struct timeval @var{tvp}@t{[2]})
2250 This function sets the file access and modification times for the file
2251 named by @var{filename}.  The new file access time is specified by
2252 @code{@var{tvp}[0]}, and the new modification time by
2253 @code{@var{tvp}[1]}.  This function comes from BSD.
2254
2255 The return values and error conditions are the same as for the @code{utime}
2256 function.
2257 @end deftypefun
2258
2259 @node Making Special Files
2260 @section Making Special Files
2261 @cindex creating special files
2262 @cindex special files
2263
2264 The @code{mknod} function is the primitive for making special files,
2265 such as files that correspond to devices.  The GNU library includes
2266 this function for compatibility with BSD.
2267
2268 The prototype for @code{mknod} is declared in @file{sys/stat.h}.
2269 @pindex sys/stat.h
2270
2271 @comment sys/stat.h
2272 @comment BSD
2273 @deftypefun int mknod (const char *@var{filename}, int @var{mode}, int @var{dev})
2274 The @code{mknod} function makes a special file with name @var{filename}.
2275 The @var{mode} specifies the mode of the file, and may include the various
2276 special file bits, such as @code{S_IFCHR} (for a character special file)
2277 or @code{S_IFBLK} (for a block special file).  @xref{Testing File Type}.
2278
2279 The @var{dev} argument specifies which device the special file refers to.
2280 Its exact interpretation depends on the kind of special file being created.
2281
2282 The return value is @code{0} on success and @code{-1} on error.  In addition
2283 to the usual file name errors (@pxref{File Name Errors}), the
2284 following @code{errno} error conditions are defined for this function:
2285
2286 @table @code
2287 @item EPERM
2288 The calling process is not privileged.  Only the superuser can create
2289 special files.
2290
2291 @item ENOSPC
2292 The directory or file system that would contain the new file is full
2293 and cannot be extended.
2294
2295 @item EROFS
2296 The directory containing the new file can't be modified because it's on
2297 a read-only file system.
2298
2299 @item EEXIST
2300 There is already a file named @var{filename}.  If you want to replace
2301 this file, you must remove the old file explicitly first.
2302 @end table
2303 @end deftypefun
2304
2305 @node Temporary Files
2306 @section Temporary Files
2307
2308 If you need to use a temporary file in your program, you can use the
2309 @code{tmpfile} function to open it.  Or you can use the @code{tmpnam}
2310 (better: @code{tmpnam_r}) function make a name for a temporary file and
2311 then open it in the usual way with @code{fopen}.
2312
2313 The @code{tempnam} function is like @code{tmpnam} but lets you choose
2314 what directory temporary files will go in, and something about what
2315 their file names will look like.  Important for multi threaded programs
2316 is that @code{tempnam} is reentrant while @code{tmpnam} is not since it
2317 returns a pointer to a static buffer.
2318
2319 These facilities are declared in the header file @file{stdio.h}.
2320 @pindex stdio.h
2321
2322 @comment stdio.h
2323 @comment ISO
2324 @deftypefun {FILE *} tmpfile (void)
2325 This function creates a temporary binary file for update mode, as if by
2326 calling @code{fopen} with mode @code{"wb+"}.  The file is deleted
2327 automatically when it is closed or when the program terminates.  (On
2328 some other @w{ISO C} systems the file may fail to be deleted if the program
2329 terminates abnormally).
2330
2331 This function is reentrant.
2332 @end deftypefun
2333
2334 @comment stdio.h
2335 @comment ISO
2336 @deftypefun {char *} tmpnam (char *@var{result})
2337 This function constructs and returns a file name that is a valid file
2338 name and that does not name any existing file.  If the @var{result}
2339 argument is a null pointer, the return value is a pointer to an internal
2340 static string, which might be modified by subsequent calls and therefore
2341 makes this function non-reentrant.  Otherwise, the @var{result} argument
2342 should be a pointer to an array of at least @code{L_tmpnam} characters,
2343 and the result is written into that array.
2344
2345 It is possible for @code{tmpnam} to fail if you call it too many times
2346 without removing previously created files.  This is because the fixed
2347 length of a temporary file name gives room for only a finite number of
2348 different names.  If @code{tmpnam} fails, it returns a null pointer.
2349 @end deftypefun
2350
2351 @comment stdio.h
2352 @comment GNU
2353 @deftypefun {char *} tmpnam_r (char *@var{result})
2354 This function is nearly identical to the @code{tmpnam} function.  But it
2355 does not allow @var{result} to be a null pointer.  In the later case a
2356 null pointer is returned.
2357
2358 This function is reentrant because the non-reentrant situation of
2359 @code{tmpnam} cannot happen here.
2360 @end deftypefun
2361
2362 @comment stdio.h
2363 @comment ISO
2364 @deftypevr Macro int L_tmpnam
2365 The value of this macro is an integer constant expression that represents
2366 the minimum allocation size of a string large enough to hold the
2367 file name generated by the @code{tmpnam} function.
2368 @end deftypevr
2369
2370 @comment stdio.h
2371 @comment ISO
2372 @deftypevr Macro int TMP_MAX
2373 The macro @code{TMP_MAX} is a lower bound for how many temporary names
2374 you can create with @code{tmpnam}.  You can rely on being able to call
2375 @code{tmpnam} at least this many times before it might fail saying you
2376 have made too many temporary file names.
2377
2378 With the GNU library, you can create a very large number of temporary
2379 file names---if you actually create the files, you will probably run out
2380 of disk space before you run out of names.  Some other systems have a
2381 fixed, small limit on the number of temporary files.  The limit is never
2382 less than @code{25}.
2383 @end deftypevr
2384
2385 @comment stdio.h
2386 @comment SVID
2387 @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
2388 This function generates a unique temporary filename.  If @var{prefix} is
2389 not a null pointer, up to five characters of this string are used as a
2390 prefix for the file name.  The return value is a string newly allocated
2391 with @code{malloc}; you should release its storage with @code{free} when
2392 it is no longer needed.
2393
2394 Because the string is dynamically allocated this function is reentrant.
2395
2396 The directory prefix for the temporary file name is determined by testing
2397 each of the following, in sequence.  The directory must exist and be
2398 writable.
2399
2400 @itemize @bullet
2401 @item
2402 The environment variable @code{TMPDIR}, if it is defined.  For security
2403 reasons this only happens if the program is not SUID or SGID enabled.
2404
2405 @item
2406 The @var{dir} argument, if it is not a null pointer.
2407
2408 @item
2409 The value of the @code{P_tmpdir} macro.
2410
2411 @item
2412 The directory @file{/tmp}.
2413 @end itemize
2414
2415 This function is defined for SVID compatibility.
2416 @end deftypefun
2417 @cindex TMPDIR environment variable
2418
2419 @comment stdio.h
2420 @comment SVID
2421 @c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
2422 @deftypevr {SVID Macro} {char *} P_tmpdir
2423 This macro is the name of the default directory for temporary files.
2424 @end deftypevr
2425
2426 Older Unix systems did not have the functions just described.  Instead
2427 they used @code{mktemp} and @code{mkstemp}.  Both of these functions
2428 work by modifying a file name template string you pass.  The last six
2429 characters of this string must be @samp{XXXXXX}.  These six @samp{X}s
2430 are replaced with six characters which make the whole string a unique
2431 file name.  Usually the template string is something like
2432 @samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}.
2433
2434 @strong{Note:} Because @code{mktemp} and @code{mkstemp} modify the
2435 template string, you @emph{must not} pass string constants to them.
2436 String constants are normally in read-only storage, so your program
2437 would crash when @code{mktemp} or @code{mkstemp} tried to modify the
2438 string.
2439
2440 @comment unistd.h
2441 @comment Unix
2442 @deftypefun {char *} mktemp (char *@var{template})
2443 The @code{mktemp} function generates a unique file name by modifying
2444 @var{template} as described above.  If successful, it returns
2445 @var{template} as modified.  If @code{mktemp} cannot find a unique file
2446 name, it makes @var{template} an empty string and returns that.  If
2447 @var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a
2448 null pointer.
2449 @end deftypefun
2450
2451 @comment unistd.h
2452 @comment BSD
2453 @deftypefun int mkstemp (char *@var{template})
2454 The @code{mkstemp} function generates a unique file name just as
2455 @code{mktemp} does, but it also opens the file for you with @code{open}
2456 (@pxref{Opening and Closing Files}).  If successful, it modifies
2457 @var{template} in place and returns a file descriptor open on that file
2458 for reading and writing.  If @code{mkstemp} cannot create a
2459 uniquely-named file, it makes @var{template} an empty string and returns
2460 @code{-1}.  If @var{template} does not end with @samp{XXXXXX},
2461 @code{mkstemp} returns @code{-1} and does not modify @var{template}.
2462
2463 The file is opened using mode @code{0600}.  If the file is meant to be
2464 used by other users the mode must explicitly changed.
2465 @end deftypefun
2466
2467 Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a
2468 unique file that cannot possibly clash with any other program trying to
2469 create a temporary file.  This is because it works by calling
2470 @code{open} with the @code{O_EXCL} flag bit, which says you want to
2471 always create a new file, and get an error if the file already exists.