| @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. |
| |
| |
| @menu |
| * Host Identification:: Determining the name of the machine. |
| * Platform Type:: Determining operating system and basic |
| machine type |
| * Filesystem Handling:: Controlling/querying mounts |
| * System Parameters:: Getting and setting various system parameters |
| @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 |
| |
| This section explains how to identify the particular system on which your |
| program is running. First, let's review the various ways computer systems |
| are named, which is a little complicated because of the history of the |
| development of the Internet. |
| |
| Every Unix system (also known as a host) has a host name, whether it's |
| connected to a network or not. In its simplest form, as used before |
| computer networks were an issue, it's just a word like @samp{chicken}. |
| @cindex host name |
| |
| But any system attached to the Internet or any network like it conforms |
| to a more rigorous naming convention as part of the Domain Name System |
| (DNS). In DNS, every host name is composed of two parts: |
| @cindex DNS |
| @cindex Domain Name System |
| |
| @enumerate |
| @item |
| hostname |
| @cindex hostname |
| @item |
| domain name |
| @cindex domain name |
| @end enumerate |
| |
| You will note that ``hostname'' looks a lot like ``host name'', but is |
| not the same thing, and that people often incorrectly refer to entire |
| host names as ``domain names.'' |
| |
| In DNS, the full host name is properly called the FQDN (Fully Qualified |
| Domain Name) and consists of the hostname, then a period, then the |
| domain name. The domain name itself usually has multiple components |
| separated by periods. So for example, a system's hostname may be |
| @samp{chicken} and its domain name might be @samp{ai.mit.edu}, so |
| its FQDN (which is its host name) is @samp{chicken.ai.mit.edu}. |
| @cindex FQDN |
| |
| Adding to the confusion, though, is that DNS is not the only name space |
| in which a computer needs to be known. Another name space is the |
| NIS (aka YP) name space. For NIS purposes, there is another domain |
| name, which is called the NIS domain name or the YP domain name. It |
| need not have anything to do with the DNS domain name. |
| @cindex YP |
| @cindex NIS |
| @cindex NIS domain name |
| @cindex YP domain name |
| |
| Confusing things even more is the fact that in DNS, it is possible for |
| multiple FQDNs to refer to the same system. However, there is always |
| exactly one of them that is the true host name, and it is called the |
| canonical FQDN. |
| |
| In some contexts, the host name is called a ``node name.'' |
| |
| For more information on DNS host naming, see @ref{Host Names}. |
| |
| @pindex hostname |
| @pindex hostid |
| @pindex unistd.h |
| Prototypes for these functions appear in @file{unistd.h}. |
| |
| The programs @code{hostname}, @code{hostid}, and @code{domainname} work |
| by calling these functions. |
| |
| @comment unistd.h |
| @comment BSD |
| @deftypefun int gethostname (char *@var{name}, size_t @var{size}) |
| This function returns the host name of the system on which it is called, |
| in the array @var{name}. The @var{size} argument specifies the size of |
| this array, in bytes. Note that this is @emph{not} the DNS hostname. |
| If the system participates in DNS, this is the FQDN (see above). |
| |
| The return value is @code{0} on success and @code{-1} on failure. In |
| the GNU C library, @code{gethostname} fails if @var{size} is not large |
| enough; then you can try again with a larger array. The following |
| @code{errno} error condition is defined for this function: |
| |
| @table @code |
| @item ENAMETOOLONG |
| The @var{size} argument is less than the size of the host name plus one. |
| @end table |
| |
| @pindex sys/param.h |
| On some systems, there is a symbol for the maximum possible host name |
| length: @code{MAXHOSTNAMELEN}. It is defined in @file{sys/param.h}. |
| But you can't count on this to exist, so it is cleaner to handle |
| failure and try again. |
| |
| @code{gethostname} stores the beginning of the host name in @var{name} |
| even if the host name won't entirely fit. For some purposes, a |
| truncated host name is good enough. If it is, you can ignore the |
| error code. |
| @end deftypefun |
| |
| @comment unistd.h |
| @comment BSD |
| @deftypefun int sethostname (const char *@var{name}, size_t @var{length}) |
| The @code{sethostname} function sets the host name of the system that |
| calls it to @var{name}, a string with length @var{length}. Only |
| privileged processes are permitted to do this. |
| |
| Usually @code{sethostname} gets called just once, at system boot time. |
| Often, the program that calls it sets it to the value it finds in the |
| file @code{/etc/hostname}. |
| @cindex /etc/hostname |
| |
| Be sure to set the host name to the full host name, not just the DNS |
| hostname (see above). |
| |
| The return value is @code{0} on success and @code{-1} on failure. |
| The following @code{errno} error condition is defined for this function: |
| |
| @table @code |
| @item EPERM |
| This process cannot set the host name because it is not privileged. |
| @end table |
| @end deftypefun |
| |
| @comment unistd.h |
| @comment ??? |
| @deftypefun int getdomainnname (char *@var{name}, size_t @var{length}) |
| @cindex NIS domain name |
| @cindex YP domain name |
| |
| @code{getdomainname} returns the NIS (aka YP) domain name of the system |
| on which it is called. Note that this is not the more popular DNS |
| domain name. Get that with @code{gethostname}. |
| |
| The specifics of this function are analogous to @code{gethostname}, above. |
| |
| @end deftypefun |
| |
| @comment unistd.h |
| @comment ??? |
| @deftypefun int setdomainname (const char *@var{name}, size_t @var{length}) |
| @cindex NIS domain name |
| @cindex YP domain name |
| |
| @code{getdomainname} sets the NIS (aka YP) domain name of the system |
| on which it is called. Note that this is not the more popular DNS |
| domain name. Set that with @code{sethostname}. |
| |
| The specifics of this function are analogous to @code{sethostname}, above. |
| |
| @end deftypefun |
| |
| @comment unistd.h |
| @comment BSD |
| @deftypefun {long int} gethostid (void) |
| This function returns the ``host ID'' of the machine the program is |
| running on. By convention, this is usually the primary Internet IP address |
| of that machine, converted to a @w{@code{long int}}. However, on some |
| systems it is a meaningless but unique number which is hard-coded for |
| each machine. |
| |
| This is not widely used. It arose in BSD 4.2, but was dropped in BSD 4.4. |
| It is not required by POSIX. |
| |
| The proper way to query the IP address is to use @code{gethostbyname} |
| on the results of @code{gethostname}. For more information on IP addresses, |
| @xref{Host Addresses}. |
| @end deftypefun |
| |
| @comment unistd.h |
| @comment BSD |
| @deftypefun int sethostid (long int @var{id}) |
| The @code{sethostid} function sets the ``host ID'' of the host machine |
| to @var{id}. Only privileged processes are permitted to do this. Usually |
| it happens just once, at system boot time. |
| |
| The proper way to establish the primary IP address of a system |
| is to configure the IP address resolver to associate that IP address with |
| the system's host name as returned by @code{gethostname}. For example, |
| put a record for the system in @file{/etc/hosts}. |
| |
| See @code{gethostid} above for more information on host ids. |
| |
| The return value is @code{0} on success and @code{-1} on failure. |
| The following @code{errno} error conditions are defined for this function: |
| |
| @table @code |
| @item EPERM |
| This process cannot set the host name because it is not privileged. |
| |
| @item ENOSYS |
| The operating system does not support setting the host ID. On some |
| systems, the host ID is a meaningless but unique number hard-coded for |
| each machine. |
| @end table |
| @end deftypefun |
| |
| @node Platform Type |
| @section Platform Type Identification |
| |
| You can use the @code{uname} function to find out some information about |
| the type of computer your program is running on. This function and the |
| associated data type are declared in the header file |
| @file{sys/utsname.h}. |
| @pindex sys/utsname.h |
| |
| As a bonus, @code{uname} also gives some information identifying the |
| particular system your program is running on. This is the same information |
| which you can get with functions targetted to this purpose described in |
| @ref{Host Identification}. |
| |
| |
| @comment sys/utsname.h |
| @comment POSIX.1 |
| @deftp {Data Type} {struct utsname} |
| The @code{utsname} structure is used to hold information returned |
| by the @code{uname} function. It has the following members: |
| |
| @table @code |
| @item char sysname[] |
| This is the name of the operating system in use. |
| |
| @item char release[] |
| This is the current release level of the operating system implementation. |
| |
| @item char version[] |
| This is the current version level within the release of the operating |
| system. |
| |
| @item char machine[] |
| This is a description of the type of hardware that is in use. |
| |
| Some systems provide a mechanism to interrogate the kernel directly for |
| this information. On systems without such a mechanism, the GNU C |
| library fills in this field based on the configuration name that was |
| specified when building and installing the library. |
| |
| GNU uses a three-part name to describe a system configuration; the three |
| parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they |
| are separated with dashes. Any possible combination of three names is |
| potentially meaningful, but most such combinations are meaningless in |
| practice and even the meaningful ones are not necessarily supported by |
| any particular GNU program. |
| |
| Since the value in @code{machine} is supposed to describe just the |
| hardware, it consists of the first two parts of the configuration name: |
| @samp{@var{cpu}-@var{manufacturer}}. For example, it might be one of these: |
| |
| @quotation |
| @code{"sparc-sun"}, |
| @code{"i386-@var{anything}"}, |
| @code{"m68k-hp"}, |
| @code{"m68k-sony"}, |
| @code{"m68k-sun"}, |
| @code{"mips-dec"} |
| @end quotation |
| |
| @item char nodename[] |
| This is the host name of this particular computer. In the GNU C |
| library, the value is the same as that returned by @code{gethostname}; |
| see @ref{Host Identification}. |
| |
| @ gethostname() is implemented with a call to uname(). |
| |
| @item char domainname[] |
| This is the NIS or YP domain name. It is the same value returned by |
| @code{getdomainname}; see @ref{Host Identification}. This element |
| is a relatively recent invention and use of it is not as portable as |
| use of the rest of the structure. |
| |
| @c getdomainname() is implemented with a call to uname(). |
| |
| @end table |
| @end deftp |
| |
| @comment sys/utsname.h |
| @comment POSIX.1 |
| @deftypefun int uname (struct utsname *@var{info}) |
| The @code{uname} function fills in the structure pointed to by |
| @var{info} with information about the operating system and host machine. |
| A non-negative value indicates that the data was successfully stored. |
| |
| @code{-1} as the value indicates an error. The only error possible is |
| @code{EFAULT}, which we normally don't mention as it is always a |
| possibility. |
| @end deftypefun |
| |
| |
| @node Filesystem Handling |
| @section Controlling and 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 |
| |
| @node Mount Information, Mount-Unmount-Remount, , Filesystem Handling |
| @subsection Mount Information |
| |
| 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 |
| uses this file to mount at startup time of the system all the |
| necessary filesystems. The information about all the filesystems |
| actually mounted is normally kept in a file named either |
| @file{/var/run/mtab} or @file{/etc/mtab}. Both files share the same |
| syntax and it is crucial that this syntax is followed all the time. |
| Therefore it is best to never directly write the files. The 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 _PATH_MOUNTED |
| @vindex FSTAB |
| @vindex MNTTAB |
| @vindex MOUNTED |
| The filenames given above should never be used directly. The portable |
| way to handle these file is to use the macro @code{_PATH_FSTAB}, |
| defined in @file{fstab.h}, or @code{_PATH_MNTTAB}, defined in |
| @file{mntent.h} and @file{paths.h}, for @file{fstab}; and the macro |
| @code{_PATH_MOUNTED}, also defined in @file{mntent.h} and |
| @file{paths.h}, for @file{mtab}. There are also two alternate macro |
| names @code{FSTAB}, @code{MNTTAB}, and @code{MOUNTED} defined but |
| these names are deprecated and kept only for backward compatibility. |
| The names @code{_PATH_MNTTAB} and @code{_PATH_MOUNTED} 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 |
| @subsubsection The @file{fstab} file |
| |
| The internal representation for entries of the file is @w{@code{struct |
| fstab}}, defined in @file{fstab.h}. |
| |
| @comment fstab.h |
| @comment BSD |
| @deftp {Data Type} {struct fstab} |
| This structure is used with the @code{getfsent}, @code{getfsspec}, and |
| @code{getfsfile} functions. |
| |
| @table @code |
| @item char *fs_spec |
| This element describes the device from which the filesystem is mounted. |
| Normally this is the name of a special device, such as a hard disk |
| partition, but it could also be a more or less generic string. For |
| @dfn{NFS} it would be a hostname and directory name combination. |
| |
| Even though the element is not declared @code{const} it shouldn't be |
| modified. The missing @code{const} has historic reasons, since this |
| function predates @w{ISO C}. The same is true for the other string |
| elements of this structure. |
| |
| @item char *fs_file |
| This describes the mount point on the local system. I.e., accessing any |
| file in this filesystem has implicitly or explicitly this string as a |
| prefix. |
| |
| @item char *fs_vfstype |
| This is the type of the filesystem. Depending on what the underlying |
| kernel understands it can be any string. |
| |
| @item char *fs_mntops |
| This is a string containing options passed to the kernel with the |
| @code{mount} call. Again, this can be almost anything. There can be |
| more than one option, separated from the others by a comma. Each option |
| consists of a name and an optional value part, introduced by an @code{=} |
| character. |
| |
| If the value of this element must be processed it should ideally be done |
| using the @code{getsubopt} function; see @ref{Suboptions}. |
| |
| @item const char *fs_type |
| This name is poorly chosen. This element points to a string (possibly |
| in the @code{fs_mntops} string) which describes the modes with which the |
| filesystem is mounted. @file{fstab} defines five macros to describe the |
| possible values: |
| |
| @vtable @code |
| @item FSTAB_RW |
| The filesystems gets mounted with read and write enabled. |
| @item FSTAB_RQ |
| The filesystems gets mounted with read and write enabled. Write access |
| is restricted by quotas. |
| @item FSTAB_RO |
| The filesystem gets mounted read-only. |
| @item FSTAB_SW |
| This is not a real filesystem, it is a swap device. |
| @item FSTAB_XX |
| This entry from the @file{fstab} file is totally ignored. |
| @end vtable |
| |
| Testing for equality with these value must happen using @code{strcmp} |
| since these are all strings. Comparing the pointer will probably always |
| fail. |
| |
| @item int fs_freq |
| This element describes the dump frequency in days. |
| |
| @item int fs_passno |
| This element describes the pass number on parallel dumps. It is closely |
| related to the @code{dump} utility used on Unix systems. |
| @end table |
| @end deftp |
| |
| |
| To read the entire content of the of the @file{fstab} file the GNU libc |
| contains a set of three functions which are designed in the usual way. |
| |
| @comment fstab.h |
| @comment BSD |
| @deftypefun int setfsent (void) |
| This function makes sure that the internal read pointer for the |
| @file{fstab} file is at the beginning of the file. This is done by |
| either opening the file or resetting the read pointer. |
| |
| Since the file handle is internal to the libc this function is not |
| thread-safe. |
| |
| This function returns a non-zero value if the operation was successful |
| and the @code{getfs*} functions can be used to read the entries of the |
| file. |
| @end deftypefun |
| |
| @comment fstab.h |
| @comment BSD |
| @deftypefun void endfsent (void) |
| This function makes sure that all resources acquired by a prior call to |
| @code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are |
| freed. |
| @end deftypefun |
| |
| @comment fstab.h |
| @comment BSD |
| @deftypefun {struct fstab *} getfsent (void) |
| This function returns the next entry of the @file{fstab} file. If this |
| is the first call to any of the functions handling @file{fstab} since |
| program start or the last call of @code{endfsent}, the file will be |
| opened. |
| |
| The function returns a pointer to a variable of type @code{struct |
| fstab}. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred @code{getfsent} |
| returns a @code{NULL} pointer. |
| @end deftypefun |
| |
| @comment fstab.h |
| @comment BSD |
| @deftypefun {struct fstab *} getfsspec (const char *@var{name}) |
| This function returns the next entry of the @file{fstab} file which has |
| a string equal to @var{name} pointed to by the @code{fs_spec} element. |
| Since there is normally exactly one entry for each special device it |
| makes no sense to call this function more than once for the same |
| argument. If this is the first call to any of the functions handling |
| @file{fstab} since program start or the last call of @code{endfsent}, |
| the file will be opened. |
| |
| The function returns a pointer to a variable of type @code{struct |
| fstab}. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred @code{getfsent} |
| returns a @code{NULL} pointer. |
| @end deftypefun |
| |
| @comment fstab.h |
| @comment BSD |
| @deftypefun {struct fstab *} getfsfile (const char *@var{name}) |
| This function returns the next entry of the @file{fstab} file which has |
| a string equal to @var{name} pointed to by the @code{fs_file} element. |
| Since there is normally exactly one entry for each mount point it |
| makes no sense to call this function more than once for the same |
| argument. If this is the first call to any of the functions handling |
| @file{fstab} since program start or the last call of @code{endfsent}, |
| the file will be opened. |
| |
| The function returns a pointer to a variable of type @code{struct |
| fstab}. This variable is shared by all threads and therefore this |
| function is not thread-safe. If an error occurred @code{getfsent} |
| returns a @code{NULL} pointer. |
| @end deftypefun |
| |
| |
| @node mtab |
| @subsubsection The @file{mtab} file |
| The following functions and data structure access the @file{mtab} file. |
| |
| @comment mntent.h |
| @comment BSD |
| @deftp {Data Type} {struct mntent} |
| This structure is used with the @code{getmntent}, @code{getmntent_t}, |
| @code{addmntent}, and @code{hasmntopt} functions. |
| |
| @table @code |
| @item char *mnt_fsname |
| This element contains a pointer to a string describing the name of the |
| special device from which the filesystem is mounted. It corresponds to |
| the @code{fs_spec} element in @code{struct fstab}. |
| |
| @item char *mnt_dir |
| This element points to a string describing the mount point of the |
| filesystem. It corresponds to the @code{fs_file} element in |
| @code{struct fstab}. |
| |
| @item char *mnt_type |
| @code{mnt_type} describes the filesystem type and is therefore |
| equivalent to @code{fs_vfstype} in @code{struct fstab}. @file{mntent.h} |
| defines a few symbolic names for some of the values this string can have. |
| But since the kernel can support arbitrary filesystems it does not |
| make much sense to give them symbolic names. If one knows the symbol |
| name one also knows the filesystem name. Nevertheless here follows the |
| list of the symbols provided in @file{mntent.h}. |
| |
| @vtable @code |
| @item MNTTYPE_IGNORE |
| This symbol expands to @code{"ignore"}. The value is sometime used in |
| @file{fstab} files to make sure entries are not used without removing them. |
| @item MNTTYPE_NFS |
| Expands to @code{"nfs"}. Using this macro sometimes could make sense |
| since it names the default NFS implementation, in case both version 2 |
| and 3 are supported. |
| @item MNTTYPE_SWAP |
| This symbol expands to @code{"swap"}. It names the special @file{fstab} |
| entry which names one of the possibly multiple swap partitions. |
| @end vtable |
| |
| @item char *mnt_opts |
| The element contains a string describing the options used while mounting |
| the filesystem. As for the equivalent element @code{fs_mntops} of |
| @code{struct fstab} it is best to use the function @code{getsubopt} |
| (@pxref{Suboptions}) to access the parts of this string. |
| |
| The @file{mntent.h} file defines a number of macros with string values |
| which correspond to some of the options understood by the kernel. There |
| might be many more options which are possible so it doesn't make much sense |
| to rely on these macros but to be consistent here is the list: |
| |
| @vtable @code |
| @item MNTOPT_DEFAULTS |
| Expands to @code{"defaults"}. This option should be used alone since it |
| indicates all values for the customizable values are chosen to be the |
| default. |
| @item MNTOPT_RO |
| Expands to @code{"ro"}. See the @code{FSTAB_RO} value, it means the |
| filesystem is mounted read-only. |
| @item MNTOPT_RW |
| Expand to @code{"rw"}. See the @code{FSTAB_RW} value, it means the |
| filesystem is mounted with read and write permissions. |
| @item MNTOPT_SUID |
| Expands to @code{"suid"}. This means that the SUID bit (@pxref{How |
| Change Persona}) is respected when a program from the filesystem is |
| started. |
| @item MNTOPT_NOSUID |
| Expands to @code{"nosuid"}. This is the opposite of @code{MNTOPT_SUID}, |
| the SUID bit for all files from the filesystem is ignored. |
| @item MNTOPT_NOAUTO |
| Expands to @code{"noauto"}. At startup time the @code{mount} program |
| will ignore this entry if it is started with the @code{-a} option to |
| mount all filesystems mentioned in the @file{fstab} file. |
| @end vtable |
| |
| As for the @code{FSTAB_*} entries introduced above it is important to |
| use @code{strcmp} to check for equality. |
| |
| @item mnt_freq |
| This elements corresponds to @code{fs_freq} and also specifies the |
| frequency in days in which dumps are made. |
| |
| @item mnt_passno |
| This element is equivalent to @code{fs_passno} with the same meaning |
| which is uninteresting for all programs beside @code{dump}. |
| @end table |
| @end deftp |
| |
| For accessing the @file{mtab} file there is again a set of three |
| functions to access all entries in a row. Unlike the functions to |
| handle @file{fstab} these functions do not access a fixed file and there |
| is even a thread safe variant of the get function. Beside this the GNU |
| libc contains functions to alter the file and test for specific options. |
| |
| @comment mntent.h |
| @comment BSD |
| @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode}) |
| The @code{setmntent} function prepares the file named @var{FILE} which |
| must be in the format of a @file{fstab} and @file{mtab} file for the |
| upcoming processing through the other functions of the family. The |
| @var{mode} parameter can be chosen in the way the @var{opentype} |
| parameter for @code{fopen} (@pxref{Opening Streams}) can be chosen. If |
| the file is opened for writing the file is also allowed to be empty. |
| |
| If the file was successfully opened @code{setmntent} returns a file |
| descriptor for future use. Otherwise the return value is @code{NULL} |
| and @code{errno} is set accordingly. |
| @end deftypefun |
| |
| @comment mntent.h |
| @comment BSD |
| @deftypefun int endmntent (FILE *@var{stream}) |
| This function takes for the @var{stream} parameter a file handle which |
| previously was returned from the @code{setmntent} call. |
| @code{endmntent} closes the stream and frees all resources. |
| |
| The return value is @math{1} unless an error occurred in which case it |
| is @math{0}. |
| @end deftypefun |
| |
| @comment mntent.h |
| @comment BSD |
| @deftypefun {struct mntent *} getmntent (FILE *@var{stream}) |
| The @code{getmntent} function takes as the parameter a file handle |
| previously returned by successful call to @code{setmntent}. It returns |
| a pointer to a static variable of type @code{struct mntent} which is |
| filled with the information from the next entry from the file currently |
| read. |
| |
| The file format used prescribes the use of spaces or tab characters to |
| separate the fields. This makes it harder to use name containing one |
| of these characters (e.g., mount points using spaces). Therefore |
| these characters are encoded in the files and the @code{getmntent} |
| function takes care of the decoding while reading the entries back in. |
| @code{'\040'} is used to encode a space character, @code{'\011'} to |
| encode a tab character, @code{'\012'} to encode a newline character, |
| and @code{'\\'} to encode a backslash. |
| |
| If there was an error or the end of the file is reached the return value |
| is @code{NULL}. |
| |
| This function is not thread-safe since all calls to this function return |
| a pointer to the same static variable. @code{getmntent_r} should be |
| used in situations where multiple threads access the file. |
| @end deftypefun |
| |
| @comment mntent.h |
| @comment BSD |
| @deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mentent *@var{result}, char *@var{buffer}, int @var{bufsize}) |
| The @code{getmntent_r} function is the reentrant variant of |
| @code{getmntent}. It also returns the next entry from the file and |
| returns a pointer. The actual variable the values are stored in is not |
| static, though. Instead the function stores the values in the variable |
| pointed to by the @var{result} parameter. Additional information (e.g., |
| the strings pointed to by the elements of the result) are kept in the |
| buffer of size @var{bufsize} pointed to by @var{buffer}. |
| |
| Escaped characters (space, tab, backslash) are converted back in the |
| same way as it happens for @code{getmentent}. |
| |
| The function returns a @code{NULL} pointer in error cases. Errors could be: |
| @itemize @bullet |
| @item |
| error while reading the file, |
| @item |
| end of file reached, |
| @item |
| @var{bufsize} is too small for reading a complete new entry. |
| @end itemize |
| @end deftypefun |
| |
| @comment mntent.h |
| @comment BSD |
| @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt}) |
| The @code{addmntent} function allows adding a new entry to the file |
| previously opened with @code{setmntent}. The new entries are always |
| appended. I.e., even if the position of the file descriptor is not at |
| the end of the file this function does not overwrite an existing entry |
| following the current position. |
| |
| The implication of this is that to remove an entry from a file one has |
| to create a new file while leaving out the entry to be removed and after |
| closing the file remove the old one and rename the new file to the |
| chosen name. |
| |
| This function takes care of spaces and tab characters in the names to be |
| written to the file. It converts them and the backslash character into |
| the format describe in the @code{getmntent} description above. |
| |
| This function returns @math{0} in case the operation was successful. |
| Otherwise the return value is @math{1} and @code{errno} is set |
| appropriately. |
| @end deftypefun |
| |
| @comment mntent.h |
| @comment BSD |
| @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt}) |
| This function can be used to check whether the string pointed to by the |
| @code{mnt_opts} element of the variable pointed to by @var{mnt} contains |
| the option @var{opt}. If this is true a pointer to the beginning of the |
| option in the @code{mnt_opts} element is returned. If no such option |
| exists the function returns @code{NULL}. |
| |
| 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 |
| @subsubsection 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 |
| @subsection Mount, Unmount, Remount |
| |
| 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 |
| @comment SVID, BSD |
| @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 unnaturally 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 is 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 its 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 @bullet |
| |
| @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 @bullet |
| |
| @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 EACCES |
| @itemize @bullet |
| |
| @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 |
| @comment GNU |
| @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 |
| |
| This function is not available on all systems. |
| @end deftypefun |
| |
| @comment sys/mount.h |
| @comment SVID, GNU |
| @deftypefun {int} umount (const char *@var{file}) |
| |
| @code{umount} does the same thing as @code{umount2} with @var{flags} set |
| to zeroes. It is more widely available than @code{umount2} but since it |
| lacks the possibility to forcefully unmount a filesystem is deprecated |
| when @code{umount2} is also available. |
| @end deftypefun |
| |
| |
| |
| @node System Parameters |
| @section System Parameters |
| |
| This section describes the @code{sysctl} function, which gets and sets |
| a variety of system parameters. |
| |
| The symbols used in this section are declared in the file @file{sysctl.h}. |
| |
| @comment sysctl.h |
| @comment BSD |
| @deftypefun int sysctl (int *@var{names}, int @var{nlen}, void *@var{oldval}, size_t *@var{oldlenp}, void *@var{newval}, size_t @var{newlen}) |
| |
| @code{sysctl} gets or sets a specified system parameter. There are so |
| many of these parameters that it is not practical to list them all here, |
| but here are some examples: |
| |
| @itemize @bullet |
| @item network domain name |
| @item paging parameters |
| @item network Address Resolution Protocol timeout time |
| @item maximum number of files that may be open |
| @item root filesystem device |
| @item when kernel was built |
| @end itemize |
| |
| The set of available parameters depends on the kernel configuration and |
| can change while the system is running, particularly when you load and |
| unload loadable kernel modules. |
| |
| The system parameters with which @code{syslog} is concerned are arranged |
| in a hierarchical structure like a hierarchical filesystem. To identify |
| a particular parameter, you specify a path through the structure in a |
| way analogous to specifying the pathname of a file. Each component of |
| the path is specified by an integer and each of these integers has a |
| macro defined for it by @file{sysctl.h}. @var{names} is the path, in |
| the form of an array of integers. Each component of the path is one |
| element of the array, in order. @var{nlen} is the number of components |
| in the path. |
| |
| For example, the first component of the path for all the paging |
| parameters is the value @code{CTL_VM}. For the free page thresholds, the |
| second component of the path is @code{VM_FREEPG}. So to get the free |
| page threshold values, make @var{names} an array containing the two |
| elements @code{CTL_VM} and @code{VM_FREEPG} and make @var{nlen} = 2. |
| |
| |
| The format of the value of a parameter depends on the parameter. |
| Sometimes it is an integer; sometimes it is an ASCII string; sometimes |
| it is an elaborate structure. In the case of the free page thresholds |
| used in the example above, the parameter value is a structure containing |
| several integers. |
| |
| In any case, you identify a place to return the parameter's value with |
| @var{oldval} and specify the amount of storage available at that |
| location as *@var{oldlenp}. *@var{oldlenp} does double duty because it |
| is also the output location that contains the actual length of the |
| returned value. |
| |
| If you don't want the parameter value returned, specify a null pointer |
| for @var{oldval}. |
| |
| To set the parameter, specify the address and length of the new value |
| as @var{newval} and @var{newlen}. If you don't want to set the parameter, |
| specify a null pointer as @var{newval}. |
| |
| If you get and set a parameter in the same @code{sysctl} call, the value |
| returned is the value of the parameter before it was set. |
| |
| Each system parameter has a set of permissions similar to the |
| permissions for a file (including the permissions on directories in its |
| path) that determine whether you may get or set it. For the purposes of |
| these permissions, every parameter is considered to be owned by the |
| superuser and Group 0 so processes with that effective uid or gid may |
| have more access to system parameters. Unlike with files, the superuser |
| does not invariably have full permission to all system parameters, because |
| some of them are designed not to be changed ever. |
| |
| |
| @code{sysctl} returns a zero return value if it succeeds. Otherwise, it |
| returns @code{-1} and sets @code{errno} appropriately. Besides the |
| failures that apply to all system calls, the following are the |
| @code{errno} codes for all possible failures: |
| |
| @table @code |
| @item EPERM |
| The process is not permitted to access one of the components of the |
| path of the system parameter or is not permitted to access the system parameter |
| itself in the way (read or write) that it requested. |
| @c There is some indication in the Linux 2.2 code that the code is trying to |
| @c return EACCES here, but the EACCES value never actually makes it to the |
| @c user. |
| @item ENOTDIR |
| There is no system parameter corresponding to @var{name}. |
| @item EFAULT |
| @var{oldval} is not null, which means the process wanted to read the parameter, |
| but *@var{oldlenp} is zero, so there is no place to return it. |
| @item EINVAL |
| @itemize @bullet |
| @item |
| The process attempted to set a system parameter to a value that is not valid |
| for that parameter. |
| @item |
| The space provided for the return of the system parameter is not the right |
| size for that parameter. |
| @end itemize |
| @item ENOMEM |
| This value may be returned instead of the more correct @code{EINVAL} in some |
| cases where the space provided for the return of the system parameter is too |
| small. |
| |
| @end table |
| |
| @end deftypefun |
| |
| If you have a Linux kernel with the @code{proc} filesystem, you can get |
| and set most of the same parameters by reading and writing to files in |
| the @code{sys} directory of the @code{proc} filesystem. In the @code{sys} |
| directory, the directory structure represents the hierarchical structure |
| of the parameters. E.g. you can display the free page thresholds with |
| @smallexample |
| cat /proc/sys/vm/freepages |
| @end smallexample |
| @c In Linux, the sysctl() and /proc instances of the parameter are created |
| @c together. The proc filesystem accesses the same data structure as |
| @c sysctl(), which has special fields in it for /proc. But it is still |
| @c possible to create a sysctl-only parameter. |
| |
| Some more traditional and more widely available, though less general, |
| GNU C library functions for getting and setting some of the same system |
| parameters are: |
| |
| @itemize @bullet |
| @item |
| @code{getdomainname}, @code{setdomainname} |
| @item |
| @code{gethostname}, @code{sethostname} (@xref{Host Identification}.) |
| @item |
| @code{uname} (@xref{Platform Type}.) |
| @item |
| @code{bdflush} |
| @end itemize |