1: @node System Management, System Configuration, Users and Groups, Top
    2: @c %MENU% Controlling the system and getting information about it
    3: @chapter System Management
    4: 
    5: This chapter describes facilities for controlling the system that
    6: underlies a process (including the operating system and hardware) and
    7: for getting information about it.  Anyone can generally use the
    8: informational facilities, but usually only a properly privileged process
    9: can make changes.
   10: 
   11: 
   12: @menu
   13: * Host Identification::         Determining the name of the machine.
   14: * Platform Type::               Determining operating system and basic
   15:                                   machine type
   16: * Filesystem Handling::         Controlling/querying mounts
   17: * System Parameters::           Getting and setting various system parameters
   18: @end menu
   19: 
   20: To get information on parameters of the system that are built into the
   21: system, such as the maximum length of a filename, @ref{System
   22: Configuration}.
   23: 
   24: @node Host Identification
   25: @section Host Identification
   26: 
   27: This section explains how to identify the particular system on which your
   28: program is running.  First, let's review the various ways computer systems
   29: are named, which is a little complicated because of the history of the
   30: development of the Internet.
   31: 
   32: Every Unix system (also known as a host) has a host name, whether it's
   33: connected to a network or not.  In its simplest form, as used before
   34: computer networks were an issue, it's just a word like @samp{chicken}.
   35: @cindex host name
   36: 
   37: But any system attached to the Internet or any network like it conforms
   38: to a more rigorous naming convention as part of the Domain Name System
   39: (DNS).  In DNS, every host name is composed of two parts:
   40: @cindex DNS
   41: @cindex Domain Name System
   42: 
   43: @enumerate
   44: @item
   45: hostname
   46: @cindex hostname
   47: @item
   48: domain name
   49: @cindex domain name
   50: @end enumerate
   51: 
   52: You will note that ``hostname'' looks a lot like ``host name'', but is
   53: not the same thing, and that people often incorrectly refer to entire
   54: host names as ``domain names.''
   55: 
   56: In DNS, the full host name is properly called the FQDN (Fully Qualified
   57: Domain Name) and consists of the hostname, then a period, then the
   58: domain name.  The domain name itself usually has multiple components
   59: separated by periods.  So for example, a system's hostname may be
   60: @samp{chicken} and its domain name might be @samp{ai.mit.edu}, so
   61: its FQDN (which is its host name) is @samp{chicken.ai.mit.edu}.
   62: @cindex FQDN
   63: 
   64: Adding to the confusion, though, is that DNS is not the only name space
   65: in which a computer needs to be known.  Another name space is the
   66: NIS (aka YP) name space.  For NIS purposes, there is another domain
   67: name, which is called the NIS domain name or the YP domain name.  It
   68: need not have anything to do with the DNS domain name.
   69: @cindex YP
   70: @cindex NIS
   71: @cindex NIS domain name
   72: @cindex YP domain name
   73: 
   74: Confusing things even more is the fact that in DNS, it is possible for
   75: multiple FQDNs to refer to the same system.  However, there is always
   76: exactly one of them that is the true host name, and it is called the
   77: canonical FQDN.
   78: 
   79: In some contexts, the host name is called a ``node name.''
   80: 
   81: For more information on DNS host naming, @xref{Host Names}.
   82: 
   83: @pindex hostname
   84: @pindex hostid
   85: @pindex unistd.h
   86: Prototypes for these functions appear in @file{unistd.h}.
   87: 
   88: The programs @code{hostname}, @code{hostid}, and @code{domainname} work
   89: by calling these functions.
   90: 
   91: @comment unistd.h
   92: @comment BSD
   93: @deftypefun int gethostname (char *@var{name}, size_t @var{size})
   94: This function returns the host name of the system on which it is called,
   95: in the array @var{name}.  The @var{size} argument specifies the size of
   96: this array, in bytes.  Note that this is @emph{not} the DNS hostname.
   97: If the system participates in DNS, this is the FQDN (see above).
   98: 
   99: The return value is @code{0} on success and @code{-1} on failure.  In
  100: the GNU C library, @code{gethostname} fails if @var{size} is not large
  101: enough; then you can try again with a larger array.  The following
  102: @code{errno} error condition is defined for this function:
  103: 
  104: @table @code
  105: @item ENAMETOOLONG
  106: The @var{size} argument is less than the size of the host name plus one.
  107: @end table
  108: 
  109: @pindex sys/param.h
  110: On some systems, there is a symbol for the maximum possible host name
  111: length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
  112: But you can't count on this to exist, so it is cleaner to handle
  113: failure and try again.
  114: 
  115: @code{gethostname} stores the beginning of the host name in @var{name}
  116: even if the host name won't entirely fit.  For some purposes, a
  117: truncated host name is good enough.  If it is, you can ignore the
  118: error code.
  119: @end deftypefun
  120: 
  121: @comment unistd.h
  122: @comment BSD
  123: @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
  124: The @code{sethostname} function sets the host name of the system that
  125: calls it to @var{name}, a string with length @var{length}.  Only
  126: privileged processes are permitted to do this.
  127: 
  128: Usually @code{sethostname} gets called just once, at system boot time.
  129: Often, the program that calls it sets it to the value it finds in the
  130: file @code{/etc/hostname}.
  131: @cindex /etc/hostname
  132: 
  133: Be sure to set the host name to the full host name, not just the DNS
  134: hostname (see above).
  135: 
  136: The return value is @code{0} on success and @code{-1} on failure.
  137: The following @code{errno} error condition is defined for this function:
  138: 
  139: @table @code
  140: @item EPERM
  141: This process cannot set the host name because it is not privileged.
  142: @end table
  143: @end deftypefun
  144: 
  145: @comment unistd.h
  146: @comment ???
  147: @deftypefun int getdomainnname (char *@var{name}, size_t @var{length})
  148: @cindex NIS domain name
  149: @cindex YP domain name
  150: 
  151: @code{getdomainname} returns the NIS (aka YP) domain name of the system
  152: on which it is called.  Note that this is not the more popular DNS
  153: domain name.  Get that with @code{gethostname}.
  154: 
  155: The specifics of this function are analogous to @code{gethostname}, above.
  156: 
  157: @end deftypefun
  158: 
  159: @comment unistd.h
  160: @comment ???
  161: @deftypefun int setdomainname (const char *@var{name}, size_t @var{length})
  162: @cindex NIS domain name
  163: @cindex YP domain name
  164: 
  165: @code{getdomainname} sets the NIS (aka YP) domain name of the system
  166: on which it is called.  Note that this is not the more popular DNS
  167: domain name.  Set that with @code{sethostname}.
  168: 
  169: The specifics of this function are analogous to @code{sethostname}, above.
  170: 
  171: @end deftypefun
  172: 
  173: @comment unistd.h
  174: @comment BSD
  175: @deftypefun {long int} gethostid (void)
  176: This function returns the ``host ID'' of the machine the program is
  177: running on.  By convention, this is usually the primary Internet IP address
  178: of that machine, converted to a @w{@code{long int}}.  However, on some
  179: systems it is a meaningless but unique number which is hard-coded for
  180: each machine.
  181: 
  182: This is not widely used.  It arose in BSD 4.2, but was dropped in BSD 4.4.
  183: It is not required by POSIX.
  184: 
  185: The proper way to query the IP address is to use @code{gethostbyname}
  186: on the results of @code{gethostname}.  For more information on IP addresses,
  187: @xref{Host Addresses}.
  188: @end deftypefun
  189: 
  190: @comment unistd.h
  191: @comment BSD
  192: @deftypefun int sethostid (long int @var{id})
  193: The @code{sethostid} function sets the ``host ID'' of the host machine
  194: to @var{id}.  Only privileged processes are permitted to do this.  Usually
  195: it happens just once, at system boot time.
  196: 
  197: The proper way to establish the primary IP address of a system
  198: is to configure the IP address resolver to associate that IP address with
  199: the system's host name as returned by @code{gethostname}.  For example,
  200: put a record for the system in @file{/etc/hosts}.
  201: 
  202: See @code{gethostid} above for more information on host ids.
  203: 
  204: The return value is @code{0} on success and @code{-1} on failure.
  205: The following @code{errno} error conditions are defined for this function:
  206: 
  207: @table @code
  208: @item EPERM
  209: This process cannot set the host name because it is not privileged.
  210: 
  211: @item ENOSYS
  212: The operating system does not support setting the host ID.  On some
  213: systems, the host ID is a meaningless but unique number hard-coded for
  214: each machine.
  215: @end table
  216: @end deftypefun
  217: 
  218: @node Platform Type
  219: @section Platform Type Identification
  220: 
  221: You can use the @code{uname} function to find out some information about
  222: the type of computer your program is running on.  This function and the
  223: associated data type are declared in the header file
  224: @file{sys/utsname.h}.
  225: @pindex sys/utsname.h
  226: 
  227: As a bonus, @code{uname} also gives some information identifying the
  228: particular system your program is running on.  This is the same information
  229: which you can get with functions targetted to this purpose described in
  230: @ref{Host Identification}.
  231: 
  232: 
  233: @comment sys/utsname.h
  234: @comment POSIX.1
  235: @deftp {Data Type} {struct utsname}
  236: The @code{utsname} structure is used to hold information returned
  237: by the @code{uname} function.  It has the following members:
  238: 
  239: @table @code
  240: @item char sysname[]
  241: This is the name of the operating system in use.
  242: 
  243: @item char release[]
  244: This is the current release level of the operating system implementation.
  245: 
  246: @item char version[]
  247: This is the current version level within the release of the operating
  248: system.
  249: 
  250: @item char machine[]
  251: This is a description of the type of hardware that is in use.
  252: 
  253: Some systems provide a mechanism to interrogate the kernel directly for
  254: this information.  On systems without such a mechanism, the GNU C
  255: library fills in this field based on the configuration name that was
  256: specified when building and installing the library.
  257: 
  258: GNU uses a three-part name to describe a system configuration; the three
  259: parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they
  260: are separated with dashes.  Any possible combination of three names is
  261: potentially meaningful, but most such combinations are meaningless in
  262: practice and even the meaningful ones are not necessarily supported by
  263: any particular GNU program.
  264: 
  265: Since the value in @code{machine} is supposed to describe just the
  266: hardware, it consists of the first two parts of the configuration name:
  267: @samp{@var{cpu}-@var{manufacturer}}.  For example, it might be one of these:
  268: 
  269: @quotation
  270: @code{"sparc-sun"},
  271: @code{"i386-@var{anything}"},
  272: @code{"m68k-hp"},
  273: @code{"m68k-sony"},
  274: @code{"m68k-sun"},
  275: @code{"mips-dec"}
  276: @end quotation
  277: 
  278: @item char nodename[]
  279: This is the host name of this particular computer.  In the GNU C
  280: library, the value is the same as that returned by @code{gethostname};
  281: see @ref{Host Identification}.
  282: 
  283: @ gethostname() is implemented with a call to uname().
  284: 
  285: @item char domainname[]
  286: This is the NIS or YP domain name.  It is the same value returned by
  287: @code{getdomainname}; see @ref{Host Identification}.  This element
  288: is a relatively recent invention and use of it is not as portable as
  289: use of the rest of the structure.
  290: 
  291: @c getdomainname() is implemented with a call to uname().
  292: 
  293: @end table
  294: @end deftp
  295: 
  296: @comment sys/utsname.h
  297: @comment POSIX.1
  298: @deftypefun int uname (struct utsname *@var{info})
  299: The @code{uname} function fills in the structure pointed to by
  300: @var{info} with information about the operating system and host machine.
  301: A non-negative value indicates that the data was successfully stored.
  302: 
  303: @code{-1} as the value indicates an error.  The only error possible is
  304: @code{EFAULT}, which we normally don't mention as it is always a
  305: possibility.
  306: @end deftypefun
  307: 
  308: 
  309: @node Filesystem Handling
  310: @section Controlling and Querying Mounts
  311: 
  312: All files are in filesystems, and before you can access any file, its
  313: filesystem must be mounted.  Because of Unix's concept of
  314: @emph{Everything is a file}, mounting of filesystems is central to doing
  315: almost anything.  This section explains how to find out what filesystems
  316: are currently mounted and what filesystems are available for mounting,
  317: and how to change what is mounted.
  318: 
  319: The classic filesystem is the contents of a disk drive.  The concept is
  320: considerably more abstract, though, and lots of things other than disk
  321: drives can be mounted.
  322: 
  323: Some block devices don't correspond to traditional devices like disk
  324: drives.  For example, a loop device is a block device whose driver uses
  325: a regular file in another filesystem as its medium.  So if that regular
  326: file contains appropriate data for a filesystem, you can by mounting the
  327: loop device essentially mount a regular file.
  328: 
  329: Some filesystems aren't based on a device of any kind.  The ``proc''
  330: filesystem, for example, contains files whose data is made up by the
  331: filesystem driver on the fly whenever you ask for it.  And when you
  332: write to it, the data you write causes changes in the system.  No data
  333: gets stored.
  334: 
  335: @c It would be good to mention NFS mounts here.
  336: 
  337: @menu
  338: * Mount Information::           What is or could be mounted?
  339: * Mount-Unmount-Remount::       Controlling what is mounted and how
  340: @end menu
  341: 
  342: @node Mount Information, Mount-Unmount-Remount, , Filesystem Handling
  343: @subsection Mount Information
  344: 
  345: For some programs it is desirable and necessary to access information
  346: about whether a certain filesystem is mounted and, if it is, where, or
  347: simply to get lists of all the available filesystems.  The GNU libc
  348: provides some functions to retrieve this information portably.
  349: 
  350: Traditionally Unix systems have a file named @file{/etc/fstab} which
  351: describes all possibly mounted filesystems.  The @code{mount} program
  352: uses this file to mount at startup time of the system all the
  353: necessary filesystems.  The information about all the filesystems
  354: actually mounted is normally kept in a file named either
  355: @file{/var/run/mtab} or @file{/etc/mtab}.  Both files share the same
  356: syntax and it is crucial that this syntax is followed all the time.
  357: Therefore it is best to never directly write the files.  The functions
  358: described in this section can do this and they also provide the
  359: functionality to convert the external textual representation to the
  360: internal representation.
  361: 
  362: Note that the @file{fstab} and @file{mtab} files are maintained on a
  363: system by @emph{convention}.  It is possible for the files not to exist
  364: or not to be consistent with what is really mounted or available to
  365: mount, if the system's administration policy allows it.  But programs
  366: that mount and unmount filesystems typically maintain and use these
  367: files as described herein.
  368: 
  369: @vindex _PATH_FSTAB
  370: @vindex _PATH_MNTTAB
  371: @vindex _PATH_MOUNTED
  372: @vindex FSTAB
  373: @vindex MNTTAB
  374: @vindex MOUNTED
  375: The filenames given above should never be used directly.  The portable
  376: way to handle these file is to use the macro @code{_PATH_FSTAB},
  377: defined in @file{fstab.h}, or @code{_PATH_MNTTAB}, defined in
  378: @file{mntent.h} and @file{paths.h}, for @file{fstab}; and the macro
  379: @code{_PATH_MOUNTED}, also defined in @file{mntent.h} and
  380: @file{paths.h}, for @file{mtab}.  There are also two alternate macro
  381: names @code{FSTAB}, @code{MNTTAB}, and @code{MOUNTED} defined but
  382: these names are deprecated and kept only for backward compatibility.
  383: The names @code{_PATH_MNTTAB} and @code{_PATH_MOUNTED} should always be used.
  384: 
  385: @menu
  386: * fstab::                       The @file{fstab} file
  387: * mtab::                        The @file{mtab} file
  388: * Other Mount Information::     Other (non-libc) sources of mount information
  389: @end menu
  390: 
  391: @node fstab
  392: @subsubsection The @file{fstab} file
  393: 
  394: The internal representation for entries of the file is @w{@code{struct
  395: fstab}}, defined in @file{fstab.h}.
  396: 
  397: @comment fstab.h
  398: @comment BSD
  399: @deftp {Data Type} {struct fstab}
  400: This structure is used with the @code{getfsent}, @code{getfsspec}, and
  401: @code{getfsfile} functions.
  402: 
  403: @table @code
  404: @item char *fs_spec
  405: This element describes the device from which the filesystem is mounted.
  406: Normally this is the name of a special device, such as a hard disk
  407: partition, but it could also be a more or less generic string.  For
  408: @dfn{NFS} it would be a hostname and directory name combination.
  409: 
  410: Even though the element is not declared @code{const} it shouldn't be
  411: modified.  The missing @code{const} has historic reasons, since this
  412: function predates @w{ISO C}.  The same is true for the other string
  413: elements of this structure.
  414: 
  415: @item char *fs_file
  416: This describes the mount point on the local system.  I.e., accessing any
  417: file in this filesystem has implicitly or explicitly this string as a
  418: prefix.
  419: 
  420: @item char *fs_vfstype
  421: This is the type of the filesystem.  Depending on what the underlying
  422: kernel understands it can be any string.
  423: 
  424: @item char *fs_mntops
  425: This is a string containing options passed to the kernel with the
  426: @code{mount} call.  Again, this can be almost anything.  There can be
  427: more than one option, separated from the others by a comma.  Each option
  428: consists of a name and an optional value part, introduced by an @code{=}
  429: character.
  430: 
  431: If the value of this element must be processed it should ideally be done
  432: using the @code{getsubopt} function; see @ref{Suboptions}.
  433: 
  434: @item const char *fs_type
  435: This name is poorly chosen.  This element points to a string (possibly
  436: in the @code{fs_mntops} string) which describes the modes with which the
  437: filesystem is mounted.  @file{fstab} defines five macros to describe the
  438: possible values:
  439: 
  440: @vtable @code
  441: @item FSTAB_RW
  442: The filesystems gets mounted with read and write enabled.
  443: @item FSTAB_RQ
  444: The filesystems gets mounted with read and write enabled.  Write access
  445: is restricted by quotas.
  446: @item FSTAB_RO
  447: The filesystem gets mounted read-only.
  448: @item FSTAB_SW
  449: This is not a real filesystem, it is a swap device.
  450: @item FSTAB_XX
  451: This entry from the @file{fstab} file is totally ignored.
  452: @end vtable
  453: 
  454: Testing for equality with these value must happen using @code{strcmp}
  455: since these are all strings.  Comparing the pointer will probably always
  456: fail.
  457: 
  458: @item int fs_freq
  459: This element describes the dump frequency in days.
  460: 
  461: @item int fs_passno
  462: This element describes the pass number on parallel dumps.  It is closely
  463: related to the @code{dump} utility used on Unix systems.
  464: @end table
  465: @end deftp
  466: 
  467: 
  468: To read the entire content of the of the @file{fstab} file the GNU libc
  469: contains a set of three functions which are designed in the usual way.
  470: 
  471: @comment fstab.h
  472: @comment BSD
  473: @deftypefun int setfsent (void)
  474: This function makes sure that the internal read pointer for the
  475: @file{fstab} file is at the beginning of the file.  This is done by
  476: either opening the file or resetting the read pointer.
  477: 
  478: Since the file handle is internal to the libc this function is not
  479: thread-safe.
  480: 
  481: This function returns a non-zero value if the operation was successful
  482: and the @code{getfs*} functions can be used to read the entries of the
  483: file.
  484: @end deftypefun
  485: 
  486: @comment fstab.h
  487: @comment BSD
  488: @deftypefun void endfsent (void)
  489: This function makes sure that all resources acquired by a prior call to
  490: @code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are
  491: freed.
  492: @end deftypefun
  493: 
  494: @comment fstab.h
  495: @comment BSD
  496: @deftypefun {struct fstab *} getfsent (void)
  497: This function returns the next entry of the @file{fstab} file.  If this
  498: is the first call to any of the functions handling @file{fstab} since
  499: program start or the last call of @code{endfsent}, the file will be
  500: opened.
  501: 
  502: The function returns a pointer to a variable of type @code{struct
  503: fstab}.  This variable is shared by all threads and therefore this
  504: function is not thread-safe.  If an error occurred @code{getfsent}
  505: returns a @code{NULL} pointer.
  506: @end deftypefun
  507: 
  508: @comment fstab.h
  509: @comment BSD
  510: @deftypefun {struct fstab *} getfsspec (const char *@var{name})
  511: This function returns the next entry of the @file{fstab} file which has
  512: a string equal to @var{name} pointed to by the @code{fs_spec} element.
  513: Since there is normally exactly one entry for each special device it
  514: makes no sense to call this function more than once for the same
  515: argument.  If this is the first call to any of the functions handling
  516: @file{fstab} since program start or the last call of @code{endfsent},
  517: the file will be opened.
  518: 
  519: The function returns a pointer to a variable of type @code{struct
  520: fstab}.  This variable is shared by all threads and therefore this
  521: function is not thread-safe.  If an error occurred @code{getfsent}
  522: returns a @code{NULL} pointer.
  523: @end deftypefun
  524: 
  525: @comment fstab.h
  526: @comment BSD
  527: @deftypefun {struct fstab *} getfsfile (const char *@var{name})
  528: This function returns the next entry of the @file{fstab} file which has
  529: a string equal to @var{name} pointed to by the @code{fs_file} element.
  530: Since there is normally exactly one entry for each mount point it
  531: makes no sense to call this function more than once for the same
  532: argument.  If this is the first call to any of the functions handling
  533: @file{fstab} since program start or the last call of @code{endfsent},
  534: the file will be opened.
  535: 
  536: The function returns a pointer to a variable of type @code{struct
  537: fstab}.  This variable is shared by all threads and therefore this
  538: function is not thread-safe.  If an error occurred @code{getfsent}
  539: returns a @code{NULL} pointer.
  540: @end deftypefun
  541: 
  542: 
  543: @node mtab
  544: @subsubsection The @file{mtab} file
  545: The following functions and data structure access the @file{mtab} file.
  546: 
  547: @comment mntent.h
  548: @comment BSD
  549: @deftp {Data Type} {struct mntent}
  550: This structure is used with the @code{getmntent}, @code{getmntent_t},
  551: @code{addmntent}, and @code{hasmntopt} functions.
  552: 
  553: @table @code
  554: @item char *mnt_fsname
  555: This element contains a pointer to a string describing the name of the
  556: special device from which the filesystem is mounted.  It corresponds to
  557: the @code{fs_spec} element in @code{struct fstab}.
  558: 
  559: @item char *mnt_dir
  560: This element points to a string describing the mount point of the
  561: filesystem.  It corresponds to the @code{fs_file} element in
  562: @code{struct fstab}.
  563: 
  564: @item char *mnt_type
  565: @code{mnt_type} describes the filesystem type and is therefore
  566: equivalent to @code{fs_vfstype} in @code{struct fstab}.  @file{mntent.h}
  567: defines a few symbolic names for some of the values this string can have.
  568: But since the kernel can support arbitrary filesystems it does not
  569: make much sense to give them symbolic names.  If one knows the symbol
  570: name one also knows the filesystem name.  Nevertheless here follows the
  571: list of the symbols provided in @file{mntent.h}.
  572: 
  573: @vtable @code
  574: @item MNTTYPE_IGNORE
  575: This symbol expands to @code{"ignore"}.  The value is sometime used in
  576: @file{fstab} files to make sure entries are not used without removing them.
  577: @item MNTTYPE_NFS
  578: Expands to @code{"nfs"}.  Using this macro sometimes could make sense
  579: since it names the default NFS implementation, in case both version 2
  580: and 3 are supported.
  581: @item MNTTYPE_SWAP
  582: This symbol expands to @code{"swap"}.  It names the special @file{fstab}
  583: entry which names one of the possibly multiple swap partitions.
  584: @end vtable
  585: 
  586: @item char *mnt_opts
  587: The element contains a string describing the options used while mounting
  588: the filesystem.  As for the equivalent element @code{fs_mntops} of
  589: @code{struct fstab} it is best to use the function @code{getsubopt}
  590: (@pxref{Suboptions}) to access the parts of this string.
  591: 
  592: The @file{mntent.h} file defines a number of macros with string values
  593: which correspond to some of the options understood by the kernel.  There
  594: might be many more options which are possible so it doesn't make much sense
  595: to rely on these macros but to be consistent here is the list:
  596: 
  597: @vtable @code
  598: @item MNTOPT_DEFAULTS
  599: Expands to @code{"defaults"}.  This option should be used alone since it
  600: indicates all values for the customizable values are chosen to be the
  601: default.
  602: @item MNTOPT_RO
  603: Expands to @code{"ro"}.  See the @code{FSTAB_RO} value, it means the
  604: filesystem is mounted read-only.
  605: @item MNTOPT_RW
  606: Expand to @code{"rw"}.  See the @code{FSTAB_RW} value, it means the
  607: filesystem is mounted with read and write permissions.
  608: @item MNTOPT_SUID
  609: Expands to @code{"suid"}.  This means that the SUID bit (@pxref{How
  610: Change Persona}) is respected when a program from the filesystem is
  611: started.
  612: @item MNTOPT_NOSUID
  613: Expands to @code{"nosuid"}.  This is the opposite of @code{MNTOPT_SUID},
  614: the SUID bit for all files from the filesystem is ignored.
  615: @item MNTOPT_NOAUTO
  616: Expands to @code{"noauto"}.  At startup time the @code{mount} program
  617: will ignore this entry if it is started with the @code{-a} option to
  618: mount all filesystems mentioned in the @file{fstab} file.
  619: @end vtable
  620: 
  621: As for the @code{FSTAB_*} entries introduced above it is important to
  622: use @code{strcmp} to check for equality.
  623: 
  624: @item mnt_freq
  625: This elements corresponds to @code{fs_freq} and also specifies the
  626: frequency in days in which dumps are made.
  627: 
  628: @item mnt_passno
  629: This element is equivalent to @code{fs_passno} with the same meaning
  630: which is uninteresting for all programs beside @code{dump}.
  631: @end table
  632: @end deftp
  633: 
  634: For accessing the @file{mtab} file there is again a set of three
  635: functions to access all entries in a row.  Unlike the functions to
  636: handle @file{fstab} these functions do not access a fixed file and there
  637: is even a thread safe variant of the get function.  Beside this the GNU
  638: libc contains functions to alter the file and test for specific options.
  639: 
  640: @comment mntent.h
  641: @comment BSD
  642: @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode})
  643: The @code{setmntent} function prepares the file named @var{FILE} which
  644: must be in the format of a @file{fstab} and @file{mtab} file for the
  645: upcoming processing through the other functions of the family.  The
  646: @var{mode} parameter can be chosen in the way the @var{opentype}
  647: parameter for @code{fopen} (@pxref{Opening Streams}) can be chosen.  If
  648: the file is opened for writing the file is also allowed to be empty.
  649: 
  650: If the file was successfully opened @code{setmntent} returns a file
  651: descriptor for future use.  Otherwise the return value is @code{NULL}
  652: and @code{errno} is set accordingly.
  653: @end deftypefun
  654: 
  655: @comment mntent.h
  656: @comment BSD
  657: @deftypefun int endmntent (FILE *@var{stream})
  658: This function takes for the @var{stream} parameter a file handle which
  659: previously was returned from the @code{setmntent} call.
  660: @code{endmntent} closes the stream and frees all resources.
  661: 
  662: The return value is @math{1} unless an error occurred in which case it
  663: is @math{0}.
  664: @end deftypefun
  665: 
  666: @comment mntent.h
  667: @comment BSD
  668: @deftypefun {struct mntent *} getmntent (FILE *@var{stream})
  669: The @code{getmntent} function takes as the parameter a file handle
  670: previously returned by successful call to @code{setmntent}.  It returns
  671: a pointer to a static variable of type @code{struct mntent} which is
  672: filled with the information from the next entry from the file currently
  673: read.
  674: 
  675: The file format used prescribes the use of spaces or tab characters to
  676: separate the fields.  This makes it harder to use name containing one
  677: of these characters (e.g., mount points using spaces).  Therefore
  678: these characters are encoded in the files and the @code{getmntent}
  679: function takes care of the decoding while reading the entries back in.
  680: @code{'\040'} is used to encode a space character, @code{'\011'} to
  681: encode a tab character, @code{'\012'} to encode a newline character,
  682: and @code{'\\'} to encode a backslash.
  683: 
  684: If there was an error or the end of the file is reached the return value
  685: is @code{NULL}.
  686: 
  687: This function is not thread-safe since all calls to this function return
  688: a pointer to the same static variable.  @code{getmntent_r} should be
  689: used in situations where multiple threads access the file.
  690: @end deftypefun
  691: 
  692: @comment mntent.h
  693: @comment BSD
  694: @deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mentent *@var{result}, char *@var{buffer}, int @var{bufsize})
  695: The @code{getmntent_r} function is the reentrant variant of
  696: @code{getmntent}.  It also returns the next entry from the file and
  697: returns a pointer.  The actual variable the values are stored in is not
  698: static, though.  Instead the function stores the values in the variable
  699: pointed to by the @var{result} parameter.  Additional information (e.g.,
  700: the strings pointed to by the elements of the result) are kept in the
  701: buffer of size @var{bufsize} pointed to by @var{buffer}.
  702: 
  703: Escaped characters (space, tab, backslash) are converted back in the
  704: same way as it happens for @code{getmentent}.
  705: 
  706: The function returns a @code{NULL} pointer in error cases.  Errors could be:
  707: @itemize @bullet
  708: @item
  709: error while reading the file,
  710: @item
  711: end of file reached,
  712: @item
  713: @var{bufsize} is too small for reading a complete new entry.
  714: @end itemize
  715: @end deftypefun
  716: 
  717: @comment mntent.h
  718: @comment BSD
  719: @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt})
  720: The @code{addmntent} function allows adding a new entry to the file
  721: previously opened with @code{setmntent}.  The new entries are always
  722: appended.  I.e., even if the position of the file descriptor is not at
  723: the end of the file this function does not overwrite an existing entry
  724: following the current position.
  725: 
  726: The implication of this is that to remove an entry from a file one has
  727: to create a new file while leaving out the entry to be removed and after
  728: closing the file remove the old one and rename the new file to the
  729: chosen name.
  730: 
  731: This function takes care of spaces and tab characters in the names to be
  732: written to the file.  It converts them and the backslash character into
  733: the format describe in the @code{getmntent} description above.
  734: 
  735: This function returns @math{0} in case the operation was successful.
  736: Otherwise the return value is @math{1} and @code{errno} is set
  737: appropriately.
  738: @end deftypefun
  739: 
  740: @comment mntent.h
  741: @comment BSD
  742: @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt})
  743: This function can be used to check whether the string pointed to by the
  744: @code{mnt_opts} element of the variable pointed to by @var{mnt} contains
  745: the option @var{opt}.  If this is true a pointer to the beginning of the
  746: option in the @code{mnt_opts} element is returned.  If no such option
  747: exists the function returns @code{NULL}.
  748: 
  749: This function is useful to test whether a specific optio