man3/getmntent.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu)
  30 .\" Modified 961109, 031115, aeb
  31 .\"
  32 .TH GETMNTENT 3  2021-03-22 "" "Linux Programmer's Manual"
  33 .SH NAME
  34 getmntent, setmntent, addmntent, endmntent, hasmntopt,
  35 getmntent_r \- get filesystem descriptor file entry
  36 .SH SYNOPSIS
  37 .nf
  38 .B #include <stdio.h>
  39 .B #include <mntent.h>
  40 .PP
  41 .BI "FILE *setmntent(const char *" filename ", const char *" type );
  42 .PP
  43 .BI "struct mntent *getmntent(FILE *" stream );
  44 .PP
  45 .BI "int addmntent(FILE *restrict " stream ,
  46 .BI "              const struct mntent *restrict " mnt );
  47 .PP
  48 .BI "int endmntent(FILE *" streamp );
  49 .PP
  50 .BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt );
  51 .PP
  52 /* GNU extension */
  53 .B #include <mntent.h>
  54 .PP
  55 .BI "struct mntent *getmntent_r(FILE *restrict " streamp ,
  56 .BI "              struct mntent *restrict " mntbuf ,
  57 .BI "              char *restrict " buf ", int " buflen );
  58 .fi
  59 .PP
  60 .RS -4
  61 Feature Test Macro Requirements for glibc (see
  62 .BR feature_test_macros (7)):
  63 .RE
  64 .PP
  65 .BR getmntent_r ():
  66 .nf
  67     Since glibc 2.19:
  68         _DEFAULT_SOURCE
  69     Glibc 2.19 and earlier:
  70         _BSD_SOURCE || _SVID_SOURCE
  71 .fi
  72 .SH DESCRIPTION
  73 These routines are used to access the filesystem description file
  74 .I /etc/fstab
  75 and the mounted filesystem description file
  76 .IR /etc/mtab .
  77 .PP
  78 The
  79 .BR setmntent ()
  80 function opens the filesystem description file
  81 .I filename
  82 and returns a file pointer which can be used by
  83 .BR getmntent ().
  84 The argument
  85 .I type
  86 is the type of access
  87 required and can take the same values as the
  88 .I mode
  89 argument of
  90 .BR fopen (3).
  91 The returned stream should be closed using
  92 .BR endmntent ()
  93 rather than
  94 .BR fclose (3).
  95 .PP
  96 The
  97 .BR getmntent ()
  98 function reads the next line of the filesystem
  99 description file from
 100 .I stream
 101 and returns a pointer to a structure
 102 containing the broken out fields from a line in the file.
 103 The pointer
 104 points to a static area of memory which is overwritten by subsequent
 105 calls to
 106 .BR getmntent ().
 107 .PP
 108 The
 109 .BR addmntent ()
 110 function adds the
 111 .I mntent
 112 structure
 113 .I mnt
 114 to
 115 the end of the open
 116 .IR stream .
 117 .PP
 118 The
 119 .BR endmntent ()
 120 function closes the
 121 .IR stream
 122 associated with the filesystem description file.
 123 .PP
 124 The
 125 .BR hasmntopt ()
 126 function scans the
 127 .I mnt_opts
 128 field (see below)
 129 of the
 130 .I mntent
 131 structure
 132 .I mnt
 133 for a substring that matches
 134 .IR opt .
 135 See
 136 .I <mntent.h>
 137 and
 138 .BR mount (8)
 139 for valid mount options.
 140 .PP
 141 The reentrant
 142 .BR getmntent_r ()
 143 function is similar to
 144 .BR getmntent (),
 145 but stores the
 146 .IR "struct mount"
 147 in the provided
 148 .I *mntbuf
 149 and stores the strings pointed to by the entries in that struct
 150 in the provided array
 151 .I buf
 152 of size
 153 .IR buflen .
 154 .PP
 155 The
 156 .I mntent
 157 structure is defined in
 158 .I <mntent.h>
 159 as follows:
 160 .PP
 161 .in +4n
 162 .EX
 163 struct mntent {
 164     char *mnt_fsname;   /* name of mounted filesystem */
 165     char *mnt_dir;      /* filesystem path prefix */
 166     char *mnt_type;     /* mount type (see mntent.h) */
 167     char *mnt_opts;     /* mount options (see mntent.h) */
 168     int   mnt_freq;     /* dump frequency in days */
 169     int   mnt_passno;   /* pass number on parallel fsck */
 170 };
 171 .EE
 172 .in
 173 .PP
 174 Since fields in the mtab and fstab files are separated by whitespace,
 175 octal escapes are used to represent the characters space (\e040),
 176 tab (\e011), newline (\e012), and backslash (\e\e) in those files
 177 when they occur in one of the four strings in a
 178 .I mntent
 179 structure.
 180 The routines
 181 .BR addmntent ()
 182 and
 183 .BR getmntent ()
 184 will convert
 185 from string representation to escaped representation and back.
 186 When converting from escaped representation, the sequence \e134 is
 187 also converted to a backslash.
 188 .SH RETURN VALUE
 189 The
 190 .BR getmntent ()
 191 and
 192 .BR getmntent_r ()
 193 functions return
 194 a pointer to the
 195 .I mntent
 196 structure or NULL on failure.
 197 .PP
 198 The
 199 .BR addmntent ()
 200 function returns 0 on success and 1 on failure.
 201 .PP
 202 The
 203 .BR endmntent ()
 204 function always returns 1.
 205 .PP
 206 The
 207 .BR hasmntopt ()
 208 function returns the address of the substring if
 209 a match is found and NULL otherwise.
 210 .SH FILES
 211 .TP
 212 .I /etc/fstab
 213 filesystem description file
 214 .TP
 215 .I /etc/mtab
 216 mounted filesystem description file
 217 .SH ATTRIBUTES
 218 For an explanation of the terms used in this section, see
 219 .BR attributes (7).
 220 .ad l
 221 .nh
 222 .TS
 223 allbox;
 224 lb lb lbx
 225 l l l.
 226 Interface       Attribute       Value
 227 T{
 228 .BR setmntent (),
 229 .BR endmntent (),
 230 .BR hasmntopt ()
 231 T}      Thread safety   MT-Safe
 232 T{
 233 .BR getmntent ()
 234 T}      Thread safety   T{
 235 MT-Unsafe race:mntentbuf locale
 236 T}
 237 T{
 238 .BR addmntent ()
 239 T}      Thread safety   T{
 240 MT-Safe race:stream locale
 241 T}
 242 T{
 243 .BR getmntent_r ()
 244 T}      Thread safety   MT-Safe locale
 245 .TE
 246 .hy
 247 .ad
 248 .sp 1
 249 .SH CONFORMING TO
 250 The nonreentrant functions are from SunOS 4.1.3.
 251 A routine
 252 .BR getmntent_r ()
 253 was introduced in HP-UX 10, but it returns an
 254 .IR int .
 255 The prototype shown above is glibc-only.
 256 .SH NOTES
 257 System V also has a
 258 .BR getmntent ()
 259 function but the calling sequence
 260 differs, and the returned structure is different.
 261 Under System V
 262 .I /etc/mnttab
 263 is used.
 264 4.4BSD and Digital UNIX have a routine
 265 .BR getmntinfo (),
 266 a wrapper around the system call
 267 .BR getfsstat ().
 268 .SH SEE ALSO
 269 .BR fopen (3),
 270 .BR fstab (5),
 271 .BR mount (8)