filesys.texi

一个C源代码分析器

@strong{Warning:} Writing explicit numbers for file permissions is bad
practice.  It is not only nonportable, 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 file permission bits.  As a special case, for a file to be
executable even for 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 for the newly created file.  But the specified 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 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{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 ignores the file creation mask; it uses
exactly the specified permission bits.

@pindex umask
In normal use, the file creation mask is initialized in 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 do automatically what it is supposed to
do.

When your program should 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)
@{
  mask = umask (0);
  umask (mask);
@}
@end smallexample

@noindent
However, it is better to use @code{getumask} if you just want to read
the mask value, because that 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 the @var{filename} names a symbolic link, @code{chmod} changes the
permission 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 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
This process does not have permission to change the access permission 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 file currently open via 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, or something
else that doesn't really have access permissions.

@item EPERM
This process does not have permission to change the access permission 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

When a program runs as a privileged user, this permits it to access
files off-limits to ordinary users---for example, to modify
@file{/etc/passwd}.  Programs designed to be run by ordinary users but
access such files use the setuid bit feature so that they always run
with @code{root} as the effective user ID.
 
Such a program may also access files specified by the user, files which
conceptually are being accessed explicitly by the user.  Since the
program runs as @code{root}, it has permission to access whatever file
the user specifies---but usually the desired behavior is to permit only
those files which the user could ordinarily access.

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 ID's of the calling
process, rather than the @emph{effective} ID's, 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 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.
@pindex unistd.h

@comment unistd.h
@comment POSIX.1
@deftypevr Macro int R_OK
Argument that means, test for read permission.
@end deftypevr

@comment unistd.h
@comment POSIX.1
@deftypevr Macro int W_OK
Argument that means, test for write permission.
@end deftypevr

@comment unistd.h
@comment POSIX.1
@deftypevr Macro int X_OK
Argument that means, test for execute/search permission.
@end deftypevr

@comment unistd.h
@comment POSIX.1
@deftypevr Macro int F_OK
Argument that means, 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 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; 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

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.

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 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 attributes of a file (for example, with @code{chmod}) updates
its attribute change time field.

You can also change some of the timestamps 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 at by @var{times}.  

The attribute modification time for the file is set to the current time
in either case (since changing the 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, yo