(Temporary Files): mktemp and mkstemp are
[kopensolaris-gnu/glibc.git] / manual / filesys.texi
1 @node File System Interface, Pipes and FIFOs, Low-Level I/O, Top
2 @c %MENU% Functions for manipulating files
3 @chapter File System Interface
4
5 This chapter describes the GNU C library's functions for manipulating
6 files.  Unlike the input and output functions (@pxref{I/O on Streams};
7 @pxref{Low-Level I/O}), these functions are concerned with operating
8 on the files themselves, rather 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 * File Size::                   Manually changing the size of a file.
1311 @end menu
1312
1313 @node Attribute Meanings
1314 @subsection What the File Attribute Values Mean
1315 @cindex status of a file
1316 @cindex attributes of a file
1317 @cindex file attributes
1318
1319 When you read the attributes of a file, they come back in a structure
1320 called @code{struct stat}.  This section describes the names of the
1321 attributes, their data types, and what they mean.  For the functions
1322 to read the attributes of a file, see @ref{Reading Attributes}.
1323
1324 The header file @file{sys/stat.h} declares all the symbols defined
1325 in this section.
1326 @pindex sys/stat.h
1327
1328 @comment sys/stat.h
1329 @comment POSIX.1
1330 @deftp {Data Type} {struct stat}
1331 The @code{stat} structure type is used to return information about the
1332 attributes of a file.  It contains at least the following members:
1333
1334 @table @code
1335 @item mode_t st_mode
1336 Specifies the mode of the file.  This includes file type information
1337 (@pxref{Testing File Type}) and the file permission bits
1338 (@pxref{Permission Bits}).
1339
1340 @item ino_t st_ino
1341 The file serial number, which distinguishes this file from all other
1342 files on the same device.
1343
1344 @item dev_t st_dev
1345 Identifies the device containing the file.  The @code{st_ino} and
1346 @code{st_dev}, taken together, uniquely identify the file.  The
1347 @code{st_dev} value is not necessarily consistent across reboots or
1348 system crashes, however.
1349
1350 @item nlink_t st_nlink
1351 The number of hard links to the file.  This count keeps track of how
1352 many directories have entries for this file.  If the count is ever
1353 decremented to zero, then the file itself is discarded as soon as no
1354 process still holds it open.  Symbolic links are not counted in the
1355 total.
1356
1357 @item uid_t st_uid
1358 The user ID of the file's owner.  @xref{File Owner}.
1359
1360 @item gid_t st_gid
1361 The group ID of the file.  @xref{File Owner}.
1362
1363 @item off_t st_size
1364 This specifies the size of a regular file in bytes.  For files that
1365 are really devices and the like, this field isn't usually meaningful.
1366 For symbolic links, this specifies the length of the file name the link
1367 refers to.
1368
1369 @item time_t st_atime
1370 This is the last access time for the file.  @xref{File Times}.
1371
1372 @item unsigned long int st_atime_usec
1373 This is the fractional part of the last access time for the file.
1374 @xref{File Times}.
1375
1376 @item time_t st_mtime
1377 This is the time of the last modification to the contents of the file.
1378 @xref{File Times}.
1379
1380 @item unsigned long int st_mtime_usec
1381 This is the fractional part of the time of last modification to the
1382 contents of the file.  @xref{File Times}.
1383
1384 @item time_t st_ctime
1385 This is the time of the last modification to the attributes of the file.
1386 @xref{File Times}.
1387
1388 @item unsigned long int st_ctime_usec
1389 This is the fractional part of the time of last modification to the
1390 attributes of the file.  @xref{File Times}.
1391
1392 @c !!! st_rdev
1393 @item blkcnt_t st_blocks
1394 This is the amount of disk space that the file occupies, measured in
1395 units of 512-byte blocks.
1396
1397 The number of disk blocks is not strictly proportional to the size of
1398 the file, for two reasons: the file system may use some blocks for
1399 internal record keeping; and the file may be sparse---it may have
1400 ``holes'' which contain zeros but do not actually take up space on the
1401 disk.
1402
1403 You can tell (approximately) whether a file is sparse by comparing this
1404 value with @code{st_size}, like this:
1405
1406 @smallexample
1407 (st.st_blocks * 512 < st.st_size)
1408 @end smallexample
1409
1410 This test is not perfect because a file that is just slightly sparse
1411 might not be detected as sparse at all.  For practical applications,
1412 this is not a problem.
1413
1414 @item unsigned int st_blksize
1415 The optimal block size for reading of writing this file, in bytes.  You
1416 might use this size for allocating the buffer space for reading of
1417 writing the file.  (This is unrelated to @code{st_blocks}.)
1418 @end table
1419 @end deftp
1420
1421   Some of the file attributes have special data type names which exist
1422 specifically for those attributes.  (They are all aliases for well-known
1423 integer types that you know and love.)  These typedef names are defined
1424 in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
1425 Here is a list of them.
1426
1427 The extensions for the Large File Support (LFS) require even on 32 bits
1428 machine types which can handle file sizes up to @math{2^63}.  Therefore
1429 a new definition of @code{struct stat} is necessary.
1430
1431 @comment sys/stat.h
1432 @comment LFS
1433 @deftp {Data Type} {struct stat64}
1434 The members of this type are the same and have the same names as those
1435 in @code{struct stat}.  The only difference is that the members
1436 @code{st_ino}, @code{st_size}, and @code{st_blocks} have a different
1437 type to support larger values.
1438
1439 @table @code
1440 @item mode_t st_mode
1441 Specifies the mode of the file.  This includes file type information
1442 (@pxref{Testing File Type}) and the file permission bits
1443 (@pxref{Permission Bits}).
1444
1445 @item ino64_t st_ino
1446 The file serial number, which distinguishes this file from all other
1447 files on the same device.
1448
1449 @item dev_t st_dev
1450 Identifies the device containing the file.  The @code{st_ino} and
1451 @code{st_dev}, taken together, uniquely identify the file.  The
1452 @code{st_dev} value is not necessarily consistent across reboots or
1453 system crashes, however.
1454
1455 @item nlink_t st_nlink
1456 The number of hard links to the file.  This count keeps track of how
1457 many directories have entries for this file.  If the count is ever
1458 decremented to zero, then the file itself is discarded as soon as no
1459 process still holds it open.  Symbolic links are not counted in the
1460 total.
1461
1462 @item uid_t st_uid
1463 The user ID of the file's owner.  @xref{File Owner}.
1464
1465 @item gid_t st_gid
1466 The group ID of the file.  @xref{File Owner}.
1467
1468 @item off64_t st_size
1469 This specifies the size of a regular file in bytes.  For files that
1470 are really devices and the like, this field isn't usually meaningful.
1471 For symbolic links, this specifies the length of the file name the link
1472 refers to.
1473
1474 @item time_t st_atime
1475 This is the last access time for the file.  @xref{File Times}.
1476
1477 @item unsigned long int st_atime_usec
1478 This is the fractional part of the last access time for the file.
1479 @xref{File Times}.
1480
1481 @item time_t st_mtime
1482 This is the time of the last modification to the contents of the file.
1483 @xref{File Times}.
1484
1485 @item unsigned long int st_mtime_usec
1486 This is the fractional part of the time of last modification to the
1487 contents of the file.  @xref{File Times}.
1488
1489 @item time_t st_ctime
1490 This is the time of the last modification to the attributes of the file.
1491 @xref{File Times}.
1492
1493 @item unsigned long int st_ctime_usec
1494 This is the fractional part of the time of last modification to the
1495 attributes of the file.  @xref{File Times}.
1496
1497 @c !!! st_rdev
1498 @item blkcnt64_t st_blocks
1499 This is the amount of disk space that the file occupies, measured in
1500 units of 512-byte blocks.
1501
1502 @item unsigned int st_blksize
1503 The optimal block size for reading of writing this file, in bytes.  You
1504 might use this size for allocating the buffer space for reading of
1505 writing the file.  (This is unrelated to @code{st_blocks}.)
1506 @end table
1507 @end deftp
1508
1509 @comment sys/types.h
1510 @comment POSIX.1
1511 @deftp {Data Type} mode_t
1512 This is an integer data type used to represent file modes.  In the
1513 GNU system, this is equivalent to @code{unsigned int}.
1514 @end deftp
1515
1516 @cindex inode number
1517 @comment sys/types.h
1518 @comment POSIX.1
1519 @deftp {Data Type} ino_t
1520 This is an arithmetic data type used to represent file serial numbers.
1521 (In Unix jargon, these are sometimes called @dfn{inode numbers}.)
1522 In the GNU system, this type is equivalent to @code{unsigned long int}.
1523
1524 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
1525 is transparently replaced by @code{ino64_t}.
1526 @end deftp
1527
1528 @comment sys/types.h
1529 @comment Unix98
1530 @deftp {Data Type} ino64_t
1531 This is an arithmetic data type used to represent file serial numbers
1532 for the use in LFS.  In the GNU system, this type is equivalent to
1533 @code{unsigned long longint}.
1534
1535 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
1536 available under the name @code{ino_t}.
1537 @end deftp
1538
1539 @comment sys/types.h
1540 @comment POSIX.1
1541 @deftp {Data Type} dev_t
1542 This is an arithmetic data type used to represent file device numbers.
1543 In the GNU system, this is equivalent to @code{int}.
1544 @end deftp
1545
1546 @comment sys/types.h
1547 @comment POSIX.1
1548 @deftp {Data Type} nlink_t
1549 This is an arithmetic data type used to represent file link counts.
1550 In the GNU system, this is equivalent to @code{unsigned short int}.
1551 @end deftp
1552
1553 @comment sys/types.h
1554 @comment Unix98
1555 @deftp {Data Type} blkcnt_t
1556 This is an arithmetic data type used to represent block counts.
1557 In the GNU system, this is equivalent to @code{unsigned long int}.
1558
1559 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
1560 is transparently replaced by @code{blkcnt64_t}.
1561 @end deftp
1562
1563 @comment sys/types.h
1564 @comment Unix98
1565 @deftp {Data Type} blkcnt64_t
1566 This is an arithmetic data type used to represent block counts for the
1567 use in LFS.  In the GNU system, this is equivalent to @code{unsigned
1568 long long int}.
1569
1570 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
1571 available under the name @code{blkcnt_t}.
1572 @end deftp
1573
1574 @node Reading Attributes
1575 @subsection Reading the Attributes of a File
1576
1577 To examine the attributes of files, use the functions @code{stat},
1578 @code{fstat} and @code{lstat}.  They return the attribute information in
1579 a @code{struct stat} object.  All three functions are declared in the
1580 header file @file{sys/stat.h}.
1581
1582 @comment sys/stat.h
1583 @comment POSIX.1
1584 @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf})
1585 The @code{stat} function returns information about the attributes of the
1586 file named by @w{@var{filename}} in the structure pointed at by @var{buf}.
1587
1588 If @var{filename} is the name of a symbolic link, the attributes you get
1589 describe the file that the link points to.  If the link points to a
1590 nonexistent file name, then @code{stat} fails, reporting a nonexistent
1591 file.
1592
1593 The return value is @code{0} if the operation is successful, and @code{-1}
1594 on failure.  In addition to the usual file name errors
1595 (@pxref{File Name Errors}, the following @code{errno} error conditions
1596 are defined for this function:
1597
1598 @table @code
1599 @item ENOENT
1600 The file named by @var{filename} doesn't exist.
1601 @end table
1602
1603 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1604 function is in fact @code{stat64} since the LFS interface transparently
1605 replaces the normal implementation.
1606 @end deftypefun
1607
1608 @comment sys/stat.h
1609 @comment Unix98
1610 @deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf})
1611 This function is similar to @code{stat} but it is also able to work on
1612 file larger then @math{2^31} bytes on 32 bits systems.  To be able to do
1613 this the result is stored in a variable of type @code{struct stat64} to
1614 which @var{buf} must point.
1615
1616 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1617 function is available under the name @code{stat} and so transparently
1618 replaces the interface for small fiels on 32 bits machines.
1619 @end deftypefun
1620
1621 @comment sys/stat.h
1622 @comment POSIX.1
1623 @deftypefun int fstat (int @var{filedes}, struct stat *@var{buf})
1624 The @code{fstat} function is like @code{stat}, except that it takes an
1625 open file descriptor as an argument instead of a file name.
1626 @xref{Low-Level I/O}.
1627
1628 Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1}
1629 on failure.  The following @code{errno} error conditions are defined for
1630 @code{fstat}:
1631
1632 @table @code
1633 @item EBADF
1634 The @var{filedes} argument is not a valid file descriptor.
1635 @end table
1636
1637 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1638 function is in fact @code{fstat64} since the LFS interface transparently
1639 replaces the normal implementation.
1640 @end deftypefun
1641
1642 @comment sys/stat.h
1643 @comment Unix98
1644 @deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf})
1645 This function is similar to @code{fstat} but it is prepared to work on
1646 large files on 32 bits platforms.  For large files the file descriptor
1647 @var{filedes} should be returned by @code{open64} or @code{creat64}.
1648 The @var{buf} pointer points to a variable of type @code{struct stat64}
1649 which is able to represent the larger values.
1650
1651 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1652 function is available under the name @code{fstat} and so transparently
1653 replaces the interface for small fiels on 32 bits machines.
1654 @end deftypefun
1655
1656 @comment sys/stat.h
1657 @comment BSD
1658 @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
1659 The @code{lstat} function is like @code{stat}, except that it does not
1660 follow symbolic links.  If @var{filename} is the name of a symbolic
1661 link, @code{lstat} returns information about the link itself; otherwise,
1662 @code{lstat} works like @code{stat}.  @xref{Symbolic Links}.
1663
1664 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1665 function is in fact @code{lstat64} since the LFS interface transparently
1666 replaces the normal implementation.
1667 @end deftypefun
1668
1669 @comment sys/stat.h
1670 @comment Unix98
1671 @deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf})
1672 This function is similar to @code{lstat} but it is also able to work on
1673 file larger then @math{2^31} bytes on 32 bits systems.  To be able to do
1674 this the result is stored in a variable of type @code{struct stat64} to
1675 which @var{buf} must point.
1676
1677 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1678 function is available under the name @code{lstat} and so transparently
1679 replaces the interface for small fiels on 32 bits machines.
1680 @end deftypefun
1681
1682 @node Testing File Type
1683 @subsection Testing the Type of a File
1684
1685 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1686 attributes, contains two kinds of information: the file type code, and
1687 the access permission bits.  This section discusses only the type code,
1688 which you can use to tell whether the file is a directory, whether it is
1689 a socket, and so on.  For information about the access permission,
1690 @ref{Permission Bits}.
1691
1692 There are two predefined ways you can access the file type portion of
1693 the file mode.  First of all, for each type of file, there is a
1694 @dfn{predicate macro} which examines a file mode value and returns
1695 true or false---is the file of that type, or not.  Secondly, you can
1696 mask out the rest of the file mode to get just a file type code.
1697 You can compare this against various constants for the supported file
1698 types.
1699
1700 All of the symbols listed in this section are defined in the header file
1701 @file{sys/stat.h}.
1702 @pindex sys/stat.h
1703
1704 The following predicate macros test the type of a file, given the value
1705 @var{m} which is the @code{st_mode} field returned by @code{stat} on
1706 that file:
1707
1708 @comment sys/stat.h
1709 @comment POSIX
1710 @deftypefn Macro int S_ISDIR (mode_t @var{m})
1711 This macro returns nonzero if the file is a directory.
1712 @end deftypefn
1713
1714 @comment sys/stat.h
1715 @comment POSIX
1716 @deftypefn Macro int S_ISCHR (mode_t @var{m})
1717 This macro returns nonzero if the file is a character special file (a
1718 device like a terminal).
1719 @end deftypefn
1720
1721 @comment sys/stat.h
1722 @comment POSIX
1723 @deftypefn Macro int S_ISBLK (mode_t @var{m})
1724 This macro returns nonzero if the file is a block special file (a device
1725 like a disk).
1726 @end deftypefn
1727
1728 @comment sys/stat.h
1729 @comment POSIX
1730 @deftypefn Macro int S_ISREG (mode_t @var{m})
1731 This macro returns nonzero if the file is a regular file.
1732 @end deftypefn
1733
1734 @comment sys/stat.h
1735 @comment POSIX
1736 @deftypefn Macro int S_ISFIFO (mode_t @var{m})
1737 This macro returns nonzero if the file is a FIFO special file, or a
1738 pipe.  @xref{Pipes and FIFOs}.
1739 @end deftypefn
1740
1741 @comment sys/stat.h
1742 @comment GNU
1743 @deftypefn Macro int S_ISLNK (mode_t @var{m})
1744 This macro returns nonzero if the file is a symbolic link.
1745 @xref{Symbolic Links}.
1746 @end deftypefn
1747
1748 @comment sys/stat.h
1749 @comment GNU
1750 @deftypefn Macro int S_ISSOCK (mode_t @var{m})
1751 This macro returns nonzero if the file is a socket.  @xref{Sockets}.
1752 @end deftypefn
1753
1754 An alternate non-POSIX method of testing the file type is supported for
1755 compatibility with BSD.  The mode can be bitwise ANDed with
1756 @code{S_IFMT} to extract the file type code, and compared to the
1757 appropriate type code constant.  For example,
1758
1759 @smallexample
1760 S_ISCHR (@var{mode})
1761 @end smallexample
1762
1763 @noindent
1764 is equivalent to:
1765
1766 @smallexample
1767 ((@var{mode} & S_IFMT) == S_IFCHR)
1768 @end smallexample
1769
1770 @comment sys/stat.h
1771 @comment BSD
1772 @deftypevr Macro int S_IFMT
1773 This is a bit mask used to extract the file type code portion of a mode
1774 value.
1775 @end deftypevr
1776
1777 These are the symbolic names for the different file type codes:
1778
1779 @table @code
1780 @comment sys/stat.h
1781 @comment BSD
1782 @item S_IFDIR
1783 @vindex S_IFDIR
1784 This macro represents the value of the file type code for a directory file.
1785
1786 @comment sys/stat.h
1787 @comment BSD
1788 @item S_IFCHR
1789 @vindex S_IFCHR
1790 This macro represents the value of the file type code for a
1791 character-oriented device file.
1792
1793 @comment sys/stat.h
1794 @comment BSD
1795 @item S_IFBLK
1796 @vindex S_IFBLK
1797 This macro represents the value of the file type code for a block-oriented
1798 device file.
1799
1800 @comment sys/stat.h
1801 @comment BSD
1802 @item S_IFREG
1803 @vindex S_IFREG
1804 This macro represents the value of the file type code for a regular file.
1805
1806 @comment sys/stat.h
1807 @comment BSD
1808 @item S_IFLNK
1809 @vindex S_IFLNK
1810 This macro represents the value of the file type code for a symbolic link.
1811
1812 @comment sys/stat.h
1813 @comment BSD
1814 @item S_IFSOCK
1815 @vindex S_IFSOCK
1816 This macro represents the value of the file type code for a socket.
1817
1818 @comment sys/stat.h
1819 @comment BSD
1820 @item S_IFIFO
1821 @vindex S_IFIFO
1822 This macro represents the value of the file type code for a FIFO or pipe.
1823 @end table
1824
1825 @node File Owner
1826 @subsection File Owner
1827 @cindex file owner
1828 @cindex owner of a file
1829 @cindex group owner of a file
1830
1831 Every file has an @dfn{owner} which is one of the registered user names
1832 defined on the system.  Each file also has a @dfn{group}, which is one
1833 of the defined groups.  The file owner can often be useful for showing
1834 you who edited the file (especially when you edit with GNU Emacs), but
1835 its main purpose is for access control.
1836
1837 The file owner and group play a role in determining access because the
1838 file has one set of access permission bits for the user that is the
1839 owner, another set that apply to users who belong to the file's group,
1840 and a third set of bits that apply to everyone else.  @xref{Access
1841 Permission}, for the details of how access is decided based on this
1842 data.
1843
1844 When a file is created, its owner is set from the effective user ID of
1845 the process that creates it (@pxref{Process Persona}).  The file's group
1846 ID may be set from either effective group ID of the process, or the
1847 group ID of the directory that contains the file, depending on the
1848 system where the file is stored.  When you access a remote file system,
1849 it behaves according to its own rule, not according to the system your
1850 program is running on.  Thus, your program must be prepared to encounter
1851 either kind of behavior, no matter what kind of system you run it on.
1852
1853 @pindex chown
1854 @pindex chgrp
1855 You can change the owner and/or group owner of an existing file using
1856 the @code{chown} function.  This is the primitive for the @code{chown}
1857 and @code{chgrp} shell commands.
1858
1859 @pindex unistd.h
1860 The prototype for this function is declared in @file{unistd.h}.
1861
1862 @comment unistd.h
1863 @comment POSIX.1
1864 @deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group})
1865 The @code{chown} function changes the owner of the file @var{filename} to
1866 @var{owner}, and its group owner to @var{group}.
1867
1868 Changing the owner of the file on certain systems clears the set-user-ID
1869 and set-group-ID bits of the file's permissions.  (This is because those
1870 bits may not be appropriate for the new owner.)  The other file
1871 permission bits are not changed.
1872
1873 The return value is @code{0} on success and @code{-1} on failure.
1874 In addition to the usual file name errors (@pxref{File Name Errors}),
1875 the following @code{errno} error conditions are defined for this function:
1876
1877 @table @code
1878 @item EPERM
1879 This process lacks permission to make the requested change.
1880
1881 Only privileged users or the file's owner can change the file's group.
1882 On most file systems, only privileged users can change the file owner;
1883 some file systems allow you to change the owner if you are currently the
1884 owner.  When you access a remote file system, the behavior you encounter
1885 is determined by the system that actually holds the file, not by the
1886 system your program is running on.
1887
1888 @xref{Options for Files}, for information about the
1889 @code{_POSIX_CHOWN_RESTRICTED} macro.
1890
1891 @item EROFS
1892 The file is on a read-only file system.
1893 @end table
1894 @end deftypefun
1895
1896 @comment unistd.h
1897 @comment BSD
1898 @deftypefun int fchown (int @var{filedes}, int @var{owner}, int @var{group})
1899 This is like @code{chown}, except that it changes the owner of the file
1900 with open file descriptor @var{filedes}.
1901
1902 The return value from @code{fchown} is @code{0} on success and @code{-1}
1903 on failure.  The following @code{errno} error codes are defined for this
1904 function:
1905
1906 @table @code
1907 @item EBADF
1908 The @var{filedes} argument is not a valid file descriptor.
1909
1910 @item EINVAL
1911 The @var{filedes} argument corresponds to a pipe or socket, not an ordinary
1912 file.
1913
1914 @item EPERM
1915 This process lacks permission to make the requested change.  For
1916 details, see @code{chmod}, above.
1917
1918 @item EROFS
1919 The file resides on a read-only file system.
1920 @end table
1921 @end deftypefun
1922
1923 @node Permission Bits
1924 @subsection The Mode Bits for Access Permission
1925
1926 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1927 attributes, contains two kinds of information: the file type code, and
1928 the access permission bits.  This section discusses only the access
1929 permission bits, which control who can read or write the file.
1930 @xref{Testing File Type}, for information about the file type code.
1931
1932 All of the symbols listed in this section are defined in the header file
1933 @file{sys/stat.h}.
1934 @pindex sys/stat.h
1935
1936 @cindex file permission bits
1937 These symbolic constants are defined for the file mode bits that control
1938 access permission for the file:
1939
1940 @table @code
1941 @comment sys/stat.h
1942 @comment POSIX.1
1943 @item S_IRUSR
1944 @vindex S_IRUSR
1945 @comment sys/stat.h
1946 @comment BSD
1947 @itemx S_IREAD
1948 @vindex S_IREAD
1949 Read permission bit for the owner of the file.  On many systems, this
1950 bit is 0400.  @code{S_IREAD} is an obsolete synonym provided for BSD
1951 compatibility.
1952
1953 @comment sys/stat.h
1954 @comment POSIX.1
1955 @item S_IWUSR
1956 @vindex S_IWUSR
1957 @comment sys/stat.h
1958 @comment BSD
1959 @itemx S_IWRITE
1960 @vindex S_IWRITE
1961 Write permission bit for the owner of the file.  Usually 0200.
1962 @w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility.
1963
1964 @comment sys/stat.h
1965 @comment POSIX.1
1966 @item S_IXUSR
1967 @vindex S_IXUSR
1968 @comment sys/stat.h
1969 @comment BSD
1970 @itemx S_IEXEC
1971 @vindex S_IEXEC
1972 Execute (for ordinary files) or search (for directories) permission bit
1973 for the owner of the file.  Usually 0100.  @code{S_IEXEC} is an obsolete
1974 synonym provided for BSD compatibility.
1975
1976 @comment sys/stat.h
1977 @comment POSIX.1
1978 @item S_IRWXU
1979 @vindex S_IRWXU
1980 This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
1981
1982 @comment sys/stat.h
1983 @comment POSIX.1
1984 @item S_IRGRP
1985 @vindex S_IRGRP
1986 Read permission bit for the group owner of the file.  Usually 040.
1987
1988 @comment sys/stat.h
1989 @comment POSIX.1
1990 @item S_IWGRP
1991 @vindex S_IWGRP
1992 Write permission bit for the group owner of the file.  Usually 020.
1993
1994 @comment sys/stat.h
1995 @comment POSIX.1
1996 @item S_IXGRP
1997 @vindex S_IXGRP
1998 Execute or search permission bit for the group owner of the file.
1999 Usually 010.
2000
2001 @comment sys/stat.h
2002 @comment POSIX.1
2003 @item S_IRWXG
2004 @vindex S_IRWXG
2005 This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
2006
2007 @comment sys/stat.h
2008 @comment POSIX.1
2009 @item S_IROTH
2010 @vindex S_IROTH
2011 Read permission bit for other users.  Usually 04.
2012
2013 @comment sys/stat.h
2014 @comment POSIX.1
2015 @item S_IWOTH
2016 @vindex S_IWOTH
2017 Write permission bit for other users.  Usually 02.
2018
2019 @comment sys/stat.h
2020 @comment POSIX.1
2021 @item S_IXOTH
2022 @vindex S_IXOTH
2023 Execute or search permission bit for other users.  Usually 01.
2024
2025 @comment sys/stat.h
2026 @comment POSIX.1
2027 @item S_IRWXO
2028 @vindex S_IRWXO
2029 This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
2030
2031 @comment sys/stat.h
2032 @comment POSIX
2033 @item S_ISUID
2034 @vindex S_ISUID
2035 This is the set-user-ID on execute bit, usually 04000.
2036 @xref{How Change Persona}.
2037
2038 @comment sys/stat.h
2039 @comment POSIX
2040 @item S_ISGID
2041 @vindex S_ISGID
2042 This is the set-group-ID on execute bit, usually 02000.
2043 @xref{How Change Persona}.
2044
2045 @cindex sticky bit
2046 @comment sys/stat.h
2047 @comment BSD
2048 @item S_ISVTX
2049 @vindex S_ISVTX
2050 This is the @dfn{sticky} bit, usually 01000.
2051
2052 On a directory, it gives permission to delete a file in the directory
2053 only if you own that file.  Ordinarily, a user either can delete all the
2054 files in the directory or cannot delete any of them (based on whether
2055 the user has write permission for the directory).  The same restriction
2056 applies---you must both have write permission for the directory and own
2057 the file you want to delete.  The one exception is that the owner of the
2058 directory can delete any file in the directory, no matter who owns it
2059 (provided the owner has given himself write permission for the
2060 directory).  This is commonly used for the @file{/tmp} directory, where
2061 anyone may create files, but not delete files created by other users.
2062
2063 Originally the sticky bit on an executable file modified the swapping
2064 policies of the system.  Normally, when a program terminated, its pages
2065 in core were immediately freed and reused.  If the sticky bit was set on
2066 the executable file, the system kept the pages in core for a while as if
2067 the program were still running.  This was advantageous for a program
2068 likely to be run many times in succession.  This usage is obsolete in
2069 modern systems.  When a program terminates, its pages always remain in
2070 core as long as there is no shortage of memory in the system.  When the
2071 program is next run, its pages will still be in core if no shortage
2072 arose since the last run.
2073
2074 On some modern systems where the sticky bit has no useful meaning for an
2075 executable file, you cannot set the bit at all for a non-directory.
2076 If you try, @code{chmod} fails with @code{EFTYPE};
2077 @pxref{Setting Permissions}.
2078
2079 Some systems (particularly SunOS) have yet another use for the sticky
2080 bit.  If the sticky bit is set on a file that is @emph{not} executable,
2081 it means the opposite: never cache the pages of this file at all.  The
2082 main use of this is for the files on an NFS server machine which are
2083 used as the swap area of diskless client machines.  The idea is that the
2084 pages of the file will be cached in the client's memory, so it is a
2085 waste of the server's memory to cache them a second time.  In this use
2086 the sticky bit also says that the filesystem may fail to record the
2087 file's modification time onto disk reliably (the idea being that no-one
2088 cares for a swap file).
2089
2090 This bit is only available on BSD systems (and those derived from
2091 them).  Therefore one has to use the @code{_BSD_SOURCE} feature select
2092 macro to get the definition (@pxref{Feature Test Macros}).
2093 @end table
2094
2095 The actual bit values of the symbols are listed in the table above
2096 so you can decode file mode values when debugging your programs.
2097 These bit values are correct for most systems, but they are not
2098 guaranteed.
2099
2100 @strong{Warning:} Writing explicit numbers for file permissions is bad
2101 practice.  It is not only non-portable, it also requires everyone who
2102 reads your program to remember what the bits mean.  To make your
2103 program clean, use the symbolic names.
2104
2105 @node Access Permission
2106 @subsection How Your Access to a File is Decided
2107 @cindex permission to access a file
2108 @cindex access permission for a file
2109 @cindex file access permission
2110
2111 Recall that the operating system normally decides access permission for
2112 a file based on the effective user and group IDs of the process, and its
2113 supplementary group IDs, together with the file's owner, group and
2114 permission bits.  These concepts are discussed in detail in
2115 @ref{Process Persona}.
2116
2117 If the effective user ID of the process matches the owner user ID of the
2118 file, then permissions for read, write, and execute/search are
2119 controlled by the corresponding ``user'' (or ``owner'') bits.  Likewise,
2120 if any of the effective group ID or supplementary group IDs of the
2121 process matches the group owner ID of the file, then permissions are
2122 controlled by the ``group'' bits.  Otherwise, permissions are controlled
2123 by the ``other'' bits.
2124
2125 Privileged users, like @samp{root}, can access any file, regardless of
2126 its file permission bits.  As a special case, for a file to be
2127 executable even for a privileged user, at least one of its execute bits
2128 must be set.
2129
2130 @node Setting Permissions
2131 @subsection Assigning File Permissions
2132
2133 @cindex file creation mask
2134 @cindex umask
2135 The primitive functions for creating files (for example, @code{open} or
2136 @code{mkdir}) take a @var{mode} argument, which specifies the file
2137 permissions for the newly created file.  But the specified mode is
2138 modified by the process's @dfn{file creation mask}, or @dfn{umask},
2139 before it is used.
2140
2141 The bits that are set in the file creation mask identify permissions
2142 that are always to be disabled for newly created files.  For example, if
2143 you set all the ``other'' access bits in the mask, then newly created
2144 files are not accessible at all to processes in the ``other''
2145 category, even if the @var{mode} argument specified to the creation
2146 function would permit such access.  In other words, the file creation
2147 mask is the complement of the ordinary access permissions you want to
2148 grant.
2149
2150 Programs that create files typically specify a @var{mode} argument that
2151 includes all the permissions that make sense for the particular file.
2152 For an ordinary file, this is typically read and write permission for
2153 all classes of users.  These permissions are then restricted as
2154 specified by the individual user's own file creation mask.
2155
2156 @findex chmod
2157 To change the permission of an existing file given its name, call
2158 @code{chmod}.  This function ignores the file creation mask; it uses
2159 exactly the specified permission bits.
2160
2161 @pindex umask
2162 In normal use, the file creation mask is initialized in the user's login
2163 shell (using the @code{umask} shell command), and inherited by all
2164 subprocesses.  Application programs normally don't need to worry about
2165 the file creation mask.  It will do automatically what it is supposed to
2166 do.
2167
2168 When your program should create a file and bypass the umask for its
2169 access permissions, the easiest way to do this is to use @code{fchmod}
2170 after opening the file, rather than changing the umask.
2171
2172 In fact, changing the umask is usually done only by shells.  They use
2173 the @code{umask} function.
2174
2175 The functions in this section are declared in @file{sys/stat.h}.
2176 @pindex sys/stat.h
2177
2178 @comment sys/stat.h
2179 @comment POSIX.1
2180 @deftypefun mode_t umask (mode_t @var{mask})
2181 The @code{umask} function sets the file creation mask of the current
2182 process to @var{mask}, and returns the previous value of the file
2183 creation mask.
2184
2185 Here is an example showing how to read the mask with @code{umask}
2186 without changing it permanently:
2187
2188 @smallexample
2189 mode_t
2190 read_umask (void)
2191 @{
2192   mode_t mask = umask (0);
2193   umask (mask);
2194   return mask;
2195 @}
2196 @end smallexample
2197
2198 @noindent
2199 However, it is better to use @code{getumask} if you just want to read
2200 the mask value, because that is reentrant (at least if you use the GNU
2201 operating system).
2202 @end deftypefun
2203
2204 @comment sys/stat.h
2205 @comment GNU
2206 @deftypefun mode_t getumask (void)
2207 Return the current value of the file creation mask for the current
2208 process.  This function is a GNU extension.
2209 @end deftypefun
2210
2211 @comment sys/stat.h
2212 @comment POSIX.1
2213 @deftypefun int chmod (const char *@var{filename}, mode_t @var{mode})
2214 The @code{chmod} function sets the access permission bits for the file
2215 named by @var{filename} to @var{mode}.
2216
2217 If the @var{filename} names a symbolic link, @code{chmod} changes the
2218 permission of the file pointed to by the link, not those of the link
2219 itself.
2220
2221 This function returns @code{0} if successful and @code{-1} if not.  In
2222 addition to the usual file name errors (@pxref{File Name
2223 Errors}), the following @code{errno} error conditions are defined for
2224 this function:
2225
2226 @table @code
2227 @item ENOENT
2228 The named file doesn't exist.
2229
2230 @item EPERM
2231 This process does not have permission to change the access permission of
2232 this file.  Only the file's owner (as judged by the effective user ID of
2233 the process) or a privileged user can change them.
2234
2235 @item EROFS
2236 The file resides on a read-only file system.
2237
2238 @item EFTYPE
2239 @var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set,
2240 and the named file is not a directory.  Some systems do not allow setting the
2241 sticky bit on non-directory files, and some do (and only some of those
2242 assign a useful meaning to the bit for non-directory files).
2243
2244 You only get @code{EFTYPE} on systems where the sticky bit has no useful
2245 meaning for non-directory files, so it is always safe to just clear the
2246 bit in @var{mode} and call @code{chmod} again.  @xref{Permission Bits},
2247 for full details on the sticky bit.
2248 @end table
2249 @end deftypefun
2250
2251 @comment sys/stat.h
2252 @comment BSD
2253 @deftypefun int fchmod (int @var{filedes}, int @var{mode})
2254 This is like @code{chmod}, except that it changes the permissions of
2255 the file currently open via descriptor @var{filedes}.
2256
2257 The return value from @code{fchmod} is @code{0} on success and @code{-1}
2258 on failure.  The following @code{errno} error codes are defined for this
2259 function:
2260
2261 @table @code
2262 @item EBADF
2263 The @var{filedes} argument is not a valid file descriptor.
2264
2265 @item EINVAL
2266 The @var{filedes} argument corresponds to a pipe or socket, or something
2267 else that doesn't really have access permissions.
2268
2269 @item EPERM
2270 This process does not have permission to change the access permission of
2271 this file.  Only the file's owner (as judged by the effective user ID of
2272 the process) or a privileged user can change them.
2273
2274 @item EROFS
2275 The file resides on a read-only file system.
2276 @end table
2277 @end deftypefun
2278
2279 @node Testing File Access
2280 @subsection Testing Permission to Access a File
2281 @cindex testing access permission
2282 @cindex access, testing for
2283 @cindex setuid programs and file access
2284
2285 When a program runs as a privileged user, this permits it to access
2286 files off-limits to ordinary users---for example, to modify
2287 @file{/etc/passwd}.  Programs designed to be run by ordinary users but
2288 access such files use the setuid bit feature so that they always run
2289 with @code{root} as the effective user ID.
2290
2291 Such a program may also access files specified by the user, files which
2292 conceptually are being accessed explicitly by the user.  Since the
2293 program runs as @code{root}, it has permission to access whatever file
2294 the user specifies---but usually the desired behavior is to permit only
2295 those files which the user could ordinarily access.
2296
2297 The program therefore must explicitly check whether @emph{the user}
2298 would have the necessary access to a file, before it reads or writes the
2299 file.
2300
2301 To do this, use the function @code{access}, which checks for access
2302 permission based on the process's @emph{real} user ID rather than the
2303 effective user ID.  (The setuid feature does not alter the real user ID,
2304 so it reflects the user who actually ran the program.)
2305
2306 There is another way you could check this access, which is easy to
2307 describe, but very hard to use.  This is to examine the file mode bits
2308 and mimic the system's own access computation.  This method is
2309 undesirable because many systems have additional access control
2310 features; your program cannot portably mimic them, and you would not
2311 want to try to keep track of the diverse features that different systems
2312 have.  Using @code{access} is simple and automatically does whatever is
2313 appropriate for the system you are using.
2314
2315 @code{access} is @emph{only} only appropriate to use in setuid programs.
2316 A non-setuid program will always use the effective ID rather than the
2317 real ID.
2318
2319 @pindex unistd.h
2320 The symbols in this section are declared in @file{unistd.h}.
2321
2322 @comment unistd.h
2323 @comment POSIX.1
2324 @deftypefun int access (const char *@var{filename}, int @var{how})
2325 The @code{access} function checks to see whether the file named by
2326 @var{filename} can be accessed in the way specified by the @var{how}
2327 argument.  The @var{how} argument either can be the bitwise OR of the
2328 flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test
2329 @code{F_OK}.
2330
2331 This function uses the @emph{real} user and group ID's of the calling
2332 process, rather than the @emph{effective} ID's, to check for access
2333 permission.  As a result, if you use the function from a @code{setuid}
2334 or @code{setgid} program (@pxref{How Change Persona}), it gives
2335 information relative to the user who actually ran the program.
2336
2337 The return value is @code{0} if the access is permitted, and @code{-1}
2338 otherwise.  (In other words, treated as a predicate function,
2339 @code{access} returns true if the requested access is @emph{denied}.)
2340
2341 In addition to the usual file name errors (@pxref{File Name
2342 Errors}), the following @code{errno} error conditions are defined for
2343 this function:
2344
2345 @table @code
2346 @item EACCES
2347 The access specified by @var{how} is denied.
2348
2349 @item ENOENT
2350 The file doesn't exist.
2351
2352 @item EROFS
2353 Write permission was requested for a file on a read-only file system.
2354 @end table
2355 @end deftypefun
2356
2357 These macros are defined in the header file @file{unistd.h} for use
2358 as the @var{how} argument to the @code{access} function.  The values
2359 are integer constants.
2360 @pindex unistd.h
2361
2362 @comment unistd.h
2363 @comment POSIX.1
2364 @deftypevr Macro int R_OK
2365 Argument that means, test for read permission.
2366 @end deftypevr
2367
2368 @comment unistd.h
2369 @comment POSIX.1
2370 @deftypevr Macro int W_OK
2371 Argument that means, test for write permission.
2372 @end deftypevr
2373
2374 @comment unistd.h
2375 @comment POSIX.1
2376 @deftypevr Macro int X_OK
2377 Argument that means, test for execute/search permission.
2378 @end deftypevr
2379
2380 @comment unistd.h
2381 @comment POSIX.1
2382 @deftypevr Macro int F_OK
2383 Argument that means, test for existence of the file.
2384 @end deftypevr
2385
2386 @node File Times
2387 @subsection File Times
2388
2389 @cindex file access time
2390 @cindex file modification time
2391 @cindex file attribute modification time
2392 Each file has three time stamps associated with it:  its access time,
2393 its modification time, and its attribute modification time.  These
2394 correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime}
2395 members of the @code{stat} structure; see @ref{File Attributes}.
2396
2397 All of these times are represented in calendar time format, as
2398 @code{time_t} objects.  This data type is defined in @file{time.h}.
2399 For more information about representation and manipulation of time
2400 values, see @ref{Calendar Time}.
2401 @pindex time.h
2402
2403 Reading from a file updates its access time attribute, and writing
2404 updates its modification time.  When a file is created, all three
2405 time stamps for that file are set to the current time.  In addition, the
2406 attribute change time and modification time fields of the directory that
2407 contains the new entry are updated.
2408
2409 Adding a new name for a file with the @code{link} function updates the
2410 attribute change time field of the file being linked, and both the
2411 attribute change time and modification time fields of the directory
2412 containing the new name.  These same fields are affected if a file name
2413 is deleted with @code{unlink}, @code{remove}, or @code{rmdir}.  Renaming
2414 a file with @code{rename} affects only the attribute change time and
2415 modification time fields of the two parent directories involved, and not
2416 the times for the file being renamed.
2417
2418 Changing attributes of a file (for example, with @code{chmod}) updates
2419 its attribute change time field.
2420
2421 You can also change some of the time stamps of a file explicitly using
2422 the @code{utime} function---all except the attribute change time.  You
2423 need to include the header file @file{utime.h} to use this facility.
2424 @pindex utime.h
2425
2426 @comment time.h
2427 @comment POSIX.1
2428 @deftp {Data Type} {struct utimbuf}
2429 The @code{utimbuf} structure is used with the @code{utime} function to
2430 specify new access and modification times for a file.  It contains the
2431 following members:
2432
2433 @table @code
2434 @item time_t actime
2435 This is the access time for the file.
2436
2437 @item time_t modtime
2438 This is the modification time for the file.
2439 @end table
2440 @end deftp
2441
2442 @comment time.h
2443 @comment POSIX.1
2444 @deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times})
2445 This function is used to modify the file times associated with the file
2446 named @var{filename}.
2447
2448 If @var{times} is a null pointer, then the access and modification times
2449 of the file are set to the current time.  Otherwise, they are set to the
2450 values from the @code{actime} and @code{modtime} members (respectively)
2451 of the @code{utimbuf} structure pointed at by @var{times}.
2452
2453 The attribute modification time for the file is set to the current time
2454 in either case (since changing the time stamps is itself a modification
2455 of the file attributes).
2456
2457 The @code{utime} function returns @code{0} if successful and @code{-1}
2458 on failure.  In addition to the usual file name errors
2459 (@pxref{File Name Errors}), the following @code{errno} error conditions
2460 are defined for this function:
2461
2462 @table @code
2463 @item EACCES
2464 There is a permission problem in the case where a null pointer was
2465 passed as the @var{times} argument.  In order to update the time stamp on
2466 the file, you must either be the owner of the file, have write
2467 permission on the file, or be a privileged user.
2468
2469 @item ENOENT
2470 The file doesn't exist.
2471
2472 @item EPERM
2473 If the @var{times} argument is not a null pointer, you must either be
2474 the owner of the file or be a privileged user.  This error is used to
2475 report the problem.
2476
2477 @item EROFS
2478 The file lives on a read-only file system.
2479 @end table
2480 @end deftypefun
2481
2482 Each of the three time stamps has a corresponding microsecond part,
2483 which extends its resolution.  These fields are called
2484 @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
2485 each has a value between 0 and 999,999, which indicates the time in
2486 microseconds.  They correspond to the @code{tv_usec} field of a
2487 @code{timeval} structure; see @ref{High-Resolution Calendar}.
2488
2489 The @code{utimes} function is like @code{utime}, but also lets you specify
2490 the fractional part of the file times.  The prototype for this function is
2491 in the header file @file{sys/time.h}.
2492 @pindex sys/time.h
2493
2494 @comment sys/time.h
2495 @comment BSD
2496 @deftypefun int utimes (const char *@var{filename}, struct timeval @var{tvp}@t{[2]})
2497 This function sets the file access and modification times for the file
2498 named by @var{filename}.  The new file access time is specified by
2499 @code{@var{tvp}[0]}, and the new modification time by
2500 @code{@var{tvp}[1]}.  This function comes from BSD.
2501
2502 The return values and error conditions are the same as for the @code{utime}
2503 function.
2504 @end deftypefun
2505
2506 @node File Size
2507 @subsection File Size
2508
2509 Normally file sizes are maintained automatically.  A file begins with a
2510 size of @math{0} and is automatically extended when data is written
2511 past its end.  It is also possible to empty a file completely in an
2512 @code{open} or @code{fopen} call.
2513
2514 However, sometimes it is neccessary to @emph{reduce} the size of a file.
2515 This can be done with the @code{truncate} and @code{ftruncate} functions.
2516 They were introduced in BSD Unix.  @code{ftruncate} was later added to
2517 POSIX.1.
2518
2519 Some systems allow you to extend a file (creating holes) with these
2520 functions.  This is useful when using memory-mapped I/O
2521 (@pxref{Memory-mapped I/O}), where files are not automatically extended.
2522 However it is not portable but must be implemented if @code{mmap} allows
2523 mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined).
2524
2525 Using these functions on anything other than a regular file gives
2526 @emph{undefined} results.  On many systems, such a call will appear to
2527 succeed, without actually accomplishing anything.
2528
2529 @deftypefun int truncate (const char *@var{filename}, off_t @var{length})
2530
2531 The @code{truncate} function changes the size of @var{filename} to
2532 @var{length}.  If @var{length} is shorter than the previous length, data at
2533 the end will be lost.
2534
2535 If @var{length} is longer, holes will be added to the end.  However, some
2536 systems do not support this feature and will leave the file unchanged.
2537
2538 The return value is @math{0} for success, or @math{-1} for an error.  In
2539 addition to the usual file name errors, the following errors may occur:
2540
2541 @table @code
2542
2543 @item EACCES
2544 The file is a directory or not writable.
2545
2546 @item EINVAL
2547 @var{length} is negative.
2548
2549 @item EFBIG
2550 The operation would extend the file beyond the limits of the operating system.
2551
2552 @item EIO
2553 A hardware I/O error occured.
2554
2555 @item EPERM
2556 The file is "append-only" or "immutable".
2557
2558 @item EINTR
2559 The operation was interrupted by a signal.
2560
2561 @end table
2562
2563 @end deftypefun
2564
2565 @deftypefun int ftruncate (int @var{fd}, off_t @var{length})
2566
2567 This is like @code{truncate}, but it works on a file descriptor @var{fd}.
2568
2569 @code{ftruncate} is especially useful in combination with @code{mmap}.
2570 Since the mapped region must have a fixed size one cannot enlarge the
2571 file by writing something beyond the last mapped page.  Instead one has
2572 to enlarge the file itself and then remap the file with the new size.
2573 The example below shows how this works.
2574
2575 The return value is @math{0} for success, or @math{-1} for an error.  The
2576 following errors may occur:
2577
2578 @table @code
2579
2580 @item EBADF
2581 @var{fd} does not correspond to an open file.
2582
2583 @item EACCES
2584 @var{fd} is a directory or not open for write.
2585
2586 @item EINVAL
2587 @var{length} is negative.
2588
2589 @item EFBIG
2590 The operation would extend the file beyond the limits of the operating system.
2591 @c or the open() call -- with the not-yet-discussed feature of opening
2592 @c files with extra-large offsets.
2593
2594 @item EIO
2595 A hardware I/O error occured.
2596
2597 @item EPERM
2598 The file is "append-only" or "immutable".
2599
2600 @item EINTR
2601 The operation was interrupted by a signal.
2602
2603 @c ENOENT is also possible on Linux --- however it only occurs if the file
2604 @c descriptor has a `file' structure but no `inode' structure.  I'm not
2605 @c sure how such an fd could be created.  Perhaps it's a bug.
2606
2607 @end table
2608
2609 @end deftypefun
2610
2611 As announced here is a little example how to use @code{ftruncate} in
2612 combination with @code{mmap}:
2613
2614 @smallexample
2615 int fd;
2616 void *start;
2617 size_t len;
2618
2619 int
2620 add (off_t at, void *block, size_t size)
2621 @{
2622   if (at + size > len)
2623     @{
2624       /* Resize the file and remap.  */
2625       size_t ps = sysconf (_SC_PAGESIZE);
2626       size_t ns = (at + size + ps - 1) & ~(ps - 1);
2627       void *np;
2628       if (ftruncate (fd, ns) < 0)
2629         return -1;
2630       np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
2631       if (np == MAP_FAILED)
2632         return -1;
2633       start = np;
2634       len = ns;
2635     @}
2636   memcpy ((char *) start + at, block, size);
2637   return 0;
2638 @}
2639 @end smallexample
2640
2641 The function @code{add} allows to add at arbitrary positions in the file
2642 given blocks of memory.  If the current size of the file is too small it
2643 is extended.  Please note the it is extended in multiples of a pagesize.
2644 This is a requirement of @code{mmap}.  The program has to track the real
2645 size and once the program finished to work a final @code{ftruncate} call
2646 should set the real size of the file.
2647
2648 @node Making Special Files
2649 @section Making Special Files
2650 @cindex creating special files
2651 @cindex special files
2652
2653 The @code{mknod} function is the primitive for making special files,
2654 such as files that correspond to devices.  The GNU library includes
2655 this function for compatibility with BSD.
2656
2657 The prototype for @code{mknod} is declared in @file{sys/stat.h}.
2658 @pindex sys/stat.h
2659
2660 @comment sys/stat.h
2661 @comment BSD
2662 @deftypefun int mknod (const char *@var{filename}, int @var{mode}, int @var{dev})
2663 The @code{mknod} function makes a special file with name @var{filename}.
2664 The @var{mode} specifies the mode of the file, and may include the various
2665 special file bits, such as @code{S_IFCHR} (for a character special file)
2666 or @code{S_IFBLK} (for a block special file).  @xref{Testing File Type}.
2667
2668 The @var{dev} argument specifies which device the special file refers to.
2669 Its exact interpretation depends on the kind of special file being created.
2670
2671 The return value is @code{0} on success and @code{-1} on error.  In addition
2672 to the usual file name errors (@pxref{File Name Errors}), the
2673 following @code{errno} error conditions are defined for this function:
2674
2675 @table @code
2676 @item EPERM
2677 The calling process is not privileged.  Only the superuser can create
2678 special files.
2679
2680 @item ENOSPC
2681 The directory or file system that would contain the new file is full
2682 and cannot be extended.
2683
2684 @item EROFS
2685 The directory containing the new file can't be modified because it's on
2686 a read-only file system.
2687
2688 @item EEXIST
2689 There is already a file named @var{filename}.  If you want to replace
2690 this file, you must remove the old file explicitly first.
2691 @end table
2692 @end deftypefun
2693
2694 @node Temporary Files
2695 @section Temporary Files
2696
2697 If you need to use a temporary file in your program, you can use the
2698 @code{tmpfile} function to open it.  Or you can use the @code{tmpnam}
2699 (better: @code{tmpnam_r}) function to make a name for a temporary file and
2700 then you can open it in the usual way with @code{fopen}.
2701
2702 The @code{tempnam} function is like @code{tmpnam} but lets you choose
2703 what directory temporary files will go in, and something about what
2704 their file names will look like.  Important for multi threaded programs
2705 is that @code{tempnam} is reentrant while @code{tmpnam} is not since it
2706 returns a pointer to a static buffer.
2707
2708 These facilities are declared in the header file @file{stdio.h}.
2709 @pindex stdio.h
2710
2711 @comment stdio.h
2712 @comment ISO
2713 @deftypefun {FILE *} tmpfile (void)
2714 This function creates a temporary binary file for update mode, as if by
2715 calling @code{fopen} with mode @code{"wb+"}.  The file is deleted
2716 automatically when it is closed or when the program terminates.  (On
2717 some other @w{ISO C} systems the file may fail to be deleted if the program
2718 terminates abnormally).
2719
2720 This function is reentrant.
2721
2722 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
2723 32 bits system this function is in fact @code{tmpfile64}.  I.e., the
2724 LFS interface transparently replaces the old interface.
2725 @end deftypefun
2726
2727 @comment stdio.h
2728 @comment Unix98
2729 @deftypefun {FILE *} tmpfile64 (void)
2730 This function is similar to @code{tmpfile} but the stream it returns a
2731 pointer for is opened using @code{tmpfile64}.  Therefore this stream can be
2732 used even on files larger then @math{2^31} bytes on 32 bits machines.
2733
2734 Please note that the return type is still @code{FILE *}.  There is no
2735 special @code{FILE} type for the LFS interface.
2736
2737 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
2738 bits machine this function is available under the name @code{tmpfile}
2739 and so transparently replaces the old interface.
2740 @end deftypefun
2741
2742 @comment stdio.h
2743 @comment ISO
2744 @deftypefun {char *} tmpnam (char *@var{result})
2745 This function constructs and returns a file name that is a valid file
2746 name and that does not name any existing file.  If the @var{result}
2747 argument is a null pointer, the return value is a pointer to an internal
2748 static string, which might be modified by subsequent calls and therefore
2749 makes this function non-reentrant.  Otherwise, the @var{result} argument
2750 should be a pointer to an array of at least @code{L_tmpnam} characters,
2751 and the result is written into that array.
2752
2753 It is possible for @code{tmpnam} to fail if you call it too many times
2754 without removing previously created files.  This is because the fixed
2755 length of a temporary file name gives room for only a finite number of
2756 different names.  If @code{tmpnam} fails, it returns a null pointer.
2757
2758 @strong{Warning:} Since between the time the pathname is constructed and
2759 the file is created another process might have created a file with this
2760 name using @code{tmpnam} is a possible security hole.  The
2761 implementation generates names which hardly can be predicted but opening
2762 the file in any case should use the @code{O_EXCL} flag.  Using
2763 @code{tmpfile} is a safe way to avoid this problem.
2764 @end deftypefun
2765
2766 @comment stdio.h
2767 @comment GNU
2768 @deftypefun {char *} tmpnam_r (char *@var{result})
2769 This function is nearly identical to the @code{tmpnam} function.  But it
2770 does not allow @var{result} to be a null pointer.  In the later case a
2771 null pointer is returned.
2772
2773 This function is reentrant because the non-reentrant situation of
2774 @code{tmpnam} cannot happen here.
2775 @end deftypefun
2776
2777 @comment stdio.h
2778 @comment ISO
2779 @deftypevr Macro int L_tmpnam
2780 The value of this macro is an integer constant expression that represents
2781 the minimum allocation size of a string large enough to hold the
2782 file name generated by the @code{tmpnam} function.
2783 @end deftypevr
2784
2785 @comment stdio.h
2786 @comment ISO
2787 @deftypevr Macro int TMP_MAX
2788 The macro @code{TMP_MAX} is a lower bound for how many temporary names
2789 you can create with @code{tmpnam}.  You can rely on being able to call
2790 @code{tmpnam} at least this many times before it might fail saying you
2791 have made too many temporary file names.
2792
2793 With the GNU library, you can create a very large number of temporary
2794 file names---if you actually create the files, you will probably run out
2795 of disk space before you run out of names.  Some other systems have a
2796 fixed, small limit on the number of temporary files.  The limit is never
2797 less than @code{25}.
2798 @end deftypevr
2799
2800 @comment stdio.h
2801 @comment SVID
2802 @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
2803 This function generates a unique temporary filename.  If @var{prefix} is
2804 not a null pointer, up to five characters of this string are used as a
2805 prefix for the file name.  The return value is a string newly allocated
2806 with @code{malloc}; you should release its storage with @code{free} when
2807 it is no longer needed.
2808
2809 Because the string is dynamically allocated this function is reentrant.
2810
2811 The directory prefix for the temporary file name is determined by testing
2812 each of the following, in sequence.  The directory must exist and be
2813 writable.
2814
2815 @itemize @bullet
2816 @item
2817 The environment variable @code{TMPDIR}, if it is defined.  For security
2818 reasons this only happens if the program is not SUID or SGID enabled.
2819
2820 @item
2821 The @var{dir} argument, if it is not a null pointer.
2822
2823 @item
2824 The value of the @code{P_tmpdir} macro.
2825
2826 @item
2827 The directory @file{/tmp}.
2828 @end itemize
2829
2830 This function is defined for SVID compatibility.
2831 @end deftypefun
2832 @cindex TMPDIR environment variable
2833
2834 @comment stdio.h
2835 @comment SVID
2836 @c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
2837 @deftypevr {SVID Macro} {char *} P_tmpdir
2838 This macro is the name of the default directory for temporary files.
2839 @end deftypevr
2840
2841 Older Unix systems did not have the functions just described.  Instead
2842 they used @code{mktemp} and @code{mkstemp}.  Both of these functions
2843 work by modifying a file name template string you pass.  The last six
2844 characters of this string must be @samp{XXXXXX}.  These six @samp{X}s
2845 are replaced with six characters which make the whole string a unique
2846 file name.  Usually the template string is something like
2847 @samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}.
2848
2849 @strong{Note:} Because @code{mktemp} and @code{mkstemp} modify the
2850 template string, you @emph{must not} pass string constants to them.
2851 String constants are normally in read-only storage, so your program
2852 would crash when @code{mktemp} or @code{mkstemp} tried to modify the
2853 string.
2854
2855 @comment stdlib.h
2856 @comment Unix
2857 @deftypefun {char *} mktemp (char *@var{template})
2858 The @code{mktemp} function generates a unique file name by modifying
2859 @var{template} as described above.  If successful, it returns
2860 @var{template} as modified.  If @code{mktemp} cannot find a unique file
2861 name, it makes @var{template} an empty string and returns that.  If
2862 @var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a
2863 null pointer.
2864
2865 @strong{Warning:} Since between the time the pathname is constructed and
2866 the file is created another process might have created a file with this
2867 name using @code{mktemp} is a possible security hole.  The
2868 implementation generates names which hardly can be predicted but opening
2869 the file in any case should use the @code{O_EXCL} flag.  Using
2870 @code{mkstemp} is a safe way to avoid this problem.
2871 @end deftypefun
2872
2873 @comment stdlib.h
2874 @comment BSD
2875 @deftypefun int mkstemp (char *@var{template})
2876 The @code{mkstemp} function generates a unique file name just as
2877 @code{mktemp} does, but it also opens the file for you with @code{open}
2878 (@pxref{Opening and Closing Files}).  If successful, it modifies
2879 @var{template} in place and returns a file descriptor open on that file
2880 for reading and writing.  If @code{mkstemp} cannot create a
2881 uniquely-named file, it returns @code{-1}.  If @var{template} does not
2882 end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not
2883 modify @var{template}.
2884
2885 The file is opened using mode @code{0600}.  If the file is meant to be
2886 used by other users the mode must explicitly changed.
2887 @end deftypefun
2888
2889 Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a
2890 unique file that cannot possibly clash with any other program trying to
2891 create a temporary file.  This is because it works by calling
2892 @code{open} with the @code{O_EXCL} flag bit, which says you want to
2893 always create a new file, and get an error if the file already exists.