about summary refs log tree commit diff
path: root/manual
diff options
context:
space:
mode:
Diffstat (limited to 'manual')
-rw-r--r--manual/argp.texi13
-rw-r--r--manual/conf.texi2
-rw-r--r--manual/intro.texi6
-rw-r--r--manual/sysinfo.texi386
-rw-r--r--manual/users.texi2
5 files changed, 381 insertions, 28 deletions
diff --git a/manual/argp.texi b/manual/argp.texi
index 14a9df2bce..0a5d56dc7d 100644
--- a/manual/argp.texi
+++ b/manual/argp.texi
@@ -74,10 +74,10 @@ in @var{flags}, calling @code{argp_parse} may result in the program
 exiting---for instance when an unknown option is encountered.
 @xref{Program Termination}.
 
-If @var{arg_index} is non-NULL, the index of the first unparsed option
+If @var{arg_index} is non-null, the index of the first unparsed option
 in @var{argv} is returned in it.
 
-The return value is zero for successful parsing, or a unix error code
+The return value is zero for successful parsing, or an error code
 (@pxref{Error Codes}) if an error was detected.  Different argp parsers
 may return arbitrary error codes, but standard ones are @code{ENOMEM} if
 a memory allocation error occurred, or @code{EINVAL} if an unknown option
@@ -556,11 +556,14 @@ combined).
 Some non-option argument was unrecognized.
 
 This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN}
-for an argument, in which case parsing stops at that argument.  If a
-non-NULL value for @var{arg_index} was passed to @code{argp_parse}, the
-index of this argument is returned in it, otherwise an error occurs.
+for an argument, in which case parsing stops at that argument.  If
+@var{arg_index} is a null pointer otherwise an error occurs.
 @end table
 
+In all cases, if a non-null value for @var{arg_index} was passed to
+@code{argp_parse}, the index of the first unparsed command-line argument
+is passed back in it.
+
 If an error occurs (either detected by argp, or because a parser
 function returned an error value), then each parser is called with
 @code{ARGP_KEY_ERROR}, and no further calls are made except the final
diff --git a/manual/conf.texi b/manual/conf.texi
index a684a5b2e2..9fdaa1cf9a 100644
--- a/manual/conf.texi
+++ b/manual/conf.texi
@@ -1,4 +1,4 @@
-@node System Configuration, Cryptographic Functions, System Information, Top
+@node System Configuration, Cryptographic Functions, System Management, Top
 @c %MENU% Parameters describing operating system limits
 @chapter System Configuration Parameters
 
diff --git a/manual/intro.texi b/manual/intro.texi
index 2ac893e316..b3c1b05614 100644
--- a/manual/intro.texi
+++ b/manual/intro.texi
@@ -698,9 +698,9 @@ implemented so that contributors can design their own services.
 the system user and group databases.
 
 @item
-@ref{System Information}, describes functions for getting information
-about the hardware and software configuration your program is executing
-under.
+@ref{System Management}, describes functions for controlling and getting
+information about the hardware and software configuration your program
+is executing under.
 
 @item
 @ref{System Configuration}, tells you how you can get information about
diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi
index 5bce9a53ef..152c24e61b 100644
--- a/manual/sysinfo.texi
+++ b/manual/sysinfo.texi
@@ -1,19 +1,25 @@
-@node System Information, System Configuration, Users and Groups, Top
-@c %MENU% Getting information about the hardware and operating system
-@chapter System Information
+@node System Management, System Configuration, Users and Groups, Top
+@c %MENU% Controlling the system and getting information about it
+@chapter System Management
+
+This chapter describes facilities for controlling the system that
+underlies a process (including the operating system and hardware) and
+for getting information about it.  Anyone can generally use the
+informational facilities, but usually only a properly privileged process
+can make changes.
 
-This chapter describes functions that return information about the
-particular machine that is in use---the type of hardware, the type of
-software, and the individual machine's name.
 
 @menu
 * Host Identification::         Determining the name of the machine.
 * Hardware/Software Type ID::   Determining the hardware type of the
                                  machine and what operating system it is
                                  running.
-* Filesystem handling::         Which is mounted and/or available?
+* Filesystem Handling::         Controlling/querying mounts
 @end menu
 
+To get information on parameters of the system that are built into the
+system, such as the maximum length of a filename, @ref{System
+Configuration}.
 
 @node Host Identification
 @section Host Identification
@@ -182,15 +188,45 @@ possibility.
 @end deftypefun
 
 
-@node Filesystem handling
-@section Which filesystems are mounted and/or available?
+@node Filesystem Handling
+@section Controlling/querying mounts
+
+All files are in filesystems, and before you can access any file, its
+filesystem must be mounted.  Because of Unix's concept of
+@emph{Everything is a file}, mounting of filesystems is central to doing
+almost anything.  This section explains how to find out what filesystems
+are currently mounted and what filesystems are available for mounting,
+and how to change what is mounted.
+
+The classic filesystem is the contents of a disk drive.  The concept is
+considerably more abstract, though, and lots of things other than disk
+drives can be mounted.  
+
+Some block devices don't correspond to traditional devices like disk
+drives.  For example, a loop device is a block device whose driver uses
+a regular file in another filesystem as its medium.  So if that regular
+file contains appropriate data for a filesystem, you can by mounting the
+loop device essentially mount a regular file.
+
+Some filesystems aren't based on a device of any kind.  The ``proc''
+filesystem, for example, contains files whose data is made up by the
+filesystem driver on the fly whenever you ask for it.  And when you
+write to it, the data you write causes changes in the system.  No data
+gets stored.
+
+@c It would be good to mention NFS mounts here.
+
+@menu
+* Mount Information::           What is or could be mounted?
+* Mount/Unmount/Remount::       Controlling what is mounted and how
+@end menu
 
-The Unix concept of @emph{Everything is a file} is based on the
-ability to @dfn{mount} filesystems or other things into the
-filesystem.  For some programs it is desirable and necessary to access
-information about whether a certain filesystem is mounted and, if it is, 
-where, or simply to get lists of all the available filesystems.  The
-GNU libc provides some functions to retrieve this information portably.
+@node Mount Information, Mount/Unmount/Remount, , Filesystem Handling
+
+For some programs it is desirable and necessary to access information
+about whether a certain filesystem is mounted and, if it is, where, or
+simply to get lists of all the available filesystems.  The GNU libc
+provides some functions to retrieve this information portably.
 
 Traditionally Unix systems have a file named @file{/etc/fstab} which
 describes all possibly mounted filesystems.  The @code{mount} program
@@ -203,6 +239,13 @@ functions described in this section can do this and they also provide
 the functionality to convert the external textual representation to the
 internal representation.
 
+Note that the @file{fstab} and @file{mtab} files are maintained on a
+system by @emph{convention}.  It is possible for the files not to exist
+or not to be consistent with what is really mounted or available to
+mount, if the system's administration policy allows it.  But programs
+that mount and unmount filesystems typically maintain and use these
+files as described herein.
+
 @vindex _PATH_FSTAB
 @vindex _PATH_MNTTAB
 @vindex FSTAB
@@ -215,6 +258,15 @@ defined in @file{fstab.h} and @code{_PATH_MNTTAB}, defined in
 deprecated and kept only for backward compatibility.  The two former
 names should always be used.
 
+@menu
+* fstab::                       The @file{fstab} file
+* mtab::                        The @file{mtab} file
+* Other Mount Information::     Other (non-libc) sources of mount information
+@end menu
+
+@node fstab
+@subsection The @file{fstab} file
+
 The internal representation for entries of the file is @w{@code{struct
 fstab}}, defined in @file{fstab.h}.
 
@@ -363,11 +415,12 @@ function is not thread-safe.  If an error occurred @code{getfsent}
 returns a @code{NULL} pointer.
 @end deftypefun
 
-To access the @file{mtab} file there is a different set of functions and
-also a different structure to describe the results.
 
+@node mtab
+@subsection The @file{mtab} file
+The following functions and data structure access the @file{mtab} file.
 
-@comment fstab.h
+@comment mntent.h
 @comment BSD
 @deftp {Data Type} {struct mntent}
 This structure is used with the @code{getmntent}, @code{getmntent_t},
@@ -572,3 +625,300 @@ This function is useful to test whether a specific option is present but
 when all options have to be processed one is better off with using the
 @code{getsubopt} function to iterate over all options in the string.
 @end deftypefun
+
+@node Other Mount Information
+@subsection Other (Non-libc) Sources of Mount Information
+
+On a system with a Linux kernel and the @code{proc} filesystem, you can
+get information on currently mounted filesystems from the file
+@file{mounts} in the @code{proc} filesystem.  Its format is similar to
+that of the @file{mtab} file, but represents what is truly mounted
+without relying on facilities outside the kernel to keep @file{mtab} up
+to date.
+
+
+@node Mount/Unmount/Remount, , Mount Information, Filesystem Handling
+
+This section describes the functions for mounting, unmounting, and
+remounting filesystems.
+
+Only the superuser can mount, unmount, or remount a filesystem.
+
+These functions do not access the @file{fstab} and @file{mtab} files.  You
+should maintain and use these separately.  @xref{Mount Information}.
+
+The symbols in this section are declared in @file{sys/mount.h}.
+
+@comment sys/mount.h
+@deftypefun {int} mount (const char *@var{special_file}, const char *@var{dir}, const char *@var{fstype}, unsigned long int @var{options}, const void *@var{data})
+
+@code{mount} mounts or remounts a filesystem.  The two operations are 
+quite different and are merged rather unnnaturally into this one function.
+The @code{MS_REMOUNT} option, explained below, determines whether 
+@code{mount} mounts or remounts.
+
+For a mount, the filesystem on the block device represented by the
+device special file named @var{special_file} gets mounted over the mount
+point @var{dir}.  This means that the directory @var{dir} (along with any
+files in it) is no longer visible; in its place (and still with the name
+@var{dir}) is the root directory of the filesystem on the device.
+
+As an exception, if the filesystem type (see below) is one which is not
+based on a device (e.g. ``proc''), @code{mount} instantiates a
+filesystem and mounts it over @var{dir} and ignores @var{special_file}.
+
+For a remount, @var{dir} specifies the mount point where the filesystem
+to be remounted is (and remains) mounted and @var{special_file} is
+ignored.  Remounting a filesystem means changing the options that control
+operations on the filesystem while it is mounted.  It does not mean
+unmounting and mounting again.
+
+For a mount, you must identify the type of the filesystem as
+@var{fstype}.  This type tells the kernel how to access the filesystem
+and can be thought of as the name of a filesystem driver.  The
+acceptable values are system dependent.  On a system with a Linux kernel
+and the @code{proc} filesystem, the list of possible values is in the
+file @file{filesystems} in the @code{proc} filesystem (e.g. type
+@kbd{cat /proc/filesystems} to see the list).  With a Linux kernel, the
+types of filesystems that @code{mount} can mount, and their type names,
+depends on what filesystem drivers are configured into the kernel or
+loaded as loadable kernel modules.  An example of a common value for
+@var{fstype} is @code{ext2}.
+
+For a remount, @code{mount} ignores @var{fstype}.
+
+@c This is traditionally called "rwflag" for historical reasons.
+@c No point in confusing people today, though.
+@var{options} specifies a variety of options that apply until the
+filesystem in unmounted or remounted.  The precise meaning of an option
+depends on the filesystem and with some filesystems, an option may have
+no effect at all.  Furthermore, for some filesystems, some of these
+options (but never @code{MS_RDONLY}) can be overridden for individual
+file accesses via @code{ioctl}.
+
+@var{options} is a bit string with bit fields defined using the
+following mask and masked value macros:
+
+@table @code
+@item MS_MGC_MASK
+This multibit field contains a magic number.  If it does not have the value
+@code{MS_MGC_VAL}, @code{mount} assumes all the following bits are zero and
+the @var{data} argument is a null string, regardless of their actual values.
+
+@item MS_REMOUNT
+This bit on means to remount the filesystem.  Off means to mount it.
+@c There is a mask MS_RMT_MASK in mount.h that says only two of the options
+@c can be reset by remount.  But the Linux kernel has it's own version of
+@c MS_RMT_MASK that says they all can be reset.  As far as I can tell,
+@c libc just passes the arguments straight through to the kernel.
+
+@item MS_RDONLY
+This bit on specifies that no writing to the filesystem shall be allowed
+while it is mounted.  This cannot be overridden by @code{ioctl}.  This 
+option is available on nearly all filesystems.
+
+@item S_IMMUTABLE
+This bit on specifies that no writing to the files in the filesystem
+shall be allowed while it is mounted.  This can be overridden for a
+particular file access by a properly privileged call to @code{ioctl}.
+This option is a relatively new invention and is not available on many
+filesystems.
+
+@item S_APPEND
+This bit on specifies that the only file writing that shall be allowed
+while the filesystem is mounted is appending.  Some filesystems allow
+this to be overridden for a particular process by a properly privileged
+call to @code{ioctl}.  This is a relatively new invention and is not
+available on many filesystems.
+
+@item MS_NOSUID
+This bit on specifies that Setuid and Setgid permissions on files in the
+filesystem shall be ignored while it is mounted.
+
+@item MS_NOEXEC
+This bit on specifies that no files in the filesystem shall be executed
+while the filesystem is mounted.
+
+@item MS_NODEV
+This bit on specifies that no device special files in the filesystem 
+shall be accessible while the filesystem is mounted.
+
+@item MS_SYNCHRONOUS
+This bit on specifies that all writes to the filesystem while it is 
+mounted shall be synchronous; i.e. data shall be synced before each 
+write completes rather than held in the buffer cache.
+
+@item MS_MANDLOCK
+This bit on specifies that mandatory locks on files shall be permitted while
+the filesystem is mounted.
+
+@item MS_NOATIME
+This bit on specifies that access times of files shall not be updated when
+the files are accessed while the filesystem is mounted.
+
+@item MS_NODIRATIME
+This bit on specifies that access times of directories shall not be updated
+when the directories are accessed while the filesystem in mounted.
+
+@c there is also S_QUOTA Linux fs.h (mount.h still uses its former name
+@c S_WRITE), but I can't see what it does.  Turns on quotas, I guess.
+
+@end table
+
+Any bits not covered by the above masks should be set off; otherwise,
+results are undefined.
+
+The meaning of @var{data} depends on the filesystem type and is controlled
+entirely by the filesystem driver in the kernel.
+
+Example:
+
+@smallexample
+@group
+#include <sys/mount.h>
+
+mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");
+
+mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");
+
+@end group
+@end smallexample
+
+Appropriate arguments for @code{mount} are conventionally recorded in
+the @file{fstab} table.  @xref{Mount Information}.
+
+The return value is zero if the mount or remount is successful.  Otherwise,
+it is @code{-1} and @code{errno} is set appropriately.  The values of 
+@code{errno} are filesystem dependent, but here is a general list:
+
+@table @code
+@item EPERM
+The process is not superuser.
+@item ENODEV
+The file system type @var{fstype} is not known to the kernel.
+@item ENOTBLK
+The file @var{dev} is not a block device special file.
+@item EBUSY
+
+@itemize
+
+@item 
+The device is already mounted.
+
+@item
+The mount point is busy.  (E.g. it is some process' working directory or
+has a filesystem mounted on it already).
+
+@item
+The request is to remount read-only, but there are files open for write.
+@end itemize
+
+@item EINVAL
+@itemize
+
+@item
+A remount was attempted, but there is no filesystem mounted over the
+specified mount point.
+
+@item 
+The supposed filesystem has an invalid superblock.
+
+@end itemize
+
+@item EACCESS
+@itemize
+
+@item
+The filesystem is inherently read-only (possibly due to a switch on the 
+device) and the process attempted to mount it read/write (by setting the
+@code{MS_RDONLY} bit off).
+
+@item
+@var{special_file} or @var{dir} is not accessible due to file permissions.
+
+@item
+@var{special_file} is not accessible because it is in a filesystem that is
+mounted with the @code{MS_NODEV} option.
+
+@end itemize
+
+@item EM_FILE
+The table of dummy devices is full.  @code{mount} needs to create a
+dummy device (aka ``unnamed'' device) if the filesystem being mounted is
+not one that uses a device.
+
+@end table
+
+@end deftypefun
+
+
+@comment sys/mount.h
+@deftypefun {int} umount2 (const char *@var{file}, int @var{flags})
+
+@code{umount2} unmounts a filesystem.
+
+You can identify the filesystem to unmount either by the device special
+file that contains the filesystem or by the mount point.  The effect is
+the same.  Specify either as the string @var{file}.
+
+@var{flags} contains the one-bit field identified by the following 
+mask macro:
+
+@table @code
+
+@item MNT_FORCE
+This bit on means to force the unmounting even if the filesystem is
+busy, by making it unbusy first.  If the bit is off and the filesystem is
+busy, @code{umount2} fails with @code{errno} = @code{EBUSY}.  Depending
+on the filesystem, this may override all, some, or no busy conditions.
+
+@end table
+
+All other bits in @var{flags} should be set to zero; otherwise, the result
+is undefined.
+
+Example:
+
+@smallexample
+@group
+#include <sys/mount.h>
+
+umount2("/mnt", MNT_FORCE);
+
+umount2("/dev/hdd1", 0);
+
+@end group
+@end smallexample
+
+After the filesystem is unmounted, the directory that was the mount point
+is visible, as are any files in it.
+
+As part of unmounting, @code{umount2} syncs the filesystem.
+
+If the unmounting is successful, the return value is zero.  Otherwise, it
+is @code{-1} and @code{errno} is set accordingly:
+
+@table @code
+@item EPERM
+The process is not superuser.
+@item EBUSY
+The filesystem cannot be unmounted because it is busy.  E.g. it contains
+a directory that is some process's working directory or a file that some
+process has open.  With some filesystems in some cases, you can avoid
+this failure with the @code{MNT_FORCE} option.
+
+@item EINVAL
+@var{file} validly refers to a file, but that file is neither a mount 
+point nor a device special file of a currently mounted filesystem.
+
+@end table
+@end deftypefun
+
+@comment sys/mount.h
+@deftypefun {int} umount (const char *@var{file})
+
+@code{umount} does the same thing as @code{umount2} with @var{flags}
+set to zeroes.  It exists for compatibility.
+
+
+@end deftypefun
diff --git a/manual/users.texi b/manual/users.texi
index 64bf153f83..d13139c4c5 100644
--- a/manual/users.texi
+++ b/manual/users.texi
@@ -1,4 +1,4 @@
-@node Users and Groups, System Information, Name Service Switch, Top
+@node Users and Groups, System Management, Name Service Switch, Top
 @c %MENU% How users are identified and classified
 @chapter Users and Groups