man3/getfsent.3

   1 .\" Copyright (C) 2002 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Inspired by a page written by Walter Harms.
   6 .\"
   7 .TH GETFSENT 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   8 .SH NAME
   9 getfsent, getfsspec, getfsfile, setfsent, endfsent \- handle fstab entries
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <fstab.h>
  16 .PP
  17 .B "int setfsent(void);"
  18 .B "struct fstab *getfsent(void);"
  19 .B "void endfsent(void);"
  20 .PP
  21 .BI "struct fstab *getfsfile(const char *" mount_point );
  22 .BI "struct fstab *getfsspec(const char *" special_file );
  23 .fi
  24 .SH DESCRIPTION
  25 These functions read from the file
  26 .IR /etc/fstab .
  27 The
  28 .I struct fstab
  29 is defined by:
  30 .PP
  31 .in +4n
  32 .EX
  33 struct fstab {
  34     char       *fs_spec;       /* block device name */
  35     char       *fs_file;       /* mount point */
  36     char       *fs_vfstype;    /* filesystem type */
  37     char       *fs_mntops;     /* mount options */
  38     const char *fs_type;       /* rw/rq/ro/sw/xx option */
  39     int         fs_freq;       /* dump frequency, in days */
  40     int         fs_passno;     /* pass number on parallel dump */
  41 };
  42 .EE
  43 .in
  44 .PP
  45 Here the field
  46 .I fs_type
  47 contains (on a *BSD system)
  48 one of the five strings "rw", "rq", "ro", "sw", "xx"
  49 (read-write, read-write with quota, read-only, swap, ignore).
  50 .PP
  51 The function
  52 .BR setfsent ()
  53 opens the file when required and positions it at the first line.
  54 .PP
  55 The function
  56 .BR getfsent ()
  57 parses the next line from the file.
  58 (After opening it when required.)
  59 .PP
  60 The function
  61 .BR endfsent ()
  62 closes the file when required.
  63 .PP
  64 The function
  65 .BR getfsspec ()
  66 searches the file from the start and returns the first entry found
  67 for which the
  68 .I fs_spec
  69 field matches the
  70 .I special_file
  71 argument.
  72 .PP
  73 The function
  74 .BR getfsfile ()
  75 searches the file from the start and returns the first entry found
  76 for which the
  77 .I fs_file
  78 field matches the
  79 .I mount_point
  80 argument.
  81 .SH RETURN VALUE
  82 Upon success, the functions
  83 .BR getfsent (),
  84 .BR getfsfile (),
  85 and
  86 .BR getfsspec ()
  87 return a pointer to a
  88 .IR "struct fstab" ,
  89 while
  90 .BR setfsent ()
  91 returns 1.
  92 Upon failure or end-of-file, these functions return NULL and 0, respectively.
  93 .\" .SH HISTORY
  94 .\" The
  95 .\" .BR getfsent ()
  96 .\" function appeared in 4.0BSD; the other four functions appeared in 4.3BSD.
  97 .SH ATTRIBUTES
  98 For an explanation of the terms used in this section, see
  99 .BR attributes (7).
 100 .ad l
 101 .nh
 102 .TS
 103 allbox;
 104 lb lb lbx
 105 l l l.
 106 Interface       Attribute       Value
 107 T{
 108 .BR endfsent (),
 109 .BR setfsent ()
 110 T}      Thread safety   T{
 111 MT-Unsafe race:fsent
 112 T}
 113 T{
 114 .BR getfsent (),
 115 .BR getfsspec (),
 116 .BR getfsfile ()
 117 T}      Thread safety   T{
 118 MT-Unsafe race:fsent locale
 119 T}
 120 .TE
 121 .hy
 122 .ad
 123 .sp 1
 124 .SH STANDARDS
 125 These functions are not in POSIX.1.
 126 Several operating systems have them, for example,
 127 *BSD, SunOS, Digital UNIX, AIX (which also has a
 128 .BR getfstype ()).
 129 HP-UX has functions of the same names,
 130 that however use a
 131 .I struct checklist
 132 instead of a
 133 .IR "struct fstab" ,
 134 and calls these functions obsolete, superseded by
 135 .BR getmntent (3).
 136 .SH NOTES
 137 These functions are not thread-safe.
 138 .PP
 139 Since Linux allows mounting a block special device in several places,
 140 and since several devices can have the same mount point, where the
 141 last device with a given mount point is the interesting one,
 142 while
 143 .BR getfsfile ()
 144 and
 145 .BR getfsspec ()
 146 only return the first occurrence, these two functions are not suitable
 147 for use under Linux.
 148 .SH SEE ALSO
 149 .BR getmntent (3),
 150 .BR fstab (5)