diff options
| -rw-r--r-- | ChangeLog | 2 | ||||
| -rw-r--r-- | libc.map | 6 | ||||
| -rw-r--r-- | manual/sysinfo.texi | 384 |
3 files changed, 383 insertions, 9 deletions
diff --git a/ChangeLog b/ChangeLog index 1dc8862d95..c180ac2096 100644 --- a/ChangeLog +++ b/ChangeLog @@ -2,6 +2,8 @@ * libc.map: Don't export argp's fmtstream handling functions. + * manual/sysinfo.h: Document fstab and mtab handling functions. + 1998-06-03 03:09 Geoff Keating <geoffk@ozemail.com.au> * sysdeps/unix/sysv/linux/pread.c: Detect missing syscall, like poll(). diff --git a/libc.map b/libc.map index 3d3f45a4eb..f6c3b657e5 100644 --- a/libc.map +++ b/libc.map @@ -530,12 +530,6 @@ GLIBC_2.1 { argp_error; argp_failure; argp_help; argp_parse; argp_state_help; argp_usage; - # These probably shouldn't be exported, they are internal. - # argp_fmtstream_free; argp_fmtstream_point; argp_fmtstream_printf; - # argp_fmtstream_putc; argp_fmtstream_puts; argp_fmtstream_set_lmargin; - # argp_fmtstream_set_rmargin; argp_fmtstream_set_wmargin; - # argp_fmtstream_write; argp_make_fmtstream; - authdes_create; authdes_getucred; authdes_pk_create; # b* diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi index a30536db6e..cb9b954417 100644 --- a/manual/sysinfo.texi +++ b/manual/sysinfo.texi @@ -9,7 +9,8 @@ software, and the individual machine's name. * 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. + running. +* Filesystem handling:: Which is mounted and/or available? @end menu @@ -157,9 +158,9 @@ 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{"sparc-sun"}, @code{"i386-@var{anything}"}, -@code{"m68k-hp"}, +@code{"m68k-hp"}, @code{"m68k-sony"}, @code{"m68k-sun"}, @code{"mips-dec"} @@ -178,3 +179,380 @@ A non-negative value indicates that the data was successfully stored. @code{EFAULT}, which we normally don't mention as it is always a possibility. @end deftypefun + + +@node Filesystem handling +@section Which filesystems are mounted and/or available? + +The Unix concept of @emph{Everything is a file} is based on the +possibility to @dfn{mount} filesystems or other things into the +filesystem. For some programs it is desirable and necessary to access +the information whether and if yes, where a certain filesystem is +mounted 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 @file{/etc/mtab}. Both files shared +the same synteax 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. + +@vindex _PATH_FSTAB +@vindex _PATH_MNTTAB +@vindex FSTAB +@vindex _PATH_MOUNTED +The filenames given above should never be used directly. The portable +way to handle these file is to use the macros @code{_PATH_FSTAB}, +defined in @file{fsab.h} and @code{_PATH_MNTTAB}, defined in +@file{mntent.h}, respectively. There are also two alternate macro names +@code{FSTAB} and @code{_PATH_MOUNTED} defined but both names are +depricated and kept only for backward compatibility. The two former +names always should be used. + +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 desribes 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 desribes the mount point on the local system. I.e., accessing any +file in this filesystem has implicitly or explicitily 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 best should happen +using the @code{getsubopt} function; see @ref{Suboptions}. + +@item const char *fs_type +This name os 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 get mounted read-only. +@item FSTAB_SW +This is no 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 probably always will +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 actual @code{dump} program 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} (explicit 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 an 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} +return 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 an 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} +return 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 an 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} +return a @code{NULL} pointer. +@end deftypefun + +To access the @file{matb} file there is a different set of functions and +also a different structure to describe the results. + + +@comment fstab.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 value this string can have. +But since the kernel can support an 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 symbol 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 makes not 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 custumizable values are chosen to be the +default. +@item MNTOPT_RO +Expand to @code{"ro"}. See the the @code{FSTAB_RO} value, it means the +filesystem is mounted read-only. +@item MNTOPT_RW +Expand to @code{"rw"}. See the 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 is for all files from the filesystem 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 +even is a thread safe variant of the get-function. Beside this the GNU +libc contains function 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 @code[1} unless an error occurred in which case it +is @code{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. + +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 use 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}. + +The function return in error cases a @code{NULL} pointer. 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 to add 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 +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 returns @code{0} in case the operation was successful. +Otherwise the return value is @code{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 +exist 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 |