original/man3/getmntent.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" References consulted:
  24 .\"     Linux libc source code
  25 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  26 .\"     386BSD man pages
  27 .\" Modified Sat Jul 24 21:46:57 1993 by Rik Faith (faith@cs.unc.edu)
  28 .\" Modified 961109, 031115, aeb
  29 .\"
  30 .TH GETMNTENT 3  2009-09-15 "" "Linux Programmer's Manual"
  31 .SH NAME
  32 getmntent, setmntent, addmntent, endmntent, hasmntopt,
  33 getmntent_r \- get file system descriptor file entry
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <stdio.h>
  37 .B #include <mntent.h>
  38 .sp
  39 .BI "FILE *setmntent(const char *" filename ", const char *" type );
  40 .sp
  41 .BI "struct mntent *getmntent(FILE *" fp );
  42 .sp
  43 .BI "int addmntent(FILE *" fp ", const struct mntent *" mnt );
  44 .sp
  45 .BI "int endmntent(FILE *" fp );
  46 .sp
  47 .BI "char *hasmntopt(const struct mntent *" mnt ", const char *" opt );
  48 .sp
  49 /* GNU extension */
  50 .B #include <mntent.h>
  51 .sp
  52 .BI "struct mntent *getmntent_r(FILE *" fp ", struct mntent *" mntbuf ,
  53 .BI "                           char *" buf ", int " buflen );
  54 .fi
  55 .sp
  56 .in -4n
  57 Feature Test Macro Requirements for glibc (see
  58 .BR feature_test_macros (7)):
  59 .in
  60 .sp
  61 .BR getmntent_r ():
  62 _BSD_SOURCE || _SVID_SOURCE
  63 .SH DESCRIPTION
  64 These routines are used to access the file system description file
  65 \fI/etc/fstab\fP and the mounted file system description file
  66 \fI/etc/mtab\fP.
  67 .PP
  68 The
  69 .BR setmntent ()
  70 function opens the file system description file
  71 \fIfilename\fP and returns a file pointer which can be used by
  72 .BR getmntent ().
  73 The argument \fItype\fP is the type of access
  74 required and can take the same values as the \fImode\fP argument of
  75 .BR fopen (3).
  76 .PP
  77 The
  78 .BR getmntent ()
  79 function reads the next line from the file system
  80 description file \fIfp\fP and returns a pointer to a structure
  81 containing the broken out fields from a line in the file.
  82 The pointer
  83 points to a static area of memory which is overwritten by subsequent
  84 calls to
  85 .BR getmntent ().
  86 .PP
  87 The
  88 .BR addmntent ()
  89 function adds the
  90 .I mntent
  91 structure \fImnt\fP to
  92 the end of the open file \fIfp\fP.
  93 .PP
  94 The
  95 .BR endmntent ()
  96 function closes the file system description file
  97 \fIfp\fP.
  98 .PP
  99 The
 100 .BR hasmntopt ()
 101 function scans the \fImnt_opts\fP field (see below)
 102 of the
 103 .I mntent
 104 structure \fImnt\fP for a substring that matches \fIopt\fP.
 105 See \fI<mntent.h>\fP and
 106 .BR mount (8)
 107 for valid mount options.
 108 .PP
 109 The reentrant
 110 .BR getmntent_r ()
 111 function is similar to
 112 .BR getmntent (),
 113 but stores the \fIstruct mount\fP in the provided
 114 .I *mntbuf
 115 and stores the strings pointed to by the entries in that struct
 116 in the provided array
 117 .I buf
 118 of size
 119 .IR buflen .
 120 .PP
 121 The \fImntent\fP structure is defined in \fI<mntent.h>\fP as follows:
 122 .sp
 123 .in +4n
 124 .nf
 125 struct mntent {
 126     char *mnt_fsname;   /* name of mounted file system */
 127     char *mnt_dir;      /* file system path prefix */
 128     char *mnt_type;     /* mount type (see mntent.h) */
 129     char *mnt_opts;     /* mount options (see mntent.h) */
 130     int   mnt_freq;     /* dump frequency in days */
 131     int   mnt_passno;   /* pass number on parallel fsck */
 132 };
 133 .fi
 134 .in
 135
 136 Since fields in the mtab and fstab files are separated by whitespace,
 137 octal escapes are used to represent the four characters space (\e040),
 138 tab (\e011), newline (\e012) and backslash (\e134) in those files
 139 when they occur in one of the four strings in a
 140 .I mntent
 141 structure.
 142 The routines
 143 .BR addmntent ()
 144 and
 145 .BR getmntent ()
 146 will convert
 147 from string representation to escaped representation and back.
 148 .SH "RETURN VALUE"
 149 The
 150 .BR getmntent ()
 151 and
 152 .BR getmntent_r ()
 153 functions return
 154 a pointer to the
 155 .I mntent
 156 structure or NULL on failure.
 157 .PP
 158 The
 159 .BR addmntent ()
 160 function returns 0 on success and 1 on failure.
 161 .PP
 162 The
 163 .BR endmntent ()
 164 function always returns 1.
 165 .PP
 166 The
 167 .BR hasmntopt ()
 168 function returns the address of the substring if
 169 a match is found and NULL otherwise.
 170 .SH FILES
 171 .nf
 172 /etc/fstab          file system description file
 173 /etc/mtab           mounted file system description file
 174 .fi
 175 .SH "CONFORMING TO"
 176 The nonreentrant functions are from SunOS 4.1.3.
 177 A routine
 178 .BR getmntent_r ()
 179 was introduced in HP-UX 10, but it returns an int.
 180 The prototype shown above is glibc-only.
 181 .SH NOTES
 182 System V also has a
 183 .BR getmntent ()
 184 function but the calling sequence
 185 differs, and the returned structure is different.
 186 Under System V
 187 .I /etc/mnttab
 188 is used.
 189 4.4BSD and Digital Unix have a routine
 190 .BR getmntinfo (),
 191 a wrapper around the system call
 192 .BR getfsstat ().
 193 .SH "SEE ALSO"
 194 .BR fopen (3),
 195 .BR fstab (5),
 196 .BR mount (8)