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