path: root/manual/filesys.texi

@node File System Interface
@chapter File System Interface

This chapter describes the GNU C Library's functions for manipulating
files.  Unlike the input and output functions described in
@ref{Input/Output on Streams} and @ref{Low-Level Input/Output}, these
functions are concerned with operating on the files themselves, rather
than on their contents.

Among the facilities described in this chapter are functions for
examining or modifying directories, and functions for inquiring about or
setting file attributes, such as access modes and modification times.

@menu
* Working Directory::			This is used to resolve relative
					 file names.
* Accessing Directories::		Finding out what files a directory
					 contains.
* Adding Links::			Adding entries to a directory.
* Removing and Renaming Files::		Removing entries from a directory.
* Making and Removing Directories::	Functions for adding and removing
					 the directories themselves.
* File Attributes::			Attributes of individual files.
* Making Special Files::		How to create special 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 to the computer 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 inquire about any
user's home directory using the @code{getpwuid} or @code{getpwnam}
functions; @pxref{User Database}.

You can change the working directory using shell commands like
@samp{cd}.  The functions described in this section are the primitives
used by those commands for examining and changing the working directory.

Prototypes for these functions are declared in the header file
@file{<unistd.h>}.

@comment unistd.h
@comment POSIX.1
@deftypefun {char *} getcwd (char *@var{buffer}, int @var{size})
The @code{getcwd} function returns an absolute file name representing
the current working directory in the character array @var{buffer}.
The @var{size} argument specifies the allocation size of the array.

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 less than or equal to zero.

@item ERANGE
The @var{size} argument is less than the length of the file name.
You need to allocate a bigger array to hold the result.

@item EACCES
Permission to read or search a component of the file name was denied.
@end table
@end deftypefun

@comment unistd.h
@comment BSD
@deftypefun {char *} getwd (char *@var{buffer})
This is similar to @code{getcwd}.  The GNU Library provides @code{getwd}
for backwards compatibility with BSD.  The @var{buffer} should be a
pointer to an array at least @code{PATH_MAX} bytes long.
@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}).
@end deftypefun


@node Accessing Directories
@section Accessing Directories

The facilities described in this section let you read the contents of a
directory file.  This is useful if you want your program to list the
files for which it contains entries, perhaps as part of a menu.

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

@example
#include <stddef.h>
#include <stdio.h>
#include <sys/types.h>
#include <dirent.h>

main ()
@{   
  DIR *dp;
  struct dirent *ep;

  if (dp = opendir ("./")) @{
    while (ep = readdir (dp))
      puts (ep->d_name);
    (void) closedir (dp);
    @}
  else
    puts ("Couldn't open the directory.");
@}
@end example

@cindex directory stream
There are obvious parallels here to the facilities for manipulating
ordinary files, described in @ref{Input/Output on Streams}.  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 @code{struct
dirent} objects.  The name of the file for each entry is stored in the
@code{d_name} member of this structure.

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.

These facilities 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 members:

@table @code
@item char *d_name
This is the null-terminated file name component.

@item ino_t d_fileno
This is the file serial number.  @xref{File Attribute Inquiry}.
For BSD compatibility, you can also refer to this member as @code{d_ino}.

@strong{Incomplete:}  This is not part of POSIX.  Do we want to advertise it?

@item size_t d_namlen
This is the length of the file name.

@strong{Incomplete:}  This is not part of POSIX.  Do we want to advertise it?
@end table

This structure contains other members too, to identify the actual
file that the directory entry names.  But you don't need to know about
these, because you can find the file by referring to its name instead.

Attributes such as file size, modification times, and the like are
associated with the file itself, not its directory entry.  @xref{File
Attributes}.
@end deftp

@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 have to allocate objects of the @code{struct dirent}
or @code{DIR} data types, since the directory access functions do
that for you.  Instead, you should just allocate pointers to them.

@comment dirent.h
@comment POSIX.1
@deftypefun {DIR *} opendir (const char *@var{dirname})
The @code{opendir} function is used to open a directory stream for
reading the directory whose file name is @var{dirname}.  The stream
(a @code{DIR *} value) is returned.

If the operation is not successful, this function returns a null pointer.
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
Read permission is denied for the directory named by @code{dirname}.

@item EMFILE
The process has too many files open.

@item ENFILE
The system has too many files open.
@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 Input/Output}.  Directory streams and the underlying
file descriptors are closed on @code{exec} (@pxref{Executing a File}).
@end deftypefun

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

The @code{readdir} may or may not return entries for @file{.} and @file{..}.
@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
@end deftypefun

@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, GNU
@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, GNU
@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 @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


@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 Adding Links
@section Adding Links

@cindex adding directory links
@cindex linking a file to a directory
The most obvious way to add an entry to a directory is to create a new
file, for example using @code{fopen} (@pxref{Opening and Closing
Streams}) or @code{open} (@pxref{Opening and Closing Files}).  But you
can also add additional directory entries for an existing file using the
@code{link} or @code{symlink} functions.  These functions are the
primitives for the @code{ln} shell command.


@menu
* Hard Links::		Making a hard link to a file.
* Symbolic Links::	Making a soft or symbolic link to a file.
@end menu

@node Hard Links
@subsection Hard Links

@cindex hard link
The @code{link} function makes what is called a @dfn{hard link}.  A hard
link is indistinguishible from the initial directory entry for 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.  The file is
also still known by all of its old names.

Because of the possibility of links across branches, the organization of
the file system is not a strict hierarchy or tree.

The prototype for the @code{link} function is declared in the header
file @file{<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 syntax 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 EACESS
The directory in which the new link is to be written is not writable.
Some implementations also require that the existing file be accessible
by the caller, and use this error to report failure for that reason.

@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 @code{LINK_MAX}; 
@pxref{File System Parameters}.)

@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
Some implementations only allow privileged users to make links to
directories, and others prohibit this operation entirely.  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
Some implementations don't allow you to make links across file systems.
This error is used to report the problem.
@end table
@end deftypefun

@strong{Incomplete:}  What does GNU do with the implementation-specific
behavior?


@node Symbolic Links
@subsection Symbolic Links

@cindex soft link
@cindex symbolic link
The GNU system also supports @dfn{soft links} or @dfn{symbolic links}.
While a hard link is essentially a pointer to a file, a symbolic link is
a pointer to a file name.  Unlike hard links, symbolic links can be made
to directories or across file systems.

A symbolic link is actually a special kind of file.  If you pass the
name of a symbolic link to the @code{open} (@pxref{Opening and Closing
Files}) and @code{stat} (@pxref{File Attributes}) functions, they behave
as if the operation were performed on the file the link points to.
However, other operations (such as deleting the file) operate on the
link itself.

Making a symbolic link to a file does not increase its link count.  This
means that it is possible to delete the file under its original name and
leave the link pointing to a nonexistent file.  @xref{File Attributes}.

Prototypes for the functions listed in this section are in
@file{<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
An I/O error occurred.

@item EFAULT
An invalid pointer argument was passed.
@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}.

A value of @code{-1} is returned in case of 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 EINVAL
The named file is not a symbolic link.

@item EIO
An I/O error occurred.

@item EFAULT
An invalid pointer was passed as an argument.
@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.
@end ignore
@end table
@end deftypefun

@strong{Portability Note:}  The @code{symlink} and @code{readlink}
functions are provided for compatibility with BSD.

@node Removing and Renaming Files
@section Removing and Renaming Files

You can remove a file with the @code{unlink} or @code{remove} functions,
or give it another name with the @code{rename} function.

Prototypes for @code{remove} and @code{rename} are in the header file
@file{<stdio.h>}.  The prototype for @code{unlink} is in
@file{<unistd.h>}.

@cindex removing directory links
@cindex unlinking a file from a directory
@comment unistd.h
@comment POSIX.1
@deftypefun int unlink (const char *@var{filename})
The @code{unlink} function removes the link named by the @var{filename}.
If there are no other links to the file, the file itself is also
removed.  (Actually, if any process has the file open when it is
unlinked, the file is simply marked for deletion and the removal is
postponed until everybody has closed the file.)

This function returns @code{0} on successful completion, and @code{-1}
on 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 EACCESS
Write permission is denied for the directory from which the file is to be
removed.

@item EBUSY
This error indicates that the file is being used by the system in such a
way that it can't be unlinked.  Examples of situations where you might
see this error are if the file name specifies the root directory or a
mount point for a file system.

@item ENOENT
The file being unlinked doesn't exist.

@item EPERM
Some implementations don't allow you to use @code{unlink} on directories,
and others only permit privileged users to do this.  This error is used
to indicate the problem.  You should use @code{rmdir} to delete directories
instead.

@item EROFS
The directory from which the file is to be unlinked is on a read-only
file system, and can't be modified.
@end table
@end deftypefun

@cindex removing a file
@comment stdio.h
@comment ANSI
@deftypefun int remove (const char *@var{filename})
The @code{remove} function is equivalent to @code{unlink}: it causes the
file named by @var{filename} to be removed.
@end deftypefun

@cindex renaming a file
@comment stdio.h
@comment ANSI
@deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
The @code{rename} function makes the file currently named by
@var{oldname} be called @var{newname} instead.

If both @var{oldname} and @var{newname} are links referring to the exact
same file, nothing is done.

If the @var{oldname} is not a directory, then any existing file named
@var{newname} is removed during the renaming operation.  The @var{newname}
must not be a directory itself in this case.

If the @var{oldname} is a directory, then either @var{newname} must not
exist or it must name a directory that is empty.  In the second case,
the existing file named @var{newname} is removed first.  The
@var{newname} can't live in a directory of the directory @code{oldname}
that is being renamed.

If @code{rename} fails, it returns @code{-1}.  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
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.  For example,
a directory that is a mount point for a filesystem might have this
problem.

@item EEXIST
The directory @var{newname} isn't empty.

@item ENOTEMPTY
The directory @var{newname} isn't empty.

@item EINVAL
The @var{oldname} is a directory that contains @var{newname}.

@item EISDIR
The @var{newname} names a directory, but the @var{oldname} doesn't.

@item EMLINK
The parent directory of @var{newname} would have too many links.

@item ENOENT
The file named by @var{oldname} doesn't exist.

@item ENOSPC
The directory that would contain the @var{newname} can't be extended.

@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{oldnames} are on different
file systems, and the implementation can't rename files across file systems.
@end table
@end deftypefun

@strong{Portability Note:} The ANSI C standard includes the
@code{remove} and @code{rename} functions, but says very little about
their behavior.  The POSIX.1 standard defines @code{remove} as a synonym
for @code{unlink} and also specifies the behavior for @code{rename}
defined here.

@node Making and Removing Directories
@section Making and Removing Directories

Directories are created and removed with the @code{mkdir} and
@code{rmdir} functions, respectively.  (There are shell commands with
the same names that do these operations, too.)

@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 whose name is
@var{filename}.

The @var{mode} specifies the file permissions for the new directory
file.  @xref{Assigning File Permissions}, 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 directory in which the file is to be
added.

@item EEXIST
The named file already exists.

@item EMLINK
The parent directory has too many links.

@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 files
@file{<sys/types.h>} and @file{<sys/stat.h>}.
@end deftypefun

@comment unistd.h
@comment POSIX.1
@deftypefun int rmdir (const char *@var{filename})
The @code{rmdir} function removes a directory.  The directory must
be empty before it can be removed; in other words, it can only contain
entries for @file{.} and @file {..}.

The other effects of this function are like those of @code{unlink};
@pxref{Removing and Renaming Files}.  There are two additional
@code{errno} error conditions defined for @code{rmdir}:

@table @code
@item EEXIST
The directory is not empty.

@item ENOTEMPTY
The directory is not empty.
@end table

The prototype for this function is declared in the header file
@file{<unistd.h>}.
@end deftypefun


@node File Attributes
@section File Attributes

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, and the like.  This kind of information is associated with the
file itself and not a particular directory entry for it.  

This section contains information about how you can inquire about and
modify these attributes of files.

@menu
* File Attribute Inquiry::	Getting information about a file.
* File Modes::			How information about who can access a file
				 is stored.
* Permission to Access a File::	How to find out if your process can access
				 a file.
* Assigning File Permissions::	How permissions for new files are assigned,
				 and how to change them.
* File Ownership::		How ownership for new files is determined,
				 and how to change it.
* File Times::			About the time attributes of a file.
@end menu

@node File Attribute Inquiry
@subsection File Attribute Inquiry

@cindex status of a file
@cindex file status
@cindex attributes of a file
@cindex file attributes
You can inquire about the attributes or @dfn{status} of a file using the
@code{stat} or @code{fstat} functions.  These functions return the
information in a @code{struct stat} object.  This structure and the
related macros are defined in the header file @file{<sys/stat.h>}.
The types of some of its component members are defined in the header
files @file{<sys/types.h>} and @file{<time.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.  @xref{File Modes}.

@item ino_t st_ino
The file serial number.

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

@item nlink_t st_nlink
The number of 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.  Symbolic links
are not counted in the total.

@item uid_t st_uid
The user ID of the file's owner.  @xref{File Ownership}.

@item gid_t st_gid
The group ID of the file's owner.  @xref{File Ownership}.

@item off_t st_size
This specifies the size of a regular file in bytes.  For files that
are really devices and the like, this field isn't usually meaningful.

@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 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 last modification to the
attributes of the file.  @xref{File Times}.
@end table
@end deftp

@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 short int}.
@xref{File Modes}.
@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}.
@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{short 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

Here is the description of the @code{stat} function itself.

@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 @var{filename} in the structure pointed at by @var{buf}.

The return value is @code{0} if the operation is successful, and @code{-1}
on 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 ENOENT
The file named by @var{filename} doesn't exist.
@end table
@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 Input/Output}.

Like @code{stat}, a value of @code{0} is returned on success and @code{-1}
on failure.  The following @code{errno} error conditions are defined
for this function:

@table @code
@item EBADF
The @var{filedes} argument is not a valid file descriptor.
@end table
@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.  @xref{Symbolic Links}.  This function is provided
for compatibility with BSD.
@end deftypefun


@node File Modes
@subsection File Modes

@cindex file mode
@cindex mode, of a file
The @dfn{mode} of a file encodes both information to identify the format
of the file, and information about the access permissions granted by the
owner of the file.  The mode is represented as the bitwise OR of the
individual flags.

All of the macros and constants listed in this section are defined in
the header file @file{<sys/stat.h>}.

The following macros test the format encoded in the file mode.

@comment sys/stat.h
@comment POSIX
@deftypefn Macro int S_ISDIR (mode_t @var{m})
This macro returns true 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 true 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 true 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 true 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 true 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 true 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 true if the file is a socket.  @xref{Sockets}.
@end deftypefn

Alternatively, you can bitwise AND the mode with @code{S_IFMT} to
extract the file format part, and compare the result to the appropriate
file format constant.  For example,

@example
S_ISCHR (@var{mode})
@end example

is equivalent to:

@example
(@var{mode} & S_IFMT) == S_IFCHR
@end example

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFMT
This is a bit mask used to extract the file format portion of a mode value.
@end defvr

These are the constants for the different file format values:

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFDIR
This macro represents the value of the file format for a directory file.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFCHR
This macro represents the value of the file format for a character-oriented
device file.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFBLK
This macro represents the value of the file format for a block-oriented
device file.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFREG
This macro represents the value of the file format for a regular file.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFLNK
This macro represents the value of the file format for a symbolic link.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFSOCK
This macro represents the value of the file format for a socket.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr Macro S_IFIFO
This macro represents the value of the file format for a FIFO or pipe.
@end defvr


@cindex file permission bits
These symbolic constants are defined for referring to the @dfn{file
permission bits} part of the file mode.

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IRUSR
Read permission bit for the owner of the file.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IWUSR
Write permission bit for the owner of the file.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IXUSR
Execute (for ordinary files) or search (for directories) permission bit
for the owner of the file.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IRWXU
This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
@end defvr


@comment sys/stat.h
@comment BSD
@defvr {Macro} S_IREAD
This is a synonym for @code{S_IRUSR}, provided for compatibility with
old BSD code.  Use @code{S_IRUSR} instead.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr {Macro} S_IWRITE
This is a synonym for @code{S_IWUSR}, provided for compatibility with
old BSD code.  Use @code{S_IWUSR} instead.
@end defvr

@comment sys/stat.h
@comment BSD
@defvr {Macro} S_IEXEC
This is a synonym for @code{S_IXUSR}, provided for compatibility with
old BSD code.  Use @code{S_IXUSR} instead.
@end defvr


@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IRGRP
Read permission bit for the group owner of the file.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IWGRP
Write permission bit for the group owner of the file.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IXGRP
Execute or search permission bit for the group owner of the file.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IRWXG
This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
@end defvr


@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IROTH
Read permission bit for other users.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IWOTH
Write permission bit for other users.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IXOTH
Execute or search permission bit for other users.
@end defvr

@comment sys/stat.h
@comment POSIX.1
@defvr {Macro} S_IRWXO
This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
@end defvr


@comment sys/stat.h
@comment POSIX
@defvr {Macro} S_ISUID
This is the set-user-ID on execute bit.  @xref{User/Group IDs of a Process}.
@end defvr

@comment sys/stat.h
@comment POSIX
@defvr {Macro} S_ISGID
This is the set-group-ID on execute bit.  @xref{User/Group IDs of a Process}.
@end defvr

@cindex sticky bit
@comment sys/stat.h
@comment BSD
@defvr {Macro} S_ISVTX
This is the @dfn{sticky} bit.  On executables, this bit inhibits swapping.
On directories, this allows deletion of files in the directory only by
users who have write permission on the specific file (not anybody who has
write permission on the directory).
@end defvr

On most systems, you can also specify the file permission bits as
an octal number using the following bit assignments:

@table @code
@item 4000
@code{S_ISUID}, set-user-ID on execute

@item 2000
@code{S_ISGID}, set-group-ID on execute

@item 1000
@code{S_ISVTX}, sticky bit

@item 0400
@code{S_IRUSR}, read by owner

@item 0200
@code{S_IWUSR}, write by owner

@item 0100
@code{S_IXUSR}, execute/search by owner

@item 0040
@code{S_IRGRP}, read by group

@item 0020
@code{S_IWGRP}, write by group

@item 0010
@code{S_IXGRP}, execute/search by group

@item 0004
@code{S_IROTH}, read by other

@item 0002
@code{S_IWOTH}, write by other

@item 0001
@code{S_IXOTH}, execute/search by other
@end table

So, for example, a mode of @code{644} permits the owner to read and
write the file, and gives only read access to the group and other users.

Referring to file modes by numbers is a convenient shorthand, provided
that you can remember what the numbers mean.  Using the symbolic
constants instead can make your program easier to read, though, as well
as making it more robust in case it is ever ported to a system that uses
different bit assignments for the various permissions.

@node Permission to Access a File
@subsection Permission to Access a File
@cindex permission to access a file

The determination of whether a process has permission to access a file
are made based on the effective user and group IDs of the process, and
its supplementary group IDs.  These concepts are discussed in detail in
@ref{User/Group IDs of a Process}.

If the effective user ID of the process matches the owner user ID of the
file, then permissions for read, write, and execute/search are
controlled by the corresponding ``user'' (or ``owner'') bits.  Likewise,
if any of the effective group ID or supplementary group IDs of the
process match 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 file permission bits.  As a special case, for a file to be
executable by a privileged user, at least one of its execute bits must
be set.

Some systems might support additional file security mechanisms (like
access control lists) that further restrict file access.  Consult the
documentation for your specific operating system, or your local system
administrator, to find out about this.

You can check whether a file is accessible to your process using the
@code{access} function.  This function is 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 ID's of the calling
process, rather than the @emph{effective} ID's, to check for access
permission.  This means that, even if you use the function from a
@code{setuid} or @code{setgid} program (@pxref{User/Group IDs of a
Process}), it gives information relative to the user who is really
running 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 denied.)  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
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.

@comment unistd.h
@comment POSIX.1
@defvr Macro R_OK
Test for read permission.
@end defvr

@comment unistd.h
@comment POSIX.1
@defvr Macro W_OK
Test for write permission.
@end defvr

@comment unistd.h
@comment POSIX.1
@defvr Macro X_OK
Test for execute/search permission.
@end defvr

@comment unistd.h
@comment POSIX.1
@defvr Macro F_OK
Test for existence of the file.
@end defvr

@node Assigning File Permissions
@subsection Assigning File Permissions

@cindex file creation mask
@cindex umask
The primitive functions for creating files (for example, @code{open} or
@code{mkdir}) are defined to take a @var{mode} argument, which specifies
the file permissions for the newly created file.  But this mode is
modified by the process's @dfn{file creation mask}, or @dfn{umask}.

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{mask} argument specified to the creation 
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{mask} 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.

You normally don't need to worry about the file creation mask, and it's
an especially bad idea for a program to arbitrarily change the file
creation mask.  In normal use, the file creation mask is initialized in
the user's login shell, and inherited by all subprocesses.

The @code{umask} function is the primitive for the shell command of
the same name.

The file creation mask only applies to permissions for newly created
files.  You can change the file permissions of an existing file without
regard to the file creation mask using @code{chmod}.  Again, this is the
primitive for the shell command of the same name.

These functions are declared in @file{<sys/stat.h>}.

@comment sys/stat.h
@comment POSIX.1
@deftypefun mode_t umask (mode_t @var{mask})
The @code{umask} function sets the process's file creation mask to 
@var{mask}, and returns the previous value of the mask.
@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 file protection bits for the file named
by @var{filename} to @var{mode}.

This function returns @code{0} if successful and @code{-1} if not.
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 ENOENT
The named file doesn't exist.

@item EPERM
Either the effective user ID of the calling process must be the same
as the owner of the file, or the calling process must be privileged.
This error is used to report this problem.

@item EROFS
The file resides on a read-only file system.
@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 file with open file descriptor @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, not an ordinary
file.

@item EPERM
Either the effective user ID of the calling process must be the same
as the owner of the file, or the calling process must be privileged.
This error is used to report this problem.

@item EROFS
The file resides on a read-only file system.
@end table
@end deftypefun


@node File Ownership
@subsection File Ownership

When a file is created, its owner user ID is set to be the same as the
effective user ID of the process that creates it.  Its group owner ID
may either be the effective group ID of the process, or the group ID of
the directory that contains the file.

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.

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 usually clears the set-user-ID and
set-group-ID bits of the file's permissions.  (This is because those
bits may not be appropriate for the new owner.)  The 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 syntax errors (@pxref{File Name Errors}), 
the following @code{errno} error conditions are defined for this function:

@table @code
@item EPERM
You don't have privilege to change the file ownership.  In order to
change the ownership of a file, either the effective user ID of the
calling process must match the original owner of the file, or the
calling process must be privileged.  In addition, some implementations
allow nonprivileged users only to change the group owner of the file;
@pxref{File System Parameters}, for information about the
@code{_POSIX_CHOWN_RESTRICTED} macro.

@strong{Incomplete:}  What does the GNU system do?

@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 file
with open file 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 EROFS
The file resides on a read-only file system.
@end table
@end deftypefun

@node File Times
@subsection File Times

@cindex file access time
@cindex file modification time
@cindex file attribute modification time
Each file has three timestamps 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; @pxref{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, @pxref{Calendar and Local Time}.

When a file is created, all three timestamps 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 directory link 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.
These same fields are affected if a file is unlinked 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 attributes of a file (for example, with @code{chmod}) updates
its attribute change time field.

When an existing file is opened, its attribute change time and
modification time fields are updated.  Reading from a file updates its
access time attribute, and writing updates its modification time.

You can also change the timestamps of a file explicitly using the
@code{utime} function.  You need to include the header file
@file{<utime.h>} to use this facility.

@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 at
least 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 at by @var{times}.  

The attribute modification time for the file is set to the current time
in either case (since changing its timestamps 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 syntax 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 timestamp on
the file, you must either be the owner of the file, have write
permission on 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.  This error is used to
report the problem.

@item EROFS
The file lives on a read-only file system.
@end table
@end deftypefun

For each of the three time fields, there is also an additional structure
member that holds the fractional part of the time value.  These are the
@code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec}
members.

The fractional time value is given in microseconds and corresponds to
the @code{tv_usec} field of a @code{timeval} structure;
@pxref{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>}.

@comment sys/time.h
@comment BSD
@deftypefun int utimes (const char *@var{filename}, struct timeval @var{tvp}[2])
This function sets the file access and modification times for the file
named by @var{filename}.  The new file access time is specified by
@code{@var{tvp}[0]}, and the new modification time by
@code{@var{tvp}[1]}.

The return values and error conditions are the same as for the @code{utime}
function.
@end deftypefun


@strong{Portability Note:}  The @code{utimes} function is provided for
compatibility with BSD.  The POSIX.1 standard specifies only the @code{utime}
function.

@node Making Special Files
@section Making 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>}.

@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{File Modes}.

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