14. File System Interface

This chapter describes the GNU C library's functions for manipulating files. Unlike the input and output functions (see section 12. Input/Output on Streams; see section 13. Low-Level Input/Output), 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.

14.1 Working Directory		This is used to resolve relative file names.
14.2 Accessing Directories		Finding out what files a directory contains.
14.3 Working with Directory Trees		Apply actions to all files or a selectable subset of a directory hierarchy.
14.4 Hard Links		Adding alternate names to a file.
14.5 Symbolic Links		A file that "points to" a file name.
14.6 Deleting Files		How to delete a file, and what that means.
14.7 Renaming Files		Changing a file's name.
14.8 Creating Directories		A system call just for creating a directory.
14.9 File Attributes		Attributes of individual files.
14.10 Making Special Files		How to create special files.
14.11 Temporary Files		Naming and creating temporary files.

14.1 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 section 11.2.2 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 29.13 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)

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 GNU library 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 section 3.2.2 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 section 3.2.2.2 Examples of malloc, 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)

This is similar to getcwd, but has no way to specify the size of the buffer. The GNU library 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 section 31.6 Limits on File System Capacity). In the GNU system 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)

This get_current_dir_name function is bascially equivalent to getcwd (NULL, 0). The only difference is that the value of the PWD variable is returned if this value is correct. This is a subtle difference which is visible if the path described by the PWD value is using one or more symbol links in which case the value returned by getcwd can resolve the symbol links and therefore yield a different result.

This function is a GNU extension.

Function: int chdir (const char *filename)

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 section 11.2.3 File Name Errors), plus ENOTDIR if the file filename is not a directory.

Function: int fchdir (int filedes)

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.

14.2 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. 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 12. Input/Output on Streams.

14.2.1 Format of a Directory Entry		Format of one directory entry.
14.2.2 Opening a Directory Stream		How to open a directory stream.
14.2.3 Reading and Closing a Directory Stream		How to read directory entries from the stream.
14.2.4 Simple Program to List a Directory		A very simple directory listing program.
14.2.5 Random Access in a Directory Stream		Rereading part of the directory already read with the same stream.
14.2.6 Scanning the Content of a Directory		Get entries for user selected subset of contents in given directory.
14.2.7 Simple Program to List a Directory, Mark II		Revised version of the program.

14.2.1 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

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. In the GNU system and most POSIX systems, for most files this the same as the st_ino member that stat will return for the file. See section 14.9 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

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. On some systems this is the only value returned.

DT_REG

A regular file.

DT_DIR

A directory.

DT_FIFO

A named pipe, or FIFO. See section 15.3 FIFO Special Files.

DT_SOCK

A local-domain socket.

DT_CHR

A character device.

DT_BLK

A block device.

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 statbuf. If the value cannot be determine the member value is DT_UNKNOWN. These two macros convert between d_type values and st_mode values:

Function: int IFTODT (mode_t mode)

This returns the d_type value corresponding to mode.

Function: mode_t DTTOIF (int dtype)

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 names _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 section 14.9 File Attributes.

14.2.2 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

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.

Function: DIR * opendir (const char *dirname)

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 section 11.2.3 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 the GNU system.)

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

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 the GNU C library. Instead a separate function is provided to allow access.

Function: int dirfd (DIR *dirstream)

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.

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

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 statically allocated 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 section 11.2.2 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.

readdir is not thread safe. Multiple threads using readdir on the same dirstream may overwrite the return value. Use readdir_r when this is critical.

Function: int readdir_r (DIR *dirstream, struct dirent *entry, struct dirent **result)

This function is the reentrant version of readdir. Like readdir it returns the next entry from the directory. But to prevent conflicts between simultaneously running threads the result is not stored in statically allocated memory. Instead the argument entry points to a place to store the result.

The return value is 0 in case the next entry was read successfully. In this case a pointer to the result is returned in *result. It is not required that *result is the same as entry. If something goes wrong while executing readdir_r the function returns a value indicating the error (as described for readdir).

If there are no more directory entries, readdir_r's return value is 0, and *result is set to NULL.

Portability Note: On some systems readdir_r may not return a NUL terminated string for the file name, even when there is no d_reclen field in struct dirent and the file name is the maximum allowed size. Modern systems all have the d_reclen field, and on old systems multi-threading is not critical. In any case there is no such problem with the readdir function, so that even on systems without the d_reclen member one could use multiple threads by using external locking.

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)

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)

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

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.

14.2.4 Simple Program to List a Directory

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

#include <stddef.h> #include <stdio.h> #include <sys/types.h> #include <dirent.h> int main (void) { DIR *dp; struct dirent *ep; dp = opendir ("./"); if (dp != NULL) { while (ep = readdir (dp)) puts (ep->d_name); (void) closedir (dp); } else perror ("Couldn't open the directory"); return 0; }

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 14.2.6 Scanning the Content of a Directory, and 9.3 Array Sort Function.

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

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: off_t telldir (DIR *dirstream)

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, off_t pos)

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.

14.2.6 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 void *, const void *))

The scandir function scans the contents of the directory selected by dir. The result in *namelist is an array of pointers to structure 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 the malloc call 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 the GNU C library contains implementations of functions which are very helpful for this purpose.

Function: int alphasort (const void *a, const void *b)

The alphasort function behaves like the strcoll function (see section 5.5 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 void *a, const void *b)

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 void *, const void *))

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 void *a, const void *b)

The alphasort64 function behaves like the strcoll function (see section 5.5 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 void *a, const void *b)

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.

14.2.7 Simple Program to List a Directory, Mark II

Here is a revised version of the directory lister found above (see section 14.2.4 Simple Program to List a Directory). 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.

#include <stdio.h> #include <dirent.h> static int one (struct dirent *unused) { return 1; } int main (void) { struct dirent **eps; int n; n = scandir ("./", &eps, one, alphasort); if (n >= 0) { int cnt; for (cnt = 0; cnt < n; ++cnt) puts (eps[cnt]->d_name); } else perror ("Couldn't open the directory"); return 0; }

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

14.3 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

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 paramater 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 _BSD_SOURCE or _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

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

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

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

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)

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

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)

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.

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)

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.

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

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 section 11.2.3 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 31.6 Limits on File System Capacity.)

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

In the GNU system 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.

14.5 Symbolic Links

The GNU system supports 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 have 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

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

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 section 11.2.3 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: int readlink (const char *filename, char *buffer, size_t size)

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) { int size = 100; while (1) { char *buffer = (char *) xmalloc (size); int nchars = readlink (filename, buffer, size); if (nchars < 0) return NULL; if (nchars < size) return buffer; free (buffer); size *= 2; } }

A value of -1 is returned in case of error. In addition to the usual file name errors (see section 11.2.3 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 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 compare in which case different names can refer to the same inode.

Function: char * canonicalize_file_name (const char *name)

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.

In any of the path components except the last one is 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)

The realpath function behaves just like canonicalize_file_name but instead of allocating a buffer for the result it is placed in the buffer pointed to by resolved.

One other difference is that the buffer resolved 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 path on systems which have no limits on the file name length.

14.6 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 section 14.4 Hard Links), it remains accessible under those names.

Function: int unlink (const char *filename)

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 section 11.2.3 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. (In the GNU system 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)

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. The GNU system always uses ENOTEMPTY.

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

Function: int remove (const char *filename)

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

14.7 Renaming Files

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

Function: int rename (const char *oldname, const char *newname)

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 section 11.2.3 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. The GNU system always returns 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.

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

The mkdir function creates a new, empty directory with name filename.

The argument mode specifies the file permissions for the new directory file. See section 14.9.5 The Mode Bits for Access Permission, 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 section 11.2.3 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'.

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

14.9.1 The meaning of the File Attributes		The names of the file attributes, and what their values mean.
14.9.2 Reading the Attributes of a File		How to read the attributes of a file.
14.9.3 Testing the Type of a File		Distinguishing ordinary files, directories, links...
14.9.4 File Owner		How ownership for new files is determined, and how to change it.
14.9.5 The Mode Bits for Access Permission		How information about a file's access mode is stored.
14.9.6 How Your Access to a File is Decided		How the system decides who can access a file.
14.9.7 Assigning File Permissions		How permissions for new files are assigned, and how to change them.
14.9.8 Testing Permission to Access a File		How to find out if your process can access a file.
14.9.9 File Times		About the time attributes of a file.
14.9.10 File Size		Manually changing the size of a file.

14.9.1 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 14.9.2 Reading the Attributes of a File.

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

Data Type: struct stat

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 section 14.9.3 Testing the Type of a File) and the file permission bits (see section 14.9.5 The Mode Bits for Access Permission).

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 section 14.9.4 File Owner.

gid_t st_gid

The group ID of the file. See section 14.9.4 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 section 14.9.9 File Times.

unsigned long int st_atime_usec

This is the fractional part of the last access time for the file. See section 14.9.9 File Times.

time_t st_mtime

This is the time of the last modification to the contents of the file. See section 14.9.9 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 section 14.9.9 File Times.

time_t st_ctime

This is the time of the last modification to the attributes of the file. See section 14.9.9 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 section 14.9.9 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 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.)

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

Data Type: struct stat64

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 section 14.9.3 Testing the Type of a File) and the file permission bits (see section 14.9.5 The Mode Bits for Access Permission).

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 section 14.9.4 File Owner.

gid_t st_gid

The group ID of the file. See section 14.9.4 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 section 14.9.9 File Times.

unsigned long int st_atime_usec

This is the fractional part of the last access time for the file. See section 14.9.9 File Times.

time_t st_mtime

This is the time of the last modification to the contents of the file. See section 14.9.9 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 section 14.9.9 File Times.

time_t st_ctime

This is the time of the last modification to the attributes of the file. See section 14.9.9 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 section 14.9.9 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

This is an integer data type used to represent file modes. In the GNU system, this is equivalent to unsigned int.

Data Type: ino_t

This is an arithmetic data type used to represent file serial numbers. (In Unix jargon, these are sometimes called inode numbers.) In the GNU system, this type is equivalent to unsigned long int.

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

Data Type: ino64_t

This is an arithmetic data type used to represent file serial numbers for the use in LFS. In the GNU system, this type is equivalent to unsigned long longint.

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

Data Type: dev_t

This is an arithmetic data type used to represent file device numbers. In the GNU system, this is equivalent to int.

Data Type: nlink_t

This is an arithmetic data type used to represent file link counts. In the GNU system, this is equivalent to unsigned short int.

Data Type: blkcnt_t

This is an arithmetic data type used to represent block counts. In the GNU system, this is equivalent to unsigned long int.

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

Data Type: blkcnt64_t

This is an arithmetic data type used to represent block counts for the use in LFS. In the GNU system, this is equivalent to unsigned long long int.

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

14.9e of the last modification to the contents of the file. See section 14.9.9 File Times.