File System Interface
*********************

This chapter describes theglibc's functions for manipulating files.  Unlike the input and output functions (see I/O on Streams; see 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.

Working Directory
=================

Each process has associated with it a directory, called its current working directory or simply working directory, that is used in the resolution of relative file names (see 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 getpwuid or getpwnam functions; see User Database.

Users can change the working directory using shell commands like 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.

Prototypes for these functions are declared in the header file unistd.h.

 -- Function: char * getcwd (char *BUFFER, size_t SIZE)
     POSIX.1, unistd.h

     The getcwd function returns an absolute file name representing the current working directory, storing it in the character array BUFFER that you provide.  The SIZE argument is how you tell the system the allocation size of BUFFER.

     The glibcadj version of this function also permits you to specify a null pointer for the BUFFER argument.  Then getcwd allocates a buffer automatically, as with malloc (see Unconstrained Allocation).  If the 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 BUFFER on success and a null pointer on failure. The following errno error conditions are defined for this function:

     EINVAL
          The SIZE argument is zero and BUFFER is not a null pointer.

     ERANGE
          The SIZE argument is less than the length of the working directory name.  You need to allocate a bigger array and try again.

     EACCES
          Permission to read or search a component of the file name was denied.

You could implement the behavior of GNU's getcwd (NULL, 0) using only the standard behavior of getcwd:

     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;
         }
     }

See Malloc Examples, for information about xmalloc, which is not a library function but is a customary name used in most GNU software.

 -- Deprecated Function: char * getwd (char *BUFFER)
     BSD, unistd.h This is similar to getcwd, but has no way to specify the size of the buffer.  Theglibc provides getwd only for backwards compatibility with BSD.

     The BUFFER argument should be a pointer to an array at least PATH_MAX bytes long (see 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.

 -- Function: char * get_current_dir_name (void)
     GNU, unistd.h The get_current_dir_name function is basically equivalent to getcwd (NULL, 0), except the value of the PWD environment variable is first examined, and if it does in fact correspond to the current directory, that value is returned.  This is a subtle difference which is visible if the path described by the value in PWD is using one or more symbolic links, in which case the value returned by getcwd would resolve the symbolic links and therefore yield a different result.

     This function is a GNU extension.

 -- Function: int chdir (const char *FILENAME)
     POSIX.1, unistd.h This function is used to set the process's working directory to FILENAME.

     The normal, successful return value from chdir is 0.  A value of -1 is returned to indicate an error.  The errno error conditions defined for this function are the usual file name syntax errors (see File Name Errors), plus ENOTDIR if the file FILENAME is not a directory.

 -- Function: int fchdir (int FILEDES)
     XPG, unistd.h This function is used to set the process's working directory to directory associated with the file descriptor FILEDES.

     The normal, successful return value from fchdir is 0.  A value of -1 is returned to indicate an error.  The following errno error conditions are defined for this function:

     EACCES
          Read permission is denied for the directory named by dirname.

     EBADF
          The FILEDES argument is not a valid file descriptor.

     ENOTDIR
          The file descriptor FILEDES is not associated with a directory.

     EINTR
          The function call was interrupt by a signal.

     EIO
          An I/O error occurred.

Accessing Directories
=====================

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.

The opendir function opens a directory stream whose elements are directory entries.  Alternatively 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 O_NOATIME flag to open.

You use the readdir function on the directory stream to retrieve these entries, represented as struct dirent objects.  The name of the file for each entry is stored in the d_name member of this structure.  There are obvious parallels here to the stream facilities for ordinary files, described in I/O on Streams.

Format of a Directory Entry
---------------------------

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 dirent.h.

 -- Data Type: struct dirent
     POSIX.1, dirent.h This is a structure type used to return information about directory entries.  It contains the following fields:

     char d_name[]
          This is the null-terminated file name component.  This is the only field you can count on in all POSIX systems.

     ino_t d_fileno
          This is the file serial number.  For BSD compatibility, you can also refer to this member as d_ino.  On gnulinuxhurdsystems and most POSIX systems, for most files this the same as the st_ino member that stat will return for the file.  See File Attributes.

     unsigned char d_namlen
          This is the length of the file name, not including the terminating null character.  Its type is unsigned char because that is the integer type of the appropriate size.  This member is a BSD extension. The symbol _DIRENT_HAVE_D_NAMLEN is defined if this member is available.

     unsigned char d_type
          This is the type of the file, possibly unknown.  The following constants are defined for its value:

          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.

          DT_REG
               A regular file.

          DT_DIR
               A directory.

          DT_FIFO
               A named pipe, or FIFO.  See FIFO Special Files.

          DT_SOCK
               A local-domain socket.

          DT_CHR
               A character device.

          DT_BLK
               A block device.

          DT_LNK
               A symbolic link.

          This member is a BSD extension.  The symbol _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 st_mode member of struct stat.  If the value cannot be determined the member value is DT_UNKNOWN.  These two macros convert between d_type values and st_mode values:

           -- Function: int IFTODT (mode_t MODE)
               BSD, dirent.h This returns the d_type value corresponding to MODE.

           -- Function: mode_t DTTOIF (int DTYPE)
               BSD, dirent.h This returns the st_mode value corresponding to DTYPE.

     This structure may contain additional members in the future.  Their availability is always announced in the compilation environment by a macro named _DIRENT_HAVE_D_XXX where XXX is replaced by the name of the new member.  For instance, the member d_reclen available on some systems is announced through the macro _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 d_fileno field.

     File attributes such as size, modification times etc., are part of the file itself, not of any particular directory entry.  See File Attributes.

Opening a Directory Stream
--------------------------

This section describes how to open a directory stream.  All the symbols are declared in the header file dirent.h.

 -- Data Type: DIR
     POSIX.1, dirent.h The DIR data type represents a directory stream.

You shouldn't ever allocate objects of the struct dirent or 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.

Directory streams are a high-level interface.  On Linux, alternative interfaces for accessing directories using file descriptors are available.  See Low-level Directory Access.

 -- Function: DIR * opendir (const char *DIRNAME)
     POSIX.1, dirent.h The opendir function opens and returns a directory stream for reading the directory whose file name is DIRNAME.  The stream has type DIR *.

     If unsuccessful, opendir returns a null pointer.  In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     EACCES
          Read permission is denied for the directory named by dirname.

     EMFILE
          The process has too many files open.

     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.)

     ENOMEM
          Not enough memory available.

     The DIR type is typically implemented using a file descriptor, and the opendir function in terms of the open function. See Low-Level I/O.  Directory streams and the underlying file descriptors are closed on exec (see Executing a File).

The directory which is opened for reading by opendir is identified by the name.  In some situations this is not sufficient. Or the way 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.

 -- Function: DIR * fdopendir (int FD)
     GNU, dirent.h The fdopendir function works just like 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 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 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 errno error conditions are defined for this function:

     EBADF
          The file descriptor is not valid.

     ENOTDIR
          The file descriptor is not associated with a directory.

     EINVAL
          The descriptor does not allow reading the directory content.

     ENOMEM
          Not enough memory available.

In some situations it can be desirable to get hold of the file descriptor which is created by the opendir call.  For instance, to switch the current working directory to the directory just read the fchdir function could be used.  Historically the 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.

 -- Function: int dirfd (DIR *DIRSTREAM)
     GNU, dirent.h The function dirfd returns the file descriptor associated with the directory stream DIRSTREAM.  This descriptor can be used until the directory is closed with closedir.  If the directory stream implementation is not using file descriptors the return value is -1.

Reading and Closing a Directory Stream
--------------------------------------

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 dirent.h.

 -- Function: struct dirent * readdir (DIR *DIRSTREAM)
     POSIX.1, dirent.h 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 DIRSTREAM handle and can be rewritten by a subsequent call.

     Portability Note: On some systems readdir may not return entries for . and .., even though these are always valid file names in any directory.  See File Name Resolution.

     If there are no more entries in the directory or an error is detected, readdir returns a null pointer.  The following errno error conditions are defined for this function:

     EBADF
          The DIRSTREAM argument is not valid.

     To distinguish between an end-of-directory condition or an error, you must set errno to zero before calling readdir.  To avoid entering an infinite loop, you should stop reading from the directory after the first error.

     Caution: The pointer returned by readdir points to a buffer within the DIR object.  The data in that buffer will be overwritten by the next call to readdir.  You must take care, for instance, to copy the d_name string if you need it later.

     Because of this, it is not safe to share a DIR object among multiple threads, unless you use your own locking to ensure that no thread calls readdir while another thread is still using the data from the previous call.  In theglibc, it is safe to call readdir from multiple threads as long as each thread uses its own 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.

     readdir_r allows you to provide your own buffer for the struct dirent, but it is less portable than readdir, and has problems with very long filenames (see below).  We recommend you use readdir, but do not share DIR objects.

 -- Function: int readdir_r (DIR *DIRSTREAM, struct dirent *ENTRY, struct dirent **RESULT)
     GNU, dirent.h This function is a version of readdir which performs internal locking.  Like readdir it returns the next entry from the directory.  To prevent conflicts between simultaneously running threads the result is stored inside the ENTRY object.

     Portability Note: readdir_r is deprecated.  It is recommended to use readdir instead of readdir_r for the following reasons:

       * On systems which do not define NAME_MAX, it may not be possible to use readdir_r safely because the caller does not specify the length of the buffer for the directory entry.

       * On some systems, readdir_r cannot read directory entries with very long names.  If such a name is encountered, theglibc implementation of readdir_r returns with an error code of ENAMETOOLONG after the final directory entry has been read.  On other systems, readdir_r may return successfully, but the d_name member may not be NUL-terminated or may be truncated.

       * POSIX-1.2008 does not guarantee that readdir is thread-safe, even when access to the same DIRSTREAM is serialized.  But in current implementations (including theglibc), it is safe to call readdir concurrently on different DIRSTREAMs, so there is no need to use readdir_r in most multi-threaded programs.  In the rare case that multiple threads need to read from the same DIRSTREAM, it is still better to use readdir and external synchronization.

       * It is expected that future versions of POSIX will obsolete readdir_r and mandate the level of thread safety for readdir which is provided by theglibc and other implementations today.

     Normally readdir_r returns zero and sets *RESULT to ENTRY.  If there are no more entries in the directory or an error is detected, readdir_r sets *RESULT to a null pointer and returns a nonzero error code, also stored in errno, as described for readdir.

     It is also important to look at the definition of the struct dirent type.  Simply passing a pointer to an object of this type for the second parameter of readdir_r might not be enough.  Some systems don't define the d_name element sufficiently long.  In this case the user has to provide additional space.  There must be room for at least NAME_MAX + 1 characters in the d_name array. Code to call readdir_r could look like this:

            union
            {
              struct dirent d;
              char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
            } u;

            if (readdir_r (dir, &u.d, &res) == 0)
              ...

To support large filesystems on 32-bit machines there are LFS variants of the last two functions.

 -- Function: struct dirent64 * readdir64 (DIR *DIRSTREAM)
     LFS, dirent.h The readdir64 function is just like the readdir function except that it returns a pointer to a record of type struct dirent64.  Some of the members of this data type (notably d_ino) might have a different size to allow large filesystems.

     In all other aspects this function is equivalent to readdir.

 -- Function: int readdir64_r (DIR *DIRSTREAM, struct dirent64 *ENTRY, struct dirent64 **RESULT)
     LFS, dirent.h The deprecated readdir64_r function is equivalent to the readdir_r function except that it takes parameters of base type struct dirent64 instead of struct dirent in the second and third position.  The same precautions mentioned in the documentation of readdir_r also apply here.

 -- Function: int closedir (DIR *DIRSTREAM)
     POSIX.1, dirent.h prelim mtsafe ascuheap /hurd acsmem acsfd /hurd This function closes the directory stream DIRSTREAM.  It returns 0 on success and -1 on failure.

     The following errno error conditions are defined for this function:

     EBADF
          The DIRSTREAM argument is not valid.

Simple Program to List a Directory
----------------------------------

Here's a simple program that prints the names of the files in the current working directory:

          [file dir.c.texi not included]

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 Scanning Directory Content, and Array Sort Function.

Random Access in a Directory Stream
-----------------------------------

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 dirent.h.

 -- Function: void rewinddir (DIR *DIRSTREAM)
     POSIX.1, dirent.h The rewinddir function is used to reinitialize the directory stream DIRSTREAM, so that if you call 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 opendir.  (Entries for these files might or might not be returned by readdir if they were added or removed since you last called opendir or rewinddir.)

 -- Function: long int telldir (DIR *DIRSTREAM)
     BSD, dirent.h prelim mtsafe/bsd /bsd/bsd /bsd The telldir function returns the file position of the directory stream DIRSTREAM.  You can use this value with seekdir to restore the directory stream to that position.

 -- Function: void seekdir (DIR *DIRSTREAM, long int POS)
     BSD, dirent.h prelim mtsafe/bsd /bsd/bsd /bsd The seekdir function sets the file position of the directory stream DIRSTREAM to POS.  The value POS must be the result of a previous call to telldir on this particular stream; closing and reopening the directory can invalidate values returned by telldir.

Scanning the Content of a Directory
-----------------------------------

A higher-level interface to the directory handling functions is the 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.

 -- Function: int scandir (const char *DIR, struct dirent ***NAMELIST, int (*SELECTOR) (const struct dirent *), int (*CMP) (const struct dirent **, const struct dirent **))
     BSD, dirent.h SVID, dirent.h

     The scandir function scans the contents of the directory selected by DIR.  The result in *NAMELIST is an array of pointers to structures of type struct dirent which describe all selected directory entries and which is allocated using malloc.  Instead of always getting all directory entries returned, the user supplied function SELECTOR can be used to decide which entries are in the result.  Only the entries for which SELECTOR returns a non-zero value are selected.

     Finally the entries in *NAMELIST are sorted using the user-supplied function CMP.  The arguments passed to the CMP function are of type struct dirent **, therefore one cannot directly use the strcmp or strcoll functions; instead see the functions alphasort and versionsort below.

     The return value of the function is the number of entries placed in *NAMELIST.  If it is -1 an error occurred (either the directory could not be opened for reading or memory allocation failed) and the global variable errno contains more information on the error.

As described above, the fourth argument to the 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.

 -- Function: int alphasort (const struct dirent **A, const struct dirent **B)
     BSD, dirent.h SVID, dirent.h The alphasort function behaves like the strcoll function (see String/Array Comparison).  The difference is that the arguments are not string pointers but instead they are of type struct dirent **.

     The return value of alphasort is less than, equal to, or greater than zero depending on the order of the two entries A and B.

 -- Function: int versionsort (const struct dirent **A, const struct dirent **B)
     GNU, dirent.h The versionsort function is like alphasort except that it uses the strverscmp function internally.

If the filesystem supports large files we cannot use the scandir anymore since the dirent structure might not able to contain all the information.  The LFS provides the new type struct dirent64.  To use this we need a new function.

 -- Function: int scandir64 (const char *DIR, struct dirent64 ***NAMELIST, int (*SELECTOR) (const struct dirent64 *), int (*CMP) (const struct dirent64 **, const struct dirent64 **))
     GNU, dirent.h The scandir64 function works like the scandir function except that the directory entries it returns are described by elements of type struct dirent64.  The function pointed to by SELECTOR is again used to select the desired entries, except that SELECTOR now must point to a function which takes a struct dirent64 * parameter.

     Similarly the CMP function should expect its two arguments to be of type struct dirent64 **.

As CMP is now a function of a different type, the functions alphasort and versionsort cannot be supplied for that argument.  Instead we provide the two replacement functions below.

 -- Function: int alphasort64 (const struct dirent64 **A, const struct dirent **B)
     GNU, dirent.h The alphasort64 function behaves like the strcoll function (see String/Array Comparison).  The difference is that the arguments are not string pointers but instead they are of type struct dirent64 **.

     Return value of alphasort64 is less than, equal to, or greater than zero depending on the order of the two entries A and B.

 -- Function: int versionsort64 (const struct dirent64 **A, const struct dirent64 **B)
     GNU, dirent.h The versionsort64 function is like alphasort64, excepted that it uses the strverscmp function internally.

It is important not to mix the use of scandir and the 64-bit comparison functions or vice versa.  There are systems on which this works but on others it will fail miserably.

Simple Program to List a Directory, Mark II
-------------------------------------------

Here is a revised version of the directory lister found above (see Simple Directory Lister).  Using the 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.

          [file dir2.c.texi not included]

Note the simple selector function in this example.  Since we want to see all directory entries we always return 1.

Low-level Directory Access
--------------------------

The stream-based directory functions are not AS-Safe and cannot be used after vfork.  See POSIX Safety Concepts.  The functions below provide an alternative that can be used in these contexts.

Directory data is obtained from a file descriptor, as created by the open function, with or without the O_DIRECTORY flag. See Opening and Closing Files.

 -- Function: ssize_t getdents64 (int FD, void *BUFFER, size_t LENGTH)
     Linux, dirent.h The getdents64 function reads at most LENGTH bytes of directory entry data from the file descriptor FD and stores it into the byte array starting at BUFFER.

     On success, the function returns the number of bytes written to the buffer.  This number is zero if FD is already at the end of the directory stream.  On error, the function returns -1 and sets errno to the appropriate error code.

     The data is stored as a sequence of struct dirent64 records, which can be traversed using the d_reclen member.  The buffer should be large enough to hold the largest possible directory entry. Note that some file systems support file names longer than NAME_MAX bytes (e.g., because they support up to 255 Unicode characters), so a buffer size of at least 1024 is recommended.

     This function is specific to Linux.

Working with Directory Trees
============================

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 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 System V systems and therefore this function is available on SVID-derived systems.  The prototypes and required definitions can be found in the ftw.h header.

There are four functions in this family: ftw, nftw and their 64-bit counterparts ftw64 and nftw64.  These functions take as one of their arguments a pointer to a callback function of the appropriate type.

 -- Data Type: __ftw_func_t
     GNU, ftw.h

          int (*) (const char *, const struct stat *, int)

     The type of callback functions given to the ftw function.  The first parameter points to the file name, the second parameter to an object of type struct stat which is filled in for the file named in the first parameter.

     The last parameter is a flag giving more information about the current file.  It can have the following values:

     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.

     FTW_D
          The item is a directory.

     FTW_NS
          The stat call failed and so the information pointed to by the second parameter is invalid.

     FTW_DNR
          The item is a directory which cannot be read.

     FTW_SL
          The item is a symbolic link.  Since symbolic links are normally followed seeing this value in a ftw callback function means the referenced file does not exist.  The situation for nftw is different.

          This value is only available if the program is compiled with _XOPEN_EXTENDED defined before including the first header.  The original SVID systems do not have symbolic links.

     If the sources are compiled with _FILE_OFFSET_BITS == 64 this type is in fact __ftw64_func_t since this mode changes struct stat to be struct stat64.

For the LFS interface and for use in the function ftw64, the header ftw.h defines another function type.

 -- Data Type: __ftw64_func_t
     GNU, ftw.h

          int (*) (const char *, const struct stat64 *, int)

     This type is used just like __ftw_func_t for the callback function, but this time is called from ftw64.  The second parameter to the function is a pointer to a variable of type struct stat64 which is able to represent the larger values.

 -- Data Type: __nftw_func_t
     GNU, ftw.h

          int (*) (const char *, const struct stat *, int, struct FTW *)

     The first three arguments are the same as for the __ftw_func_t type.  However for the third argument some additional values are defined to allow finer differentiation:

     FTW_DP
          The current item is a directory and all subdirectories have already been visited and reported.  This flag is returned instead of FTW_D if the FTW_DEPTH flag is passed to nftw (see below).

     FTW_SLN
          The current item is a stale symbolic link.  The file it points to does not exist.

     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 _FILE_OFFSET_BITS == 64 this type is in fact __nftw64_func_t since this mode changes struct stat to be struct stat64.

For the LFS interface there is also a variant of this data type available which has to be used with the nftw64 function.

 -- Data Type: __nftw64_func_t
     GNU, ftw.h

          int (*) (const char *, const struct stat64 *, int, struct FTW *)

     This type is used just like __nftw_func_t for the callback function, but this time is called from nftw64.  The second parameter to the function is this time a pointer to a variable of type struct stat64 which is able to represent the larger values.

 -- Data Type: struct FTW
     XPG4.2, ftw.h 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.

     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 FTW_CHDIR flag was set in calling nftw since then the current directory is the one the current item is found in.

     int level
          Whilst processing, the code tracks how many directories down it has gone to find the current file.  This nesting level starts at 0 for files in the initial directory (or is zero for the initial file if a file was passed).

 -- Function: int ftw (const char *FILENAME, __ftw_func_t FUNC, int DESCRIPTORS)
     SVID, ftw.h The ftw function calls the callback function given in the parameter FUNC for every item which is found in the directory specified by FILENAME and all directories below.  The function follows symbolic links if necessary but does not process an item twice. If 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 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.  ftw also calls stat for the file and passes that information on to the callback function.  If this stat call is not successful the failure is indicated by setting the third argument of the callback function to FTW_NS.  Otherwise it is set according to the description given in the account of __ftw_func_t above.

     The callback function is expected to return 0 to indicate that no error occurred and that processing should continue.  If an error occurred in the callback function or it wants ftw to return immediately, the callback function can return a value other than 0.  This is the only correct way to stop the function.  The program must not use setjmp or similar techniques to continue from another place.  This would leave resources allocated by the ftw function unfreed.

     The DESCRIPTORS parameter to 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 ftw function is 0 if all callback function calls returned 0 and all actions performed by the ftw succeeded.  If a function call failed (other than calling stat on an item) the function returns -1.  If a callback function returns a value other than 0 this value is returned as the return value of ftw.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact ftw64, i.e., the LFS interface transparently replaces the old interface.

 -- Function: int ftw64 (const char *FILENAME, __ftw64_func_t FUNC, int DESCRIPTORS)
     Unix98, ftw.h This function is similar to ftw but it can work on filesystems with large files.  File information is reported using a variable of type struct stat64 which is passed by reference to the callback function.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is available under the name ftw and transparently replaces the old implementation.

 -- Function: int nftw (const char *FILENAME, __nftw_func_t FUNC, int DESCRIPTORS, int FLAG)
     XPG4.2, ftw.h The nftw function works like the ftw functions.  They call the callback function FUNC for all items found in the directory FILENAME and below.  At most DESCRIPTORS file descriptors are consumed during the nftw call.

     One difference is that the callback function is of a different type.  It is of type struct FTW * and provides the callback function with the extra information described above.

     A second difference is that nftw takes a fourth argument, which is 0 or a bitwise-OR combination of any of the following values.

     FTW_PHYS
          While traversing the directory symbolic links are not followed.  Instead symbolic links are reported using the FTW_SL value for the type parameter to the callback function.  If the file referenced by a symbolic link does not exist FTW_SLN is returned instead.

     FTW_MOUNT
          The callback function is only called for items which are on the same mounted filesystem as the directory given by the FILENAME parameter to nftw.

     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 ntfw finally returns the current directory is restored to its original value.

     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 FTW_DP and not FTW_D.

     FTW_ACTIONRETVAL
          If this option is specified then return values from callbacks are handled differently.  If the callback returns FTW_CONTINUE, walking continues normally.  FTW_STOP means walking stops and FTW_STOP is returned to the caller.  If FTW_SKIP_SUBTREE is returned by the callback with FTW_D argument, the subtree is skipped and walking continues with next sibling of the directory. If 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.

     The return value is computed in the same way as for ftw. nftw returns 0 if no failures occurred and all callback functions returned 0.  In case of internal errors, such as memory problems, the return value is -1 and 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 _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact nftw64, i.e., the LFS interface transparently replaces the old interface.

 -- Function: int nftw64 (const char *FILENAME, __nftw64_func_t FUNC, int DESCRIPTORS, int FLAG)
     Unix98, ftw.h This function is similar to nftw but it can work on filesystems with large files.  File information is reported using a variable of type struct stat64 which is passed by reference to the callback function.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is available under the name nftw and transparently replaces the old implementation.

Hard Links
==========

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 link function.  (The new name is also called a 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.  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 link function is declared in the header file unistd.h.

 -- Function: int link (const char *OLDNAME, const char *NEWNAME)
     POSIX.1, unistd.h The link function makes a new link to the existing file named by OLDNAME, under the new name NEWNAME.

     This function returns a value of 0 if it is successful and -1 on failure.  In addition to the usual file name errors (see File Name Errors) for both OLDNAME and NEWNAME, the following errno error conditions are defined for this function:

     EACCES
          You are not allowed to write to the directory in which the new link is to be written.

     EEXIST
          There is already a file named NEWNAME.  If you want to replace this link with a new link, you must remove the old link explicitly first.

     EMLINK
          There are already too many links to the file named by OLDNAME. (The maximum number of links to a file is LINK_MAX; see Limits for Files.)

     ENOENT
          The file named by OLDNAME doesn't exist.  You can't make a link to a file that doesn't exist.

     ENOSPC
          The directory or file system that would contain the new link is full and cannot be extended.

     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.

     EROFS
          The directory containing the new link can't be modified because it's on a read-only file system.

     EXDEV
          The directory specified in NEWNAME is on a different file system than the existing file.

     EIO
          A hardware error occurred while trying to read or write the to filesystem.

 -- Function: int linkat (int oldfd, const char *OLDNAME, int newfd, const char *NEWNAME, int flags)
     POSIX.1, unistd.h

     The linkat function is analogous to the link function, except that it identifies its source and target using a combination of a file descriptor (referring to a directory) and a pathname.  If a pathnames is not absolute, it is resolved relative to the corresponding file descriptor.  The special file descriptor AT_FDCWD denotes the current directory.

     The FLAGS argument is a combination of the following flags:

     AT_SYMLINK_FOLLOW
          If the source path identified by OLDFD and OLDNAME is a symbolic link, linkat follows the symbolic link and creates a link to its target.  If the flag is not set, a link for the symbolic link itself is created; this is not supported by all file systems and linkat can fail in this case.

     AT_EMPTY_PATH
          If this flag is specified, OLDNAME can be an empty string.  In this case, a new link to the file denoted by the descriptor OLDFD is created, which may have been opened with O_PATH or O_TMPFILE.  This flag is a GNU extension.

Symbolic Links
==============

gnusystems support soft links or 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 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 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 readlink and lstat also refrain from following symbolic links, because their purpose is to obtain information about the link.  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 sys/param.h header file.

 -- Macro: int MAXSYMLINKS
     BSD, sys/param.h

     The macro MAXSYMLINKS specifies how many symlinks some function will follow before returning ELOOP.  Not all functions behave the same and this value is not the same as that returned for _SC_SYMLOOP by sysconf.  In fact, the sysconf result can indicate that there is no fixed limit although MAXSYMLINKS exists and has a finite value.

Prototypes for most of the functions listed in this section are in unistd.h.

 -- Function: int symlink (const char *OLDNAME, const char *NEWNAME)
     BSD, unistd.h The symlink function makes a symbolic link to OLDNAME named NEWNAME.

     The normal return value from symlink is 0.  A return value of -1 indicates an error.  In addition to the usual file name syntax errors (see File Name Errors), the following errno error conditions are defined for this function:

     EEXIST
          There is already an existing file named NEWNAME.

     EROFS
          The file NEWNAME would exist on a read-only file system.

     ENOSPC
          The directory or file system cannot be extended to make the new link.

     EIO
          A hardware error occurred while reading or writing data on the disk.

 -- Function: ssize_t readlink (const char *FILENAME, char *BUFFER, size_t SIZE)
     BSD, unistd.h The readlink function gets the value of the symbolic link FILENAME.  The file name that the link points to is copied into BUFFER.  This file name string is not null-terminated; readlink normally returns the number of characters copied.  The SIZE argument specifies the maximum number of characters to copy, usually the allocation size of BUFFER.

     If the return value equals SIZE, you cannot tell whether or not there was room to return the entire name.  So make a bigger buffer and call readlink again.  Here is an example:

          char *
          readlink_malloc (const char *filename)
          {
            size_t size = 50;
            char *buffer = NULL;

            while (1)
              {
                buffer = xreallocarray (buffer, size, 2);
                size *= 2;
                ssize_t nchars = readlink (filename, buffer, size);
                if (nchars < 0)
                  {
                    free (buffer);
                    return NULL;
                  }
                if (nchars < size)
                  return buffer;
              }
          }

     A value of -1 is returned in case of error.  In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     EINVAL
          The named file is not a symbolic link.

     EIO
          A hardware error occurred while reading or writing data on the disk.

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 . or ...  This is for instance desirable if files have to be compared in which case different names can refer to the same inode.

 -- Function: char * canonicalize_file_name (const char *NAME)
     GNU, stdlib.h

     The canonicalize_file_name function returns the absolute name of the file named by NAME which contains no ., .. components nor any repeated path separators (/) or symlinks.  The result is passed back as the return value of the function in a block of memory allocated with malloc.  If the result is not used anymore the memory should be freed with a call to 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 PATH_MAX characters.  In any case errno is set accordingly.

     ENAMETOOLONG
          The resulting path is too long.  This error only occurs on systems which have a limit on the file name length.

     EACCES
          At least one of the path components is not readable.

     ENOENT
          The input file name is empty.

     ENOENT
          At least one of the path components does not exist.

     ELOOP
          More than MAXSYMLINKS many symlinks have been followed.

     This function is a GNU extension and is declared in stdlib.h.

The Unix standard includes a similar function which differs from canonicalize_file_name in that the user has to provide the buffer where the result is placed in.

 -- Function: char * realpath (const char *restrict NAME, char *restrict RESOLVED)
     XPG, stdlib.h

     A call to realpath where the RESOLVED parameter is NULL behaves exactly like canonicalize_file_name.  The function allocates a buffer for the file name and returns a pointer to it.  If RESOLVED is not 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 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 realpath with anything but NULL for the second parameter.

     One other difference is that the buffer RESOLVED (if nonzero) will contain the part of the path component which does not exist or is not readable if the function returns NULL and errno is set to EACCES or ENOENT.

     This function is declared in stdlib.h.

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.

Deleting Files
==============

You can delete a file with unlink or 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 (see Hard Links), it remains accessible under those names.

 -- Function: int unlink (const char *FILENAME)
     POSIX.1, unistd.h The unlink function deletes the file name 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.)

     The function unlink is declared in the header file unistd.h.

     This function returns 0 on successful completion, and -1 on error.  In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     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.

     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.

     ENOENT
          The file name to be deleted doesn't exist.

     EPERM
          On some systems 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 rmdir to delete directories.  (On gnulinuxhurdsystems unlink can never delete the name of a directory.)

     EROFS
          The directory containing the file name to be deleted is on a read-only file system and can't be modified.

 -- Function: int rmdir (const char *FILENAME)
     POSIX.1, unistd.h The rmdir function deletes a directory.  The directory must be empty before it can be removed; in other words, it can only contain entries for . and ...

     In most other respects, rmdir behaves like unlink.  There are two additional errno error conditions defined for rmdir:

     ENOTEMPTY
     EEXIST
          The directory to be deleted is not empty.

     These two error codes are synonymous; some systems use one, and some use the other.  gnulinuxhurdsystems always use ENOTEMPTY.

     The prototype for this function is declared in the header file unistd.h.

 -- Function: int remove (const char *FILENAME)
     ISO, stdio.h This is the ISO C function to remove a file.  It works like unlink for files and like rmdir for directories. remove is declared in stdio.h.

Renaming Files
==============

The rename function is used to change a file's name.

 -- Function: int rename (const char *OLDNAME, const char *NEWNAME)
     ISO, stdio.h The rename function renames the file OLDNAME to NEWNAME.  The file formerly accessible under the name OLDNAME is afterwards accessible as NEWNAME instead.  (If the file had any other names aside from OLDNAME, it continues to have those names.)

     The directory containing the name NEWNAME must be on the same file system as the directory containing the name OLDNAME.

     One special case for rename is when OLDNAME and NEWNAME are two names for the same file.  The consistent way to handle this case is to delete OLDNAME.  However, in this case POSIX requires that rename do nothing and report success---which is inconsistent.  We don't know what your operating system will do.

     If OLDNAME is not a directory, then any existing file named NEWNAME is removed during the renaming operation.  However, if NEWNAME is the name of a directory, rename fails in this case.

     If OLDNAME is a directory, then either NEWNAME must not exist or it must name a directory that is empty.  In the latter case, the existing directory named NEWNAME is deleted first.  The name NEWNAME must not specify a subdirectory of the directory oldname which is being renamed.

     One useful feature of rename is that the meaning of NEWNAME changes ``atomically'' from any previously existing file by that name to its new meaning (i.e., the file that was called OLDNAME).  There is no instant at which 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 NEWNAME will always be intact if it exists at all.

     If rename fails, it returns -1.  In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     EACCES
          One of the directories containing NEWNAME or OLDNAME refuses write permission; or NEWNAME and OLDNAME are directories and write permission is refused for one of them.

     EBUSY
          A directory named by OLDNAME or 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.

     ENOTEMPTY
     EEXIST
          The directory NEWNAME isn't empty.  gnulinuxhurdsystems always return ENOTEMPTY for this, but some other systems return EEXIST.

     EINVAL
          OLDNAME is a directory that contains NEWNAME.

     EISDIR
          NEWNAME is a directory but the OLDNAME isn't.

     EMLINK
          The parent directory of NEWNAME would have too many links (entries).

     ENOENT
          The file OLDNAME doesn't exist.

     ENOSPC
          The directory that would contain NEWNAME has no room for another entry, and there is no space left in the file system to expand it.

     EROFS
          The operation would involve writing to a directory on a read-only file system.

     EXDEV
          The two file names NEWNAME and OLDNAME are on different file systems.

Creating Directories
====================

Directories are created with the mkdir function.  (There is also a shell command mkdir which does the same thing.)

 -- Function: int mkdir (const char *FILENAME, mode_t MODE)
     POSIX.1, sys/stat.h The mkdir function creates a new, empty directory with name FILENAME.

     The argument MODE specifies the file permissions for the new directory file.  See Permission Bits, for more information about this.

     A return value of 0 indicates successful completion, and -1 indicates failure.  In addition to the usual file name syntax errors (see File Name Errors), the following errno error conditions are defined for this function:

     EACCES
          Write permission is denied for the parent directory in which the new directory is to be added.

     EEXIST
          A file named FILENAME already exists.

     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.

     ENOSPC
          The file system doesn't have enough room to create the new directory.

     EROFS
          The parent directory of the directory being created is on a read-only file system and cannot be modified.

     To use this function, your program should include the header file sys/stat.h.

File Attributes
===============

When you issue an 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 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.

The meaning of the File Attributes
----------------------------------

When you read the attributes of a file, they come back in a structure called 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 Reading Attributes.

The header file sys/stat.h declares all the symbols defined in this section.

 -- Data Type: struct stat
     POSIX.1, sys/stat.h The stat structure type is used to return information about the attributes of a file.  It contains at least the following members:

     mode_t st_mode
          Specifies the mode of the file.  This includes file type information (see Testing File Type) and the file permission bits (see Permission Bits).

     ino_t st_ino
          The file serial number, which distinguishes this file from all other files on the same device.

     dev_t st_dev
          Identifies the device containing the file.  The st_ino and st_dev, taken together, uniquely identify the file.  The st_dev value is not necessarily consistent across reboots or system crashes, however.

     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.

     uid_t st_uid
          The user ID of the file's owner.  See File Owner.

     gid_t st_gid
          The group ID of the file.  See File Owner.

     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.

     time_t st_atime
          This is the last access time for the file.  See File Times.

     unsigned long int st_atime_usec
          This is the fractional part of the last access time for the file. See File Times.

     time_t st_mtime
          This is the time of the last modification to the contents of the file. See File Times.

     unsigned long int st_mtime_usec
          This is the fractional part of the time of the last modification to the contents of the file.  See File Times.

     time_t st_ctime
          This is the time of the last modification to the attributes of the file. See File Times.

     unsigned long int st_ctime_usec
          This is the fractional part of the time of the last modification to the attributes of the file.  See File Times.

     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 st_size, like this:

               (st.st_blocks * 512 < st.st_size)

          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.

     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 st_blocks.)

The extensions for the Large File Support (LFS) require, even on 32-bit machines, types which can handle file sizes up to 63. Therefore a new definition of struct stat is necessary.

 -- Data Type: struct stat64
     LFS, sys/stat.h The members of this type are the same and have the same names as those in struct stat.  The only difference is that the members st_ino, st_size, and st_blocks have a different type to support larger values.

     mode_t st_mode
          Specifies the mode of the file.  This includes file type information (see Testing File Type) and the file permission bits (see Permission Bits).

     ino64_t st_ino
          The file serial number, which distinguishes this file from all other files on the same device.

     dev_t st_dev
          Identifies the device containing the file.  The st_ino and st_dev, taken together, uniquely identify the file.  The st_dev value is not necessarily consistent across reboots or system crashes, however.

     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.

     uid_t st_uid
          The user ID of the file's owner.  See File Owner.

     gid_t st_gid
          The group ID of the file.  See File Owner.

     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.

     time_t st_atime
          This is the last access time for the file.  See File Times.

     unsigned long int st_atime_usec
          This is the fractional part of the last access time for the file. See File Times.

     time_t st_mtime
          This is the time of the last modification to the contents of the file. See File Times.

     unsigned long int st_mtime_usec
          This is the fractional part of the time of the last modification to the contents of the file.  See File Times.

     time_t st_ctime
          This is the time of the last modification to the attributes of the file. See File Times.

     unsigned long int st_ctime_usec
          This is the fractional part of the time of the last modification to the attributes of the file.  See File Times.

     blkcnt64_t st_blocks
          This is the amount of disk space that the file occupies, measured in units of 512-byte blocks.

     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 st_blocks.)

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 sys/types.h as well as in sys/stat.h. Here is a list of them.

 -- Data Type: mode_t
     POSIX.1, sys/types.h This is an integer data type used to represent file modes.  In theglibc, this is an unsigned type no narrower than unsigned int.

 -- Data Type: ino_t
     POSIX.1, sys/types.h This is an unsigned integer type used to represent file serial numbers. (In Unix jargon, these are sometimes called inode numbers.) In theglibc, this type is no narrower than unsigned int.

     If the source is compiled with _FILE_OFFSET_BITS == 64 this type is transparently replaced by ino64_t.

 -- Data Type: ino64_t
     Unix98, sys/types.h 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 unsigned int.

     When compiling with _FILE_OFFSET_BITS == 64 this type is available under the name ino_t.

 -- Data Type: dev_t
     POSIX.1, sys/types.h This is an arithmetic data type used to represent file device numbers. In theglibc, this is an integer type no narrower than int.

 -- Data Type: nlink_t
     POSIX.1, sys/types.h This is an integer type used to represent file link counts.

 -- Data Type: blkcnt_t
     Unix98, sys/types.h This is a signed integer type used to represent block counts. In theglibc, this type is no narrower than int.

     If the source is compiled with _FILE_OFFSET_BITS == 64 this type is transparently replaced by blkcnt64_t.

 -- Data Type: blkcnt64_t
     Unix98, sys/types.h This is a signed integer type used to represent block counts for the use in LFS.  In theglibc, this type is no narrower than int.

     When compiling with _FILE_OFFSET_BITS == 64 this type is available under the name blkcnt_t.

Reading the Attributes of a File
--------------------------------

To examine the attributes of files, use the functions stat, fstat and lstat.  They return the attribute information in a struct stat object.  All three functions are declared in the header file sys/stat.h.

 -- Function: int stat (const char *FILENAME, struct stat *BUF)
     POSIX.1, sys/stat.h The stat function returns information about the attributes of the file named by FILENAME in the structure pointed to by BUF.

     If 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 stat fails reporting a nonexistent file.

     The return value is 0 if the operation is successful, or -1 on failure.  In addition to the usual file name errors (see File Name Errors, the following errno error conditions are defined for this function:

     ENOENT
          The file named by FILENAME doesn't exist.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact stat64 since the LFS interface transparently replaces the normal implementation.

 -- Function: int stat64 (const char *FILENAME, struct stat64 *BUF)
     Unix98, sys/stat.h This function is similar to stat but it is also able to work on files larger than 31 bytes on 32-bit systems.  To be able to do this the result is stored in a variable of type struct stat64 to which BUF must point.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name stat and so transparently replaces the interface for small files on 32-bit machines.

 -- Function: int fstat (int FILEDES, struct stat *BUF)
     POSIX.1, sys/stat.h The fstat function is like stat, except that it takes an open file descriptor as an argument instead of a file name. See Low-Level I/O.

     Like stat, fstat returns 0 on success and -1 on failure.  The following errno error conditions are defined for fstat:

     EBADF
          The FILEDES argument is not a valid file descriptor.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact fstat64 since the LFS interface transparently replaces the normal implementation.

 -- Function: int fstat64 (int FILEDES, struct stat64 *BUF)
     Unix98, sys/stat.h This function is similar to fstat but is able to work on large files on 32-bit platforms.  For large files the file descriptor FILEDES should be obtained by open64 or creat64. The BUF pointer points to a variable of type struct stat64 which is able to represent the larger values.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name fstat and so transparently replaces the interface for small files on 32-bit machines.

 -- Function: int lstat (const char *FILENAME, struct stat *BUF)
     BSD, sys/stat.h The lstat function is like stat, except that it does not follow symbolic links.  If FILENAME is the name of a symbolic link, lstat returns information about the link itself; otherwise lstat works like stat.  See Symbolic Links.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact lstat64 since the LFS interface transparently replaces the normal implementation.

 -- Function: int lstat64 (const char *FILENAME, struct stat64 *BUF)
     Unix98, sys/stat.h This function is similar to lstat but it is also able to work on files larger than 31 bytes on 32-bit systems.  To be able to do this the result is stored in a variable of type struct stat64 to which BUF must point.

     When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name lstat and so transparently replaces the interface for small files on 32-bit machines.

Testing the Type of a File
--------------------------

The file mode, stored in the 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 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 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 sys/stat.h.

The following predicate macros test the type of a file, given the value M which is the st_mode field returned by stat on that file:

 -- Macro: int S_ISDIR (mode_t M)
     POSIX, sys/stat.h This macro returns non-zero if the file is a directory.

 -- Macro: int S_ISCHR (mode_t M)
     POSIX, sys/stat.h This macro returns non-zero if the file is a character special file (a device like a terminal).

 -- Macro: int S_ISBLK (mode_t M)
     POSIX, sys/stat.h This macro returns non-zero if the file is a block special file (a device like a disk).

 -- Macro: int S_ISREG (mode_t M)
     POSIX, sys/stat.h This macro returns non-zero if the file is a regular file.

 -- Macro: int S_ISFIFO (mode_t M)
     POSIX, sys/stat.h This macro returns non-zero if the file is a FIFO special file, or a pipe.  See Pipes and FIFOs.

 -- Macro: int S_ISLNK (mode_t M)
     GNU, sys/stat.h This macro returns non-zero if the file is a symbolic link. See Symbolic Links.

 -- Macro: int S_ISSOCK (mode_t M)
     GNU, sys/stat.h This macro returns non-zero if the file is a socket.  See Sockets.

An alternate non-POSIX method of testing the file type is supported for compatibility with BSD.  The mode can be bitwise AND-ed with S_IFMT to extract the file type code, and compared to the appropriate constant.  For example,

     S_ISCHR (MODE)

is equivalent to:

     ((MODE & S_IFMT) == S_IFCHR)

 -- Macro: int S_IFMT
     BSD, sys/stat.h This is a bit mask used to extract the file type code from a mode value.

These are the symbolic names for the different file type codes:

S_IFDIR
     BSD, sys/stat.h This is the file type constant of a directory file.

S_IFCHR
     BSD, sys/stat.h This is the file type constant of a character-oriented device file.

S_IFBLK
     BSD, sys/stat.h This is the file type constant of a block-oriented device file.

S_IFREG
     BSD, sys/stat.h This is the file type constant of a regular file.

S_IFLNK
     BSD, sys/stat.h This is the file type constant of a symbolic link.

S_IFSOCK
     BSD, sys/stat.h This is the file type constant of a socket.

S_IFIFO
     BSD, sys/stat.h This is the file type constant of a FIFO or pipe.

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 st_mode field as the parameter.  Instead they expect a pointer to the whole struct stat structure.

 -- Macro: int S_TYPEISMQ (struct stat *S)
     POSIX, sys/stat.h 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.

 -- Macro: int S_TYPEISSEM (struct stat *S)
     POSIX, sys/stat.h 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.

 -- Macro: int S_TYPEISSHM (struct stat *S)
     POSIX, sys/stat.h 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.

File Owner
----------

Every file has an owner which is one of the registered user names defined on the system.  Each file also has a 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.  See 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 (see 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.

You can change the owner and/or group owner of an existing file using the chown function.  This is the primitive for the chown and chgrp shell commands.

The prototype for this function is declared in unistd.h.

 -- Function: int chown (const char *FILENAME, uid_t OWNER, gid_t GROUP)
     POSIX.1, unistd.h The chown function changes the owner of the file FILENAME to OWNER, and its group owner to 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 0 on success and -1 on failure. In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     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.

          See Options for Files, for information about the _POSIX_CHOWN_RESTRICTED macro.

     EROFS
          The file is on a read-only file system.

 -- Function: int fchown (int FILEDES, uid_t OWNER, gid_t GROUP)
     BSD, unistd.h This is like chown, except that it changes the owner of the open file with descriptor FILEDES.

     The return value from fchown is 0 on success and -1 on failure.  The following errno error codes are defined for this function:

     EBADF
          The FILEDES argument is not a valid file descriptor.

     EINVAL
          The FILEDES argument corresponds to a pipe or socket, not an ordinary file.

     EPERM
          This process lacks permission to make the requested change.  For details see chmod above.

     EROFS
          The file resides on a read-only file system.

The Mode Bits for Access Permission
-----------------------------------

The file mode, stored in the 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. See Testing File Type, for information about the file type code.

All of the symbols listed in this section are defined in the header file sys/stat.h.

These symbolic constants are defined for the file mode bits that control access permission for the file:

S_IRUSR
S_IREAD
     POSIX.1, sys/stat.h S_IREAD, BSD, sys/stat.h Read permission bit for the owner of the file.  On many systems this bit is 0400.  S_IREAD is an obsolete synonym provided for BSD compatibility.

S_IWUSR
S_IWRITE
     POSIX.1, sys/stat.h S_IWRITE, BSD, sys/stat.h Write permission bit for the owner of the file.  Usually 0200. S_IWRITE is an obsolete synonym provided for BSD compatibility.

S_IXUSR
S_IEXEC
     POSIX.1, sys/stat.h S_IEXEC, BSD, sys/stat.h Execute (for ordinary files) or search (for directories) permission bit for the owner of the file.  Usually 0100.  S_IEXEC is an obsolete synonym provided for BSD compatibility.

S_IRWXU
     POSIX.1, sys/stat.h This is equivalent to (S_IRUSR | S_IWUSR | S_IXUSR).

S_IRGRP
     POSIX.1, sys/stat.h Read permission bit for the group owner of the file.  Usually 040.

S_IWGRP
     POSIX.1, sys/stat.h Write permission bit for the group owner of the file.  Usually 020.

S_IXGRP
     POSIX.1, sys/stat.h Execute or search permission bit for the group owner of the file. Usually 010.

S_IRWXG
     POSIX.1, sys/stat.h This is equivalent to (S_IRGRP | S_IWGRP | S_IXGRP).

S_IROTH
     POSIX.1, sys/stat.h Read permission bit for other users.  Usually 04.

S_IWOTH
     POSIX.1, sys/stat.h Write permission bit for other users.  Usually 02.

S_IXOTH
     POSIX.1, sys/stat.h Execute or search permission bit for other users.  Usually 01.

S_IRWXO
     POSIX.1, sys/stat.h This is equivalent to (S_IROTH | S_IWOTH | S_IXOTH).

S_ISUID
     POSIX, sys/stat.h This is the set-user-ID on execute bit, usually 04000. See How Change Persona.

S_ISGID
     POSIX, sys/stat.h This is the set-group-ID on execute bit, usually 02000. See How Change Persona.

S_ISVTX
     BSD, sys/stat.h This is the 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 /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, chmod fails with EFTYPE; see 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 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 _GNU_SOURCE feature select macro, or not define any feature test macros, to get the definition (see Feature Test Macros).

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.

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.

How Your Access to a File is Decided
------------------------------------

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 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 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.

Assigning File Permissions
--------------------------

The primitive functions for creating files (for example, open or mkdir) take a MODE argument, which specifies the file permissions to give the newly created file.  This mode is modified by the process's file creation mask, or 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 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 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.

To change the permission of an existing file given its name, call chmod.  This function uses the specified permission bits and ignores the file creation mask.

In normal use, the file creation mask is initialized by the user's login shell (using the 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 fchmod after opening the file, rather than changing the umask.  In fact, changing the umask is usually done only by shells.  They use the umask function.

The functions in this section are declared in sys/stat.h.

 -- Function: mode_t umask (mode_t MASK)
     POSIX.1, sys/stat.h The umask function sets the file creation mask of the current process to MASK, and returns the previous value of the file creation mask.

     Here is an example showing how to read the mask with umask without changing it permanently:

          mode_t
          read_umask (void)
          {
            mode_t mask = umask (0);
            umask (mask);
            return mask;
          }

     However, on gnuhurdsystems it is better to use getumask if you just want to read the mask value, because it is reentrant.

 -- Function: mode_t getumask (void)
     GNU, sys/stat.h 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.

 -- Function: int chmod (const char *FILENAME, mode_t MODE)
     POSIX.1, sys/stat.h The chmod function sets the access permission bits for the file named by FILENAME to MODE.

     If FILENAME is a symbolic link, chmod changes the permissions of the file pointed to by the link, not those of the link itself.

     This function returns 0 if successful and -1 if not.  In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     ENOENT
          The named file doesn't exist.

     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.

     EROFS
          The file resides on a read-only file system.

     EFTYPE
          MODE has the 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 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 MODE and call chmod again.  See Permission Bits, for full details on the sticky bit.

 -- Function: int fchmod (int FILEDES, mode_t MODE)
     BSD, sys/stat.h This is like chmod, except that it changes the permissions of the currently open file given by FILEDES.

     The return value from fchmod is 0 on success and -1 on failure.  The following errno error codes are defined for this function:

     EBADF
          The FILEDES argument is not a valid file descriptor.

     EINVAL
          The FILEDES argument corresponds to a pipe or socket, or something else that doesn't really have access permissions.

     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.

     EROFS
          The file resides on a read-only file system.

Testing Permission to Access a File
-----------------------------------

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 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 /etc/passwd, which normally can be written only by the super-user, the modifying program will have to be owned by 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 the user would have the necessary access to a file, before it reads or writes the file.

To do this, use the function access, which checks for access permission based on the process's 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 access is simple and automatically does whatever is appropriate for the system you are using.

access is only appropriate to use in setuid programs. A non-setuid program will always use the effective ID rather than the real ID.

The symbols in this section are declared in unistd.h.

 -- Function: int access (const char *FILENAME, int HOW)
     POSIX.1, unistd.h The access function checks to see whether the file named by FILENAME can be accessed in the way specified by the HOW argument.  The HOW argument either can be the bitwise OR of the flags R_OK, W_OK, X_OK, or the existence test F_OK.

     This function uses the real user and group IDs of the calling process, rather than the effective IDs, to check for access permission.  As a result, if you use the function from a setuid or setgid program (see How Change Persona), it gives information relative to the user who actually ran the program.

     The return value is 0 if the access is permitted, and -1 otherwise.  (In other words, treated as a predicate function, access returns true if the requested access is denied.)

     In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     EACCES
          The access specified by HOW is denied.

     ENOENT
          The file doesn't exist.

     EROFS
          Write permission was requested for a file on a read-only file system.

These macros are defined in the header file unistd.h for use as the HOW argument to the access function.  The values are integer constants.

 -- Macro: int R_OK
     POSIX.1, unistd.h Flag meaning test for read permission.

 -- Macro: int W_OK
     POSIX.1, unistd.h Flag meaning test for write permission.

 -- Macro: int X_OK
     POSIX.1, unistd.h Flag meaning test for execute/search permission.

 -- Macro: int F_OK
     POSIX.1, unistd.h Flag meaning test for existence of the file.

File Times
----------

Each file has three time stamps associated with it:  its access time, its modification time, and its attribute modification time.  These correspond to the st_atime, st_mtime, and st_ctime members of the stat structure; see File Attributes.

All of these times are represented in calendar time format, as time_t objects.  This data type is defined in time.h. For more information about representation and manipulation of time values, see Calendar Time.

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 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 unlink, remove or rmdir.  Renaming a file with 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 chmod) updates its attribute change time field.

You can also change some of the time stamps of a file explicitly using the utime function---all except the attribute change time.  You need to include the header file utime.h to use this facility.

 -- Data Type: struct utimbuf
     POSIX.1, utime.h The utimbuf structure is used with the utime function to specify new access and modification times for a file.  It contains the following members:

     time_t actime
          This is the access time for the file.

     time_t modtime
          This is the modification time for the file.

 -- Function: int utime (const char *FILENAME, const struct utimbuf *TIMES)
     POSIX.1, utime.h This function is used to modify the file times associated with the file named FILENAME.

     If 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 actime and modtime members (respectively) of the utimbuf structure pointed to by 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 utime function returns 0 if successful and -1 on failure.  In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     EACCES
          There is a permission problem in the case where a null pointer was passed as the 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.

     ENOENT
          The file doesn't exist.

     EPERM
          If the TIMES argument is not a null pointer, you must either be the owner of the file or be a privileged user.

     EROFS
          The file lives on a read-only file system.

Each of the three time stamps has a corresponding microsecond part, which extends its resolution.  These fields are called st_atime_usec, st_mtime_usec, and st_ctime_usec; each has a value between 0 and 999,999, which indicates the time in microseconds.  They correspond to the tv_usec field of a timeval structure; see Time Types.

The utimes function is like utime, but also lets you specify the fractional part of the file times.  The prototype for this function is in the header file sys/time.h.

 -- Function: int utimes (const char *FILENAME, const struct timeval TVP[2])
     BSD, sys/time.h This function sets the file access and modification times of the file FILENAME.  The new file access time is specified by TVP[0], and the new modification time by TVP[1].  Similar to utime, if 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 utime function.

 -- Function: int lutimes (const char *FILENAME, const struct timeval TVP[2])
     BSD, sys/time.h This function is like utimes, except that it does not follow symbolic links.  If FILENAME is the name of a symbolic link, lutimes sets the file access and modification times of the symbolic link special file itself (as seen by lstat; see Symbolic Links) while 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 ENOSYS).

     The return values and error conditions are the same as for the utime function.

 -- Function: int futimes (int FD, const struct timeval TVP[2])
     BSD, sys/time.h This function is like utimes, except that it takes an open file descriptor as an argument instead of a file name.  See Low-Level I/O.  This function comes from FreeBSD, and is not available on all platforms (if not available, it will fail with ENOSYS).

     Like utimes, futimes returns 0 on success and -1 on failure.  The following errno error conditions are defined for futimes:

     EACCES
          There is a permission problem in the case where a null pointer was passed as the 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.

     EBADF
          The FILEDES argument is not a valid file descriptor.

     EPERM
          If the TIMES argument is not a null pointer, you must either be the owner of the file or be a privileged user.

     EROFS
          The file lives on a read-only file system.

File Size
---------

Normally file sizes are maintained automatically.  A file begins with a size of 0 and is automatically extended when data is written past its end.  It is also possible to empty a file completely by an open or fopen call.

However, sometimes it is necessary to reduce the size of a file. This can be done with the truncate and ftruncate functions. They were introduced in BSD Unix.  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 (see Memory-mapped I/O), where files are not automatically extended. However, it is not portable but must be implemented if mmap allows mapping of files (i.e., _POSIX_MAPPED_FILES is defined).

Using these functions on anything other than a regular file gives undefined results.  On many systems, such a call will appear to succeed, without actually accomplishing anything.

 -- Function: int truncate (const char *FILENAME, off_t LENGTH)
     X/Open, unistd.h

     The truncate function changes the size of FILENAME to LENGTH.  If 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 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 _FILE_OFFSET_BITS == 64 the truncate function is in fact truncate64 and the type off_t has 64 bits which makes it possible to handle files up to 63 bytes in length.

     The return value is 0 for success, or -1 for an error.  In addition to the usual file name errors, the following errors may occur:

     EACCES
          The file is a directory or not writable.

     EINVAL
          LENGTH is negative.

     EFBIG
          The operation would extend the file beyond the limits of the operating system.

     EIO
          A hardware I/O error occurred.

     EPERM
          The file is "append-only" or "immutable".

     EINTR
          The operation was interrupted by a signal.

 -- Function: int truncate64 (const char *NAME, off64_t LENGTH)
     Unix98, unistd.h This function is similar to the truncate function.  The difference is that the LENGTH argument is 64 bits wide even on 32 bits machines, which allows the handling of files with sizes up to 63 bytes.

     When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name truncate and so transparently replaces the 32 bits interface.

 -- Function: int ftruncate (int FD, off_t LENGTH)
     POSIX, unistd.h

     This is like truncate, but it works on a file descriptor 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 LENGTH of the file is bigger than the original size. The 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 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.

     ftruncate is especially useful in combination with 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 _FILE_OFFSET_BITS == 64 the ftruncate function is in fact ftruncate64 and the type off_t has 64 bits which makes it possible to handle files up to 63 bytes in length.

     The return value is 0 for success, or -1 for an error.  The following errors may occur:

     EBADF
          FD does not correspond to an open file.

     EACCES
          FD is a directory or not open for writing.

     EINVAL
          LENGTH is negative.

     EFBIG
          The operation would extend the file beyond the limits of the operating system.

     EIO
          A hardware I/O error occurred.

     EPERM
          The file is "append-only" or "immutable".

     EINTR
          The operation was interrupted by a signal.

 -- Function: int ftruncate64 (int ID, off64_t LENGTH)
     Unix98, unistd.h This function is similar to the ftruncate function.  The difference is that the LENGTH argument is 64 bits wide even on 32 bits machines which allows the handling of files with sizes up to 63 bytes.

     When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name ftruncate and so transparently replaces the 32 bits interface.

As announced here is a little example of how to use ftruncate in combination with mmap:

     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;
     }

The function 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 mmap.  The program has to keep track of the real size, and when it has finished a final ftruncate call should set the real size of the file.

Storage Allocation
------------------

Most file systems support allocating large files in a non-contiguous fashion: the file is split into 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 sparse files with 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 mmap can still result in SIGBUS.

 -- Function: int posix_fallocate (int FD, off_t OFFSET, off_t LENGTH)

     Allocate backing store for the region of LENGTH bytes starting at byte OFFSET in the file for the descriptor FD.  The file length is increased to LENGTH + OFFSET if necessary.

     FD must be a regular file opened for writing, or EBADF is returned.  If there is insufficient disk space to fulfill the allocation request, ENOSPC is returned.

     Note: If fallocate is not available (because the file system does not support it), posix_fallocate is emulated, which has the following drawbacks:

       * 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 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).

       * 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.

       * If FD has been opened with the O_WRONLY flag, the function will fail with an errno value of EBADF.

       * If FD has been opened with the O_APPEND flag, the function will fail with an errno value of EBADF.

       * If LENGTH is zero, ftruncate is used to increase the file size as requested, without allocating file system blocks.  There is a race condition which means that ftruncate can accidentally truncate the file if it has been extended concurrently.

     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 fallocate function, with a zero flag argument.  For the fallocate function, theglibc does not perform allocation emulation if the file system does not support allocation.  Instead, an EOPNOTSUPP is returned to the caller.

 -- Function: int posix_fallocate64 (int FD, off64_t OFFSET, off64_t LENGTH)

     This function is a variant of posix_fallocate64 which accepts 64-bit file offsets on all platforms.

Making Special Files
====================

The 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 mknod is declared in sys/stat.h.

 -- Function: int mknod (const char *FILENAME, mode_t MODE, dev_t DEV)
     BSD, sys/stat.h The mknod function makes a special file with name FILENAME. The MODE specifies the mode of the file, and may include the various special file bits, such as S_IFCHR (for a character special file) or S_IFBLK (for a block special file).  See Testing File Type.

     The 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 0 on success and -1 on error.  In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

     EPERM
          The calling process is not privileged.  Only the superuser can create special files.

     ENOSPC
          The directory or file system that would contain the new file is full and cannot be extended.

     EROFS
          The directory containing the new file can't be modified because it's on a read-only file system.

     EEXIST
          There is already a file named FILENAME.  If you want to replace this file, you must remove the old file explicitly first.

Temporary Files
===============

If you need to use a temporary file in your program, you can use the tmpfile function to open it.  Or you can use the tmpnam (better: tmpnam_r) function to provide a name for a temporary file and then you can open it in the usual way with fopen.

The tempnam function is like 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 tempnam is reentrant, while tmpnam is not since it returns a pointer to a static buffer.

These facilities are declared in the header file stdio.h.

 -- Function: FILE * tmpfile (void)
     ISO, stdio.h This function creates a temporary binary file for update mode, as if by calling fopen with mode "wb+".  The file is deleted automatically when it is closed or when the program terminates.  (On some other 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 _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact tmpfile64, i.e., the LFS interface transparently replaces the old interface.

 -- Function: FILE * tmpfile64 (void)
     Unix98, stdio.h This function is similar to tmpfile, but the stream it returns a pointer to was opened using tmpfile64.  Therefore this stream can be used for files larger than 31 bytes on 32-bit machines.

     Please note that the return type is still FILE *.  There is no special FILE type for the LFS interface.

     If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name tmpfile and so transparently replaces the old interface.

 -- Function: char * tmpnam (char *RESULT)
     ISO, stdio.h prelim:tmpnam/!result asunsafe acsafe This function constructs and returns a valid file name that does not refer to any existing file.  If the 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 RESULT argument should be a pointer to an array of at least L_tmpnam characters, and the result is written into that array.

     It is possible for 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 tmpnam fails it returns a null pointer.

     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 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 O_EXCL flag.  Using tmpfile or mkstemp is a safe way to avoid this problem.

 -- Function: char * tmpnam_r (char *RESULT)
     GNU, stdio.h This function is nearly identical to the tmpnam function, except that if RESULT is a null pointer it returns a null pointer.

     This guarantees reentrancy because the non-reentrant situation of tmpnam cannot happen here.

     Warning: This function has the same security problems as tmpnam.

 -- Macro: int L_tmpnam
     ISO, stdio.h 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 tmpnam function.

 -- Macro: int TMP_MAX
     ISO, stdio.h The macro TMP_MAX is a lower bound for how many temporary names you can create with tmpnam.  You can rely on being able to call 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 25.

 -- Function: char * tempnam (const char *DIR, const char *PREFIX)
     SVID, stdio.h This function generates a unique temporary file name.  If 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 malloc, so you should release its storage with 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.

       * The environment variable TMPDIR, if it is defined.  For security reasons this only happens if the program is not SUID or SGID enabled.

       * The DIR argument, if it is not a null pointer.

       * The value of the P_tmpdir macro.

       * The directory /tmp.

     This function is defined for SVID compatibility.

     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 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 O_EXCL flag.  Using tmpfile or mkstemp is a safe way to avoid this problem.

 -- SVID Macro: char * P_tmpdir
     SVID, stdio.h This macro is the name of the default directory for temporary files.

Older Unix systems did not have the functions just described.  Instead they used mktemp and mkstemp.  Both of these functions work by modifying a file name template string you pass.  The last six characters of this string must be XXXXXX.  These six Xs are replaced with six characters which make the whole string a unique file name.  Usually the template string is something like /tmp/PREFIXXXXXXX, and each program uses a unique PREFIX.

NB: Because mktemp and mkstemp modify the template string, you must not pass string constants to them. String constants are normally in read-only storage, so your program would crash when mktemp or mkstemp tried to modify the string.  These functions are declared in the header file stdlib.h.

 -- Function: char * mktemp (char *TEMPLATE)
     Unix, stdlib.h The mktemp function generates a unique file name by modifying TEMPLATE as described above.  If successful, it returns TEMPLATE as modified.  If mktemp cannot find a unique file name, it makes TEMPLATE an empty string and returns that.  If TEMPLATE does not end with XXXXXX, mktemp returns a null pointer.

     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 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 O_EXCL flag.  Using mkstemp is a safe way to avoid this problem.

 -- Function: int mkstemp (char *TEMPLATE)
     BSD, stdlib.h The mkstemp function generates a unique file name just as mktemp does, but it also opens the file for you with open (see Opening and Closing Files).  If successful, it modifies TEMPLATE in place and returns a file descriptor for that file open for reading and writing.  If mkstemp cannot create a uniquely-named file, it returns -1.  If TEMPLATE does not end with XXXXXX, mkstemp returns -1 and does not modify TEMPLATE.

     The file is opened using mode 0600.  If the file is meant to be used by other users this mode must be changed explicitly.

Unlike mktemp, 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 open with the O_EXCL flag, which says you want to create a new file and get an error if the file already exists.

 -- Function: char * mkdtemp (char *TEMPLATE)
     BSD, stdlib.h The mkdtemp function creates a directory with a unique name.  If it succeeds, it overwrites TEMPLATE with the name of the directory, and returns TEMPLATE.  As with mktemp and mkstemp, TEMPLATE should be a string ending with XXXXXX.

     If mkdtemp cannot create an uniquely named directory, it returns NULL and sets errno appropriately.  If TEMPLATE does not end with XXXXXX, mkdtemp returns NULL and does not modify TEMPLATE.  errno will be set to EINVAL in this case.

     The directory is created using mode 0700.

The directory created by mkdtemp cannot clash with temporary files or directories created by other users.  This is because directory creation always works like open with O_EXCL. See Creating Directories.

The mkdtemp function comes from OpenBSD.