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