This chapter describes the GNU C library's functions for manipulating files. Unlike the input and output functions (see section Input/Output on Streams; see section 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.
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 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 section 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'.
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 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
ERANGE
EACCES
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 Examples of malloc, for information about xmalloc, which is
not a library function but is a customary name used in most GNU
software.
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 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.
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.
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 File Name Errors), plus ENOTDIR if the
file filename is not a directory.
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
dirname.
EBADF
ENOTDIR
EINTR
EIO
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
section Input/Output on Streams.
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'.
char d_name[]
ino_t d_fileno
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 File Attributes.
unsigned char d_namlen
unsigned char because that is the integer
type of the appropriate size
unsigned char d_type
DT_UNKNOWN
DT_REG
DT_DIR
DT_FIFO
DT_SOCK
DT_CHR
DT_BLK
_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:
d_type value corresponding to mode.
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 File Attributes.
This section describes how to open a directory stream. All the symbols are declared in the header file `dirent.h'.
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.
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 File Name Errors), the
following errno error conditions are defined for this function:
EACCES
dirname.
EMFILE
ENFILE
The DIR type is typically implemented using a file descriptor,
and the opendir function in terms of the open function.
See section Low-Level Input/Output. Directory streams and the underlying
file descriptors are closed on exec (see section 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.
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.
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'.
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 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
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.
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.
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.
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.
0 on success and -1 on failure.
The following errno error conditions are defined for this
function:
EBADF
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
puts ("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 section Scanning the Content of a Directory, and section Array Sort Function.
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'.
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.)
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.
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.
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.
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.
alphasort function behaves like the strcoll function
(see section 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.
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.
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.
alphasort64 function behaves like the strcoll function
(see section 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.
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.
Here is a revised version of the directory lister found above
(see section 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.
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.
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
FTW_D
FTW_NS
stat call failed and so the information pointed to by the
second paramater is invalid.
FTW_DNR
FTW_SL
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.
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.
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
FTW_D if
the FTW_DEPTH flag is passed to nftw (see below).
FTW_SLN
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.
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.
int base
FTW_CHDIR flag was set in calling nftw
since then the current directory is the one the current item is found
in.
int level
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 @math{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
@math{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 @math{0} if all callback
function calls returned @math{0} and all actions performed by the
ftw succeeded. If a function call failed (other than calling
stat on an item) the function returns @math{-1}. If a callback
function returns a value other than @math{0} this value is returned as
the return value of 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.
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.
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 @math{0} or a bitwise-OR combination of any of the following values.
FTW_PHYS
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
nftw.
FTW_CHDIR
ntfw finally returns the current directory is restored to
its original value.
FTW_DEPTH
FTW_DP and not FTW_D.
The return value is computed in the same way as for ftw.
nftw returns @math{0} if no failures occurred and all callback
functions returned @math{0}. In case of internal errors, such as memory
problems, the return value is @math{-1} and 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.
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.
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'.
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 File Name Errors) for both oldname and newname, the
following errno error conditions are defined for this function:
EACCES
EEXIST
EMLINK
LINK_MAX; see
section Limits on File System Capacity.)
ENOENT
ENOSPC
EPERM
EROFS
EXDEV
EIO
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.
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'.
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 File Name Errors), the following errno
error conditions are defined for this function:
EEXIST
EROFS
ENOSPC
EIO
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 (char *filename)
{
int size = 100;
while (1)
{
char *buffer = (char *) xmalloc (size);
int nchars = readlink (filename, buffer, size);
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 File Name Errors), the following
errno error conditions are defined for this function:
EINVAL
EIO
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.
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
EACCES
ENOENT
ENOENT
ELOOP
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.
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.
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 Hard Links), it remains accessible under those names.
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 File Name Errors), the following errno error conditions are
defined for this function:
EACCES
EBUSY
ENOENT
EPERM
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
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
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'.
unlink for files and like rmdir for directories.
remove is declared in `stdio.h'.
The rename function is used to change a file's name.
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 File Name Errors), the following
errno error conditions are defined for this function:
EACCES
EBUSY
ENOTEMPTY
EEXIST
ENOTEMPTY for this, but some other systems return EEXIST.
EINVAL
EISDIR
EMLINK
ENOENT
ENOSPC
EROFS
EXDEV
Directories are created with the mkdir function. (There is also
a shell command mkdir which does the same thing.)
mkdir function creates a new, empty directory with name
filename.
The argument mode specifies the file permissions for the new directory file. See section 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 File Name Errors), the following errno error
conditions are defined for this function:
EACCES
EEXIST
EMLINK
ENOSPC
EROFS
To use this function, your program should include the header file `sys/stat.h'.
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.
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 section Reading the Attributes of a File.
The header file `sys/stat.h' declares all the symbols defined in this section.
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
ino_t st_ino
dev_t st_dev
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
uid_t st_uid
gid_t st_gid
off_t st_size
time_t st_atime
unsigned long int st_atime_usec
time_t st_mtime
unsigned long int st_mtime_usec
time_t st_ctime
unsigned long int st_ctime_usec
blkcnt_t st_blocks
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
st_blocks.)
The extensions for the Large File Support (LFS) require, even on 32-bit
machines, types which can handle file sizes up to @math{2^63}.
Therefore a new definition of struct stat is necessary.
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
ino64_t st_ino
dev_t st_dev
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
uid_t st_uid
gid_t st_gid
off64_t st_size
time_t st_atime
unsigned long int st_atime_usec
time_t st_mtime
unsigned long int st_mtime_usec
time_t st_ctime
unsigned long int st_ctime_usec
blkcnt64_t st_blocks
unsigned int st_blksize
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.
unsigned int.
unsigned long int.
If the source is compiled with _FILE_OFFSET_BITS == 64 this type
is transparently replaced by ino64_t.
unsigned long longint.
When compiling with _FILE_OFFSET_BITS == 64 this type is
available under the name ino_t.
int.
unsigned short int.
unsigned long int.
If the source is compiled with _FILE_OFFSET_BITS == 64 this type
is transparently replaced by blkcnt64_t.
unsigned
long long int.
When compiling with _FILE_OFFSET_BITS == 64 this type is
available under the name blkcnt_t.
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'.
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 section File Name Errors, the following errno error conditions
are defined for this function:
ENOENT
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.
stat but it is also able to work on
files larger then @math{2^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.
fstat function is like stat, except that it takes an
open file descriptor as an argument instead of a file name.
See section Low-Level Input/Output.
Like stat, fstat returns 0 on success and -1
on failure. The following errno error conditions are defined for
fstat:
EBADF
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.
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.
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 section 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.
lstat but it is also able to work on
files larger then @math{2^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.
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
section The Mode Bits for Access Permission.
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:
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)
These are the symbolic names for the different file type codes:
S_IFDIR
S_IFCHR
S_IFBLK
S_IFREG
S_IFLNK
S_IFSOCK
S_IFIFO
The POSIX.1b standard introduced a few more objects which possibly can
be implemented as object in the filesystem. These are message queues,
semaphores, and shared memory objects. To allow differentiating these
objects from other files the POSIX standard introduces three new test
macros. But unlike the other macros it does not take the value of the
st_mode field as the parameter. Instead they expect a pointer to
the whole struct stat structure.
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 section How Your Access to a File is Decided, 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 section The Persona of a Process). 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'.
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 section File Name Errors),
the following errno error conditions are defined for this function:
EPERM
_POSIX_CHOWN_RESTRICTED macro.
EROFS
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
EINVAL
EPERM
chmod above.
EROFS
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 section Testing the Type of a File, 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
S_IREAD is an obsolete synonym provided for BSD
compatibility.
S_IWUSR
S_IWRITE
S_IWRITE is an obsolete synonym provided for BSD compatibility.
S_IXUSR
S_IEXEC
S_IEXEC is an obsolete
synonym provided for BSD compatibility.
S_IRWXU
S_IRGRP
S_IWGRP
S_IXGRP
S_IRWXG
S_IROTH
S_IWOTH
S_IXOTH
S_IRWXO
S_ISUID
S_ISGID
S_ISVTX
chmod fails with EFTYPE;
see section Assigning File 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 _BSD_SOURCE feature select
macro to get the definition (see section 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.
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 section The Persona of a Process.
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.
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'.
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, it is better to use getumask if you just want to read
the mask value, because it is reentrant (at least if you use the GNU
operating system).
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 section File Name Errors), the following errno error conditions are defined for
this function:
ENOENT
EPERM
EROFS
EFTYPE
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 section The Mode Bits for Access Permission,
for full details on the sticky bit.
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
EINVAL
EPERM
EROFS
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 beside 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 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'.
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 section How an Application Can 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 section File Name Errors), the following errno error conditions are defined for
this function:
EACCES
ENOENT
EROFS
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.
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 section 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 section 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.
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
time_t modtime
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 section File Name Errors), the following errno error conditions
are defined for this function:
EACCES
ENOENT
EPERM
EROFS
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 section High-Resolution Calendar.
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'.
tvp[0], and the new modification time by
tvp[1]. This function comes from BSD.
The return values and error conditions are the same as for the utime
function.
Normally file sizes are maintained automatically. A file begins with a
size of @math{0} and is automatically extended when data is written past
its end. It is also possible to empty a file completely by an
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 section 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.
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
@math{2^63} bytes in length.
The return value is @math{0} for success, or @math{-1} for an error. In addition to the usual file name errors, the following errors may occur:
EACCES
EINVAL
EFBIG
EIO
EPERM
EINTR
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
@math{2^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.
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
@math{2^63} bytes in length.
The return value is @math{0} for success, or @math{-1} for an error. The following errors may occur:
EBADF
EACCES
EINVAL
EFBIG
EIO
EPERM
EINTR
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
@math{2^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 the it is extended by a round 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.
The mknod function is the primitive for making special files,
such as files that correspond to devices. The GNU library includes
this function for compatibility with BSD.
The prototype for mknod is declared in `sys/stat.h'.
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 section Testing the Type of a File.
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 section File Name Errors), the
following errno error conditions are defined for this function:
EPERM
ENOSPC
EROFS
EEXIST
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'.
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.
tmpfile, but the stream it returns a
pointer to was opened using tmpfile64. Therefore this stream can
be used for files larger then @math{2^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.
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.
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.
tmpnam function.
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 the GNU library, 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.
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.
TMPDIR, if it is defined. For security
reasons this only happens if the program is not SUID or SGID enabled.
P_tmpdir macro.
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.
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 `X's
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.
Note: 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.
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.
mkstemp function generates a unique file name just as
mktemp does, but it also opens the file for you with open
(see section 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.
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 section Creating Directories.
The mkdtemp function comes from OpenBSD.
Go to the first, previous, next, last section, table of contents.