filesys.texi

一个C源代码分析器

This macro returns nonzero 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 nonzero 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 nonzero 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 nonzero 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 nonzero if the file is a socket.  @xref{Sockets}.
@end deftypefn

An alterate non-POSIX method of testing the file type is supported for
compatibility with BSD.  The mode can be bitwise ANDed with
@code{S_IFMT} to extract the file type code, and compared to the
appropriate type code 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 portion of 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 macro represents the value of the file type code for a directory file.

@comment sys/stat.h
@comment BSD
@item S_IFCHR
@vindex S_IFCHR
This macro represents the value of the file type code for a
character-oriented device file.

@comment sys/stat.h
@comment BSD
@item S_IFBLK
@vindex S_IFBLK
This macro represents the value of the file type code for a block-oriented
device file.

@comment sys/stat.h
@comment BSD
@item S_IFREG
@vindex S_IFREG
This macro represents the value of the file type code for a regular file.

@comment sys/stat.h
@comment BSD
@item S_IFLNK
@vindex S_IFLNK
This macro represents the value of the file type code for a symbolic link.

@comment sys/stat.h
@comment BSD
@item S_IFSOCK
@vindex S_IFSOCK
This macro represents the value of the file type code for a socket.

@comment sys/stat.h
@comment BSD
@item S_IFIFO
@vindex S_IFIFO
This macro represents the value of the file type code for a FIFO or pipe.
@end table

@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 user that is the
owner, another set that apply to users who belong to the file's group,
and a third set of bits that apply 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 from the effective user ID of
the process that creates it (@pxref{Process Persona}).  The file's group
ID may be set from either 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 rule, 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 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
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 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 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.
@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.

On a directory, it gives permission to delete a file in the directory
only if you own that file.  Ordinarily, a user either can delete all the
files in the directory or cannot delete any of them (based on whether
the user has write permission for the directory).  The same restriction
applies---you must both have 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.  In this use
the sticky bit also says that the filesystem may fail to record the
file's modification time onto disk reliably (the idea being that noone
cares for a swap file).
@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.