diff options
Diffstat (limited to 'manual/filesys.texi')
| -rw-r--r-- | manual/filesys.texi | 3657 |
1 files changed, 0 insertions, 3657 deletions
diff --git a/manual/filesys.texi b/manual/filesys.texi deleted file mode 100644 index e3fe323f47..0000000000 --- a/manual/filesys.texi +++ /dev/null @@ -1,3657 +0,0 @@ -@node File System Interface, Pipes and FIFOs, Low-Level I/O, Top -@c %MENU% Functions for manipulating files -@chapter File System Interface - -This chapter describes @theglibc{}'s functions for manipulating -files. Unlike the input and output functions (@pxref{I/O on Streams}; -@pxref{Low-Level I/O}), these functions are concerned with operating -on the files themselves rather than on their contents. - -Among the facilities described in this chapter are functions for -examining or modifying directories, functions for renaming and deleting -files, and functions for examining and setting file attributes such as -access permissions and modification times. - -@menu -* Working Directory:: This is used to resolve relative - file names. -* Accessing Directories:: Finding out what files a directory - contains. -* Working with Directory Trees:: Apply actions to all files or a selectable - subset of a directory hierarchy. -* Hard Links:: Adding alternate names to a file. -* Symbolic Links:: A file that ``points to'' a file name. -* Deleting Files:: How to delete a file, and what that means. -* Renaming Files:: Changing a file's name. -* Creating Directories:: A system call just for creating a directory. -* File Attributes:: Attributes of individual files. -* Making Special Files:: How to create special files. -* Temporary Files:: Naming and creating temporary files. -@end menu - -@node Working Directory -@section Working Directory - -@cindex current working directory -@cindex working directory -@cindex change working directory -Each process has associated with it a directory, called its @dfn{current -working directory} or simply @dfn{working directory}, that is used in -the resolution of relative file names (@pxref{File Name Resolution}). - -When you log in and begin a new session, your working directory is -initially set to the home directory associated with your login account -in the system user database. You can find any user's home directory -using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User -Database}. - -Users can change the working directory using shell commands like -@code{cd}. The functions described in this section are the primitives -used by those commands and by other programs for examining and changing -the working directory. -@pindex cd - -Prototypes for these functions are declared in the header file -@file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.1 -@deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c If buffer is NULL, this function calls malloc and realloc, and, in -@c case of error, free. Linux offers a getcwd syscall that we use on -@c GNU/Linux systems, but it may fail if the pathname is too long. As a -@c fallback, and on other systems, the generic implementation opens each -@c parent directory with opendir, which allocates memory for the -@c directory stream with malloc. If a fstatat64 syscall is not -@c available, very deep directory trees may also have to malloc to build -@c longer sequences of ../../../... than those supported by a global -@c const read-only string. - -@c linux/__getcwd -@c posix/__getcwd -@c malloc/realloc/free if buffer is NULL, or if dir is too deep -@c lstat64 -> see its own entry -@c fstatat64 -@c direct syscall if possible, alloca+snprintf+*stat64 otherwise -@c openat64_not_cancel_3, close_not_cancel_no_status -@c __fdopendir, __opendir, __readdir, rewinddir -The @code{getcwd} function returns an absolute file name representing -the current working directory, storing it in the character array -@var{buffer} that you provide. The @var{size} argument is how you tell -the system the allocation size of @var{buffer}. - -The @glibcadj{} version of this function also permits you to specify a -null pointer for the @var{buffer} argument. Then @code{getcwd} -allocates a buffer automatically, as with @code{malloc} -(@pxref{Unconstrained Allocation}). If the @var{size} is greater than -zero, then the buffer is that large; otherwise, the buffer is as large -as necessary to hold the result. - -The return value is @var{buffer} on success and a null pointer on failure. -The following @code{errno} error conditions are defined for this function: - -@table @code -@item EINVAL -The @var{size} argument is zero and @var{buffer} is not a null pointer. - -@item ERANGE -The @var{size} argument is less than the length of the working directory -name. You need to allocate a bigger array and try again. - -@item EACCES -Permission to read or search a component of the file name was denied. -@end table -@end deftypefun - -You could implement the behavior of GNU's @w{@code{getcwd (NULL, 0)}} -using only the standard behavior of @code{getcwd}: - -@smallexample -char * -gnu_getcwd () -@{ - size_t size = 100; - - while (1) - @{ - char *buffer = (char *) xmalloc (size); - if (getcwd (buffer, size) == buffer) - return buffer; - free (buffer); - if (errno != ERANGE) - return 0; - size *= 2; - @} -@} -@end smallexample - -@noindent -@xref{Malloc Examples}, for information about @code{xmalloc}, which is -not a library function but is a customary name used in most GNU -software. - -@comment unistd.h -@comment BSD -@deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{} @acsfd{}}} -@c Besides the getcwd safety issues, it calls strerror_r on error, which -@c brings in all of the i18n issues. -This is similar to @code{getcwd}, but has no way to specify the size of -the buffer. @Theglibc{} provides @code{getwd} only -for backwards compatibility with BSD. - -The @var{buffer} argument should be a pointer to an array at least -@code{PATH_MAX} bytes long (@pxref{Limits for Files}). On @gnuhurdsystems{} -there is no limit to the size of a file name, so this is not -necessarily enough space to contain the directory name. That is why -this function is deprecated. -@end deftypefn - -@comment unistd.h -@comment GNU -@deftypefun {char *} get_current_dir_name (void) -@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c Besides getcwd, which this function calls as a fallback, it calls -@c getenv, with the potential thread-safety issues that brings about. -@vindex PWD -This @code{get_current_dir_name} function is basically equivalent to -@w{@code{getcwd (NULL, 0)}}. The only difference is that the value of -the @code{PWD} variable is returned if this value is correct. This is a -subtle difference which is visible if the path described by the -@code{PWD} value is using one or more symbol links in which case the -value returned by @code{getcwd} can resolve the symbol links and -therefore yield a different result. - -This function is a GNU extension. -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun int chdir (const char *@var{filename}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function is used to set the process's working directory to -@var{filename}. - -The normal, successful return value from @code{chdir} is @code{0}. A -value of @code{-1} is returned to indicate an error. The @code{errno} -error conditions defined for this function are the usual file name -syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the -file @var{filename} is not a directory. -@end deftypefun - -@comment unistd.h -@comment XPG -@deftypefun int fchdir (int @var{filedes}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function is used to set the process's working directory to -directory associated with the file descriptor @var{filedes}. - -The normal, successful return value from @code{fchdir} is @code{0}. A -value of @code{-1} is returned to indicate an error. The following -@code{errno} error conditions are defined for this function: - -@table @code -@item EACCES -Read permission is denied for the directory named by @code{dirname}. - -@item EBADF -The @var{filedes} argument is not a valid file descriptor. - -@item ENOTDIR -The file descriptor @var{filedes} is not associated with a directory. - -@item EINTR -The function call was interrupt by a signal. - -@item EIO -An I/O error occurred. -@end table -@end deftypefun - - -@node Accessing Directories -@section Accessing Directories -@cindex accessing directories -@cindex reading from a directory -@cindex directories, accessing - -The facilities described in this section let you read the contents of a -directory file. This is useful if you want your program to list all the -files in a directory, perhaps as part of a menu. - -@cindex directory stream -The @code{opendir} function opens a @dfn{directory stream} whose -elements are directory entries. Alternatively @code{fdopendir} can be -used which can have advantages if the program needs to have more -control over the way the directory is opened for reading. This -allows, for instance, to pass the @code{O_NOATIME} flag to -@code{open}. - -You use the @code{readdir} function on the directory stream to -retrieve these entries, represented as @w{@code{struct dirent}} -objects. The name of the file for each entry is stored in the -@code{d_name} member of this structure. There are obvious parallels -here to the stream facilities for ordinary files, described in -@ref{I/O on Streams}. - -@menu -* Directory Entries:: Format of one directory entry. -* Opening a Directory:: How to open a directory stream. -* Reading/Closing Directory:: How to read directory entries from the stream. -* Simple Directory Lister:: A very simple directory listing program. -* Random Access Directory:: Rereading part of the directory - already read with the same stream. -* Scanning Directory Content:: Get entries for user selected subset of - contents in given directory. -* Simple Directory Lister Mark II:: Revised version of the program. -@end menu - -@node Directory Entries -@subsection Format of a Directory Entry - -@pindex dirent.h -This section describes what you find in a single directory entry, as you -might obtain it from a directory stream. All the symbols are declared -in the header file @file{dirent.h}. - -@comment dirent.h -@comment POSIX.1 -@deftp {Data Type} {struct dirent} -This is a structure type used to return information about directory -entries. It contains the following fields: - -@table @code -@item char d_name[] -This is the null-terminated file name component. This is the only -field you can count on in all POSIX systems. - -@item ino_t d_fileno -This is the file serial number. For BSD compatibility, you can also -refer to this member as @code{d_ino}. On @gnulinuxhurdsystems{} and most POSIX -systems, for most files this the same as the @code{st_ino} member that -@code{stat} will return for the file. @xref{File Attributes}. - -@item unsigned char d_namlen -This is the length of the file name, not including the terminating -null character. Its type is @code{unsigned char} because that is the -integer type of the appropriate size. This member is a BSD extension. -The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is -available. - -@item unsigned char d_type -This is the type of the file, possibly unknown. The following constants -are defined for its value: - -@vtable @code -@item DT_UNKNOWN -The type is unknown. Only some filesystems have full support to -return the type of the file, others might always return this value. - -@item DT_REG -A regular file. - -@item DT_DIR -A directory. - -@item DT_FIFO -A named pipe, or FIFO. @xref{FIFO Special Files}. - -@item DT_SOCK -A local-domain socket. @c !!! @xref{Local Domain}. - -@item DT_CHR -A character device. - -@item DT_BLK -A block device. - -@item DT_LNK -A symbolic link. -@end vtable - -This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_TYPE} -is defined if this member is available. On systems where it is used, it -corresponds to the file type bits in the @code{st_mode} member of -@code{struct stat}. If the value cannot be determined the member -value is DT_UNKNOWN. These two macros convert between @code{d_type} -values and @code{st_mode} values: - -@comment dirent.h -@comment BSD -@deftypefun int IFTODT (mode_t @var{mode}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This returns the @code{d_type} value corresponding to @var{mode}. -@end deftypefun - -@comment dirent.h -@comment BSD -@deftypefun mode_t DTTOIF (int @var{dtype}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This returns the @code{st_mode} value corresponding to @var{dtype}. -@end deftypefun -@end table - -This structure may contain additional members in the future. Their -availability is always announced in the compilation environment by a -macro named @code{_DIRENT_HAVE_D_@var{xxx}} where @var{xxx} is replaced -by the name of the new member. For instance, the member @code{d_reclen} -available on some systems is announced through the macro -@code{_DIRENT_HAVE_D_RECLEN}. - -When a file has multiple names, each name has its own directory entry. -The only way you can tell that the directory entries belong to a -single file is that they have the same value for the @code{d_fileno} -field. - -File attributes such as size, modification times etc., are part of the -file itself, not of any particular directory entry. @xref{File -Attributes}. -@end deftp - -@node Opening a Directory -@subsection Opening a Directory Stream - -@pindex dirent.h -This section describes how to open a directory stream. All the symbols -are declared in the header file @file{dirent.h}. - -@comment dirent.h -@comment POSIX.1 -@deftp {Data Type} DIR -The @code{DIR} data type represents a directory stream. -@end deftp - -You shouldn't ever allocate objects of the @code{struct dirent} or -@code{DIR} data types, since the directory access functions do that for -you. Instead, you refer to these objects using the pointers returned by -the following functions. - -@comment dirent.h -@comment POSIX.1 -@deftypefun {DIR *} opendir (const char *@var{dirname}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c Besides the safe syscall, we have to allocate the DIR object with -@c __alloc_dir, that calls malloc. -The @code{opendir} function opens and returns a directory stream for -reading the directory whose file name is @var{dirname}. The stream has -type @code{DIR *}. - -If unsuccessful, @code{opendir} returns a null pointer. In addition to -the usual file name errors (@pxref{File Name Errors}), the -following @code{errno} error conditions are defined for this function: - -@table @code -@item EACCES -Read permission is denied for the directory named by @code{dirname}. - -@item EMFILE -The process has too many files open. - -@item ENFILE -The entire system, or perhaps the file system which contains the -directory, cannot support any additional open files at the moment. -(This problem cannot happen on @gnuhurdsystems{}.) - -@item ENOMEM -Not enough memory available. -@end table - -The @code{DIR} type is typically implemented using a file descriptor, -and the @code{opendir} function in terms of the @code{open} function. -@xref{Low-Level I/O}. Directory streams and the underlying -file descriptors are closed on @code{exec} (@pxref{Executing a File}). -@end deftypefun - -The directory which is opened for reading by @code{opendir} is -identified by the name. In some situations this is not sufficient. -Or the way @code{opendir} implicitly creates a file descriptor for the -directory is not the way a program might want it. In these cases an -alternative interface can be used. - -@comment dirent.h -@comment GNU -@deftypefun {DIR *} fdopendir (int @var{fd}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c The DIR object is allocated with __alloc_dir, that calls malloc. -The @code{fdopendir} function works just like @code{opendir} but -instead of taking a file name and opening a file descriptor for the -directory the caller is required to provide a file descriptor. This -file descriptor is then used in subsequent uses of the returned -directory stream object. - -The caller must make sure the file descriptor is associated with a -directory and it allows reading. - -If the @code{fdopendir} call returns successfully the file descriptor -is now under the control of the system. It can be used in the same -way the descriptor implicitly created by @code{opendir} can be used -but the program must not close the descriptor. - -In case the function is unsuccessful it returns a null pointer and the -file descriptor remains to be usable by the program. The following -@code{errno} error conditions are defined for this function: - -@table @code -@item EBADF -The file descriptor is not valid. - -@item ENOTDIR -The file descriptor is not associated with a directory. - -@item EINVAL -The descriptor does not allow reading the directory content. - -@item ENOMEM -Not enough memory available. -@end table -@end deftypefun - -In some situations it can be desirable to get hold of the file -descriptor which is created by the @code{opendir} call. For instance, -to switch the current working directory to the directory just read the -@code{fchdir} function could be used. Historically the @code{DIR} type -was exposed and programs could access the fields. This does not happen -in @theglibc{}. Instead a separate function is provided to allow -access. - -@comment dirent.h -@comment GNU -@deftypefun int dirfd (DIR *@var{dirstream}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The function @code{dirfd} returns the file descriptor associated with -the directory stream @var{dirstream}. This descriptor can be used until -the directory is closed with @code{closedir}. If the directory stream -implementation is not using file descriptors the return value is -@code{-1}. -@end deftypefun - -@node Reading/Closing Directory -@subsection Reading and Closing a Directory Stream - -@pindex dirent.h -This section describes how to read directory entries from a directory -stream, and how to close the stream when you are done with it. All the -symbols are declared in the header file @file{dirent.h}. - -@comment dirent.h -@comment POSIX.1 -@deftypefun {struct dirent *} readdir (DIR *@var{dirstream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c This function holds dirstream's non-recursive lock, which brings -@c about the usual issues with locks and async signals and cancellation, -@c but the lock taking is not enough to make the returned value safe to -@c use, since it points to a stream's internal buffer that can be -@c overwritten by subsequent calls or even released by closedir. -This function reads the next entry from the directory. It normally -returns a pointer to a structure containing information about the -file. This structure is associated with the @var{dirstream} handle -and can be rewritten by a subsequent call. - -@strong{Portability Note:} On some systems @code{readdir} may not -return entries for @file{.} and @file{..}, even though these are always -valid file names in any directory. @xref{File Name Resolution}. - -If there are no more entries in the directory or an error is detected, -@code{readdir} returns a null pointer. The following @code{errno} error -conditions are defined for this function: - -@table @code -@item EBADF -The @var{dirstream} argument is not valid. -@end table - -To distinguish between an end-of-directory condition or an error, you -must set @code{errno} to zero before calling @code{readdir}. To avoid -entering an infinite loop, you should stop reading from the directory -after the first error. - -@strong{Caution:} The pointer returned by @code{readdir} points to -a buffer within the @code{DIR} object. The data in that buffer will -be overwritten by the next call to @code{readdir}. You must take care, -for instance, to copy the @code{d_name} string if you need it later. - -Because of this, it is not safe to share a @code{DIR} object among -multiple threads, unless you use your own locking to ensure that -no thread calls @code{readdir} while another thread is still using the -data from the previous call. In @theglibc{}, it is safe to call -@code{readdir} from multiple threads as long as each thread uses -its own @code{DIR} object. POSIX.1-2008 does not require this to -be safe, but we are not aware of any operating systems where it -does not work. - -@code{readdir_r} allows you to provide your own buffer for the -@code{struct dirent}, but it is less portable than @code{readdir}, and -has problems with very long filenames (see below). We recommend -you use @code{readdir}, but do not share @code{DIR} objects. -@end deftypefun - -@comment dirent.h -@comment GNU -@deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -This function is a version of @code{readdir} which performs internal -locking. Like @code{readdir} it returns the next entry from the -directory. To prevent conflicts between simultaneously running -threads the result is stored inside the @var{entry} object. - -@strong{Portability Note:} @code{readdir_r} is deprecated. It is -recommended to use @code{readdir} instead of @code{readdir_r} for the -following reasons: - -@itemize @bullet -@item -On systems which do not define @code{NAME_MAX}, it may not be possible -to use @code{readdir_r} safely because the caller does not specify the -length of the buffer for the directory entry. - -@item -On some systems, @code{readdir_r} cannot read directory entries with -very long names. If such a name is encountered, @theglibc{} -implementation of @code{readdir_r} returns with an error code of -@code{ENAMETOOLONG} after the final directory entry has been read. On -other systems, @code{readdir_r} may return successfully, but the -@code{d_name} member may not be NUL-terminated or may be truncated. - -@item -POSIX-1.2008 does not guarantee that @code{readdir} is thread-safe, -even when access to the same @var{dirstream} is serialized. But in -current implementations (including @theglibc{}), it is safe to call -@code{readdir} concurrently on different @var{dirstream}s, so there is -no need to use @code{readdir_r} in most multi-threaded programs. In -the rare case that multiple threads need to read from the same -@var{dirstream}, it is still better to use @code{readdir} and external -synchronization. - -@item -It is expected that future versions of POSIX will obsolete -@code{readdir_r} and mandate the level of thread safety for -@code{readdir} which is provided by @theglibc{} and other -implementations today. -@end itemize - -Normally @code{readdir_r} returns zero and sets @code{*@var{result}} -to @var{entry}. If there are no more entries in the directory or an -error is detected, @code{readdir_r} sets @code{*@var{result}} to a -null pointer and returns a nonzero error code, also stored in -@code{errno}, as described for @code{readdir}. - -It is also important to look at the definition of the @code{struct -dirent} type. Simply passing a pointer to an object of this type for -the second parameter of @code{readdir_r} might not be enough. Some -systems don't define the @code{d_name} element sufficiently long. In -this case the user has to provide additional space. There must be room -for at least @code{NAME_MAX + 1} characters in the @code{d_name} array. -Code to call @code{readdir_r} could look like this: - -@smallexample - union - @{ - struct dirent d; - char b[offsetof (struct dirent, d_name) + NAME_MAX + 1]; - @} u; - - if (readdir_r (dir, &u.d, &res) == 0) - @dots{} -@end smallexample -@end deftypefun - -To support large filesystems on 32-bit machines there are LFS variants -of the last two functions. - -@comment dirent.h -@comment LFS -@deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -The @code{readdir64} function is just like the @code{readdir} function -except that it returns a pointer to a record of type @code{struct -dirent64}. Some of the members of this data type (notably @code{d_ino}) -might have a different size to allow large filesystems. - -In all other aspects this function is equivalent to @code{readdir}. -@end deftypefun - -@comment dirent.h -@comment LFS -@deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -The deprecated @code{readdir64_r} function is equivalent to the -@code{readdir_r} function except that it takes parameters of base type -@code{struct dirent64} instead of @code{struct dirent} in the second and -third position. The same precautions mentioned in the documentation of -@code{readdir_r} also apply here. -@end deftypefun - -@comment dirent.h -@comment POSIX.1 -@deftypefun int closedir (DIR *@var{dirstream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@acsmem{} @acsfd{} @aculock{/hurd}}} -@c No synchronization in the posix implementation, only in the hurd -@c one. This is regarded as safe because it is undefined behavior if -@c other threads could still be using the dir stream while it's closed. -This function closes the directory stream @var{dirstream}. It returns -@code{0} on success and @code{-1} on failure. - -The following @code{errno} error conditions are defined for this -function: - -@table @code -@item EBADF -The @var{dirstream} argument is not valid. -@end table -@end deftypefun - -@node Simple Directory Lister -@subsection Simple Program to List a Directory - -Here's a simple program that prints the names of the files in -the current working directory: - -@smallexample -@include dir.c.texi -@end smallexample - -The order in which files appear in a directory tends to be fairly -random. A more useful program would sort the entries (perhaps by -alphabetizing them) before printing them; see -@ref{Scanning Directory Content}, and @ref{Array Sort Function}. - - -@node Random Access Directory -@subsection Random Access in a Directory Stream - -@pindex dirent.h -This section describes how to reread parts of a directory that you have -already read from an open directory stream. All the symbols are -declared in the header file @file{dirent.h}. - -@comment dirent.h -@comment POSIX.1 -@deftypefun void rewinddir (DIR *@var{dirstream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -The @code{rewinddir} function is used to reinitialize the directory -stream @var{dirstream}, so that if you call @code{readdir} it -returns information about the first entry in the directory again. This -function also notices if files have been added or removed to the -directory since it was opened with @code{opendir}. (Entries for these -files might or might not be returned by @code{readdir} if they were -added or removed since you last called @code{opendir} or -@code{rewinddir}.) -@end deftypefun - -@comment dirent.h -@comment BSD -@deftypefun {long int} telldir (DIR *@var{dirstream}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} -@c The implementation is safe on most platforms, but on BSD it uses -@c cookies, buckets and records, and the global array of pointers to -@c dynamically allocated records is guarded by a non-recursive lock. -The @code{telldir} function returns the file position of the directory -stream @var{dirstream}. You can use this value with @code{seekdir} to -restore the directory stream to that position. -@end deftypefun - -@comment dirent.h -@comment BSD -@deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}} -@c The implementation is safe on most platforms, but on BSD it uses -@c cookies, buckets and records, and the global array of pointers to -@c dynamically allocated records is guarded by a non-recursive lock. -The @code{seekdir} function sets the file position of the directory -stream @var{dirstream} to @var{pos}. The value @var{pos} must be the -result of a previous call to @code{telldir} on this particular stream; -closing and reopening the directory can invalidate values returned by -@code{telldir}. -@end deftypefun - - -@node Scanning Directory Content -@subsection Scanning the Content of a Directory - -A higher-level interface to the directory handling functions is the -@code{scandir} function. With its help one can select a subset of the -entries in a directory, possibly sort them and get a list of names as -the result. - -@comment dirent.h -@comment BSD, SVID -@deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const struct dirent **, const struct dirent **)) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c The scandir function calls __opendirat, __readdir, and __closedir to -@c go over the named dir; malloc and realloc to allocate the namelist -@c and copies of each selected dirent, besides the selector, if given, -@c and qsort and the cmp functions if the latter is given. In spite of -@c the cleanup handler that releases memory and the file descriptor in -@c case of synchronous cancellation, an asynchronous cancellation may -@c still leak memory and a file descriptor. Although readdir is unsafe -@c in general, the use of an internal dir stream for sequential scanning -@c of the directory with copying of dirents before subsequent calls -@c makes the use safe, and the fact that the dir stream is private to -@c each scandir call does away with the lock issues in readdir and -@c closedir. - -The @code{scandir} function scans the contents of the directory selected -by @var{dir}. The result in *@var{namelist} is an array of pointers to -structures of type @code{struct dirent} which describe all selected -directory entries and which is allocated using @code{malloc}. Instead -of always getting all directory entries returned, the user supplied -function @var{selector} can be used to decide which entries are in the -result. Only the entries for which @var{selector} returns a non-zero -value are selected. - -Finally the entries in *@var{namelist} are sorted using the -user-supplied function @var{cmp}. The arguments passed to the @var{cmp} -function are of type @code{struct dirent **}, therefore one cannot -directly use the @code{strcmp} or @code{strcoll} functions; instead see -the functions @code{alphasort} and @code{versionsort} below. - -The return value of the function is the number of entries placed in -*@var{namelist}. If it is @code{-1} an error occurred (either the -directory could not be opened for reading or the malloc call failed) and -the global variable @code{errno} contains more information on the error. -@end deftypefun - -As described above, the fourth argument to the @code{scandir} function -must be a pointer to a sorting function. For the convenience of the -programmer @theglibc{} contains implementations of functions which -are very helpful for this purpose. - -@comment dirent.h -@comment BSD, SVID -@deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -@c Calls strcoll. -The @code{alphasort} function behaves like the @code{strcoll} function -(@pxref{String/Array Comparison}). The difference is that the arguments -are not string pointers but instead they are of type -@code{struct dirent **}. - -The return value of @code{alphasort} is less than, equal to, or greater -than zero depending on the order of the two entries @var{a} and @var{b}. -@end deftypefun - -@comment dirent.h -@comment GNU -@deftypefun int versionsort (const struct dirent **@var{a}, const struct dirent **@var{b}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -@c Calls strverscmp, which will accesses the locale object multiple -@c times. -The @code{versionsort} function is like @code{alphasort} except that it -uses the @code{strverscmp} function internally. -@end deftypefun - -If the filesystem supports large files we cannot use the @code{scandir} -anymore since the @code{dirent} structure might not able to contain all -the information. The LFS provides the new type @w{@code{struct -dirent64}}. To use this we need a new function. - -@comment dirent.h -@comment GNU -@deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const struct dirent64 **, const struct dirent64 **)) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c See scandir. -The @code{scandir64} function works like the @code{scandir} function -except that the directory entries it returns are described by elements -of type @w{@code{struct dirent64}}. The function pointed to by -@var{selector} is again used to select the desired entries, except that -@var{selector} now must point to a function which takes a -@w{@code{struct dirent64 *}} parameter. - -Similarly the @var{cmp} function should expect its two arguments to be -of type @code{struct dirent64 **}. -@end deftypefun - -As @var{cmp} is now a function of a different type, the functions -@code{alphasort} and @code{versionsort} cannot be supplied for that -argument. Instead we provide the two replacement functions below. - -@comment dirent.h -@comment GNU -@deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -@c See alphasort. -The @code{alphasort64} function behaves like the @code{strcoll} function -(@pxref{String/Array Comparison}). The difference is that the arguments -are not string pointers but instead they are of type -@code{struct dirent64 **}. - -Return value of @code{alphasort64} is less than, equal to, or greater -than zero depending on the order of the two entries @var{a} and @var{b}. -@end deftypefun - -@comment dirent.h -@comment GNU -@deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b}) -@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}} -@c See versionsort. -The @code{versionsort64} function is like @code{alphasort64}, excepted that it -uses the @code{strverscmp} function internally. -@end deftypefun - -It is important not to mix the use of @code{scandir} and the 64-bit -comparison functions or vice versa. There are systems on which this -works but on others it will fail miserably. - -@node Simple Directory Lister Mark II -@subsection Simple Program to List a Directory, Mark II - -Here is a revised version of the directory lister found above -(@pxref{Simple Directory Lister}). Using the @code{scandir} function we -can avoid the functions which work directly with the directory contents. -After the call the returned entries are available for direct use. - -@smallexample -@include dir2.c.texi -@end smallexample - -Note the simple selector function in this example. Since we want to see -all directory entries we always return @code{1}. - - -@node Working with Directory Trees -@section Working with Directory Trees -@cindex directory hierarchy -@cindex hierarchy, directory -@cindex tree, directory - -The functions described so far for handling the files in a directory -have allowed you to either retrieve the information bit by bit, or to -process all the files as a group (see @code{scandir}). Sometimes it is -useful to process whole hierarchies of directories and their contained -files. The X/Open specification defines two functions to do this. The -simpler form is derived from an early definition in @w{System V} systems -and therefore this function is available on SVID-derived systems. The -prototypes and required definitions can be found in the @file{ftw.h} -header. - -There are four functions in this family: @code{ftw}, @code{nftw} and -their 64-bit counterparts @code{ftw64} and @code{nftw64}. These -functions take as one of their arguments a pointer to a callback -function of the appropriate type. - -@comment ftw.h -@comment GNU -@deftp {Data Type} __ftw_func_t - -@smallexample -int (*) (const char *, const struct stat *, int) -@end smallexample - -The type of callback functions given to the @code{ftw} function. The -first parameter points to the file name, the second parameter to an -object of type @code{struct stat} which is filled in for the file named -in the first parameter. - -@noindent -The last parameter is a flag giving more information about the current -file. It can have the following values: - -@vtable @code -@item FTW_F -The item is either a normal file or a file which does not fit into one -of the following categories. This could be special files, sockets etc. -@item FTW_D -The item is a directory. -@item FTW_NS -The @code{stat} call failed and so the information pointed to by the -second parameter is invalid. -@item FTW_DNR -The item is a directory which cannot be read. -@item FTW_SL -The item is a symbolic link. Since symbolic links are normally followed -seeing this value in a @code{ftw} callback function means the referenced -file does not exist. The situation for @code{nftw} is different. - -This value is only available if the program is compiled with -@code{_XOPEN_EXTENDED} defined before including -the first header. The original SVID systems do not have symbolic links. -@end vtable - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -type is in fact @code{__ftw64_func_t} since this mode changes -@code{struct stat} to be @code{struct stat64}. -@end deftp - -For the LFS interface and for use in the function @code{ftw64}, the -header @file{ftw.h} defines another function type. - -@comment ftw.h -@comment GNU -@deftp {Data Type} __ftw64_func_t - -@smallexample -int (*) (const char *, const struct stat64 *, int) -@end smallexample - -This type is used just like @code{__ftw_func_t} for the callback -function, but this time is called from @code{ftw64}. The second -parameter to the function is a pointer to a variable of type -@code{struct stat64} which is able to represent the larger values. -@end deftp - -@comment ftw.h -@comment GNU -@deftp {Data Type} __nftw_func_t - -@smallexample -int (*) (const char *, const struct stat *, int, struct FTW *) -@end smallexample - -The first three arguments are the same as for the @code{__ftw_func_t} -type. However for the third argument some additional values are defined -to allow finer differentiation: -@vtable @code -@item FTW_DP -The current item is a directory and all subdirectories have already been -visited and reported. This flag is returned instead of @code{FTW_D} if -the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below). -@item FTW_SLN -The current item is a stale symbolic link. The file it points to does -not exist. -@end vtable - -The last parameter of the callback function is a pointer to a structure -with some extra information as described below. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -type is in fact @code{__nftw64_func_t} since this mode changes -@code{struct stat} to be @code{struct stat64}. -@end deftp - -For the LFS interface there is also a variant of this data type -available which has to be used with the @code{nftw64} function. - -@comment ftw.h -@comment GNU -@deftp {Data Type} __nftw64_func_t - -@smallexample -int (*) (const char *, const struct stat64 *, int, struct FTW *) -@end smallexample - -This type is used just like @code{__nftw_func_t} for the callback -function, but this time is called from @code{nftw64}. The second -parameter to the function is this time a pointer to a variable of type -@code{struct stat64} which is able to represent the larger values. -@end deftp - -@comment ftw.h -@comment XPG4.2 -@deftp {Data Type} {struct FTW} -The information contained in this structure helps in interpreting the -name parameter and gives some information about the current state of the -traversal of the directory hierarchy. - -@table @code -@item int base -The value is the offset into the string passed in the first parameter to -the callback function of the beginning of the file name. The rest of -the string is the path of the file. This information is especially -important if the @code{FTW_CHDIR} flag was set in calling @code{nftw} -since then the current directory is the one the current item is found -in. -@item int level -Whilst processing, the code tracks how many directories down it has gone -to find the current file. This nesting level starts at @math{0} for -files in the initial directory (or is zero for the initial file if a -file was passed). -@end table -@end deftp - - -@comment ftw.h -@comment SVID -@deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c see nftw for safety details -The @code{ftw} function calls the callback function given in the -parameter @var{func} for every item which is found in the directory -specified by @var{filename} and all directories below. The function -follows symbolic links if necessary but does not process an item twice. -If @var{filename} is not a directory then it itself is the only object -returned to the callback function. - -The file name passed to the callback function is constructed by taking -the @var{filename} parameter and appending the names of all passed -directories and then the local file name. So the callback function can -use this parameter to access the file. @code{ftw} also calls -@code{stat} for the file and passes that information on to the callback -function. If this @code{stat} call is not successful the failure is -indicated by setting the third argument of the callback function to -@code{FTW_NS}. Otherwise it is set according to the description given -in the account of @code{__ftw_func_t} above. - -The callback function is expected to return @math{0} to indicate that no -error occurred and that processing should continue. If an error -occurred in the callback function or it wants @code{ftw} to return -immediately, the callback function can return a value other than -@math{0}. This is the only correct way to stop the function. The -program must not use @code{setjmp} or similar techniques to continue -from another place. This would leave resources allocated by the -@code{ftw} function unfreed. - -The @var{descriptors} parameter to @code{ftw} specifies how many file -descriptors it is allowed to consume. The function runs faster the more -descriptors it can use. For each level in the directory hierarchy at -most one descriptor is used, but for very deep ones any limit on open -file descriptors for the process or the system may be exceeded. -Moreover, file descriptor limits in a multi-threaded program apply to -all the threads as a group, and therefore it is a good idea to supply a -reasonable limit to the number of open descriptors. - -The return value of the @code{ftw} function is @math{0} if all callback -function calls returned @math{0} and all actions performed by the -@code{ftw} succeeded. If a function call failed (other than calling -@code{stat} on an item) the function returns @math{-1}. If a callback -function returns a value other than @math{0} this value is returned as -the return value of @code{ftw}. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32-bit system this function is in fact @code{ftw64}, i.e., the LFS -interface transparently replaces the old interface. -@end deftypefun - -@comment ftw.h -@comment Unix98 -@deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -This function is similar to @code{ftw} but it can work on filesystems -with large files. File information is reported using a variable of type -@code{struct stat64} which is passed by reference to the callback -function. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32-bit system this function is available under the name @code{ftw} and -transparently replaces the old implementation. -@end deftypefun - -@comment ftw.h -@comment XPG4.2 -@deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag}) -@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} -@c ftw_startup calls alloca, malloc, free, xstat/lxstat, tdestroy, and ftw_dir -@c if FTW_CHDIR, call open, and fchdir, or chdir and getcwd -@c ftw_dir calls open_dir_stream, readdir64, process_entry, closedir -@c if FTW_CHDIR, also calls fchdir -@c open_dir_stream calls malloc, realloc, readdir64, free, closedir, -@c then openat64_not_cancel_3 and fdopendir or opendir, then dirfd. -@c process_entry may cal realloc, fxstatat/lxstat/xstat, ftw_dir, and -@c find_object (tsearch) and add_object (tfind). -@c Since each invocation of *ftw uses its own private search tree, none -@c of the search tree concurrency issues apply. -The @code{nftw} function works like the @code{ftw} functions. They call -the callback function @var{func} for all items found in the directory -@var{filename} and below. At most @var{descriptors} file descriptors -are consumed during the @code{nftw} call. - -One difference is that the callback function is of a different type. It -is of type @w{@code{struct FTW *}} and provides the callback function -with the extra information described above. - -A second difference is that @code{nftw} takes a fourth argument, which -is @math{0} or a bitwise-OR combination of any of the following values. - -@vtable @code -@item FTW_PHYS -While traversing the directory symbolic links are not followed. Instead -symbolic links are reported using the @code{FTW_SL} value for the type -parameter to the callback function. If the file referenced by a -symbolic link does not exist @code{FTW_SLN} is returned instead. -@item FTW_MOUNT -The callback function is only called for items which are on the same -mounted filesystem as the directory given by the @var{filename} -parameter to @code{nftw}. -@item FTW_CHDIR -If this flag is given the current working directory is changed to the -directory of the reported object before the callback function is called. -When @code{ntfw} finally returns the current directory is restored to -its original value. -@item FTW_DEPTH -If this option is specified then all subdirectories and files within -them are processed before processing the top directory itself -(depth-first processing). This also means the type flag given to the -callback function is @code{FTW_DP} and not @code{FTW_D}. -@item FTW_ACTIONRETVAL -If this option is specified then return values from callbacks -are handled differently. If the callback returns @code{FTW_CONTINUE}, -walking continues normally. @code{FTW_STOP} means walking stops -and @code{FTW_STOP} is returned to the caller. If @code{FTW_SKIP_SUBTREE} -is returned by the callback with @code{FTW_D} argument, the subtree -is skipped and walking continues with next sibling of the directory. -If @code{FTW_SKIP_SIBLINGS} is returned by the callback, all siblings -of the current entry are skipped and walking continues in its parent. -No other return values should be returned from the callbacks if -this option is set. This option is a GNU extension. -@end vtable - -The return value is computed in the same way as for @code{ftw}. -@code{nftw} returns @math{0} if no failures occurred and all callback -functions returned @math{0}. In case of internal errors, such as memory -problems, the return value is @math{-1} and @var{errno} is set -accordingly. If the return value of a callback invocation was non-zero -then that value is returned. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32-bit system this function is in fact @code{nftw64}, i.e., the LFS -interface transparently replaces the old interface. -@end deftypefun - -@comment ftw.h -@comment Unix98 -@deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag}) -@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}} -This function is similar to @code{nftw} but it can work on filesystems -with large files. File information is reported using a variable of type -@code{struct stat64} which is passed by reference to the callback -function. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32-bit system this function is available under the name @code{nftw} and -transparently replaces the old implementation. -@end deftypefun - - -@node Hard Links -@section Hard Links -@cindex hard link -@cindex link, hard -@cindex multiple names for one file -@cindex file names, multiple - -In POSIX systems, one file can have many names at the same time. All of -the names are equally real, and no one of them is preferred to the -others. - -To add a name to a file, use the @code{link} function. (The new name is -also called a @dfn{hard link} to the file.) Creating a new link to a -file does not copy the contents of the file; it simply makes a new name -by which the file can be known, in addition to the file's existing name -or names. - -One file can have names in several directories, so the organization -of the file system is not a strict hierarchy or tree. - -In most implementations, it is not possible to have hard links to the -same file in multiple file systems. @code{link} reports an error if you -try to make a hard link to the file from another file system when this -cannot be done. - -The prototype for the @code{link} function is declared in the header -file @file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.1 -@deftypefun int link (const char *@var{oldname}, const char *@var{newname}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{link} function makes a new link to the existing file named by -@var{oldname}, under the new name @var{newname}. - -This function returns a value of @code{0} if it is successful and -@code{-1} on failure. In addition to the usual file name errors -(@pxref{File Name Errors}) for both @var{oldname} and @var{newname}, the -following @code{errno} error conditions are defined for this function: - -@table @code -@item EACCES -You are not allowed to write to the directory in which the new link is -to be written. -@ignore -Some implementations also require that the existing file be accessible -by the caller, and use this error to report failure for that reason. -@end ignore - -@item EEXIST -There is already a file named @var{newname}. If you want to replace -this link with a new link, you must remove the old link explicitly first. - -@item EMLINK -There are already too many links to the file named by @var{oldname}. -(The maximum number of links to a file is @w{@code{LINK_MAX}}; see -@ref{Limits for Files}.) - -@item ENOENT -The file named by @var{oldname} doesn't exist. You can't make a link to -a file that doesn't exist. - -@item ENOSPC -The directory or file system that would contain the new link is full -and cannot be extended. - -@item EPERM -On @gnulinuxhurdsystems{} and some others, you cannot make links to -directories. -Many systems allow only privileged users to do so. This error -is used to report the problem. - -@item EROFS -The directory containing the new link can't be modified because it's on -a read-only file system. - -@item EXDEV -The directory specified in @var{newname} is on a different file system -than the existing file. - -@item EIO -A hardware error occurred while trying to read or write the to filesystem. -@end table -@end deftypefun - -@node Symbolic Links -@section Symbolic Links -@cindex soft link -@cindex link, soft -@cindex symbolic link -@cindex link, symbolic - -@gnusystems{} support @dfn{soft links} or @dfn{symbolic links}. This -is a kind of ``file'' that is essentially a pointer to another file -name. Unlike hard links, symbolic links can be made to directories or -across file systems with no restrictions. You can also make a symbolic -link to a name which is not the name of any file. (Opening this link -will fail until a file by that name is created.) Likewise, if the -symbolic link points to an existing file which is later deleted, the -symbolic link continues to point to the same file name even though the -name no longer names any file. - -The reason symbolic links work the way they do is that special things -happen when you try to open the link. The @code{open} function realizes -you have specified the name of a link, reads the file name contained in -the link, and opens that file name instead. The @code{stat} function -likewise operates on the file that the symbolic link points to, instead -of on the link itself. - -By contrast, other operations such as deleting or renaming the file -operate on the link itself. The functions @code{readlink} and -@code{lstat} also refrain from following symbolic links, because their -purpose is to obtain information about the link. @code{link}, the -function that makes a hard link, does too. It makes a hard link to the -symbolic link, which one rarely wants. - -Some systems have, for some functions operating on files, a limit on -how many symbolic links are followed when resolving a path name. The -limit if it exists is published in the @file{sys/param.h} header file. - -@comment sys/param.h -@comment BSD -@deftypevr Macro int MAXSYMLINKS - -The macro @code{MAXSYMLINKS} specifies how many symlinks some function -will follow before returning @code{ELOOP}. Not all functions behave the -same and this value is not the same as that returned for -@code{_SC_SYMLOOP} by @code{sysconf}. In fact, the @code{sysconf} -result can indicate that there is no fixed limit although -@code{MAXSYMLINKS} exists and has a finite value. -@end deftypevr - -Prototypes for most of the functions listed in this section are in -@file{unistd.h}. -@pindex unistd.h - -@comment unistd.h -@comment BSD -@deftypefun int symlink (const char *@var{oldname}, const char *@var{newname}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{symlink} function makes a symbolic link to @var{oldname} named -@var{newname}. - -The normal return value from @code{symlink} is @code{0}. A return value -of @code{-1} indicates an error. In addition to the usual file name -syntax errors (@pxref{File Name Errors}), the following @code{errno} -error conditions are defined for this function: - -@table @code -@item EEXIST -There is already an existing file named @var{newname}. - -@item EROFS -The file @var{newname} would exist on a read-only file system. - -@item ENOSPC -The directory or file system cannot be extended to make the new link. - -@item EIO -A hardware error occurred while reading or writing data on the disk. - -@comment not sure about these -@ignore -@item ELOOP -There are too many levels of indirection. This can be the result of -circular symbolic links to directories. - -@item EDQUOT -The new link can't be created because the user's disk quota has been -exceeded. -@end ignore -@end table -@end deftypefun - -@comment unistd.h -@comment BSD -@deftypefun ssize_t readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{readlink} function gets the value of the symbolic link -@var{filename}. The file name that the link points to is copied into -@var{buffer}. This file name string is @emph{not} null-terminated; -@code{readlink} normally returns the number of characters copied. The -@var{size} argument specifies the maximum number of characters to copy, -usually the allocation size of @var{buffer}. - -If the return value equals @var{size}, you cannot tell whether or not -there was room to return the entire name. So make a bigger buffer and -call @code{readlink} again. Here is an example: - -@smallexample -char * -readlink_malloc (const char *filename) -@{ - int size = 100; - char *buffer = NULL; - - while (1) - @{ - buffer = (char *) xrealloc (buffer, size); - int nchars = readlink (filename, buffer, size); - if (nchars < 0) - @{ - free (buffer); - return NULL; - @} - if (nchars < size) - return buffer; - size *= 2; - @} -@} -@end smallexample - -@c @group Invalid outside example. -A value of @code{-1} is returned in case of error. In addition to the -usual file name errors (@pxref{File Name Errors}), the following -@code{errno} error conditions are defined for this function: - -@table @code -@item EINVAL -The named file is not a symbolic link. - -@item EIO -A hardware error occurred while reading or writing data on the disk. -@end table -@c @end group -@end deftypefun - -In some situations it is desirable to resolve all the -symbolic links to get the real -name of a file where no prefix names a symbolic link which is followed -and no filename in the path is @code{.} or @code{..}. This is for -instance desirable if files have to be compared in which case different -names can refer to the same inode. - -@comment stdlib.h -@comment GNU -@deftypefun {char *} canonicalize_file_name (const char *@var{name}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c Calls realpath. - -The @code{canonicalize_file_name} function returns the absolute name of -the file named by @var{name} which contains no @code{.}, @code{..} -components nor any repeated path separators (@code{/}) or symlinks. The -result is passed back as the return value of the function in a block of -memory allocated with @code{malloc}. If the result is not used anymore -the memory should be freed with a call to @code{free}. - -If any of the path components are missing the function returns a NULL -pointer. This is also what is returned if the length of the path -reaches or exceeds @code{PATH_MAX} characters. In any case -@code{errno} is set accordingly. - -@table @code -@item ENAMETOOLONG -The resulting path is too long. This error only occurs on systems which -have a limit on the file name length. - -@item EACCES -At least one of the path components is not readable. - -@item ENOENT -The input file name is empty. - -@item ENOENT -At least one of the path components does not exist. - -@item ELOOP -More than @code{MAXSYMLINKS} many symlinks have been followed. -@end table - -This function is a GNU extension and is declared in @file{stdlib.h}. -@end deftypefun - -The Unix standard includes a similar function which differs from -@code{canonicalize_file_name} in that the user has to provide the buffer -where the result is placed in. - -@comment stdlib.h -@comment XPG -@deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved}) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}} -@c Calls malloc, realloc, getcwd, lxstat64, readlink, alloca. - -A call to @code{realpath} where the @var{resolved} parameter is -@code{NULL} behaves exactly like @code{canonicalize_file_name}. The -function allocates a buffer for the file name and returns a pointer to -it. If @var{resolved} is not @code{NULL} it points to a buffer into -which the result is copied. It is the callers responsibility to -allocate a buffer which is large enough. On systems which define -@code{PATH_MAX} this means the buffer must be large enough for a -pathname of this size. For systems without limitations on the pathname -length the requirement cannot be met and programs should not call -@code{realpath} with anything but @code{NULL} for the second parameter. - -One other difference is that the buffer @var{resolved} (if nonzero) will -contain the part of the path component which does not exist or is not -readable if the function returns @code{NULL} and @code{errno} is set to -@code{EACCES} or @code{ENOENT}. - -This function is declared in @file{stdlib.h}. -@end deftypefun - -The advantage of using this function is that it is more widely -available. The drawback is that it reports failures for long paths on -systems which have no limits on the file name length. - -@node Deleting Files -@section Deleting Files -@cindex deleting a file -@cindex removing a file -@cindex unlinking a file - -You can delete a file with @code{unlink} or @code{remove}. - -Deletion actually deletes a file name. If this is the file's only name, -then the file is deleted as well. If the file has other remaining names -(@pxref{Hard Links}), it remains accessible under those names. - -@comment unistd.h -@comment POSIX.1 -@deftypefun int unlink (const char *@var{filename}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{unlink} function deletes the file name @var{filename}. If -this is a file's sole name, the file itself is also deleted. (Actually, -if any process has the file open when this happens, deletion is -postponed until all processes have closed the file.) - -@pindex unistd.h -The function @code{unlink} is declared in the header file @file{unistd.h}. - -This function returns @code{0} on successful completion, and @code{-1} -on error. In addition to the usual file name errors -(@pxref{File Name Errors}), the following @code{errno} error conditions are -defined for this function: - -@table @code -@item EACCES -Write permission is denied for the directory from which the file is to be -removed, or the directory has the sticky bit set and you do not own the file. - -@item EBUSY -This error indicates that the file is being used by the system in such a -way that it can't be unlinked. For example, you might see this error if -the file name specifies the root directory or a mount point for a file -system. - -@item ENOENT -The file name to be deleted doesn't exist. - -@item EPERM -On some systems @code{unlink} cannot be used to delete the name of a -directory, or at least can only be used this way by a privileged user. -To avoid such problems, use @code{rmdir} to delete directories. (On -@gnulinuxhurdsystems{} @code{unlink} can never delete the name of a directory.) - -@item EROFS -The directory containing the file name to be deleted is on a read-only -file system and can't be modified. -@end table -@end deftypefun - -@comment unistd.h -@comment POSIX.1 -@deftypefun int rmdir (const char *@var{filename}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@cindex directories, deleting -@cindex deleting a directory -The @code{rmdir} function deletes a directory. The directory must be -empty before it can be removed; in other words, it can only contain -entries for @file{.} and @file{..}. - -In most other respects, @code{rmdir} behaves like @code{unlink}. There -are two additional @code{errno} error conditions defined for -@code{rmdir}: - -@table @code -@item ENOTEMPTY -@itemx EEXIST -The directory to be deleted is not empty. -@end table - -These two error codes are synonymous; some systems use one, and some use -the other. @gnulinuxhurdsystems{} always use @code{ENOTEMPTY}. - -The prototype for this function is declared in the header file -@file{unistd.h}. -@pindex unistd.h -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun int remove (const char *@var{filename}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Calls unlink and rmdir. -This is the @w{ISO C} function to remove a file. It works like -@code{unlink} for files and like @code{rmdir} for directories. -@code{remove} is declared in @file{stdio.h}. -@pindex stdio.h -@end deftypefun - -@node Renaming Files -@section Renaming Files - -The @code{rename} function is used to change a file's name. - -@cindex renaming a file -@comment stdio.h -@comment ISO -@deftypefun int rename (const char *@var{oldname}, const char *@var{newname}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c In the absence of a rename syscall, there's an emulation with link -@c and unlink, but it's racy, even more so if newname exists and is -@c unlinked first. -The @code{rename} function renames the file @var{oldname} to -@var{newname}. The file formerly accessible under the name -@var{oldname} is afterwards accessible as @var{newname} instead. (If -the file had any other names aside from @var{oldname}, it continues to -have those names.) - -The directory containing the name @var{newname} must be on the same file -system as the directory containing the name @var{oldname}. - -One special case for @code{rename} is when @var{oldname} and -@var{newname} are two names for the same file. The consistent way to -handle this case is to delete @var{oldname}. However, in this case -POSIX requires that @code{rename} do nothing and report success---which -is inconsistent. We don't know what your operating system will do. - -If @var{oldname} is not a directory, then any existing file named -@var{newname} is removed during the renaming operation. However, if -@var{newname} is the name of a directory, @code{rename} fails in this -case. - -If @var{oldname} is a directory, then either @var{newname} must not -exist or it must name a directory that is empty. In the latter case, -the existing directory named @var{newname} is deleted first. The name -@var{newname} must not specify a subdirectory of the directory -@code{oldname} which is being renamed. - -One useful feature of @code{rename} is that the meaning of @var{newname} -changes ``atomically'' from any previously existing file by that name to -its new meaning (i.e., the file that was called @var{oldname}). There is -no instant at which @var{newname} is non-existent ``in between'' the old -meaning and the new meaning. If there is a system crash during the -operation, it is possible for both names to still exist; but -@var{newname} will always be intact if it exists at all. - -If @code{rename} fails, it returns @code{-1}. In addition to the usual -file name errors (@pxref{File Name Errors}), the following -@code{errno} error conditions are defined for this function: - -@table @code -@item EACCES -One of the directories containing @var{newname} or @var{oldname} -refuses write permission; or @var{newname} and @var{oldname} are -directories and write permission is refused for one of them. - -@item EBUSY -A directory named by @var{oldname} or @var{newname} is being used by -the system in a way that prevents the renaming from working. This includes -directories that are mount points for filesystems, and directories -that are the current working directories of processes. - -@item ENOTEMPTY -@itemx EEXIST -The directory @var{newname} isn't empty. @gnulinuxhurdsystems{} always return -@code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}. - -@item EINVAL -@var{oldname} is a directory that contains @var{newname}. - -@item EISDIR -@var{newname} is a directory but the @var{oldname} isn't. - -@item EMLINK -The parent directory of @var{newname} would have too many links -(entries). - -@item ENOENT -The file @var{oldname} doesn't exist. - -@item ENOSPC -The directory that would contain @var{newname} has no room for another -entry, and there is no space left in the file system to expand it. - -@item EROFS -The operation would involve writing to a directory on a read-only file -system. - -@item EXDEV -The two file names @var{newname} and @var{oldname} are on different -file systems. -@end table -@end deftypefun - -@node Creating Directories -@section Creating Directories -@cindex creating a directory -@cindex directories, creating - -@pindex mkdir -Directories are created with the @code{mkdir} function. (There is also -a shell command @code{mkdir} which does the same thing.) -@c !!! umask - -@comment sys/stat.h -@comment POSIX.1 -@deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{mkdir} function creates a new, empty directory with name -@var{filename}. - -The argument @var{mode} specifies the file permissions for the new -directory file. @xref{Permission Bits}, for more information about -this. - -A return value of @code{0} indicates successful completion, and -@code{-1} indicates failure. In addition to the usual file name syntax -errors (@pxref{File Name Errors}), the following @code{errno} error -conditions are defined for this function: - -@table @code -@item EACCES -Write permission is denied for the parent directory in which the new -directory is to be added. - -@item EEXIST -A file named @var{filename} already exists. - -@item EMLINK -The parent directory has too many links (entries). - -Well-designed file systems never report this error, because they permit -more links than your disk could possibly hold. However, you must still -take account of the possibility of this error, as it could result from -network access to a file system on another machine. - -@item ENOSPC -The file system doesn't have enough room to create the new directory. - -@item EROFS -The parent directory of the directory being created is on a read-only -file system and cannot be modified. -@end table - -To use this function, your program should include the header file -@file{sys/stat.h}. -@pindex sys/stat.h -@end deftypefun - -@node File Attributes -@section File Attributes - -@pindex ls -When you issue an @samp{ls -l} shell command on a file, it gives you -information about the size of the file, who owns it, when it was last -modified, etc. These are called the @dfn{file attributes}, and are -associated with the file itself and not a particular one of its names. - -This section contains information about how you can inquire about and -modify the attributes of a file. - -@menu -* Attribute Meanings:: The names of the file attributes, - and what their values mean. -* Reading Attributes:: How to read the attributes of a file. -* Testing File Type:: Distinguishing ordinary files, - directories, links@dots{} -* File Owner:: How ownership for new files is determined, - and how to change it. -* Permission Bits:: How information about a file's access - mode is stored. -* Access Permission:: How the system decides who can access a file. -* Setting Permissions:: How permissions for new files are assigned, - and how to change them. -* Testing File Access:: How to find out if your process can - access a file. -* File Times:: About the time attributes of a file. -* File Size:: Manually changing the size of a file. -* Storage Allocation:: Allocate backing storage for files. -@end menu - -@node Attribute Meanings -@subsection The meaning of the File Attributes -@cindex status of a file -@cindex attributes of a file -@cindex file attributes - -When you read the attributes of a file, they come back in a structure -called @code{struct stat}. This section describes the names of the -attributes, their data types, and what they mean. For the functions -to read the attributes of a file, see @ref{Reading Attributes}. - -The header file @file{sys/stat.h} declares all the symbols defined -in this section. -@pindex sys/stat.h - -@comment sys/stat.h -@comment POSIX.1 -@deftp {Data Type} {struct stat} -The @code{stat} structure type is used to return information about the -attributes of a file. It contains at least the following members: - -@table @code -@item mode_t st_mode -Specifies the mode of the file. This includes file type information -(@pxref{Testing File Type}) and the file permission bits -(@pxref{Permission Bits}). - -@item ino_t st_ino -The file serial number, which distinguishes this file from all other -files on the same device. - -@item dev_t st_dev -Identifies the device containing the file. The @code{st_ino} and -@code{st_dev}, taken together, uniquely identify the file. The -@code{st_dev} value is not necessarily consistent across reboots or -system crashes, however. - -@item nlink_t st_nlink -The number of hard links to the file. This count keeps track of how -many directories have entries for this file. If the count is ever -decremented to zero, then the file itself is discarded as soon as no -process still holds it open. Symbolic links are not counted in the -total. - -@item uid_t st_uid -The user ID of the file's owner. @xref{File Owner}. - -@item gid_t st_gid -The group ID of the file. @xref{File Owner}. - -@item off_t st_size -This specifies the size of a regular file in bytes. For files that are -really devices this field isn't usually meaningful. For symbolic links -this specifies the length of the file name the link refers to. - -@item time_t st_atime -This is the last access time for the file. @xref{File Times}. - -@item unsigned long int st_atime_usec -This is the fractional part of the last access time for the file. -@xref{File Times}. - -@item time_t st_mtime -This is the time of the last modification to the contents of the file. -@xref{File Times}. - -@item unsigned long int st_mtime_usec -This is the fractional part of the time of the last modification to the -contents of the file. @xref{File Times}. - -@item time_t st_ctime -This is the time of the last modification to the attributes of the file. -@xref{File Times}. - -@item unsigned long int st_ctime_usec -This is the fractional part of the time of the last modification to the -attributes of the file. @xref{File Times}. - -@c !!! st_rdev -@item blkcnt_t st_blocks -This is the amount of disk space that the file occupies, measured in -units of 512-byte blocks. - -The number of disk blocks is not strictly proportional to the size of -the file, for two reasons: the file system may use some blocks for -internal record keeping; and the file may be sparse---it may have -``holes'' which contain zeros but do not actually take up space on the -disk. - -You can tell (approximately) whether a file is sparse by comparing this -value with @code{st_size}, like this: - -@smallexample -(st.st_blocks * 512 < st.st_size) -@end smallexample - -This test is not perfect because a file that is just slightly sparse -might not be detected as sparse at all. For practical applications, -this is not a problem. - -@item unsigned int st_blksize -The optimal block size for reading or writing this file, in bytes. You -might use this size for allocating the buffer space for reading or -writing the file. (This is unrelated to @code{st_blocks}.) -@end table -@end deftp - -The extensions for the Large File Support (LFS) require, even on 32-bit -machines, types which can handle file sizes up to @twoexp{63}. -Therefore a new definition of @code{struct stat} is necessary. - -@comment sys/stat.h -@comment LFS -@deftp {Data Type} {struct stat64} -The members of this type are the same and have the same names as those -in @code{struct stat}. The only difference is that the members -@code{st_ino}, @code{st_size}, and @code{st_blocks} have a different -type to support larger values. - -@table @code -@item mode_t st_mode -Specifies the mode of the file. This includes file type information -(@pxref{Testing File Type}) and the file permission bits -(@pxref{Permission Bits}). - -@item ino64_t st_ino -The file serial number, which distinguishes this file from all other -files on the same device. - -@item dev_t st_dev -Identifies the device containing the file. The @code{st_ino} and -@code{st_dev}, taken together, uniquely identify the file. The -@code{st_dev} value is not necessarily consistent across reboots or -system crashes, however. - -@item nlink_t st_nlink -The number of hard links to the file. This count keeps track of how -many directories have entries for this file. If the count is ever -decremented to zero, then the file itself is discarded as soon as no -process still holds it open. Symbolic links are not counted in the -total. - -@item uid_t st_uid -The user ID of the file's owner. @xref{File Owner}. - -@item gid_t st_gid -The group ID of the file. @xref{File Owner}. - -@item off64_t st_size -This specifies the size of a regular file in bytes. For files that are -really devices this field isn't usually meaningful. For symbolic links -this specifies the length of the file name the link refers to. - -@item time_t st_atime -This is the last access time for the file. @xref{File Times}. - -@item unsigned long int st_atime_usec -This is the fractional part of the last access time for the file. -@xref{File Times}. - -@item time_t st_mtime -This is the time of the last modification to the contents of the file. -@xref{File Times}. - -@item unsigned long int st_mtime_usec -This is the fractional part of the time of the last modification to the -contents of the file. @xref{File Times}. - -@item time_t st_ctime -This is the time of the last modification to the attributes of the file. -@xref{File Times}. - -@item unsigned long int st_ctime_usec -This is the fractional part of the time of the last modification to the -attributes of the file. @xref{File Times}. - -@c !!! st_rdev -@item blkcnt64_t st_blocks -This is the amount of disk space that the file occupies, measured in -units of 512-byte blocks. - -@item unsigned int st_blksize -The optimal block size for reading of writing this file, in bytes. You -might use this size for allocating the buffer space for reading of -writing the file. (This is unrelated to @code{st_blocks}.) -@end table -@end deftp - -Some of the file attributes have special data type names which exist -specifically for those attributes. (They are all aliases for well-known -integer types that you know and love.) These typedef names are defined -in the header file @file{sys/types.h} as well as in @file{sys/stat.h}. -Here is a list of them. - -@comment sys/types.h -@comment POSIX.1 -@deftp {Data Type} mode_t -This is an integer data type used to represent file modes. In -@theglibc{}, this is an unsigned type no narrower than @code{unsigned -int}. -@end deftp - -@cindex inode number -@comment sys/types.h -@comment POSIX.1 -@deftp {Data Type} ino_t -This is an unsigned integer type used to represent file serial numbers. -(In Unix jargon, these are sometimes called @dfn{inode numbers}.) -In @theglibc{}, this type is no narrower than @code{unsigned int}. - -If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type -is transparently replaced by @code{ino64_t}. -@end deftp - -@comment sys/types.h -@comment Unix98 -@deftp {Data Type} ino64_t -This is an unsigned integer type used to represent file serial numbers -for the use in LFS. In @theglibc{}, this type is no narrower than -@code{unsigned int}. - -When compiling with @code{_FILE_OFFSET_BITS == 64} this type is -available under the name @code{ino_t}. -@end deftp - -@comment sys/types.h -@comment POSIX.1 -@deftp {Data Type} dev_t -This is an arithmetic data type used to represent file device numbers. -In @theglibc{}, this is an integer type no narrower than @code{int}. -@end deftp - -@comment sys/types.h -@comment POSIX.1 -@deftp {Data Type} nlink_t -This is an integer type used to represent file link counts. -@end deftp - -@comment sys/types.h -@comment Unix98 -@deftp {Data Type} blkcnt_t -This is a signed integer type used to represent block counts. -In @theglibc{}, this type is no narrower than @code{int}. - -If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type -is transparently replaced by @code{blkcnt64_t}. -@end deftp - -@comment sys/types.h -@comment Unix98 -@deftp {Data Type} blkcnt64_t -This is a signed integer type used to represent block counts for the -use in LFS. In @theglibc{}, this type is no narrower than @code{int}. - -When compiling with @code{_FILE_OFFSET_BITS == 64} this type is -available under the name @code{blkcnt_t}. -@end deftp - -@node Reading Attributes -@subsection Reading the Attributes of a File - -To examine the attributes of files, use the functions @code{stat}, -@code{fstat} and @code{lstat}. They return the attribute information in -a @code{struct stat} object. All three functions are declared in the -header file @file{sys/stat.h}. - -@comment sys/stat.h -@comment POSIX.1 -@deftypefun int stat (const char *@var{filename}, struct stat *@var{buf}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{stat} function returns information about the attributes of the -file named by @w{@var{filename}} in the structure pointed to by @var{buf}. - -If @var{filename} is the name of a symbolic link, the attributes you get -describe the file that the link points to. If the link points to a -nonexistent file name, then @code{stat} fails reporting a nonexistent -file. - -The return value is @code{0} if the operation is successful, or -@code{-1} on failure. In addition to the usual file name errors -(@pxref{File Name Errors}, the following @code{errno} error conditions -are defined for this function: - -@table @code -@item ENOENT -The file named by @var{filename} doesn't exist. -@end table - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -function is in fact @code{stat64} since the LFS interface transparently -replaces the normal implementation. -@end deftypefun - -@comment sys/stat.h -@comment Unix98 -@deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function is similar to @code{stat} but it is also able to work on -files larger than @twoexp{31} bytes on 32-bit systems. To be able to do -this the result is stored in a variable of type @code{struct stat64} to -which @var{buf} must point. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -function is available under the name @code{stat} and so transparently -replaces the interface for small files on 32-bit machines. -@end deftypefun - -@comment sys/stat.h -@comment POSIX.1 -@deftypefun int fstat (int @var{filedes}, struct stat *@var{buf}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{fstat} function is like @code{stat}, except that it takes an -open file descriptor as an argument instead of a file name. -@xref{Low-Level I/O}. - -Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1} -on failure. The following @code{errno} error conditions are defined for -@code{fstat}: - -@table @code -@item EBADF -The @var{filedes} argument is not a valid file descriptor. -@end table - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -function is in fact @code{fstat64} since the LFS interface transparently -replaces the normal implementation. -@end deftypefun - -@comment sys/stat.h -@comment Unix98 -@deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function is similar to @code{fstat} but is able to work on large -files on 32-bit platforms. For large files the file descriptor -@var{filedes} should be obtained by @code{open64} or @code{creat64}. -The @var{buf} pointer points to a variable of type @code{struct stat64} -which is able to represent the larger values. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -function is available under the name @code{fstat} and so transparently -replaces the interface for small files on 32-bit machines. -@end deftypefun - -@c fstatat will call alloca and snprintf if the syscall is not -@c available. -@c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} - -@comment sys/stat.h -@comment BSD -@deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Direct system call through lxstat, sometimes with an xstat conv call -@c afterwards. -The @code{lstat} function is like @code{stat}, except that it does not -follow symbolic links. If @var{filename} is the name of a symbolic -link, @code{lstat} returns information about the link itself; otherwise -@code{lstat} works like @code{stat}. @xref{Symbolic Links}. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -function is in fact @code{lstat64} since the LFS interface transparently -replaces the normal implementation. -@end deftypefun - -@comment sys/stat.h -@comment Unix98 -@deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Direct system call through lxstat64, sometimes with an xstat conv -@c call afterwards. -This function is similar to @code{lstat} but it is also able to work on -files larger than @twoexp{31} bytes on 32-bit systems. To be able to do -this the result is stored in a variable of type @code{struct stat64} to -which @var{buf} must point. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -function is available under the name @code{lstat} and so transparently -replaces the interface for small files on 32-bit machines. -@end deftypefun - -@node Testing File Type -@subsection Testing the Type of a File - -The @dfn{file mode}, stored in the @code{st_mode} field of the file -attributes, contains two kinds of information: the file type code, and -the access permission bits. This section discusses only the type code, -which you can use to tell whether the file is a directory, socket, -symbolic link, and so on. For details about access permissions see -@ref{Permission Bits}. - -There are two ways you can access the file type information in a file -mode. Firstly, for each file type there is a @dfn{predicate macro} -which examines a given file mode and returns whether it is of that type -or not. Secondly, you can mask out the rest of the file mode to leave -just the file type code, and compare this against constants for each of -the supported file types. - -All of the symbols listed in this section are defined in the header file -@file{sys/stat.h}. -@pindex sys/stat.h - -The following predicate macros test the type of a file, given the value -@var{m} which is the @code{st_mode} field returned by @code{stat} on -that file: - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_ISDIR (mode_t @var{m}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns non-zero if the file is a directory. -@end deftypefn - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_ISCHR (mode_t @var{m}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns non-zero if the file is a character special file (a -device like a terminal). -@end deftypefn - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_ISBLK (mode_t @var{m}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns non-zero if the file is a block special file (a device -like a disk). -@end deftypefn - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_ISREG (mode_t @var{m}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns non-zero if the file is a regular file. -@end deftypefn - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_ISFIFO (mode_t @var{m}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns non-zero if the file is a FIFO special file, or a -pipe. @xref{Pipes and FIFOs}. -@end deftypefn - -@comment sys/stat.h -@comment GNU -@deftypefn Macro int S_ISLNK (mode_t @var{m}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns non-zero if the file is a symbolic link. -@xref{Symbolic Links}. -@end deftypefn - -@comment sys/stat.h -@comment GNU -@deftypefn Macro int S_ISSOCK (mode_t @var{m}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This macro returns non-zero if the file is a socket. @xref{Sockets}. -@end deftypefn - -An alternate non-POSIX method of testing the file type is supported for -compatibility with BSD. The mode can be bitwise AND-ed with -@code{S_IFMT} to extract the file type code, and compared to the -appropriate constant. For example, - -@smallexample -S_ISCHR (@var{mode}) -@end smallexample - -@noindent -is equivalent to: - -@smallexample -((@var{mode} & S_IFMT) == S_IFCHR) -@end smallexample - -@comment sys/stat.h -@comment BSD -@deftypevr Macro int S_IFMT -This is a bit mask used to extract the file type code from a mode value. -@end deftypevr - -These are the symbolic names for the different file type codes: - -@vtable @code -@comment sys/stat.h -@comment BSD -@item S_IFDIR -This is the file type constant of a directory file. - -@comment sys/stat.h -@comment BSD -@item S_IFCHR -This is the file type constant of a character-oriented device file. - -@comment sys/stat.h -@comment BSD -@item S_IFBLK -This is the file type constant of a block-oriented device file. - -@comment sys/stat.h -@comment BSD -@item S_IFREG -This is the file type constant of a regular file. - -@comment sys/stat.h -@comment BSD -@item S_IFLNK -This is the file type constant of a symbolic link. - -@comment sys/stat.h -@comment BSD -@item S_IFSOCK -This is the file type constant of a socket. - -@comment sys/stat.h -@comment BSD -@item S_IFIFO -This is the file type constant of a FIFO or pipe. -@end vtable - -The POSIX.1b standard introduced a few more objects which possibly can -be implemented as objects in the filesystem. These are message queues, -semaphores, and shared memory objects. To allow differentiating these -objects from other files the POSIX standard introduced three new test -macros. But unlike the other macros they do not take the value of the -@code{st_mode} field as the parameter. Instead they expect a pointer to -the whole @code{struct stat} structure. - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_TYPEISMQ (struct stat *@var{s}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -If the system implements POSIX message queues as distinct objects and the -file is a message queue object, this macro returns a non-zero value. -In all other cases the result is zero. -@end deftypefn - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_TYPEISSEM (struct stat *@var{s}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -If the system implements POSIX semaphores as distinct objects and the -file is a semaphore object, this macro returns a non-zero value. -In all other cases the result is zero. -@end deftypefn - -@comment sys/stat.h -@comment POSIX -@deftypefn Macro int S_TYPEISSHM (struct stat *@var{s}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -If the system implements POSIX shared memory objects as distinct objects -and the file is a shared memory object, this macro returns a non-zero -value. In all other cases the result is zero. -@end deftypefn - -@node File Owner -@subsection File Owner -@cindex file owner -@cindex owner of a file -@cindex group owner of a file - -Every file has an @dfn{owner} which is one of the registered user names -defined on the system. Each file also has a @dfn{group} which is one of -the defined groups. The file owner can often be useful for showing you -who edited the file (especially when you edit with GNU Emacs), but its -main purpose is for access control. - -The file owner and group play a role in determining access because the -file has one set of access permission bits for the owner, another set -that applies to users who belong to the file's group, and a third set of -bits that applies to everyone else. @xref{Access Permission}, for the -details of how access is decided based on this data. - -When a file is created, its owner is set to the effective user ID of the -process that creates it (@pxref{Process Persona}). The file's group ID -may be set to either the effective group ID of the process, or the group -ID of the directory that contains the file, depending on the system -where the file is stored. When you access a remote file system, it -behaves according to its own rules, not according to the system your -program is running on. Thus, your program must be prepared to encounter -either kind of behavior no matter what kind of system you run it on. - -@pindex chown -@pindex chgrp -You can change the owner and/or group owner of an existing file using -the @code{chown} function. This is the primitive for the @code{chown} -and @code{chgrp} shell commands. - -@pindex unistd.h -The prototype for this function is declared in @file{unistd.h}. - -@comment unistd.h -@comment POSIX.1 -@deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{chown} function changes the owner of the file @var{filename} to -@var{owner}, and its group owner to @var{group}. - -Changing the owner of the file on certain systems clears the set-user-ID -and set-group-ID permission bits. (This is because those bits may not -be appropriate for the new owner.) Other file permission bits are not -changed. - -The return value is @code{0} on success and @code{-1} on failure. -In addition to the usual file name errors (@pxref{File Name Errors}), -the following @code{errno} error conditions are defined for this function: - -@table @code -@item EPERM -This process lacks permission to make the requested change. - -Only privileged users or the file's owner can change the file's group. -On most file systems, only privileged users can change the file owner; -some file systems allow you to change the owner if you are currently the -owner. When you access a remote file system, the behavior you encounter -is determined by the system that actually holds the file, not by the -system your program is running on. - -@xref{Options for Files}, for information about the -@code{_POSIX_CHOWN_RESTRICTED} macro. - -@item EROFS -The file is on a read-only file system. -@end table -@end deftypefun - -@comment unistd.h -@comment BSD -@deftypefun int fchown (int @var{filedes}, uid_t @var{owner}, gid_t @var{group}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This is like @code{chown}, except that it changes the owner of the open -file with descriptor @var{filedes}. - -The return value from @code{fchown} is @code{0} on success and @code{-1} -on failure. The following @code{errno} error codes are defined for this -function: - -@table @code -@item EBADF -The @var{filedes} argument is not a valid file descriptor. - -@item EINVAL -The @var{filedes} argument corresponds to a pipe or socket, not an ordinary -file. - -@item EPERM -This process lacks permission to make the requested change. For details -see @code{chmod} above. - -@item EROFS -The file resides on a read-only file system. -@end table -@end deftypefun - -@node Permission Bits -@subsection The Mode Bits for Access Permission - -The @dfn{file mode}, stored in the @code{st_mode} field of the file -attributes, contains two kinds of information: the file type code, and -the access permission bits. This section discusses only the access -permission bits, which control who can read or write the file. -@xref{Testing File Type}, for information about the file type code. - -All of the symbols listed in this section are defined in the header file -@file{sys/stat.h}. -@pindex sys/stat.h - -@cindex file permission bits -These symbolic constants are defined for the file mode bits that control -access permission for the file: - -@vtable @code -@comment sys/stat.h -@comment POSIX.1 -@item S_IRUSR -@comment sys/stat.h -@comment BSD -@itemx S_IREAD -Read permission bit for the owner of the file. On many systems this bit -is 0400. @code{S_IREAD} is an obsolete synonym provided for BSD -compatibility. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IWUSR -@comment sys/stat.h -@comment BSD -@itemx S_IWRITE -Write permission bit for the owner of the file. Usually 0200. -@w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IXUSR -@comment sys/stat.h -@comment BSD -@itemx S_IEXEC -Execute (for ordinary files) or search (for directories) permission bit -for the owner of the file. Usually 0100. @code{S_IEXEC} is an obsolete -synonym provided for BSD compatibility. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IRWXU -This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IRGRP -Read permission bit for the group owner of the file. Usually 040. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IWGRP -Write permission bit for the group owner of the file. Usually 020. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IXGRP -Execute or search permission bit for the group owner of the file. -Usually 010. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IRWXG -This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IROTH -Read permission bit for other users. Usually 04. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IWOTH -Write permission bit for other users. Usually 02. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IXOTH -Execute or search permission bit for other users. Usually 01. - -@comment sys/stat.h -@comment POSIX.1 -@item S_IRWXO -This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}. - -@comment sys/stat.h -@comment POSIX -@item S_ISUID -This is the set-user-ID on execute bit, usually 04000. -@xref{How Change Persona}. - -@comment sys/stat.h -@comment POSIX -@item S_ISGID -This is the set-group-ID on execute bit, usually 02000. -@xref{How Change Persona}. - -@cindex sticky bit -@comment sys/stat.h -@comment BSD -@item S_ISVTX -This is the @dfn{sticky} bit, usually 01000. - -For a directory it gives permission to delete a file in that directory -only if you own that file. Ordinarily, a user can either delete all the -files in a directory or cannot delete any of them (based on whether the -user has write permission for the directory). The same restriction -applies---you must have both write permission for the directory and own -the file you want to delete. The one exception is that the owner of the -directory can delete any file in the directory, no matter who owns it -(provided the owner has given himself write permission for the -directory). This is commonly used for the @file{/tmp} directory, where -anyone may create files but not delete files created by other users. - -Originally the sticky bit on an executable file modified the swapping -policies of the system. Normally, when a program terminated, its pages -in core were immediately freed and reused. If the sticky bit was set on -the executable file, the system kept the pages in core for a while as if -the program were still running. This was advantageous for a program -likely to be run many times in succession. This usage is obsolete in -modern systems. When a program terminates, its pages always remain in -core as long as there is no shortage of memory in the system. When the -program is next run, its pages will still be in core if no shortage -arose since the last run. - -On some modern systems where the sticky bit has no useful meaning for an -executable file, you cannot set the bit at all for a non-directory. -If you try, @code{chmod} fails with @code{EFTYPE}; -@pxref{Setting Permissions}. - -Some systems (particularly SunOS) have yet another use for the sticky -bit. If the sticky bit is set on a file that is @emph{not} executable, -it means the opposite: never cache the pages of this file at all. The -main use of this is for the files on an NFS server machine which are -used as the swap area of diskless client machines. The idea is that the -pages of the file will be cached in the client's memory, so it is a -waste of the server's memory to cache them a second time. With this -usage the sticky bit also implies that the filesystem may fail to record -the file's modification time onto disk reliably (the idea being that -no-one cares for a swap file). - -This bit is only available on BSD systems (and those derived from -them). Therefore one has to use the @code{_GNU_SOURCE} feature select -macro, or not define any feature test macros, to get the definition -(@pxref{Feature Test Macros}). -@end vtable - -The actual bit values of the symbols are listed in the table above -so you can decode file mode values when debugging your programs. -These bit values are correct for most systems, but they are not -guaranteed. - -@strong{Warning:} Writing explicit numbers for file permissions is bad -practice. Not only is it not portable, it also requires everyone who -reads your program to remember what the bits mean. To make your program -clean use the symbolic names. - -@node Access Permission -@subsection How Your Access to a File is Decided -@cindex permission to access a file -@cindex access permission for a file -@cindex file access permission - -Recall that the operating system normally decides access permission for -a file based on the effective user and group IDs of the process and its -supplementary group IDs, together with the file's owner, group and -permission bits. These concepts are discussed in detail in @ref{Process -Persona}. - -If the effective user ID of the process matches the owner user ID of the -file, then permissions for read, write, and execute/search are -controlled by the corresponding ``user'' (or ``owner'') bits. Likewise, -if any of the effective group ID or supplementary group IDs of the -process matches the group owner ID of the file, then permissions are -controlled by the ``group'' bits. Otherwise, permissions are controlled -by the ``other'' bits. - -Privileged users, like @samp{root}, can access any file regardless of -its permission bits. As a special case, for a file to be executable -even by a privileged user, at least one of its execute bits must be set. - -@node Setting Permissions -@subsection Assigning File Permissions - -@cindex file creation mask -@cindex umask -The primitive functions for creating files (for example, @code{open} or -@code{mkdir}) take a @var{mode} argument, which specifies the file -permissions to give the newly created file. This mode is modified by -the process's @dfn{file creation mask}, or @dfn{umask}, before it is -used. - -The bits that are set in the file creation mask identify permissions -that are always to be disabled for newly created files. For example, if -you set all the ``other'' access bits in the mask, then newly created -files are not accessible at all to processes in the ``other'' category, -even if the @var{mode} argument passed to the create function would -permit such access. In other words, the file creation mask is the -complement of the ordinary access permissions you want to grant. - -Programs that create files typically specify a @var{mode} argument that -includes all the permissions that make sense for the particular file. -For an ordinary file, this is typically read and write permission for -all classes of users. These permissions are then restricted as -specified by the individual user's own file creation mask. - -@findex chmod -To change the permission of an existing file given its name, call -@code{chmod}. This function uses the specified permission bits and -ignores the file creation mask. - -@pindex umask -In normal use, the file creation mask is initialized by the user's login -shell (using the @code{umask} shell command), and inherited by all -subprocesses. Application programs normally don't need to worry about -the file creation mask. It will automatically do what it is supposed to -do. - -When your program needs to create a file and bypass the umask for its -access permissions, the easiest way to do this is to use @code{fchmod} -after opening the file, rather than changing the umask. In fact, -changing the umask is usually done only by shells. They use the -@code{umask} function. - -The functions in this section are declared in @file{sys/stat.h}. -@pindex sys/stat.h - -@comment sys/stat.h -@comment POSIX.1 -@deftypefun mode_t umask (mode_t @var{mask}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{umask} function sets the file creation mask of the current -process to @var{mask}, and returns the previous value of the file -creation mask. - -Here is an example showing how to read the mask with @code{umask} -without changing it permanently: - -@smallexample -mode_t -read_umask (void) -@{ - mode_t mask = umask (0); - umask (mask); - return mask; -@} -@end smallexample - -@noindent -However, on @gnuhurdsystems{} it is better to use @code{getumask} if -you just want to read the mask value, because it is reentrant. -@end deftypefun - -@comment sys/stat.h -@comment GNU -@deftypefun mode_t getumask (void) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -Return the current value of the file creation mask for the current -process. This function is a GNU extension and is only available on -@gnuhurdsystems{}. -@end deftypefun - -@comment sys/stat.h -@comment POSIX.1 -@deftypefun int chmod (const char *@var{filename}, mode_t @var{mode}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{chmod} function sets the access permission bits for the file -named by @var{filename} to @var{mode}. - -If @var{filename} is a symbolic link, @code{chmod} changes the -permissions of the file pointed to by the link, not those of the link -itself. - -This function returns @code{0} if successful and @code{-1} if not. In -addition to the usual file name errors (@pxref{File Name -Errors}), the following @code{errno} error conditions are defined for -this function: - -@table @code -@item ENOENT -The named file doesn't exist. - -@item EPERM -This process does not have permission to change the access permissions -of this file. Only the file's owner (as judged by the effective user ID -of the process) or a privileged user can change them. - -@item EROFS -The file resides on a read-only file system. - -@item EFTYPE -@var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set, -and the named file is not a directory. Some systems do not allow setting the -sticky bit on non-directory files, and some do (and only some of those -assign a useful meaning to the bit for non-directory files). - -You only get @code{EFTYPE} on systems where the sticky bit has no useful -meaning for non-directory files, so it is always safe to just clear the -bit in @var{mode} and call @code{chmod} again. @xref{Permission Bits}, -for full details on the sticky bit. -@end table -@end deftypefun - -@comment sys/stat.h -@comment BSD -@deftypefun int fchmod (int @var{filedes}, mode_t @var{mode}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This is like @code{chmod}, except that it changes the permissions of the -currently open file given by @var{filedes}. - -The return value from @code{fchmod} is @code{0} on success and @code{-1} -on failure. The following @code{errno} error codes are defined for this -function: - -@table @code -@item EBADF -The @var{filedes} argument is not a valid file descriptor. - -@item EINVAL -The @var{filedes} argument corresponds to a pipe or socket, or something -else that doesn't really have access permissions. - -@item EPERM -This process does not have permission to change the access permissions -of this file. Only the file's owner (as judged by the effective user ID -of the process) or a privileged user can change them. - -@item EROFS -The file resides on a read-only file system. -@end table -@end deftypefun - -@node Testing File Access -@subsection Testing Permission to Access a File -@cindex testing access permission -@cindex access, testing for -@cindex setuid programs and file access - -In some situations it is desirable to allow programs to access files or -devices even if this is not possible with the permissions granted to the -user. One possible solution is to set the setuid-bit of the program -file. If such a program is started the @emph{effective} user ID of the -process is changed to that of the owner of the program file. So to -allow write access to files like @file{/etc/passwd}, which normally can -be written only by the super-user, the modifying program will have to be -owned by @code{root} and the setuid-bit must be set. - -But besides the files the program is intended to change the user should -not be allowed to access any file to which s/he would not have access -anyway. The program therefore must explicitly check whether @emph{the -user} would have the necessary access to a file, before it reads or -writes the file. - -To do this, use the function @code{access}, which checks for access -permission based on the process's @emph{real} user ID rather than the -effective user ID. (The setuid feature does not alter the real user ID, -so it reflects the user who actually ran the program.) - -There is another way you could check this access, which is easy to -describe, but very hard to use. This is to examine the file mode bits -and mimic the system's own access computation. This method is -undesirable because many systems have additional access control -features; your program cannot portably mimic them, and you would not -want to try to keep track of the diverse features that different systems -have. Using @code{access} is simple and automatically does whatever is -appropriate for the system you are using. - -@code{access} is @emph{only} appropriate to use in setuid programs. -A non-setuid program will always use the effective ID rather than the -real ID. - -@pindex unistd.h -The symbols in this section are declared in @file{unistd.h}. - -@comment unistd.h -@comment POSIX.1 -@deftypefun int access (const char *@var{filename}, int @var{how}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -The @code{access} function checks to see whether the file named by -@var{filename} can be accessed in the way specified by the @var{how} -argument. The @var{how} argument either can be the bitwise OR of the -flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test -@code{F_OK}. - -This function uses the @emph{real} user and group IDs of the calling -process, rather than the @emph{effective} IDs, to check for access -permission. As a result, if you use the function from a @code{setuid} -or @code{setgid} program (@pxref{How Change Persona}), it gives -information relative to the user who actually ran the program. - -The return value is @code{0} if the access is permitted, and @code{-1} -otherwise. (In other words, treated as a predicate function, -@code{access} returns true if the requested access is @emph{denied}.) - -In addition to the usual file name errors (@pxref{File Name -Errors}), the following @code{errno} error conditions are defined for -this function: - -@table @code -@item EACCES -The access specified by @var{how} is denied. - -@item ENOENT -The file doesn't exist. - -@item EROFS -Write permission was requested for a file on a read-only file system. -@end table -@end deftypefun - -These macros are defined in the header file @file{unistd.h} for use -as the @var{how} argument to the @code{access} function. The values -are integer constants. -@pindex unistd.h - -@comment unistd.h -@comment POSIX.1 -@deftypevr Macro int R_OK -Flag meaning test for read permission. -@end deftypevr - -@comment unistd.h -@comment POSIX.1 -@deftypevr Macro int W_OK -Flag meaning test for write permission. -@end deftypevr - -@comment unistd.h -@comment POSIX.1 -@deftypevr Macro int X_OK -Flag meaning test for execute/search permission. -@end deftypevr - -@comment unistd.h -@comment POSIX.1 -@deftypevr Macro int F_OK -Flag meaning test for existence of the file. -@end deftypevr - -@node File Times -@subsection File Times - -@cindex file access time -@cindex file modification time -@cindex file attribute modification time -Each file has three time stamps associated with it: its access time, -its modification time, and its attribute modification time. These -correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime} -members of the @code{stat} structure; see @ref{File Attributes}. - -All of these times are represented in calendar time format, as -@code{time_t} objects. This data type is defined in @file{time.h}. -For more information about representation and manipulation of time -values, see @ref{Calendar Time}. -@pindex time.h - -Reading from a file updates its access time attribute, and writing -updates its modification time. When a file is created, all three -time stamps for that file are set to the current time. In addition, the -attribute change time and modification time fields of the directory that -contains the new entry are updated. - -Adding a new name for a file with the @code{link} function updates the -attribute change time field of the file being linked, and both the -attribute change time and modification time fields of the directory -containing the new name. These same fields are affected if a file name -is deleted with @code{unlink}, @code{remove} or @code{rmdir}. Renaming -a file with @code{rename} affects only the attribute change time and -modification time fields of the two parent directories involved, and not -the times for the file being renamed. - -Changing the attributes of a file (for example, with @code{chmod}) -updates its attribute change time field. - -You can also change some of the time stamps of a file explicitly using -the @code{utime} function---all except the attribute change time. You -need to include the header file @file{utime.h} to use this facility. -@pindex utime.h - -@comment utime.h -@comment POSIX.1 -@deftp {Data Type} {struct utimbuf} -The @code{utimbuf} structure is used with the @code{utime} function to -specify new access and modification times for a file. It contains the -following members: - -@table @code -@item time_t actime -This is the access time for the file. - -@item time_t modtime -This is the modification time for the file. -@end table -@end deftp - -@comment utime.h -@comment POSIX.1 -@deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c In the absence of a utime syscall, it non-atomically converts times -@c to a struct timeval and calls utimes. -This function is used to modify the file times associated with the file -named @var{filename}. - -If @var{times} is a null pointer, then the access and modification times -of the file are set to the current time. Otherwise, they are set to the -values from the @code{actime} and @code{modtime} members (respectively) -of the @code{utimbuf} structure pointed to by @var{times}. - -The attribute modification time for the file is set to the current time -in either case (since changing the time stamps is itself a modification -of the file attributes). - -The @code{utime} function returns @code{0} if successful and @code{-1} -on failure. In addition to the usual file name errors -(@pxref{File Name Errors}), the following @code{errno} error conditions -are defined for this function: - -@table @code -@item EACCES -There is a permission problem in the case where a null pointer was -passed as the @var{times} argument. In order to update the time stamp on -the file, you must either be the owner of the file, have write -permission for the file, or be a privileged user. - -@item ENOENT -The file doesn't exist. - -@item EPERM -If the @var{times} argument is not a null pointer, you must either be -the owner of the file or be a privileged user. - -@item EROFS -The file lives on a read-only file system. -@end table -@end deftypefun - -Each of the three time stamps has a corresponding microsecond part, -which extends its resolution. These fields are called -@code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec}; -each has a value between 0 and 999,999, which indicates the time in -microseconds. They correspond to the @code{tv_usec} field of a -@code{timeval} structure; see @ref{High-Resolution Calendar}. - -The @code{utimes} function is like @code{utime}, but also lets you specify -the fractional part of the file times. The prototype for this function is -in the header file @file{sys/time.h}. -@pindex sys/time.h - -@comment sys/time.h -@comment BSD -@deftypefun int utimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c In the absence of a utimes syscall, it non-atomically converts tvp -@c to struct timespec array and issues a utimensat syscall, or to -@c struct utimbuf and calls utime. -This function sets the file access and modification times of the file -@var{filename}. The new file access time is specified by -@code{@var{tvp}[0]}, and the new modification time by -@code{@var{tvp}[1]}. Similar to @code{utime}, if @var{tvp} is a null -pointer then the access and modification times of the file are set to -the current time. This function comes from BSD. - -The return values and error conditions are the same as for the @code{utime} -function. -@end deftypefun - -@comment sys/time.h -@comment BSD -@deftypefun int lutimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Since there's no lutimes syscall, it non-atomically converts tvp -@c to struct timespec array and issues a utimensat syscall. -This function is like @code{utimes}, except that it does not follow -symbolic links. If @var{filename} is the name of a symbolic link, -@code{lutimes} sets the file access and modification times of the -symbolic link special file itself (as seen by @code{lstat}; -@pxref{Symbolic Links}) while @code{utimes} sets the file access and -modification times of the file the symbolic link refers to. This -function comes from FreeBSD, and is not available on all platforms (if -not available, it will fail with @code{ENOSYS}). - -The return values and error conditions are the same as for the @code{utime} -function. -@end deftypefun - -@comment sys/time.h -@comment BSD -@deftypefun int futimes (int @var{fd}, const struct timeval @var{tvp}@t{[2]}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Since there's no futimes syscall, it non-atomically converts tvp -@c to struct timespec array and issues a utimensat syscall, falling back -@c to utimes on a /proc/self/fd symlink. -This function is like @code{utimes}, except that it takes an open file -descriptor as an argument instead of a file name. @xref{Low-Level -I/O}. This function comes from FreeBSD, and is not available on all -platforms (if not available, it will fail with @code{ENOSYS}). - -Like @code{utimes}, @code{futimes} returns @code{0} on success and @code{-1} -on failure. The following @code{errno} error conditions are defined for -@code{futimes}: - -@table @code -@item EACCES -There is a permission problem in the case where a null pointer was -passed as the @var{times} argument. In order to update the time stamp on -the file, you must either be the owner of the file, have write -permission for the file, or be a privileged user. - -@item EBADF -The @var{filedes} argument is not a valid file descriptor. - -@item EPERM -If the @var{times} argument is not a null pointer, you must either be -the owner of the file or be a privileged user. - -@item EROFS -The file lives on a read-only file system. -@end table -@end deftypefun - -@node File Size -@subsection File Size - -Normally file sizes are maintained automatically. A file begins with a -size of @math{0} and is automatically extended when data is written past -its end. It is also possible to empty a file completely by an -@code{open} or @code{fopen} call. - -However, sometimes it is necessary to @emph{reduce} the size of a file. -This can be done with the @code{truncate} and @code{ftruncate} functions. -They were introduced in BSD Unix. @code{ftruncate} was later added to -POSIX.1. - -Some systems allow you to extend a file (creating holes) with these -functions. This is useful when using memory-mapped I/O -(@pxref{Memory-mapped I/O}), where files are not automatically extended. -However, it is not portable but must be implemented if @code{mmap} -allows mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined). - -Using these functions on anything other than a regular file gives -@emph{undefined} results. On many systems, such a call will appear to -succeed, without actually accomplishing anything. - -@comment unistd.h -@comment X/Open -@deftypefun int truncate (const char *@var{filename}, off_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c In the absence of a truncate syscall, we use open and ftruncate. - -The @code{truncate} function changes the size of @var{filename} to -@var{length}. If @var{length} is shorter than the previous length, data -at the end will be lost. The file must be writable by the user to -perform this operation. - -If @var{length} is longer, holes will be added to the end. However, some -systems do not support this feature and will leave the file unchanged. - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the -@code{truncate} function is in fact @code{truncate64} and the type -@code{off_t} has 64 bits which makes it possible to handle files up to -@twoexp{63} bytes in length. - -The return value is @math{0} for success, or @math{-1} for an error. In -addition to the usual file name errors, the following errors may occur: - -@table @code - -@item EACCES -The file is a directory or not writable. - -@item EINVAL -@var{length} is negative. - -@item EFBIG -The operation would extend the file beyond the limits of the operating system. - -@item EIO -A hardware I/O error occurred. - -@item EPERM -The file is "append-only" or "immutable". - -@item EINTR -The operation was interrupted by a signal. - -@end table - -@end deftypefun - -@comment unistd.h -@comment Unix98 -@deftypefun int truncate64 (const char *@var{name}, off64_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c In the absence of a syscall, try truncate if length fits. -This function is similar to the @code{truncate} function. The -difference is that the @var{length} argument is 64 bits wide even on 32 -bits machines, which allows the handling of files with sizes up to -@twoexp{63} bytes. - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits machine this function is actually available under the name -@code{truncate} and so transparently replaces the 32 bits interface. -@end deftypefun - -@comment unistd.h -@comment POSIX -@deftypefun int ftruncate (int @var{fd}, off_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -This is like @code{truncate}, but it works on a file descriptor @var{fd} -for an opened file instead of a file name to identify the object. The -file must be opened for writing to successfully carry out the operation. - -The POSIX standard leaves it implementation defined what happens if the -specified new @var{length} of the file is bigger than the original size. -The @code{ftruncate} function might simply leave the file alone and do -nothing or it can increase the size to the desired size. In this later -case the extended area should be zero-filled. So using @code{ftruncate} -is no reliable way to increase the file size but if it is possible it is -probably the fastest way. The function also operates on POSIX shared -memory segments if these are implemented by the system. - -@code{ftruncate} is especially useful in combination with @code{mmap}. -Since the mapped region must have a fixed size one cannot enlarge the -file by writing something beyond the last mapped page. Instead one has -to enlarge the file itself and then remap the file with the new size. -The example below shows how this works. - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the -@code{ftruncate} function is in fact @code{ftruncate64} and the type -@code{off_t} has 64 bits which makes it possible to handle files up to -@twoexp{63} bytes in length. - -The return value is @math{0} for success, or @math{-1} for an error. The -following errors may occur: - -@table @code - -@item EBADF -@var{fd} does not correspond to an open file. - -@item EACCES -@var{fd} is a directory or not open for writing. - -@item EINVAL -@var{length} is negative. - -@item EFBIG -The operation would extend the file beyond the limits of the operating system. -@c or the open() call -- with the not-yet-discussed feature of opening -@c files with extra-large offsets. - -@item EIO -A hardware I/O error occurred. - -@item EPERM -The file is "append-only" or "immutable". - -@item EINTR -The operation was interrupted by a signal. - -@c ENOENT is also possible on Linux --- however it only occurs if the file -@c descriptor has a `file' structure but no `inode' structure. I'm not -@c sure how such an fd could be created. Perhaps it's a bug. - -@end table - -@end deftypefun - -@comment unistd.h -@comment Unix98 -@deftypefun int ftruncate64 (int @var{id}, off64_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c In the absence of a syscall, try ftruncate if length fits. -This function is similar to the @code{ftruncate} function. The -difference is that the @var{length} argument is 64 bits wide even on 32 -bits machines which allows the handling of files with sizes up to -@twoexp{63} bytes. - -When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits machine this function is actually available under the name -@code{ftruncate} and so transparently replaces the 32 bits interface. -@end deftypefun - -As announced here is a little example of how to use @code{ftruncate} in -combination with @code{mmap}: - -@smallexample -int fd; -void *start; -size_t len; - -int -add (off_t at, void *block, size_t size) -@{ - if (at + size > len) - @{ - /* Resize the file and remap. */ - size_t ps = sysconf (_SC_PAGESIZE); - size_t ns = (at + size + ps - 1) & ~(ps - 1); - void *np; - if (ftruncate (fd, ns) < 0) - return -1; - np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0); - if (np == MAP_FAILED) - return -1; - start = np; - len = ns; - @} - memcpy ((char *) start + at, block, size); - return 0; -@} -@end smallexample - -The function @code{add} writes a block of memory at an arbitrary -position in the file. If the current size of the file is too small it -is extended. Note that it is extended by a whole number of pages. This -is a requirement of @code{mmap}. The program has to keep track of the -real size, and when it has finished a final @code{ftruncate} call should -set the real size of the file. - -@node Storage Allocation -@subsection Storage Allocation -@cindex allocating file storage -@cindex file allocation -@cindex storage allocating - -@cindex file fragmentation -@cindex fragmentation of files -@cindex sparse files -@cindex files, sparse -Most file systems support allocating large files in a non-contiguous -fashion: the file is split into @emph{fragments} which are allocated -sequentially, but the fragments themselves can be scattered across the -disk. File systems generally try to avoid such fragmentation because it -decreases performance, but if a file gradually increases in size, there -might be no other option than to fragment it. In addition, many file -systems support @emph{sparse files} with @emph{holes}: regions of null -bytes for which no backing storage has been allocated by the file -system. When the holes are finally overwritten with data, fragmentation -can occur as well. - -Explicit allocation of storage for yet-unwritten parts of the file can -help the system to avoid fragmentation. Additionally, if storage -pre-allocation fails, it is possible to report the out-of-disk error -early, often without filling up the entire disk. However, due to -deduplication, copy-on-write semantics, and file compression, such -pre-allocation may not reliably prevent the out-of-disk-space error from -occurring later. Checking for write errors is still required, and -writes to memory-mapped regions created with @code{mmap} can still -result in @code{SIGBUS}. - -@deftypefun int posix_fallocate (int @var{fd}, off_t @var{offset}, off_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c If the file system does not support allocation, -@c @code{posix_fallocate} has a race with file extension (if -@c @var{length} is zero) or with concurrent writes of non-NUL bytes (if -@c @var{length} is positive). - -Allocate backing store for the region of @var{length} bytes starting at -byte @var{offset} in the file for the descriptor @var{fd}. The file -length is increased to @samp{@var{length} + @var{offset}} if necessary. - -@var{fd} must be a regular file opened for writing, or @code{EBADF} is -returned. If there is insufficient disk space to fulfill the allocation -request, @code{ENOSPC} is returned. - -@strong{Note:} If @code{fallocate} is not available (because the file -system does not support it), @code{posix_fallocate} is emulated, which -has the following drawbacks: - -@itemize @bullet -@item -It is very inefficient because all file system blocks in the requested -range need to be examined (even if they have been allocated before) and -potentially rewritten. In contrast, with proper @code{fallocate} -support (see below), the file system can examine the internal file -allocation data structures and eliminate holes directly, maybe even -using unwritten extents (which are pre-allocated but uninitialized on -disk). - -@item -There is a race condition if another thread or process modifies the -underlying file in the to-be-allocated area. Non-null bytes could be -overwritten with null bytes. - -@item -If @var{fd} has been opened with the @code{O_WRONLY} flag, the function -will fail with an @code{errno} value of @code{EBADF}. - -@item -If @var{fd} has been opened with the @code{O_APPEND} flag, the function -will fail with an @code{errno} value of @code{EBADF}. - -@item -If @var{length} is zero, @code{ftruncate} is used to increase the file -size as requested, without allocating file system blocks. There is a -race condition which means that @code{ftruncate} can accidentally -truncate the file if it has been extended concurrently. -@end itemize - -On Linux, if an application does not benefit from emulation or if the -emulation is harmful due to its inherent race conditions, the -application can use the Linux-specific @code{fallocate} function, with a -zero flag argument. For the @code{fallocate} function, @theglibc{} does -not perform allocation emulation if the file system does not support -allocation. Instead, an @code{EOPNOTSUPP} is returned to the caller. - -@end deftypefun - -@deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{offset}, off64_t @var{length}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} - -This function is a variant of @code{posix_fallocate64} which accepts -64-bit file offsets on all platforms. - -@end deftypefun - -@node Making Special Files -@section Making Special Files -@cindex creating special files -@cindex special files - -The @code{mknod} function is the primitive for making special files, -such as files that correspond to devices. @Theglibc{} includes -this function for compatibility with BSD. - -The prototype for @code{mknod} is declared in @file{sys/stat.h}. -@pindex sys/stat.h - -@comment sys/stat.h -@comment BSD -@deftypefun int mknod (const char *@var{filename}, mode_t @var{mode}, dev_t @var{dev}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c Instead of issuing the syscall directly, we go through xmknod. -@c Although the internal xmknod takes a dev_t*, that could lead to -@c @mtsrace races, it's passed a pointer to mknod's dev. -The @code{mknod} function makes a special file with name @var{filename}. -The @var{mode} specifies the mode of the file, and may include the various -special file bits, such as @code{S_IFCHR} (for a character special file) -or @code{S_IFBLK} (for a block special file). @xref{Testing File Type}. - -The @var{dev} argument specifies which device the special file refers to. -Its exact interpretation depends on the kind of special file being created. - -The return value is @code{0} on success and @code{-1} on error. In addition -to the usual file name errors (@pxref{File Name Errors}), the -following @code{errno} error conditions are defined for this function: - -@table @code -@item EPERM -The calling process is not privileged. Only the superuser can create -special files. - -@item ENOSPC -The directory or file system that would contain the new file is full -and cannot be extended. - -@item EROFS -The directory containing the new file can't be modified because it's on -a read-only file system. - -@item EEXIST -There is already a file named @var{filename}. If you want to replace -this file, you must remove the old file explicitly first. -@end table -@end deftypefun - -@node Temporary Files -@section Temporary Files - -If you need to use a temporary file in your program, you can use the -@code{tmpfile} function to open it. Or you can use the @code{tmpnam} -(better: @code{tmpnam_r}) function to provide a name for a temporary -file and then you can open it in the usual way with @code{fopen}. - -The @code{tempnam} function is like @code{tmpnam} but lets you choose -what directory temporary files will go in, and something about what -their file names will look like. Important for multi-threaded programs -is that @code{tempnam} is reentrant, while @code{tmpnam} is not since it -returns a pointer to a static buffer. - -These facilities are declared in the header file @file{stdio.h}. -@pindex stdio.h - -@comment stdio.h -@comment ISO -@deftypefun {FILE *} tmpfile (void) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} -@c The unsafety issues are those of fdopen, plus @acsfd because of the -@c open. -@c __path_search (internal buf, !dir, const pfx, !try_tmpdir) ok -@c libc_secure_genenv only if try_tmpdir -@c xstat64, strlen, strcmp, sprintf -@c __gen_tempname (internal tmpl, __GT_FILE) ok -@c strlen, memcmp, getpid, open/mkdir/lxstat64 ok -@c HP_TIMING_NOW if available ok -@c gettimeofday (!tz) first time, or every time if no HP_TIMING_NOW ok -@c static value is used and modified without synchronization ok -@c but the use is as a source of non-cryptographic randomness -@c with retries in case of collision, so it should be safe -@c unlink, fdopen -This function creates a temporary binary file for update mode, as if by -calling @code{fopen} with mode @code{"wb+"}. The file is deleted -automatically when it is closed or when the program terminates. (On -some other @w{ISO C} systems the file may fail to be deleted if the program -terminates abnormally). - -This function is reentrant. - -When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32-bit system this function is in fact @code{tmpfile64}, i.e., the LFS -interface transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment Unix98 -@deftypefun {FILE *} tmpfile64 (void) -@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}} -This function is similar to @code{tmpfile}, but the stream it returns a -pointer to was opened using @code{tmpfile64}. Therefore this stream can -be used for files larger than @twoexp{31} bytes on 32-bit machines. - -Please note that the return type is still @code{FILE *}. There is no -special @code{FILE} type for the LFS interface. - -If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 -bits machine this function is available under the name @code{tmpfile} -and so transparently replaces the old interface. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypefun {char *} tmpnam (char *@var{result}) -@safety{@prelim{}@mtunsafe{@mtasurace{:tmpnam/!result}}@asunsafe{}@acsafe{}} -@c The passed-in buffer should not be modified concurrently with the -@c call. -@c __path_search (static or passed-in buf, !dir, !pfx, !try_tmpdir) ok -@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok -This function constructs and returns a valid file name that does not -refer to any existing file. If the @var{result} argument is a null -pointer, the return value is a pointer to an internal static string, -which might be modified by subsequent calls and therefore makes this -function non-reentrant. Otherwise, the @var{result} argument should be -a pointer to an array of at least @code{L_tmpnam} characters, and the -result is written into that array. - -It is possible for @code{tmpnam} to fail if you call it too many times -without removing previously-created files. This is because the limited -length of the temporary file names gives room for only a finite number -of different names. If @code{tmpnam} fails it returns a null pointer. - -@strong{Warning:} Between the time the pathname is constructed and the -file is created another process might have created a file with the same -name using @code{tmpnam}, leading to a possible security hole. The -implementation generates names which can hardly be predicted, but when -opening the file you should use the @code{O_EXCL} flag. Using -@code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem. -@end deftypefun - -@comment stdio.h -@comment GNU -@deftypefun {char *} tmpnam_r (char *@var{result}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function is nearly identical to the @code{tmpnam} function, except -that if @var{result} is a null pointer it returns a null pointer. - -This guarantees reentrancy because the non-reentrant situation of -@code{tmpnam} cannot happen here. - -@strong{Warning}: This function has the same security problems as -@code{tmpnam}. -@end deftypefun - -@comment stdio.h -@comment ISO -@deftypevr Macro int L_tmpnam -The value of this macro is an integer constant expression that -represents the minimum size of a string large enough to hold a file name -generated by the @code{tmpnam} function. -@end deftypevr - -@comment stdio.h -@comment ISO -@deftypevr Macro int TMP_MAX -The macro @code{TMP_MAX} is a lower bound for how many temporary names -you can create with @code{tmpnam}. You can rely on being able to call -@code{tmpnam} at least this many times before it might fail saying you -have made too many temporary file names. - -With @theglibc{}, you can create a very large number of temporary -file names. If you actually created the files, you would probably run -out of disk space before you ran out of names. Some other systems have -a fixed, small limit on the number of temporary files. The limit is -never less than @code{25}. -@end deftypevr - -@comment stdio.h -@comment SVID -@deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix}) -@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} -@c There's no way (short of being setuid) to avoid getenv("TMPDIR"), -@c even with a non-NULL dir. -@c -@c __path_search (internal buf, dir, pfx, try_tmpdir) unsafe getenv -@c __gen_tempname (internal tmpl, __GT_NOCREATE) ok -@c strdup -This function generates a unique temporary file name. If @var{prefix} -is not a null pointer, up to five characters of this string are used as -a prefix for the file name. The return value is a string newly -allocated with @code{malloc}, so you should release its storage with -@code{free} when it is no longer needed. - -Because the string is dynamically allocated this function is reentrant. - -The directory prefix for the temporary file name is determined by -testing each of the following in sequence. The directory must exist and -be writable. - -@itemize @bullet -@item -The environment variable @code{TMPDIR}, if it is defined. For security -reasons this only happens if the program is not SUID or SGID enabled. - -@item -The @var{dir} argument, if it is not a null pointer. - -@item -The value of the @code{P_tmpdir} macro. - -@item -The directory @file{/tmp}. -@end itemize - -This function is defined for SVID compatibility. - -@strong{Warning:} Between the time the pathname is constructed and the -file is created another process might have created a file with the same -name using @code{tempnam}, leading to a possible security hole. The -implementation generates names which can hardly be predicted, but when -opening the file you should use the @code{O_EXCL} flag. Using -@code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem. -@end deftypefun -@cindex TMPDIR environment variable - -@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not?? -@comment stdio.h -@comment SVID -@deftypevr {SVID Macro} {char *} P_tmpdir -This macro is the name of the default directory for temporary files. -@end deftypevr - -Older Unix systems did not have the functions just described. Instead -they used @code{mktemp} and @code{mkstemp}. Both of these functions -work by modifying a file name template string you pass. The last six -characters of this string must be @samp{XXXXXX}. These six @samp{X}s -are replaced with six characters which make the whole string a unique -file name. Usually the template string is something like -@samp{/tmp/@var{prefix}XXXXXX}, and each program uses a unique @var{prefix}. - -@strong{NB:} Because @code{mktemp} and @code{mkstemp} modify the -template string, you @emph{must not} pass string constants to them. -String constants are normally in read-only storage, so your program -would crash when @code{mktemp} or @code{mkstemp} tried to modify the -string. These functions are declared in the header file @file{stdlib.h}. -@pindex stdlib.h - -@comment stdlib.h -@comment Unix -@deftypefun {char *} mktemp (char *@var{template}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c __gen_tempname (caller tmpl, __GT_NOCREATE) ok -The @code{mktemp} function generates a unique file name by modifying -@var{template} as described above. If successful, it returns -@var{template} as modified. If @code{mktemp} cannot find a unique file -name, it makes @var{template} an empty string and returns that. If -@var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a -null pointer. - -@strong{Warning:} Between the time the pathname is constructed and the -file is created another process might have created a file with the same -name using @code{mktemp}, leading to a possible security hole. The -implementation generates names which can hardly be predicted, but when -opening the file you should use the @code{O_EXCL} flag. Using -@code{mkstemp} is a safe way to avoid this problem. -@end deftypefun - -@comment stdlib.h -@comment BSD -@deftypefun int mkstemp (char *@var{template}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} -@c __gen_tempname (caller tmpl, __GT_FILE) ok -The @code{mkstemp} function generates a unique file name just as -@code{mktemp} does, but it also opens the file for you with @code{open} -(@pxref{Opening and Closing Files}). If successful, it modifies -@var{template} in place and returns a file descriptor for that file open -for reading and writing. If @code{mkstemp} cannot create a -uniquely-named file, it returns @code{-1}. If @var{template} does not -end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not -modify @var{template}. - -The file is opened using mode @code{0600}. If the file is meant to be -used by other users this mode must be changed explicitly. -@end deftypefun - -Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a -unique file that cannot possibly clash with any other program trying to -create a temporary file. This is because it works by calling -@code{open} with the @code{O_EXCL} flag, which says you want to create a -new file and get an error if the file already exists. - -@comment stdlib.h -@comment BSD -@deftypefun {char *} mkdtemp (char *@var{template}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c __gen_tempname (caller tmpl, __GT_DIR) ok -The @code{mkdtemp} function creates a directory with a unique name. If -it succeeds, it overwrites @var{template} with the name of the -directory, and returns @var{template}. As with @code{mktemp} and -@code{mkstemp}, @var{template} should be a string ending with -@samp{XXXXXX}. - -If @code{mkdtemp} cannot create an uniquely named directory, it returns -@code{NULL} and sets @var{errno} appropriately. If @var{template} does -not end with @samp{XXXXXX}, @code{mkdtemp} returns @code{NULL} and does -not modify @var{template}. @var{errno} will be set to @code{EINVAL} in -this case. - -The directory is created using mode @code{0700}. -@end deftypefun - -The directory created by @code{mkdtemp} cannot clash with temporary -files or directories created by other users. This is because directory -creation always works like @code{open} with @code{O_EXCL}. -@xref{Creating Directories}. - -The @code{mkdtemp} function comes from OpenBSD. - -@c FIXME these are undocumented: -@c faccessat -@c fchmodat -@c fchownat -@c futimesat -@c fstatat (there's a commented-out safety assessment for this one) -@c linkat -@c mkdirat -@c mkfifoat -@c name_to_handle_at -@c openat -@c open_by_handle_at -@c readlinkat -@c renameat -@c scandirat -@c symlinkat -@c unlinkat -@c utimensat -@c mknodat |