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