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