1 @node File System Interface, Pipes and FIFOs, Low-Level I/O, Top
2 @chapter File System Interface
4 This chapter describes the GNU C library's functions for manipulating
5 files. Unlike the input and output functions described in
6 @ref{I/O on Streams} and @ref{Low-Level I/O}, these
7 functions are concerned with operating on the files themselves, rather
8 than on their contents.
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.
16 * Working Directory:: This is used to resolve relative
18 * Accessing Directories:: Finding out what files a directory
20 * Working on Directory Trees:: Apply actions to all files or a selectable
21 subset of a directory hierarchy.
22 * Hard Links:: Adding alternate names to a file.
23 * Symbolic Links:: A file that ``points to'' a file name.
24 * Deleting Files:: How to delete a file, and what that means.
25 * Renaming Files:: Changing a file's name.
26 * Creating Directories:: A system call just for creating a directory.
27 * File Attributes:: Attributes of individual files.
28 * Making Special Files:: How to create special files.
29 * Temporary Files:: Naming and creating temporary files.
32 @node Working Directory
33 @section Working Directory
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}).
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
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.
54 Prototypes for these functions are declared in the header file
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}.
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.
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:
78 The @var{size} argument is zero and @var{buffer} is not a null pointer.
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.
85 Permission to read or search a component of the file name was denied.
89 You could implement the behavior of GNU's @w{@code{getcwd (NULL, 0)}}
90 using only the standard behavior of @code{getcwd}:
97 char *buffer = (char *) xmalloc (size);
101 char *value = getcwd (buffer, size);
106 buffer = (char *) xmalloc (size);
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
118 @deftypefun {char *} getwd (char *@var{buffer})
119 This is similar to @code{getcwd}, but has no way to specify the size of
120 the buffer. The GNU library provides @code{getwd} only
121 for backwards compatibility with BSD.
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.
132 @deftypefun int chdir (const char *@var{filename})
133 This function is used to set the process's working directory to
136 The normal, successful return value from @code{chdir} is @code{0}. A
137 value of @code{-1} is returned to indicate an error. The @code{errno}
138 error conditions defined for this function are the usual file name
139 syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
140 file @var{filename} is not a directory.
144 @node Accessing Directories
145 @section Accessing Directories
146 @cindex accessing directories
147 @cindex reading from a directory
148 @cindex directories, accessing
150 The facilities described in this section let you read the contents of a
151 directory file. This is useful if you want your program to list all the
152 files in a directory, perhaps as part of a menu.
154 @cindex directory stream
155 The @code{opendir} function opens a @dfn{directory stream} whose
156 elements are directory entries. You use the @code{readdir} function on
157 the directory stream to retrieve these entries, represented as
158 @w{@code{struct dirent}} objects. The name of the file for each entry is
159 stored in the @code{d_name} member of this structure. There are obvious
160 parallels here to the stream facilities for ordinary files, described in
161 @ref{I/O on Streams}.
164 * Directory Entries:: Format of one directory entry.
165 * Opening a Directory:: How to open a directory stream.
166 * Reading/Closing Directory:: How to read directory entries from the stream.
167 * Simple Directory Lister:: A very simple directory listing program.
168 * Random Access Directory:: Rereading part of the directory
169 already read with the same stream.
170 * Scanning Directory Content:: Get entries for user selected subset of
171 contents in given directory.
172 * Simple Directory Lister Mark II:: Revised version of the program.
175 @node Directory Entries
176 @subsection Format of a Directory Entry
179 This section describes what you find in a single directory entry, as you
180 might obtain it from a directory stream. All the symbols are declared
181 in the header file @file{dirent.h}.
185 @deftp {Data Type} {struct dirent}
186 This is a structure type used to return information about directory
187 entries. It contains the following fields:
191 This is the null-terminated file name component. This is the only
192 field you can count on in all POSIX systems.
195 This is the file serial number. For BSD compatibility, you can also
196 refer to this member as @code{d_ino}. In the GNU system and most POSIX
197 systems, for most files this the same as the @code{st_ino} member that
198 @code{stat} will return for the file. @xref{File Attributes}.
200 @item unsigned char d_namlen
201 This is the length of the file name, not including the terminating null
202 character. Its type is @code{unsigned char} because that is the integer
203 type of the appropriate size
205 @item unsigned char d_type
206 This is the type of the file, possibly unknown. The following constants
207 are defined for its value:
211 The type is unknown. On some systems this is the only value returned.
220 A named pipe, or FIFO. @xref{FIFO Special Files}.
223 A local-domain socket. @c !!! @xref{Local Domain}.
232 This member is a BSD extension. On systems where it is used, it
233 corresponds to the file type bits in the @code{st_mode} member of
234 @code{struct statbuf}. On other systems it will always be DT_UNKNOWN.
235 These two macros convert between @code{d_type} values and @code{st_mode}
238 @deftypefun int IFTODT (mode_t @var{mode})
239 This returns the @code{d_type} value corresponding to @var{mode}.
242 @deftypefun mode_t DTTOIF (int @var{dtype})
243 This returns the @code{st_mode} value corresponding to @var{dtype}.
247 This structure may contain additional members in the future.
249 When a file has multiple names, each name has its own directory entry.
250 The only way you can tell that the directory entries belong to a
251 single file is that they have the same value for the @code{d_fileno}
254 File attributes such as size, modification times, and the like are part
255 of the file itself, not any particular directory entry. @xref{File
259 @node Opening a Directory
260 @subsection Opening a Directory Stream
263 This section describes how to open a directory stream. All the symbols
264 are declared in the header file @file{dirent.h}.
268 @deftp {Data Type} DIR
269 The @code{DIR} data type represents a directory stream.
272 You shouldn't ever allocate objects of the @code{struct dirent} or
273 @code{DIR} data types, since the directory access functions do that for
274 you. Instead, you refer to these objects using the pointers returned by
275 the following functions.
279 @deftypefun {DIR *} opendir (const char *@var{dirname})
280 The @code{opendir} function opens and returns a directory stream for
281 reading the directory whose file name is @var{dirname}. The stream has
284 If unsuccessful, @code{opendir} returns a null pointer. In addition to
285 the usual file name errors (@pxref{File Name Errors}), the
286 following @code{errno} error conditions are defined for this function:
290 Read permission is denied for the directory named by @code{dirname}.
293 The process has too many files open.
296 The entire system, or perhaps the file system which contains the
297 directory, cannot support any additional open files at the moment.
298 (This problem cannot happen on the GNU system.)
301 The @code{DIR} type is typically implemented using a file descriptor,
302 and the @code{opendir} function in terms of the @code{open} function.
303 @xref{Low-Level I/O}. Directory streams and the underlying
304 file descriptors are closed on @code{exec} (@pxref{Executing a File}).
307 @node Reading/Closing Directory
308 @subsection Reading and Closing a Directory Stream
311 This section describes how to read directory entries from a directory
312 stream, and how to close the stream when you are done with it. All the
313 symbols are declared in the header file @file{dirent.h}.
317 @deftypefun {struct dirent *} readdir (DIR *@var{dirstream})
318 This function reads the next entry from the directory. It normally
319 returns a pointer to a structure containing information about the file.
320 This structure is statically allocated and can be rewritten by a
323 @strong{Portability Note:} On some systems, @code{readdir} may not
324 return entries for @file{.} and @file{..}, even though these are always
325 valid file names in any directory. @xref{File Name Resolution}.
327 If there are no more entries in the directory or an error is detected,
328 @code{readdir} returns a null pointer. The following @code{errno} error
329 conditions are defined for this function:
333 The @var{dirstream} argument is not valid.
336 @code{readdir} is not thread safe. Multiple threads using
337 @code{readdir} on the same @var{dirstream} may overwrite the return
338 value. Use @code{readdir_r} when this is critical.
343 @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result})
344 This function is the reentrant version of @code{readdir}. Like
345 @code{readdir} it returns the next entry from the directory. But to
346 prevent conflicts for simultaneously running threads the result is not
347 stored in some internal memory. Instead the argument @var{entry} has to
348 point to a place where the result is stored.
350 The return value is @code{0} in case the next entry was read
351 successfully. In this case a pointer to the result is returned in
352 *@var{result}. It is not required that *@var{result} is the same as
353 @var{entry}. If something goes wrong while executing @code{readdir_r}
354 the function returns a value indicating the error (as described for
357 If there are no more directory entries, @code{readdir_r}'s return value is
358 @code{0}, and *@var{result} is set to @code{NULL}.
360 @strong{Portability Note:} On some systems, @code{readdir_r} may not
361 return a terminated string as the file name even if no @code{d_reclen}
362 element is available in @code{struct dirent} and the file name as the
363 maximal allowed size. Modern systems all have the @code{d_reclen} field
364 and on old systems multi threading is not critical. In any case, there
365 is no such problem with the @code{readdir} function so that even on
366 systems without @code{d_reclen} field one could use multiple threads by
367 using external locking.
372 @deftypefun int closedir (DIR *@var{dirstream})
373 This function closes the directory stream @var{dirstream}. It returns
374 @code{0} on success and @code{-1} on failure.
376 The following @code{errno} error conditions are defined for this
381 The @var{dirstream} argument is not valid.
385 @node Simple Directory Lister
386 @subsection Simple Program to List a Directory
388 Here's a simple program that prints the names of the files in
389 the current working directory:
395 The order in which files appear in a directory tends to be fairly
396 random. A more useful program would sort the entries (perhaps by
397 alphabetizing them) before printing them; see
398 @ref{Scanning Directory Content} and @ref{Array Sort Function}.
401 @node Random Access Directory
402 @subsection Random Access in a Directory Stream
405 This section describes how to reread parts of a directory that you have
406 already read from an open directory stream. All the symbols are
407 declared in the header file @file{dirent.h}.
411 @deftypefun void rewinddir (DIR *@var{dirstream})
412 The @code{rewinddir} function is used to reinitialize the directory
413 stream @var{dirstream}, so that if you call @code{readdir} it
414 returns information about the first entry in the directory again. This
415 function also notices if files have been added or removed to the
416 directory since it was opened with @code{opendir}. (Entries for these
417 files might or might not be returned by @code{readdir} if they were
418 added or removed since you last called @code{opendir} or
424 @deftypefun off_t telldir (DIR *@var{dirstream})
425 The @code{telldir} function returns the file position of the directory
426 stream @var{dirstream}. You can use this value with @code{seekdir} to
427 restore the directory stream to that position.
432 @deftypefun void seekdir (DIR *@var{dirstream}, off_t @var{pos})
433 The @code{seekdir} function sets the file position of the directory
434 stream @var{dirstream} to @var{pos}. The value @var{pos} must be the
435 result of a previous call to @code{telldir} on this particular stream;
436 closing and reopening the directory can invalidate values returned by
441 @node Scanning Directory Content
442 @subsection Scanning the Content of a Directory
444 A higher-level interface to the directory handling functions is the
445 @code{scandir} function. With its help one can select a subset of the
446 entries in a directory, possibly sort them and get as the result a list
451 @deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const void *, const void *))
453 The @code{scandir} function scans the contents of the directory selected
454 by @var{dir}. The result in @var{namelist} is an array of pointers to
455 structure of type @code{struct dirent} which describe all selected
456 directory entries and which is allocated using @code{malloc}. Instead
457 of always getting all directory entries returned, the user supplied
458 function @var{selector} can be used to decide which entries are in the
459 result. Only the entries for which @var{selector} returns a nonzero
462 Finally the entries in the @var{namelist} are sorted using the user
463 supplied function @var{cmp}. The arguments of the @var{cmp} function
464 are of type @code{struct dirent **}. I.e., one cannot directly use the
465 @code{strcmp} or @code{strcoll} function; see the functions
466 @code{alphasort} and @code{versionsort} below.
468 The return value of the function gives the number of entries placed in
469 @var{namelist}. If it is @code{-1} an error occurred (either the
470 directory could not be opened for reading or the malloc call failed) and
471 the global variable @code{errno} contains more information on the error.
474 As said above the fourth argument to the @code{scandir} function must be
475 a pointer to a sorting function. For the convenience of the programmer
476 the GNU C library contains implementations of functions which are very
477 helpful for this purpose.
481 @deftypefun int alphasort (const void *@var{a}, const void *@var{b})
482 The @code{alphasort} function behaves like the @code{strcoll} function
483 (@pxref{String/Array Comparison}). The difference is that the arguments
484 are not string pointers but instead they are of type
485 @code{struct dirent **}.
487 Return value of @code{alphasort} is less than, equal to, or greater than
488 zero depending on the order of the two entries @var{a} and @var{b}.
493 @deftypefun int versionsort (const void *@var{a}, const void *@var{b})
494 The @code{versionsort} function is like @code{alphasort}, excepted that it
495 uses the @code{strverscmp} function internally.
498 If the filesystem supports large files we cannot use the @code{scandir}
499 anymore since the @code{dirent} structure might not able to contain all
500 the information. The LFS provides the new type @w{@code{struct
501 dirent64}}. To use this we need a new function.
505 @deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const void *, const void *))
506 The @code{scandir64} function works like the @code{scandir} function
507 only that the directory entries it returns are described by elements of
508 type @w{@code{struct dirent64}}. The function pointed to by
509 @var{selector} is again used to select the wanted entries only that
510 @var{selector} now must point to a function which takes a
511 @w{@code{struct dirent64 *}} parameter.
513 The @var{cmp} now must be a function which expects its two arguments to
514 be of type @code{struct dirent64 **}.
517 As just said the function expected as the fourth is different from the
518 function expected in @code{scandir}. Therefore we cannot use the
519 @code{alphasort} and @code{versionsort} functions anymore. Instead we
520 have two similar functions available.
524 @deftypefun int alphasort64 (const void *@var{a}, const void *@var{b})
525 The @code{alphasort64} function behaves like the @code{strcoll} function
526 (@pxref{String/Array Comparison}). The difference is that the arguments
527 are not string pointers but instead they are of type
528 @code{struct dirent64 **}.
530 Return value of @code{alphasort64} is less than, equal to, or greater
531 than zero depending on the order of the two entries @var{a} and @var{b}.
536 @deftypefun int versionsort64 (const void *@var{a}, const void *@var{b})
537 The @code{versionsort64} function is like @code{alphasort64}, excepted that it
538 uses the @code{strverscmp} function internally.
541 It is important not to mix the use of @code{scandir} and the 64 bits
542 comparison functions or vice versa. There are systems on which this
543 works but on others it will fail miserably.
545 @node Simple Directory Lister Mark II
546 @subsection Simple Program to List a Directory, Mark II
548 Here is a revised version of the directory lister found above
549 (@pxref{Simple Directory Lister}). Using the @code{scandir} function we
550 can avoid using the functions which directly work with the directory
551 contents. After the call the found entries are available for direct
558 Please note the simple selector function for this example. Since
559 we want to see all directory entries we always return @code{1}.
562 @node Working on Directory Trees
563 @section Working on Directory Trees
564 @cindex directory hierarchy
565 @cindex hierarchy, directory
566 @cindex tree, directory
568 The functions to handle files in directories described so far allowed to
569 retrieve all the information in small pieces or process all files in a
570 directory (see @code{scandir}). Sometimes it is useful to process whole
571 hierarchies of directories and the contained files. The X/Open
572 specification define two functions to do this. The simpler form is
573 derived from an early definition in @w{System V} systems and therefore
574 this function is available on SVID derived systems. The prototypes and
575 required definitions can be found in the @file{ftw.h} header.
577 Both functions of this @code{ftw} family take as one of the arguments a
578 reference to a callback function. The functions must be of these types.
582 @deftp {Data Type} __ftw_func_t
585 int (*) (const char *, const struct stat *, int)
588 Type for callback functions given to the @code{ftw} function. The first
589 parameter will contain a pointer to the filename, the second parameter
590 will point to an object of type @code{struct stat} which will be filled
591 for the file named by the first parameter.
594 The last parameter is a flag given more information about the current
595 file. It can have the following values:
599 The current item is a normal file or files which do not fit into one of
600 the following categories. This means especially special files, sockets
603 The current item is a directory.
605 The @code{stat} call to fill the object pointed to by the second
606 parameter failed and so the information is invalid.
608 The item is a directory which cannot be read.
610 The item is a symbolic link. Since symbolic links are normally followed
611 seeing this value in a @code{ftw} callback function means the referenced
612 file does not exist. The situation for @code{nftw} is different.
614 This value is only available if the program is compiled with
615 @code{_BSD_SOURCE} or @code{_XOPEN_EXTENDED} defined before including
616 the first header. The original SVID systems do not have symbolic links.
619 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
620 type is in fact @code{__ftw64_func_t} since this mode also changes
621 @code{struct stat} to be @code{struct stat64}.
624 For the LFS interface and the use in the function @code{ftw64} the
625 header @file{ftw.h} defines another function type.
629 @deftp {Data Type} __ftw64_func_t
632 int (*) (const char *, const struct stat64 *, int)
635 This type is used just like @code{__ftw_func_t} for the callback
636 function, but this time called from @code{ftw64}. The second parameter
637 to the function is this time a pointer to a variable of type
638 @code{struct stat64} which is able to represent the larger values.
643 @deftp {Data Type} __nftw_func_t
646 int (*) (const char *, const struct stat *, int, struct FTW *)
651 The first three arguments have the same as for the @code{__ftw_func_t}
652 type. A difference is that for the third argument some additional
653 values are defined to allow finer differentiation:
656 The current item is a directory and all subdirectories have already been
657 visited and reported. This flag is returned instead of @code{FTW_D} if
658 the @code{FTW_DEPTH} flag is given to @code{nftw} (see below).
660 The current item is a stale symbolic link. The file it points to does
664 The last parameter of the callback function is a pointer to a structure
665 with some extra information as described below.
667 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
668 type is in fact @code{__nftw64_func_t} since this mode also changes
669 @code{struct stat} to be @code{struct stat64}.
672 For the LFS interface there is also a variant of this data type
673 available which has to be used with the @code{nftw64} function.
677 @deftp {Data Type} __nftw64_func_t
680 int (*) (const char *, const struct stat64 *, int, struct FTW *)
683 This type is used just like @code{__nftw_func_t} for the callback
684 function, but this time called from @code{nftw64}. The second parameter
685 to the function is this time a pointer to a variable of type
686 @code{struct stat64} which is able to represent the larger values.
691 @deftp {Data Type} {struct FTW}
692 The contained information helps to interpret the name parameter and
693 gives some information about current state of the traversal of the
698 The value specifies which part of the filename argument given in the
699 first parameter to the callback function is the name of the file. The
700 rest of the string is the path to locate the file. This information is
701 especially important if the @code{FTW_CHDIR} flag for @code{nftw} was
702 set since then the current directory is the one the current item is
705 While processing the directory the functions tracks how many directories
706 have been examine to find the current item. This nesting level is
707 @math{0} for the item given starting item (file or directory) and is
708 incremented by one for each entered directory.
715 @deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors})
716 The @code{ftw} function calls the callback function given in the
717 parameter @var{func} for every item which is found in the directory
718 specified by @var{filename} and all directories below. The function
719 follows symbolic links if necessary but does not process an item twice.
720 If @var{filename} names no directory this item is the only object
721 reported by calling the callback function.
723 The filename given to the callback function is constructed by taking the
724 @var{filename} parameter and appending the names of all passed
725 directories and then the local file name. So the callback function can
726 use this parameter to access the file. Before the callback function is
727 called @code{ftw} calls @code{stat} for this file and passes the
728 information up to the callback function. If this @code{stat} call was
729 not successful the failure is indicated by setting the falg argument of
730 the callback function to @code{FTW_NS}. Otherwise the flag is set
731 according to the description given in the description of
732 @code{__ftw_func_t} above.
734 The callback function is expected to return @math{0} to indicate that no
735 error occurred and the processing should be continued. If an error
736 occurred in the callback function or the call to @code{ftw} shall return
737 immediately the callback function can return a value other than
738 @math{0}. This is the only correct way to stop the function. The
739 program must not use @code{setjmp} or similar techniques to continue the
740 program in another place. This would leave the resources allocated in
741 the @code{ftw} function allocated.
743 The @var{descriptors} parameter to the @code{ftw} function specifies how
744 many file descriptors the @code{ftw} function is allowed to consume.
745 The more descriptors can be used the faster the function can run. For
746 each level of directories at most one descriptor is used so that for
747 very deep directory hierarchies the limit on open file descriptors for
748 the process or the system can be exceeded. Beside this the limit on
749 file descriptors is counted together for all threads in a multi-threaded
750 program and therefore it is always good too limit the maximal number of
751 open descriptors to a reasonable number.
753 The return value of the @code{ftw} function is @math{0} if all callback
754 function calls returned @math{0} and all actions performed by the
755 @code{ftw} succeeded. If some function call failed (other than calling
756 @code{stat} on an item) the function return @math{-1}. If a callback
757 function returns a value other than @math{0} this value is returned as
758 the return value of @code{ftw}.
760 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
761 32 bits system this function is in fact @code{ftw64}. I.e., the LFS
762 interface transparently replaces the old interface.
767 @deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors})
768 This function is similar to @code{ftw} but it can work on filesystems
769 with large files since the information about the files is reported using
770 a variable of type @code{struct stat64} which is passed by reference to
771 the callback function.
773 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
774 32 bits system this function is available under the name @code{ftw} and
775 transparently replaces the old implementation.
780 @deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag})
781 The @code{nftw} functions works like the @code{ftw} functions. It calls
782 the callback function @var{func} for all items it finds in the directory
783 @var{filename} and below. At most @var{descriptors} file descriptors
784 are consumed during the @code{nftw} call.
786 The differences are that for one the callback function is of a different
787 type. It is of type @w{@code{struct FTW *}} and provides the callback
788 functions the information described above.
790 The second difference is that @code{nftw} takes an additional fourth
791 argument which is @math{0} or a combination of any of the following
792 values, combined using bitwise OR.
796 While traversing the directory symbolic links are not followed. I.e.,
797 if this flag is given symbolic links are reported using the
798 @code{FTW_SL} value for the type parameter to the callback function.
799 Please note that if this flag is used the appearance of @code{FTW_SL} in
800 a callback function does not mean the referenced file does not exist.
801 To indicate this the extra value @code{FTW_SLN} exists.
803 The callback function is only called for items which are on the same
804 mounted filesystem as the directory given as the @var{filename}
805 parameter to @code{nftw}.
807 If this flag is given the current working directory is changed to the
808 directory containing the reported object before the callback function is
811 If this option is given the function visits first all files and
812 subdirectories before the callback function is called for the directory
813 itself (depth-first processing). This also means the type flag given to
814 the callback function is @code{FTW_DP} and not @code{FTW_D}.
817 The return value is computed in the same way as for @code{ftw}.
818 @code{nftw} return @math{0} if no failure occurred in @code{nftw} and
819 all callback function call return values are also @math{0}. For
820 internal errors such as memory problems @math{-1} is returned and
821 @var{errno} is set accordingly. If the return value of a callback
822 invocation is nonzero this very same value is returned.
824 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
825 32 bits system this function is in fact @code{nftw64}. I.e., the LFS
826 interface transparently replaces the old interface.
831 @deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag})
832 This function is similar to @code{nftw} but it can work on filesystems
833 with large files since the information about the files is reported using
834 a variable of type @code{struct stat64} which is passed by reference to
835 the callback function.
837 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
838 32 bits system this function is available under the name @code{nftw} and
839 transparently replaces the old implementation.
847 @cindex multiple names for one file
848 @cindex file names, multiple
850 In POSIX systems, one file can have many names at the same time. All of
851 the names are equally real, and no one of them is preferred to the
854 To add a name to a file, use the @code{link} function. (The new name is
855 also called a @dfn{hard link} to the file.) Creating a new link to a
856 file does not copy the contents of the file; it simply makes a new name
857 by which the file can be known, in addition to the file's existing name
860 One file can have names in several directories, so the organization
861 of the file system is not a strict hierarchy or tree.
863 In most implementations, it is not possible to have hard links to the
864 same file in multiple file systems. @code{link} reports an error if you
865 try to make a hard link to the file from another file system when this
868 The prototype for the @code{link} function is declared in the header
869 file @file{unistd.h}.
874 @deftypefun int link (const char *@var{oldname}, const char *@var{newname})
875 The @code{link} function makes a new link to the existing file named by
876 @var{oldname}, under the new name @var{newname}.
878 This function returns a value of @code{0} if it is successful and
879 @code{-1} on failure. In addition to the usual file name errors
880 (@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the
881 following @code{errno} error conditions are defined for this function:
885 You are not allowed to write the directory in which the new link is to
888 Some implementations also require that the existing file be accessible
889 by the caller, and use this error to report failure for that reason.
893 There is already a file named @var{newname}. If you want to replace
894 this link with a new link, you must remove the old link explicitly first.
897 There are already too many links to the file named by @var{oldname}.
898 (The maximum number of links to a file is @w{@code{LINK_MAX}}; see
899 @ref{Limits for Files}.)
902 The file named by @var{oldname} doesn't exist. You can't make a link to
903 a file that doesn't exist.
906 The directory or file system that would contain the new link is full
907 and cannot be extended.
910 In the GNU system and some others, you cannot make links to directories.
911 Many systems allow only privileged users to do so. This error
912 is used to report the problem.
915 The directory containing the new link can't be modified because it's on
916 a read-only file system.
919 The directory specified in @var{newname} is on a different file system
920 than the existing file.
923 A hardware error occurred while trying to read or write the to filesystem.
928 @section Symbolic Links
931 @cindex symbolic link
932 @cindex link, symbolic
934 The GNU system supports @dfn{soft links} or @dfn{symbolic links}. This
935 is a kind of ``file'' that is essentially a pointer to another file
936 name. Unlike hard links, symbolic links can be made to directories or
937 across file systems with no restrictions. You can also make a symbolic
938 link to a name which is not the name of any file. (Opening this link
939 will fail until a file by that name is created.) Likewise, if the
940 symbolic link points to an existing file which is later deleted, the
941 symbolic link continues to point to the same file name even though the
942 name no longer names any file.
944 The reason symbolic links work the way they do is that special things
945 happen when you try to open the link. The @code{open} function realizes
946 you have specified the name of a link, reads the file name contained in
947 the link, and opens that file name instead. The @code{stat} function
948 likewise operates on the file that the symbolic link points to, instead
949 of on the link itself.
951 By contrast, other operations such as deleting or renaming the file
952 operate on the link itself. The functions @code{readlink} and
953 @code{lstat} also refrain from following symbolic links, because their
954 purpose is to obtain information about the link. So does @code{link},
955 the function that makes a hard link---it makes a hard link to the
956 symbolic link, which one rarely wants.
958 Prototypes for the functions listed in this section are in
964 @deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
965 The @code{symlink} function makes a symbolic link to @var{oldname} named
968 The normal return value from @code{symlink} is @code{0}. A return value
969 of @code{-1} indicates an error. In addition to the usual file name
970 syntax errors (@pxref{File Name Errors}), the following @code{errno}
971 error conditions are defined for this function:
975 There is already an existing file named @var{newname}.
978 The file @var{newname} would exist on a read-only file system.
981 The directory or file system cannot be extended to make the new link.
984 A hardware error occurred while reading or writing data on the disk.
987 @comment not sure about these
989 There are too many levels of indirection. This can be the result of
990 circular symbolic links to directories.
993 The new link can't be created because the user's disk quota has been
1001 @deftypefun int readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size})
1002 The @code{readlink} function gets the value of the symbolic link
1003 @var{filename}. The file name that the link points to is copied into
1004 @var{buffer}. This file name string is @emph{not} null-terminated;
1005 @code{readlink} normally returns the number of characters copied. The
1006 @var{size} argument specifies the maximum number of characters to copy,
1007 usually the allocation size of @var{buffer}.
1009 If the return value equals @var{size}, you cannot tell whether or not
1010 there was room to return the entire name. So make a bigger buffer and
1011 call @code{readlink} again. Here is an example:
1015 readlink_malloc (char *filename)
1021 char *buffer = (char *) xmalloc (size);
1022 int nchars = readlink (filename, buffer, size);
1031 @c @group Invalid outside example.
1032 A value of @code{-1} is returned in case of error. In addition to the
1033 usual file name errors (@pxref{File Name Errors}), the following
1034 @code{errno} error conditions are defined for this function:
1038 The named file is not a symbolic link.
1041 A hardware error occurred while reading or writing data on the disk.
1046 @node Deleting Files
1047 @section Deleting Files
1048 @cindex deleting a file
1049 @cindex removing a file
1050 @cindex unlinking a file
1052 You can delete a file with the functions @code{unlink} or @code{remove}.
1054 Deletion actually deletes a file name. If this is the file's only name,
1055 then the file is deleted as well. If the file has other names as well
1056 (@pxref{Hard Links}), it remains accessible under its other names.
1060 @deftypefun int unlink (const char *@var{filename})
1061 The @code{unlink} function deletes the file name @var{filename}. If
1062 this is a file's sole name, the file itself is also deleted. (Actually,
1063 if any process has the file open when this happens, deletion is
1064 postponed until all processes have closed the file.)
1067 The function @code{unlink} is declared in the header file @file{unistd.h}.
1069 This function returns @code{0} on successful completion, and @code{-1}
1070 on error. In addition to the usual file name errors
1071 (@pxref{File Name Errors}), the following @code{errno} error conditions are
1072 defined for this function:
1076 Write permission is denied for the directory from which the file is to be
1077 removed, or the directory has the sticky bit set and you do not own the file.
1080 This error indicates that the file is being used by the system in such a
1081 way that it can't be unlinked. For example, you might see this error if
1082 the file name specifies the root directory or a mount point for a file
1086 The file name to be deleted doesn't exist.
1089 On some systems, @code{unlink} cannot be used to delete the name of a
1090 directory, or can only be used this way by a privileged user.
1091 To avoid such problems, use @code{rmdir} to delete directories.
1092 (In the GNU system @code{unlink} can never delete the name of a directory.)
1095 The directory in which the file name is to be deleted is on a read-only
1096 file system, and can't be modified.
1102 @deftypefun int rmdir (const char *@var{filename})
1103 @cindex directories, deleting
1104 @cindex deleting a directory
1105 The @code{rmdir} function deletes a directory. The directory must be
1106 empty before it can be removed; in other words, it can only contain
1107 entries for @file{.} and @file{..}.
1109 In most other respects, @code{rmdir} behaves like @code{unlink}. There
1110 are two additional @code{errno} error conditions defined for
1116 The directory to be deleted is not empty.
1119 These two error codes are synonymous; some systems use one, and some use
1120 the other. The GNU system always uses @code{ENOTEMPTY}.
1122 The prototype for this function is declared in the header file
1129 @deftypefun int remove (const char *@var{filename})
1130 This is the @w{ISO C} function to remove a file. It works like
1131 @code{unlink} for files and like @code{rmdir} for directories.
1132 @code{remove} is declared in @file{stdio.h}.
1136 @node Renaming Files
1137 @section Renaming Files
1139 The @code{rename} function is used to change a file's name.
1141 @cindex renaming a file
1144 @deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
1145 The @code{rename} function renames the file name @var{oldname} with
1146 @var{newname}. The file formerly accessible under the name
1147 @var{oldname} is afterward accessible as @var{newname} instead. (If the
1148 file had any other names aside from @var{oldname}, it continues to have
1151 The directory containing the name @var{newname} must be on the same
1152 file system as the file (as indicated by the name @var{oldname}).
1154 One special case for @code{rename} is when @var{oldname} and
1155 @var{newname} are two names for the same file. The consistent way to
1156 handle this case is to delete @var{oldname}. However, POSIX requires
1157 that in this case @code{rename} do nothing and report success---which is
1158 inconsistent. We don't know what your operating system will do.
1160 If the @var{oldname} is not a directory, then any existing file named
1161 @var{newname} is removed during the renaming operation. However, if
1162 @var{newname} is the name of a directory, @code{rename} fails in this
1165 If the @var{oldname} is a directory, then either @var{newname} must not
1166 exist or it must name a directory that is empty. In the latter case,
1167 the existing directory named @var{newname} is deleted first. The name
1168 @var{newname} must not specify a subdirectory of the directory
1169 @code{oldname} which is being renamed.
1171 One useful feature of @code{rename} is that the meaning of the name
1172 @var{newname} changes ``atomically'' from any previously existing file
1173 by that name to its new meaning (the file that was called
1174 @var{oldname}). There is no instant at which @var{newname} is
1175 nonexistent ``in between'' the old meaning and the new meaning. If
1176 there is a system crash during the operation, it is possible for both
1177 names to still exist; but @var{newname} will always be intact if it
1180 If @code{rename} fails, it returns @code{-1}. In addition to the usual
1181 file name errors (@pxref{File Name Errors}), the following
1182 @code{errno} error conditions are defined for this function:
1186 One of the directories containing @var{newname} or @var{oldname}
1187 refuses write permission; or @var{newname} and @var{oldname} are
1188 directories and write permission is refused for one of them.
1191 A directory named by @var{oldname} or @var{newname} is being used by
1192 the system in a way that prevents the renaming from working. This includes
1193 directories that are mount points for filesystems, and directories
1194 that are the current working directories of processes.
1198 The directory @var{newname} isn't empty. The GNU system always returns
1199 @code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}.
1202 The @var{oldname} is a directory that contains @var{newname}.
1205 The @var{newname} names a directory, but the @var{oldname} doesn't.
1208 The parent directory of @var{newname} would have too many links.
1211 The file named by @var{oldname} doesn't exist.
1214 The directory that would contain @var{newname} has no room for another
1215 entry, and there is no space left in the file system to expand it.
1218 The operation would involve writing to a directory on a read-only file
1222 The two file names @var{newname} and @var{oldnames} are on different
1227 @node Creating Directories
1228 @section Creating Directories
1229 @cindex creating a directory
1230 @cindex directories, creating
1233 Directories are created with the @code{mkdir} function. (There is also
1234 a shell command @code{mkdir} which does the same thing.)
1239 @deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode})
1240 The @code{mkdir} function creates a new, empty directory whose name is
1243 The argument @var{mode} specifies the file permissions for the new
1244 directory file. @xref{Permission Bits}, for more information about
1247 A return value of @code{0} indicates successful completion, and
1248 @code{-1} indicates failure. In addition to the usual file name syntax
1249 errors (@pxref{File Name Errors}), the following @code{errno} error
1250 conditions are defined for this function:
1254 Write permission is denied for the parent directory in which the new
1255 directory is to be added.
1258 A file named @var{filename} already exists.
1261 The parent directory has too many links.
1263 Well-designed file systems never report this error, because they permit
1264 more links than your disk could possibly hold. However, you must still
1265 take account of the possibility of this error, as it could result from
1266 network access to a file system on another machine.
1269 The file system doesn't have enough room to create the new directory.
1272 The parent directory of the directory being created is on a read-only
1273 file system, and cannot be modified.
1276 To use this function, your program should include the header file
1281 @node File Attributes
1282 @section File Attributes
1285 When you issue an @samp{ls -l} shell command on a file, it gives you
1286 information about the size of the file, who owns it, when it was last
1287 modified, and the like. This kind of information is called the
1288 @dfn{file attributes}; it is associated with the file itself and not a
1289 particular one of its names.
1291 This section contains information about how you can inquire about and
1292 modify these attributes of files.
1295 * Attribute Meanings:: The names of the file attributes,
1296 and what their values mean.
1297 * Reading Attributes:: How to read the attributes of a file.
1298 * Testing File Type:: Distinguishing ordinary files,
1299 directories, links...
1300 * File Owner:: How ownership for new files is determined,
1301 and how to change it.
1302 * Permission Bits:: How information about a file's access
1304 * Access Permission:: How the system decides who can access a file.
1305 * Setting Permissions:: How permissions for new files are assigned,
1306 and how to change them.
1307 * Testing File Access:: How to find out if your process can
1309 * File Times:: About the time attributes of a file.
1312 @node Attribute Meanings
1313 @subsection What the File Attribute Values Mean
1314 @cindex status of a file
1315 @cindex attributes of a file
1316 @cindex file attributes
1318 When you read the attributes of a file, they come back in a structure
1319 called @code{struct stat}. This section describes the names of the
1320 attributes, their data types, and what they mean. For the functions
1321 to read the attributes of a file, see @ref{Reading Attributes}.
1323 The header file @file{sys/stat.h} declares all the symbols defined
1329 @deftp {Data Type} {struct stat}
1330 The @code{stat} structure type is used to return information about the
1331 attributes of a file. It contains at least the following members:
1334 @item mode_t st_mode
1335 Specifies the mode of the file. This includes file type information
1336 (@pxref{Testing File Type}) and the file permission bits
1337 (@pxref{Permission Bits}).
1340 The file serial number, which distinguishes this file from all other
1341 files on the same device.
1344 Identifies the device containing the file. The @code{st_ino} and
1345 @code{st_dev}, taken together, uniquely identify the file. The
1346 @code{st_dev} value is not necessarily consistent across reboots or
1347 system crashes, however.
1349 @item nlink_t st_nlink
1350 The number of hard links to the file. This count keeps track of how
1351 many directories have entries for this file. If the count is ever
1352 decremented to zero, then the file itself is discarded as soon as no
1353 process still holds it open. Symbolic links are not counted in the
1357 The user ID of the file's owner. @xref{File Owner}.
1360 The group ID of the file. @xref{File Owner}.
1363 This specifies the size of a regular file in bytes. For files that
1364 are really devices and the like, this field isn't usually meaningful.
1365 For symbolic links, this specifies the length of the file name the link
1368 @item time_t st_atime
1369 This is the last access time for the file. @xref{File Times}.
1371 @item unsigned long int st_atime_usec
1372 This is the fractional part of the last access time for the file.
1375 @item time_t st_mtime
1376 This is the time of the last modification to the contents of the file.
1379 @item unsigned long int st_mtime_usec
1380 This is the fractional part of the time of last modification to the
1381 contents of the file. @xref{File Times}.
1383 @item time_t st_ctime
1384 This is the time of the last modification to the attributes of the file.
1387 @item unsigned long int st_ctime_usec
1388 This is the fractional part of the time of last modification to the
1389 attributes of the file. @xref{File Times}.
1392 @item blkcnt_t st_blocks
1393 This is the amount of disk space that the file occupies, measured in
1394 units of 512-byte blocks.
1396 The number of disk blocks is not strictly proportional to the size of
1397 the file, for two reasons: the file system may use some blocks for
1398 internal record keeping; and the file may be sparse---it may have
1399 ``holes'' which contain zeros but do not actually take up space on the
1402 You can tell (approximately) whether a file is sparse by comparing this
1403 value with @code{st_size}, like this:
1406 (st.st_blocks * 512 < st.st_size)
1409 This test is not perfect because a file that is just slightly sparse
1410 might not be detected as sparse at all. For practical applications,
1411 this is not a problem.
1413 @item unsigned int st_blksize
1414 The optimal block size for reading of writing this file, in bytes. You
1415 might use this size for allocating the buffer space for reading of
1416 writing the file. (This is unrelated to @code{st_blocks}.)
1420 Some of the file attributes have special data type names which exist
1421 specifically for those attributes. (They are all aliases for well-known
1422 integer types that you know and love.) These typedef names are defined
1423 in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
1424 Here is a list of them.
1426 The extensions for the Large File Support (LFS) require even on 32 bits
1427 machine types which can handle file sizes up to @math{2^63}. Therefore
1428 a new definition of @code{struct stat} is necessary.
1432 @deftp {Data Type} {struct stat64}
1433 The members of this type are the same and have the same names as those
1434 in @code{struct stat}. The only difference is that the members
1435 @code{st_ino}, @code{st_size}, and @code{st_blocks} have a different
1436 type to support larger values.
1439 @item mode_t st_mode
1440 Specifies the mode of the file. This includes file type information
1441 (@pxref{Testing File Type}) and the file permission bits
1442 (@pxref{Permission Bits}).
1444 @item ino64_t st_ino
1445 The file serial number, which distinguishes this file from all other
1446 files on the same device.
1449 Identifies the device containing the file. The @code{st_ino} and
1450 @code{st_dev}, taken together, uniquely identify the file. The
1451 @code{st_dev} value is not necessarily consistent across reboots or
1452 system crashes, however.
1454 @item nlink_t st_nlink
1455 The number of hard links to the file. This count keeps track of how
1456 many directories have entries for this file. If the count is ever
1457 decremented to zero, then the file itself is discarded as soon as no
1458 process still holds it open. Symbolic links are not counted in the
1462 The user ID of the file's owner. @xref{File Owner}.
1465 The group ID of the file. @xref{File Owner}.
1467 @item off64_t st_size
1468 This specifies the size of a regular file in bytes. For files that
1469 are really devices and the like, this field isn't usually meaningful.
1470 For symbolic links, this specifies the length of the file name the link
1473 @item time_t st_atime
1474 This is the last access time for the file. @xref{File Times}.
1476 @item unsigned long int st_atime_usec
1477 This is the fractional part of the last access time for the file.
1480 @item time_t st_mtime
1481 This is the time of the last modification to the contents of the file.
1484 @item unsigned long int st_mtime_usec
1485 This is the fractional part of the time of last modification to the
1486 contents of the file. @xref{File Times}.
1488 @item time_t st_ctime
1489 This is the time of the last modification to the attributes of the file.
1492 @item unsigned long int st_ctime_usec
1493 This is the fractional part of the time of last modification to the
1494 attributes of the file. @xref{File Times}.
1497 @item blkcnt64_t st_blocks
1498 This is the amount of disk space that the file occupies, measured in
1499 units of 512-byte blocks.
1501 @item unsigned int st_blksize
1502 The optimal block size for reading of writing this file, in bytes. You
1503 might use this size for allocating the buffer space for reading of
1504 writing the file. (This is unrelated to @code{st_blocks}.)
1508 @comment sys/types.h
1510 @deftp {Data Type} mode_t
1511 This is an integer data type used to represent file modes. In the
1512 GNU system, this is equivalent to @code{unsigned int}.
1515 @cindex inode number
1516 @comment sys/types.h
1518 @deftp {Data Type} ino_t
1519 This is an arithmetic data type used to represent file serial numbers.
1520 (In Unix jargon, these are sometimes called @dfn{inode numbers}.)
1521 In the GNU system, this type is equivalent to @code{unsigned long int}.
1523 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
1524 is transparently replaced by @code{ino64_t}.
1527 @comment sys/types.h
1529 @deftp {Data Type} ino64_t
1530 This is an arithmetic data type used to represent file serial numbers
1531 for the use in LFS. In the GNU system, this type is equivalent to
1532 @code{unsigned long longint}.
1534 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
1535 available under the name @code{ino_t}.
1538 @comment sys/types.h
1540 @deftp {Data Type} dev_t
1541 This is an arithmetic data type used to represent file device numbers.
1542 In the GNU system, this is equivalent to @code{int}.
1545 @comment sys/types.h
1547 @deftp {Data Type} nlink_t
1548 This is an arithmetic data type used to represent file link counts.
1549 In the GNU system, this is equivalent to @code{unsigned short int}.
1552 @comment sys/types.h
1554 @deftp {Data Type} blkcnt_t
1555 This is an arithmetic data type used to represent block counts.
1556 In the GNU system, this is equivalent to @code{unsigned long int}.
1558 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
1559 is transparently replaced by @code{blkcnt64_t}.
1562 @comment sys/types.h
1564 @deftp {Data Type} blkcnt64_t
1565 This is an arithmetic data type used to represent block counts for the
1566 use in LFS. In the GNU system, this is equivalent to @code{unsigned
1569 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
1570 available under the name @code{blkcnt_t}.
1573 @node Reading Attributes
1574 @subsection Reading the Attributes of a File
1576 To examine the attributes of files, use the functions @code{stat},
1577 @code{fstat} and @code{lstat}. They return the attribute information in
1578 a @code{struct stat} object. All three functions are declared in the
1579 header file @file{sys/stat.h}.
1583 @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf})
1584 The @code{stat} function returns information about the attributes of the
1585 file named by @w{@var{filename}} in the structure pointed at by @var{buf}.
1587 If @var{filename} is the name of a symbolic link, the attributes you get
1588 describe the file that the link points to. If the link points to a
1589 nonexistent file name, then @code{stat} fails, reporting a nonexistent
1592 The return value is @code{0} if the operation is successful, and @code{-1}
1593 on failure. In addition to the usual file name errors
1594 (@pxref{File Name Errors}, the following @code{errno} error conditions
1595 are defined for this function:
1599 The file named by @var{filename} doesn't exist.
1602 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1603 function is in fact @code{stat64} since the LFS interface transparently
1604 replaces the normal implementation.
1609 @deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf})
1610 This function is similar to @code{stat} but it is also able to work on
1611 file larger then @math{2^31} bytes on 32 bits systems. To be able to do
1612 this the result is stored in a variable of type @code{struct stat64} to
1613 which @var{buf} must point.
1615 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1616 function is available under the name @code{stat} and so transparently
1617 replaces the interface for small fiels on 32 bits machines.
1622 @deftypefun int fstat (int @var{filedes}, struct stat *@var{buf})
1623 The @code{fstat} function is like @code{stat}, except that it takes an
1624 open file descriptor as an argument instead of a file name.
1625 @xref{Low-Level I/O}.
1627 Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1}
1628 on failure. The following @code{errno} error conditions are defined for
1633 The @var{filedes} argument is not a valid file descriptor.
1636 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1637 function is in fact @code{fstat64} since the LFS interface transparently
1638 replaces the normal implementation.
1643 @deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf})
1644 This function is similar to @code{fstat} but it is prepared to work on
1645 large files on 32 bits platforms. For large files the file descriptor
1646 @var{filedes} should be returned by @code{open64} or @code{creat64}.
1647 The @var{buf} pointer points to a variable of type @code{struct stat64}
1648 which is able to represent the larger values.
1650 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1651 function is available under the name @code{fstat} and so transparently
1652 replaces the interface for small fiels on 32 bits machines.
1657 @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
1658 The @code{lstat} function is like @code{stat}, except that it does not
1659 follow symbolic links. If @var{filename} is the name of a symbolic
1660 link, @code{lstat} returns information about the link itself; otherwise,
1661 @code{lstat} works like @code{stat}. @xref{Symbolic Links}.
1663 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1664 function is in fact @code{lstat64} since the LFS interface transparently
1665 replaces the normal implementation.
1670 @deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf})
1671 This function is similar to @code{lstat} but it is also able to work on
1672 file larger then @math{2^31} bytes on 32 bits systems. To be able to do
1673 this the result is stored in a variable of type @code{struct stat64} to
1674 which @var{buf} must point.
1676 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
1677 function is available under the name @code{lstat} and so transparently
1678 replaces the interface for small fiels on 32 bits machines.
1681 @node Testing File Type
1682 @subsection Testing the Type of a File
1684 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1685 attributes, contains two kinds of information: the file type code, and
1686 the access permission bits. This section discusses only the type code,
1687 which you can use to tell whether the file is a directory, whether it is
1688 a socket, and so on. For information about the access permission,
1689 @ref{Permission Bits}.
1691 There are two predefined ways you can access the file type portion of
1692 the file mode. First of all, for each type of file, there is a
1693 @dfn{predicate macro} which examines a file mode value and returns
1694 true or false---is the file of that type, or not. Secondly, you can
1695 mask out the rest of the file mode to get just a file type code.
1696 You can compare this against various constants for the supported file
1699 All of the symbols listed in this section are defined in the header file
1703 The following predicate macros test the type of a file, given the value
1704 @var{m} which is the @code{st_mode} field returned by @code{stat} on
1709 @deftypefn Macro int S_ISDIR (mode_t @var{m})
1710 This macro returns nonzero if the file is a directory.
1715 @deftypefn Macro int S_ISCHR (mode_t @var{m})
1716 This macro returns nonzero if the file is a character special file (a
1717 device like a terminal).
1722 @deftypefn Macro int S_ISBLK (mode_t @var{m})
1723 This macro returns nonzero if the file is a block special file (a device
1729 @deftypefn Macro int S_ISREG (mode_t @var{m})
1730 This macro returns nonzero if the file is a regular file.
1735 @deftypefn Macro int S_ISFIFO (mode_t @var{m})
1736 This macro returns nonzero if the file is a FIFO special file, or a
1737 pipe. @xref{Pipes and FIFOs}.
1742 @deftypefn Macro int S_ISLNK (mode_t @var{m})
1743 This macro returns nonzero if the file is a symbolic link.
1744 @xref{Symbolic Links}.
1749 @deftypefn Macro int S_ISSOCK (mode_t @var{m})
1750 This macro returns nonzero if the file is a socket. @xref{Sockets}.
1753 An alternate non-POSIX method of testing the file type is supported for
1754 compatibility with BSD. The mode can be bitwise ANDed with
1755 @code{S_IFMT} to extract the file type code, and compared to the
1756 appropriate type code constant. For example,
1759 S_ISCHR (@var{mode})
1766 ((@var{mode} & S_IFMT) == S_IFCHR)
1771 @deftypevr Macro int S_IFMT
1772 This is a bit mask used to extract the file type code portion of a mode
1776 These are the symbolic names for the different file type codes:
1783 This macro represents the value of the file type code for a directory file.
1789 This macro represents the value of the file type code for a
1790 character-oriented device file.
1796 This macro represents the value of the file type code for a block-oriented
1803 This macro represents the value of the file type code for a regular file.
1809 This macro represents the value of the file type code for a symbolic link.
1815 This macro represents the value of the file type code for a socket.
1821 This macro represents the value of the file type code for a FIFO or pipe.
1825 @subsection File Owner
1827 @cindex owner of a file
1828 @cindex group owner of a file
1830 Every file has an @dfn{owner} which is one of the registered user names
1831 defined on the system. Each file also has a @dfn{group}, which is one
1832 of the defined groups. The file owner can often be useful for showing
1833 you who edited the file (especially when you edit with GNU Emacs), but
1834 its main purpose is for access control.
1836 The file owner and group play a role in determining access because the
1837 file has one set of access permission bits for the user that is the
1838 owner, another set that apply to users who belong to the file's group,
1839 and a third set of bits that apply to everyone else. @xref{Access
1840 Permission}, for the details of how access is decided based on this
1843 When a file is created, its owner is set from the effective user ID of
1844 the process that creates it (@pxref{Process Persona}). The file's group
1845 ID may be set from either effective group ID of the process, or the
1846 group ID of the directory that contains the file, depending on the
1847 system where the file is stored. When you access a remote file system,
1848 it behaves according to its own rule, not according to the system your
1849 program is running on. Thus, your program must be prepared to encounter
1850 either kind of behavior, no matter what kind of system you run it on.
1854 You can change the owner and/or group owner of an existing file using
1855 the @code{chown} function. This is the primitive for the @code{chown}
1856 and @code{chgrp} shell commands.
1859 The prototype for this function is declared in @file{unistd.h}.
1863 @deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group})
1864 The @code{chown} function changes the owner of the file @var{filename} to
1865 @var{owner}, and its group owner to @var{group}.
1867 Changing the owner of the file on certain systems clears the set-user-ID
1868 and set-group-ID bits of the file's permissions. (This is because those
1869 bits may not be appropriate for the new owner.) The other file
1870 permission bits are not changed.
1872 The return value is @code{0} on success and @code{-1} on failure.
1873 In addition to the usual file name errors (@pxref{File Name Errors}),
1874 the following @code{errno} error conditions are defined for this function:
1878 This process lacks permission to make the requested change.
1880 Only privileged users or the file's owner can change the file's group.
1881 On most file systems, only privileged users can change the file owner;
1882 some file systems allow you to change the owner if you are currently the
1883 owner. When you access a remote file system, the behavior you encounter
1884 is determined by the system that actually holds the file, not by the
1885 system your program is running on.
1887 @xref{Options for Files}, for information about the
1888 @code{_POSIX_CHOWN_RESTRICTED} macro.
1891 The file is on a read-only file system.
1897 @deftypefun int fchown (int @var{filedes}, int @var{owner}, int @var{group})
1898 This is like @code{chown}, except that it changes the owner of the file
1899 with open file descriptor @var{filedes}.
1901 The return value from @code{fchown} is @code{0} on success and @code{-1}
1902 on failure. The following @code{errno} error codes are defined for this
1907 The @var{filedes} argument is not a valid file descriptor.
1910 The @var{filedes} argument corresponds to a pipe or socket, not an ordinary
1914 This process lacks permission to make the requested change. For
1915 details, see @code{chmod}, above.
1918 The file resides on a read-only file system.
1922 @node Permission Bits
1923 @subsection The Mode Bits for Access Permission
1925 The @dfn{file mode}, stored in the @code{st_mode} field of the file
1926 attributes, contains two kinds of information: the file type code, and
1927 the access permission bits. This section discusses only the access
1928 permission bits, which control who can read or write the file.
1929 @xref{Testing File Type}, for information about the file type code.
1931 All of the symbols listed in this section are defined in the header file
1935 @cindex file permission bits
1936 These symbolic constants are defined for the file mode bits that control
1937 access permission for the file:
1948 Read permission bit for the owner of the file. On many systems, this
1949 bit is 0400. @code{S_IREAD} is an obsolete synonym provided for BSD
1960 Write permission bit for the owner of the file. Usually 0200.
1961 @w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility.
1971 Execute (for ordinary files) or search (for directories) permission bit
1972 for the owner of the file. Usually 0100. @code{S_IEXEC} is an obsolete
1973 synonym provided for BSD compatibility.
1979 This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
1985 Read permission bit for the group owner of the file. Usually 040.
1991 Write permission bit for the group owner of the file. Usually 020.
1997 Execute or search permission bit for the group owner of the file.
2004 This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
2010 Read permission bit for other users. Usually 04.
2016 Write permission bit for other users. Usually 02.
2022 Execute or search permission bit for other users. Usually 01.
2028 This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
2034 This is the set-user-ID on execute bit, usually 04000.
2035 @xref{How Change Persona}.
2041 This is the set-group-ID on execute bit, usually 02000.
2042 @xref{How Change Persona}.
2049 This is the @dfn{sticky} bit, usually 01000.
2051 On a directory, it gives permission to delete a file in the directory
2052 only if you own that file. Ordinarily, a user either can delete all the
2053 files in the directory or cannot delete any of them (based on whether
2054 the user has write permission for the directory). The same restriction
2055 applies---you must both have write permission for the directory and own
2056 the file you want to delete. The one exception is that the owner of the
2057 directory can delete any file in the directory, no matter who owns it
2058 (provided the owner has given himself write permission for the
2059 directory). This is commonly used for the @file{/tmp} directory, where
2060 anyone may create files, but not delete files created by other users.
2062 Originally the sticky bit on an executable file modified the swapping
2063 policies of the system. Normally, when a program terminated, its pages
2064 in core were immediately freed and reused. If the sticky bit was set on
2065 the executable file, the system kept the pages in core for a while as if
2066 the program were still running. This was advantageous for a program
2067 likely to be run many times in succession. This usage is obsolete in
2068 modern systems. When a program terminates, its pages always remain in
2069 core as long as there is no shortage of memory in the system. When the
2070 program is next run, its pages will still be in core if no shortage
2071 arose since the last run.
2073 On some modern systems where the sticky bit has no useful meaning for an
2074 executable file, you cannot set the bit at all for a non-directory.
2075 If you try, @code{chmod} fails with @code{EFTYPE};
2076 @pxref{Setting Permissions}.
2078 Some systems (particularly SunOS) have yet another use for the sticky
2079 bit. If the sticky bit is set on a file that is @emph{not} executable,
2080 it means the opposite: never cache the pages of this file at all. The
2081 main use of this is for the files on an NFS server machine which are
2082 used as the swap area of diskless client machines. The idea is that the
2083 pages of the file will be cached in the client's memory, so it is a
2084 waste of the server's memory to cache them a second time. In this use
2085 the sticky bit also says that the filesystem may fail to record the
2086 file's modification time onto disk reliably (the idea being that no-one
2087 cares for a swap file).
2089 This bit is only available on BSD systems (and those derived from
2090 them). Therefore one has to use the @code{_BSD_SOURCE} feature select
2091 macro to get the definition (@pxref{Feature Test Macros}).
2094 The actual bit values of the symbols are listed in the table above
2095 so you can decode file mode values when debugging your programs.
2096 These bit values are correct for most systems, but they are not
2099 @strong{Warning:} Writing explicit numbers for file permissions is bad
2100 practice. It is not only non-portable, it also requires everyone who
2101 reads your program to remember what the bits mean. To make your
2102 program clean, use the symbolic names.
2104 @node Access Permission
2105 @subsection How Your Access to a File is Decided
2106 @cindex permission to access a file
2107 @cindex access permission for a file
2108 @cindex file access permission
2110 Recall that the operating system normally decides access permission for
2111 a file based on the effective user and group IDs of the process, and its
2112 supplementary group IDs, together with the file's owner, group and
2113 permission bits. These concepts are discussed in detail in
2114 @ref{Process Persona}.
2116 If the effective user ID of the process matches the owner user ID of the
2117 file, then permissions for read, write, and execute/search are
2118 controlled by the corresponding ``user'' (or ``owner'') bits. Likewise,
2119 if any of the effective group ID or supplementary group IDs of the
2120 process matches the group owner ID of the file, then permissions are
2121 controlled by the ``group'' bits. Otherwise, permissions are controlled
2122 by the ``other'' bits.
2124 Privileged users, like @samp{root}, can access any file, regardless of
2125 its file permission bits. As a special case, for a file to be
2126 executable even for a privileged user, at least one of its execute bits
2129 @node Setting Permissions
2130 @subsection Assigning File Permissions
2132 @cindex file creation mask
2134 The primitive functions for creating files (for example, @code{open} or
2135 @code{mkdir}) take a @var{mode} argument, which specifies the file
2136 permissions for the newly created file. But the specified mode is
2137 modified by the process's @dfn{file creation mask}, or @dfn{umask},
2140 The bits that are set in the file creation mask identify permissions
2141 that are always to be disabled for newly created files. For example, if
2142 you set all the ``other'' access bits in the mask, then newly created
2143 files are not accessible at all to processes in the ``other''
2144 category, even if the @var{mode} argument specified to the creation
2145 function would permit such access. In other words, the file creation
2146 mask is the complement of the ordinary access permissions you want to
2149 Programs that create files typically specify a @var{mode} argument that
2150 includes all the permissions that make sense for the particular file.
2151 For an ordinary file, this is typically read and write permission for
2152 all classes of users. These permissions are then restricted as
2153 specified by the individual user's own file creation mask.
2156 To change the permission of an existing file given its name, call
2157 @code{chmod}. This function ignores the file creation mask; it uses
2158 exactly the specified permission bits.
2161 In normal use, the file creation mask is initialized in the user's login
2162 shell (using the @code{umask} shell command), and inherited by all
2163 subprocesses. Application programs normally don't need to worry about
2164 the file creation mask. It will do automatically what it is supposed to
2167 When your program should create a file and bypass the umask for its
2168 access permissions, the easiest way to do this is to use @code{fchmod}
2169 after opening the file, rather than changing the umask.
2171 In fact, changing the umask is usually done only by shells. They use
2172 the @code{umask} function.
2174 The functions in this section are declared in @file{sys/stat.h}.
2179 @deftypefun mode_t umask (mode_t @var{mask})
2180 The @code{umask} function sets the file creation mask of the current
2181 process to @var{mask}, and returns the previous value of the file
2184 Here is an example showing how to read the mask with @code{umask}
2185 without changing it permanently:
2197 However, it is better to use @code{getumask} if you just want to read
2198 the mask value, because that is reentrant (at least if you use the GNU
2204 @deftypefun mode_t getumask (void)
2205 Return the current value of the file creation mask for the current
2206 process. This function is a GNU extension.
2211 @deftypefun int chmod (const char *@var{filename}, mode_t @var{mode})
2212 The @code{chmod} function sets the access permission bits for the file
2213 named by @var{filename} to @var{mode}.
2215 If the @var{filename} names a symbolic link, @code{chmod} changes the
2216 permission of the file pointed to by the link, not those of the link
2219 This function returns @code{0} if successful and @code{-1} if not. In
2220 addition to the usual file name errors (@pxref{File Name
2221 Errors}), the following @code{errno} error conditions are defined for
2226 The named file doesn't exist.
2229 This process does not have permission to change the access permission of
2230 this file. Only the file's owner (as judged by the effective user ID of
2231 the process) or a privileged user can change them.
2234 The file resides on a read-only file system.
2237 @var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set,
2238 and the named file is not a directory. Some systems do not allow setting the
2239 sticky bit on non-directory files, and some do (and only some of those
2240 assign a useful meaning to the bit for non-directory files).
2242 You only get @code{EFTYPE} on systems where the sticky bit has no useful
2243 meaning for non-directory files, so it is always safe to just clear the
2244 bit in @var{mode} and call @code{chmod} again. @xref{Permission Bits},
2245 for full details on the sticky bit.
2251 @deftypefun int fchmod (int @var{filedes}, int @var{mode})
2252 This is like @code{chmod}, except that it changes the permissions of
2253 the file currently open via descriptor @var{filedes}.
2255 The return value from @code{fchmod} is @code{0} on success and @code{-1}
2256 on failure. The following @code{errno} error codes are defined for this
2261 The @var{filedes} argument is not a valid file descriptor.
2264 The @var{filedes} argument corresponds to a pipe or socket, or something
2265 else that doesn't really have access permissions.
2268 This process does not have permission to change the access permission of
2269 this file. Only the file's owner (as judged by the effective user ID of
2270 the process) or a privileged user can change them.
2273 The file resides on a read-only file system.
2277 @node Testing File Access
2278 @subsection Testing Permission to Access a File
2279 @cindex testing access permission
2280 @cindex access, testing for
2281 @cindex setuid programs and file access
2283 When a program runs as a privileged user, this permits it to access
2284 files off-limits to ordinary users---for example, to modify
2285 @file{/etc/passwd}. Programs designed to be run by ordinary users but
2286 access such files use the setuid bit feature so that they always run
2287 with @code{root} as the effective user ID.
2289 Such a program may also access files specified by the user, files which
2290 conceptually are being accessed explicitly by the user. Since the
2291 program runs as @code{root}, it has permission to access whatever file
2292 the user specifies---but usually the desired behavior is to permit only
2293 those files which the user could ordinarily access.
2295 The program therefore must explicitly check whether @emph{the user}
2296 would have the necessary access to a file, before it reads or writes the
2299 To do this, use the function @code{access}, which checks for access
2300 permission based on the process's @emph{real} user ID rather than the
2301 effective user ID. (The setuid feature does not alter the real user ID,
2302 so it reflects the user who actually ran the program.)
2304 There is another way you could check this access, which is easy to
2305 describe, but very hard to use. This is to examine the file mode bits
2306 and mimic the system's own access computation. This method is
2307 undesirable because many systems have additional access control
2308 features; your program cannot portably mimic them, and you would not
2309 want to try to keep track of the diverse features that different systems
2310 have. Using @code{access} is simple and automatically does whatever is
2311 appropriate for the system you are using.
2313 @code{access} is @emph{only} only appropriate to use in setuid programs.
2314 A non-setuid program will always use the effective ID rather than the
2318 The symbols in this section are declared in @file{unistd.h}.
2322 @deftypefun int access (const char *@var{filename}, int @var{how})
2323 The @code{access} function checks to see whether the file named by
2324 @var{filename} can be accessed in the way specified by the @var{how}
2325 argument. The @var{how} argument either can be the bitwise OR of the
2326 flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test
2329 This function uses the @emph{real} user and group ID's of the calling
2330 process, rather than the @emph{effective} ID's, to check for access
2331 permission. As a result, if you use the function from a @code{setuid}
2332 or @code{setgid} program (@pxref{How Change Persona}), it gives
2333 information relative to the user who actually ran the program.
2335 The return value is @code{0} if the access is permitted, and @code{-1}
2336 otherwise. (In other words, treated as a predicate function,
2337 @code{access} returns true if the requested access is @emph{denied}.)
2339 In addition to the usual file name errors (@pxref{File Name
2340 Errors}), the following @code{errno} error conditions are defined for
2345 The access specified by @var{how} is denied.
2348 The file doesn't exist.
2351 Write permission was requested for a file on a read-only file system.
2355 These macros are defined in the header file @file{unistd.h} for use
2356 as the @var{how} argument to the @code{access} function. The values
2357 are integer constants.
2362 @deftypevr Macro int R_OK
2363 Argument that means, test for read permission.
2368 @deftypevr Macro int W_OK
2369 Argument that means, test for write permission.
2374 @deftypevr Macro int X_OK
2375 Argument that means, test for execute/search permission.
2380 @deftypevr Macro int F_OK
2381 Argument that means, test for existence of the file.
2385 @subsection File Times
2387 @cindex file access time
2388 @cindex file modification time
2389 @cindex file attribute modification time
2390 Each file has three time stamps associated with it: its access time,
2391 its modification time, and its attribute modification time. These
2392 correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime}
2393 members of the @code{stat} structure; see @ref{File Attributes}.
2395 All of these times are represented in calendar time format, as
2396 @code{time_t} objects. This data type is defined in @file{time.h}.
2397 For more information about representation and manipulation of time
2398 values, see @ref{Calendar Time}.
2401 Reading from a file updates its access time attribute, and writing
2402 updates its modification time. When a file is created, all three
2403 time stamps for that file are set to the current time. In addition, the
2404 attribute change time and modification time fields of the directory that
2405 contains the new entry are updated.
2407 Adding a new name for a file with the @code{link} function updates the
2408 attribute change time field of the file being linked, and both the
2409 attribute change time and modification time fields of the directory
2410 containing the new name. These same fields are affected if a file name
2411 is deleted with @code{unlink}, @code{remove}, or @code{rmdir}. Renaming
2412 a file with @code{rename} affects only the attribute change time and
2413 modification time fields of the two parent directories involved, and not
2414 the times for the file being renamed.
2416 Changing attributes of a file (for example, with @code{chmod}) updates
2417 its attribute change time field.
2419 You can also change some of the time stamps of a file explicitly using
2420 the @code{utime} function---all except the attribute change time. You
2421 need to include the header file @file{utime.h} to use this facility.
2426 @deftp {Data Type} {struct utimbuf}
2427 The @code{utimbuf} structure is used with the @code{utime} function to
2428 specify new access and modification times for a file. It contains the
2433 This is the access time for the file.
2435 @item time_t modtime
2436 This is the modification time for the file.
2442 @deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times})
2443 This function is used to modify the file times associated with the file
2444 named @var{filename}.
2446 If @var{times} is a null pointer, then the access and modification times
2447 of the file are set to the current time. Otherwise, they are set to the
2448 values from the @code{actime} and @code{modtime} members (respectively)
2449 of the @code{utimbuf} structure pointed at by @var{times}.
2451 The attribute modification time for the file is set to the current time
2452 in either case (since changing the time stamps is itself a modification
2453 of the file attributes).
2455 The @code{utime} function returns @code{0} if successful and @code{-1}
2456 on failure. In addition to the usual file name errors
2457 (@pxref{File Name Errors}), the following @code{errno} error conditions
2458 are defined for this function:
2462 There is a permission problem in the case where a null pointer was
2463 passed as the @var{times} argument. In order to update the time stamp on
2464 the file, you must either be the owner of the file, have write
2465 permission on the file, or be a privileged user.
2468 The file doesn't exist.
2471 If the @var{times} argument is not a null pointer, you must either be
2472 the owner of the file or be a privileged user. This error is used to
2476 The file lives on a read-only file system.
2480 Each of the three time stamps has a corresponding microsecond part,
2481 which extends its resolution. These fields are called
2482 @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
2483 each has a value between 0 and 999,999, which indicates the time in
2484 microseconds. They correspond to the @code{tv_usec} field of a
2485 @code{timeval} structure; see @ref{High-Resolution Calendar}.
2487 The @code{utimes} function is like @code{utime}, but also lets you specify
2488 the fractional part of the file times. The prototype for this function is
2489 in the header file @file{sys/time.h}.
2494 @deftypefun int utimes (const char *@var{filename}, struct timeval @var{tvp}@t{[2]})
2495 This function sets the file access and modification times for the file
2496 named by @var{filename}. The new file access time is specified by
2497 @code{@var{tvp}[0]}, and the new modification time by
2498 @code{@var{tvp}[1]}. This function comes from BSD.
2500 The return values and error conditions are the same as for the @code{utime}
2504 @node Making Special Files
2505 @section Making Special Files
2506 @cindex creating special files
2507 @cindex special files
2509 The @code{mknod} function is the primitive for making special files,
2510 such as files that correspond to devices. The GNU library includes
2511 this function for compatibility with BSD.
2513 The prototype for @code{mknod} is declared in @file{sys/stat.h}.
2518 @deftypefun int mknod (const char *@var{filename}, int @var{mode}, int @var{dev})
2519 The @code{mknod} function makes a special file with name @var{filename}.
2520 The @var{mode} specifies the mode of the file, and may include the various
2521 special file bits, such as @code{S_IFCHR} (for a character special file)
2522 or @code{S_IFBLK} (for a block special file). @xref{Testing File Type}.
2524 The @var{dev} argument specifies which device the special file refers to.
2525 Its exact interpretation depends on the kind of special file being created.
2527 The return value is @code{0} on success and @code{-1} on error. In addition
2528 to the usual file name errors (@pxref{File Name Errors}), the
2529 following @code{errno} error conditions are defined for this function:
2533 The calling process is not privileged. Only the superuser can create
2537 The directory or file system that would contain the new file is full
2538 and cannot be extended.
2541 The directory containing the new file can't be modified because it's on
2542 a read-only file system.
2545 There is already a file named @var{filename}. If you want to replace
2546 this file, you must remove the old file explicitly first.
2550 @node Temporary Files
2551 @section Temporary Files
2553 If you need to use a temporary file in your program, you can use the
2554 @code{tmpfile} function to open it. Or you can use the @code{tmpnam}
2555 (better: @code{tmpnam_r}) function make a name for a temporary file and
2556 then open it in the usual way with @code{fopen}.
2558 The @code{tempnam} function is like @code{tmpnam} but lets you choose
2559 what directory temporary files will go in, and something about what
2560 their file names will look like. Important for multi threaded programs
2561 is that @code{tempnam} is reentrant while @code{tmpnam} is not since it
2562 returns a pointer to a static buffer.
2564 These facilities are declared in the header file @file{stdio.h}.
2569 @deftypefun {FILE *} tmpfile (void)
2570 This function creates a temporary binary file for update mode, as if by
2571 calling @code{fopen} with mode @code{"wb+"}. The file is deleted
2572 automatically when it is closed or when the program terminates. (On
2573 some other @w{ISO C} systems the file may fail to be deleted if the program
2574 terminates abnormally).
2576 This function is reentrant.
2578 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
2579 32 bits system this function is in fact @code{tmpfile64}. I.e., the
2580 LFS interface transparently replaces the old interface.
2585 @deftypefun {FILE *} tmpfile64 (void)
2586 This function is similar to @code{tmpfile} but the stream it returns a
2587 pointer for is opened using @code{tmpfile64}. Therefore this stream can be
2588 used even on files larger then @math{2^31} bytes on 32 bits machines.
2590 Please note that the return type is still @code{FILE *}. There is no
2591 special @code{FILE} type for the LFS interface.
2593 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
2594 bits machine this function is available under the name @code{tmpfile}
2595 and so transparently replaces the old interface.
2600 @deftypefun {char *} tmpnam (char *@var{result})
2601 This function constructs and returns a file name that is a valid file
2602 name and that does not name any existing file. If the @var{result}
2603 argument is a null pointer, the return value is a pointer to an internal
2604 static string, which might be modified by subsequent calls and therefore
2605 makes this function non-reentrant. Otherwise, the @var{result} argument
2606 should be a pointer to an array of at least @code{L_tmpnam} characters,
2607 and the result is written into that array.
2609 It is possible for @code{tmpnam} to fail if you call it too many times
2610 without removing previously created files. This is because the fixed
2611 length of a temporary file name gives room for only a finite number of
2612 different names. If @code{tmpnam} fails, it returns a null pointer.
2614 @strong{Warning:} Since between the time the pathname is constructed and
2615 the file is created another process might have created a file with this
2616 name using @code{tmpnam} is a possible security hole. The
2617 implementation generates names which hardly can be predicted but opening
2618 the file in any case should use the @code{O_EXCL} flag. Using
2619 @code{tmpfile} is a safe way to avoid this problem.
2624 @deftypefun {char *} tmpnam_r (char *@var{result})
2625 This function is nearly identical to the @code{tmpnam} function. But it
2626 does not allow @var{result} to be a null pointer. In the later case a
2627 null pointer is returned.
2629 This function is reentrant because the non-reentrant situation of
2630 @code{tmpnam} cannot happen here.
2635 @deftypevr Macro int L_tmpnam
2636 The value of this macro is an integer constant expression that represents
2637 the minimum allocation size of a string large enough to hold the
2638 file name generated by the @code{tmpnam} function.
2643 @deftypevr Macro int TMP_MAX
2644 The macro @code{TMP_MAX} is a lower bound for how many temporary names
2645 you can create with @code{tmpnam}. You can rely on being able to call
2646 @code{tmpnam} at least this many times before it might fail saying you
2647 have made too many temporary file names.
2649 With the GNU library, you can create a very large number of temporary
2650 file names---if you actually create the files, you will probably run out
2651 of disk space before you run out of names. Some other systems have a
2652 fixed, small limit on the number of temporary files. The limit is never
2653 less than @code{25}.
2658 @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
2659 This function generates a unique temporary filename. If @var{prefix} is
2660 not a null pointer, up to five characters of this string are used as a
2661 prefix for the file name. The return value is a string newly allocated
2662 with @code{malloc}; you should release its storage with @code{free} when
2663 it is no longer needed.
2665 Because the string is dynamically allocated this function is reentrant.
2667 The directory prefix for the temporary file name is determined by testing
2668 each of the following, in sequence. The directory must exist and be
2673 The environment variable @code{TMPDIR}, if it is defined. For security
2674 reasons this only happens if the program is not SUID or SGID enabled.
2677 The @var{dir} argument, if it is not a null pointer.
2680 The value of the @code{P_tmpdir} macro.
2683 The directory @file{/tmp}.
2686 This function is defined for SVID compatibility.
2688 @cindex TMPDIR environment variable
2692 @c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
2693 @deftypevr {SVID Macro} {char *} P_tmpdir
2694 This macro is the name of the default directory for temporary files.
2697 Older Unix systems did not have the functions just described. Instead
2698 they used @code{mktemp} and @code{mkstemp}. Both of these functions
2699 work by modifying a file name template string you pass. The last six
2700 characters of this string must be @samp{XXXXXX}. These six @samp{X}s
2701 are replaced with six characters which make the whole string a unique
2702 file name. Usually the template string is something like
2703 @samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}.
2705 @strong{Note:} Because @code{mktemp} and @code{mkstemp} modify the
2706 template string, you @emph{must not} pass string constants to them.
2707 String constants are normally in read-only storage, so your program
2708 would crash when @code{mktemp} or @code{mkstemp} tried to modify the
2713 @deftypefun {char *} mktemp (char *@var{template})
2714 The @code{mktemp} function generates a unique file name by modifying
2715 @var{template} as described above. If successful, it returns
2716 @var{template} as modified. If @code{mktemp} cannot find a unique file
2717 name, it makes @var{template} an empty string and returns that. If
2718 @var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a
2721 @strong{Warning:} Since between the time the pathname is constructed and
2722 the file is created another process might have created a file with this
2723 name using @code{mktemp} is a possible security hole. The
2724 implementation generates names which hardly can be predicted but opening
2725 the file in any case should use the @code{O_EXCL} flag. Using
2726 @code{mkstemp} is a safe way to avoid this problem.
2731 @deftypefun int mkstemp (char *@var{template})
2732 The @code{mkstemp} function generates a unique file name just as
2733 @code{mktemp} does, but it also opens the file for you with @code{open}
2734 (@pxref{Opening and Closing Files}). If successful, it modifies
2735 @var{template} in place and returns a file descriptor open on that file
2736 for reading and writing. If @code{mkstemp} cannot create a
2737 uniquely-named file, it makes @var{template} an empty string and returns
2738 @code{-1}. If @var{template} does not end with @samp{XXXXXX},
2739 @code{mkstemp} returns @code{-1} and does not modify @var{template}.
2741 The file is opened using mode @code{0600}. If the file is meant to be
2742 used by other users the mode must explicitly changed.
2745 Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a
2746 unique file that cannot possibly clash with any other program trying to
2747 create a temporary file. This is because it works by calling
2748 @code{open} with the @code{O_EXCL} flag bit, which says you want to
2749 always create a new file, and get an error if the file already exists.