(Mount/Unmount/Remount): Document that umount2 is not widely available.
[kopensolaris-gnu/glibc.git] / manual / sysinfo.texi
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 * Hardware/Software Type ID::   Determining the hardware type of the
15                                  machine and what operating system it is
16                                  running.
17 * Filesystem Handling::         Controlling/querying mounts
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 machine that your
28 program is running on.  The identification of a machine consists of its
29 Internet host name and Internet address; see @ref{Internet Namespace}.
30 The host name should always be a fully qualified domain name, like
31 @w{@samp{crispy-wheats-n-chicken.ai.mit.edu}}, not a simple name like
32 just @w{@samp{crispy-wheats-n-chicken}}.
33
34 @pindex hostname
35 @pindex hostid
36 @pindex unistd.h
37 Prototypes for these functions appear in @file{unistd.h}.  The shell
38 commands @code{hostname} and @code{hostid} work by calling them.
39
40 @comment unistd.h
41 @comment BSD
42 @deftypefun int gethostname (char *@var{name}, size_t @var{size})
43 This function returns the name of the host machine in the array
44 @var{name}.  The @var{size} argument specifies the size of this array,
45 in bytes.
46
47 The return value is @code{0} on success and @code{-1} on failure.  In
48 the GNU C library, @code{gethostname} fails if @var{size} is not large
49 enough; then you can try again with a larger array.  The following
50 @code{errno} error condition is defined for this function:
51
52 @table @code
53 @item ENAMETOOLONG
54 The @var{size} argument is less than the size of the host name plus one.
55 @end table
56
57 @pindex sys/param.h
58 On some systems, there is a symbol for the maximum possible host name
59 length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
60 But you can't count on this to exist, so it is cleaner to handle
61 failure and try again.
62
63 @code{gethostname} stores the beginning of the host name in @var{name}
64 even if the host name won't entirely fit.  For some purposes, a
65 truncated host name is good enough.  If it is, you can ignore the
66 error code.
67 @end deftypefun
68
69 @comment unistd.h
70 @comment BSD
71 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
72 The @code{sethostname} function sets the name of the host machine to
73 @var{name}, a string with length @var{length}.  Only privileged
74 processes are allowed to do this.  Usually it happens just once, at
75 system boot time.
76
77 The return value is @code{0} on success and @code{-1} on failure.
78 The following @code{errno} error condition is defined for this function:
79
80 @table @code
81 @item EPERM
82 This process cannot set the host name because it is not privileged.
83 @end table
84 @end deftypefun
85
86 @comment unistd.h
87 @comment BSD
88 @deftypefun {long int} gethostid (void)
89 This function returns the ``host ID'' of the machine the program is
90 running on.  By convention, this is usually the primary Internet address
91 of that machine, converted to a @w{@code{long int}}.  However, on some
92 systems it is a meaningless but unique number which is hard-coded for
93 each machine.
94 @end deftypefun
95
96 @comment unistd.h
97 @comment BSD
98 @deftypefun int sethostid (long int @var{id})
99 The @code{sethostid} function sets the ``host ID'' of the host machine
100 to @var{id}.  Only privileged processes are allowed to do this.  Usually
101 it happens just once, at system boot time.
102
103 The return value is @code{0} on success and @code{-1} on failure.
104 The following @code{errno} error conditions are defined for this function:
105
106 @table @code
107 @item EPERM
108 This process cannot set the host name because it is not privileged.
109
110 @item ENOSYS
111 The operating system does not support setting the host ID.  On some
112 systems, the host ID is a meaningless but unique number hard-coded for
113 each machine.
114 @end table
115 @end deftypefun
116
117 @node Hardware/Software Type ID
118 @section Hardware/Software Type Identification
119
120 You can use the @code{uname} function to find out some information about
121 the type of computer your program is running on.  This function and the
122 associated data type are declared in the header file
123 @file{sys/utsname.h}.
124 @pindex sys/utsname.h
125
126 @comment sys/utsname.h
127 @comment POSIX.1
128 @deftp {Data Type} {struct utsname}
129 The @code{utsname} structure is used to hold information returned
130 by the @code{uname} function.  It has the following members:
131
132 @table @code
133 @item char sysname[]
134 This is the name of the operating system in use.
135
136 @item char nodename[]
137 This is the network name of this particular computer.  In the GNU
138 library, the value is the same as that returned by @code{gethostname};
139 see @ref{Host Identification}.
140
141 @item char release[]
142 This is the current release level of the operating system implementation.
143
144 @item char version[]
145 This is the current version level within the release of the operating
146 system.
147
148 @item char machine[]
149 This is a description of the type of hardware that is in use.
150
151 Some systems provide a mechanism to interrogate the kernel directly for
152 this information.  On systems without such a mechanism, the GNU C
153 library fills in this field based on the configuration name that was
154 specified when building and installing the library.
155
156 GNU uses a three-part name to describe a system configuration; the three
157 parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they
158 are separated with dashes.  Any possible combination of three names is
159 potentially meaningful, but most such combinations are meaningless in
160 practice and even the meaningful ones are not necessarily supported by
161 any particular GNU program.
162
163 Since the value in @code{machine} is supposed to describe just the
164 hardware, it consists of the first two parts of the configuration name:
165 @samp{@var{cpu}-@var{manufacturer}}.  For example, it might be one of these:
166
167 @quotation
168 @code{"sparc-sun"},
169 @code{"i386-@var{anything}"},
170 @code{"m68k-hp"},
171 @code{"m68k-sony"},
172 @code{"m68k-sun"},
173 @code{"mips-dec"}
174 @end quotation
175 @end table
176 @end deftp
177
178 @comment sys/utsname.h
179 @comment POSIX.1
180 @deftypefun int uname (struct utsname *@var{info})
181 The @code{uname} function fills in the structure pointed to by
182 @var{info} with information about the operating system and host machine.
183 A non-negative value indicates that the data was successfully stored.
184
185 @code{-1} as the value indicates an error.  The only error possible is
186 @code{EFAULT}, which we normally don't mention as it is always a
187 possibility.
188 @end deftypefun
189
190
191 @node Filesystem Handling
192 @section Controlling/querying mounts
193
194 All files are in filesystems, and before you can access any file, its
195 filesystem must be mounted.  Because of Unix's concept of
196 @emph{Everything is a file}, mounting of filesystems is central to doing
197 almost anything.  This section explains how to find out what filesystems
198 are currently mounted and what filesystems are available for mounting,
199 and how to change what is mounted.
200
201 The classic filesystem is the contents of a disk drive.  The concept is
202 considerably more abstract, though, and lots of things other than disk
203 drives can be mounted.
204
205 Some block devices don't correspond to traditional devices like disk
206 drives.  For example, a loop device is a block device whose driver uses
207 a regular file in another filesystem as its medium.  So if that regular
208 file contains appropriate data for a filesystem, you can by mounting the
209 loop device essentially mount a regular file.
210
211 Some filesystems aren't based on a device of any kind.  The ``proc''
212 filesystem, for example, contains files whose data is made up by the
213 filesystem driver on the fly whenever you ask for it.  And when you
214 write to it, the data you write causes changes in the system.  No data
215 gets stored.
216
217 @c It would be good to mention NFS mounts here.
218
219 @menu
220 * Mount Information::           What is or could be mounted?
221 * Mount/Unmount/Remount::       Controlling what is mounted and how
222 @end menu
223
224 @node Mount Information, Mount/Unmount/Remount, , Filesystem Handling
225
226 For some programs it is desirable and necessary to access information
227 about whether a certain filesystem is mounted and, if it is, where, or
228 simply to get lists of all the available filesystems.  The GNU libc
229 provides some functions to retrieve this information portably.
230
231 Traditionally Unix systems have a file named @file{/etc/fstab} which
232 describes all possibly mounted filesystems.  The @code{mount} program
233 uses this file to mount at startup time of the system all the necessary
234 filesystems.  The information about all the filesystems actually mounted
235 is normally kept in a file named @file{/etc/mtab}.  Both files share
236 the same syntax and it is crucial that this syntax is followed all the
237 time.  Therefore it is best to never directly write the files.  The
238 functions described in this section can do this and they also provide
239 the functionality to convert the external textual representation to the
240 internal representation.
241
242 Note that the @file{fstab} and @file{mtab} files are maintained on a
243 system by @emph{convention}.  It is possible for the files not to exist
244 or not to be consistent with what is really mounted or available to
245 mount, if the system's administration policy allows it.  But programs
246 that mount and unmount filesystems typically maintain and use these
247 files as described herein.
248
249 @vindex _PATH_FSTAB
250 @vindex _PATH_MNTTAB
251 @vindex FSTAB
252 @vindex _PATH_MOUNTED
253 The filenames given above should never be used directly.  The portable
254 way to handle these file is to use the macros @code{_PATH_FSTAB},
255 defined in @file{fstab.h} and @code{_PATH_MNTTAB}, defined in
256 @file{mntent.h}, respectively.  There are also two alternate macro names
257 @code{FSTAB} and @code{_PATH_MOUNTED} defined but both names are
258 deprecated and kept only for backward compatibility.  The two former
259 names should always be used.
260
261 @menu
262 * fstab::                       The @file{fstab} file
263 * mtab::                        The @file{mtab} file
264 * Other Mount Information::     Other (non-libc) sources of mount information
265 @end menu
266
267 @node fstab
268 @subsection The @file{fstab} file
269
270 The internal representation for entries of the file is @w{@code{struct
271 fstab}}, defined in @file{fstab.h}.
272
273 @comment fstab.h
274 @comment BSD
275 @deftp {Data Type} {struct fstab}
276 This structure is used with the @code{getfsent}, @code{getfsspec}, and
277 @code{getfsfile} functions.
278
279 @table @code
280 @item char *fs_spec
281 This element describes the device from which the filesystem is mounted.
282 Normally this is the name of a special device, such as a hard disk
283 partition, but it could also be a more or less generic string.  For
284 @dfn{NFS} it would be a hostname and directory name combination.
285
286 Even though the element is not declared @code{const} it shouldn't be
287 modified.  The missing @code{const} has historic reasons, since this
288 function predates @w{ISO C}.  The same is true for the other string
289 elements of this structure.
290
291 @item char *fs_file
292 This describes the mount point on the local system.  I.e., accessing any
293 file in this filesystem has implicitly or explicitly this string as a
294 prefix.
295
296 @item char *fs_vfstype
297 This is the type of the filesystem.  Depending on what the underlying
298 kernel understands it can be any string.
299
300 @item char *fs_mntops
301 This is a string containing options passed to the kernel with the
302 @code{mount} call.  Again, this can be almost anything.  There can be
303 more than one option, separated from the others by a comma.  Each option
304 consists of a name and an optional value part, introduced by an @code{=}
305 character.
306
307 If the value of this element must be processed it should ideally be done
308 using the @code{getsubopt} function; see @ref{Suboptions}.
309
310 @item const char *fs_type
311 This name is poorly chosen.  This element points to a string (possibly
312 in the @code{fs_mntops} string) which describes the modes with which the
313 filesystem is mounted.  @file{fstab} defines five macros to describe the
314 possible values:
315
316 @vtable @code
317 @item FSTAB_RW
318 The filesystems gets mounted with read and write enabled.
319 @item FSTAB_RQ
320 The filesystems gets mounted with read and write enabled.  Write access
321 is restricted by quotas.
322 @item FSTAB_RO
323 The filesystem gets mounted read-only.
324 @item FSTAB_SW
325 This is not a real filesystem, it is a swap device.
326 @item FSTAB_XX
327 This entry from the @file{fstab} file is totally ignored.
328 @end vtable
329
330 Testing for equality with these value must happen using @code{strcmp}
331 since these are all strings.  Comparing the pointer will probably always
332 fail.
333
334 @item int fs_freq
335 This element describes the dump frequency in days.
336
337 @item int fs_passno
338 This element describes the pass number on parallel dumps.  It is closely
339 related to the @code{dump} utility used on Unix systems.
340 @end table
341 @end deftp
342
343
344 To read the entire content of the of the @file{fstab} file the GNU libc
345 contains a set of three functions which are designed in the usual way.
346
347 @comment fstab.h
348 @comment BSD
349 @deftypefun int setfsent (void)
350 This function makes sure that the internal read pointer for the
351 @file{fstab} file is at the beginning of the file.  This is done by
352 either opening the file or resetting the read pointer.
353
354 Since the file handle is internal to the libc this function is not
355 thread-safe.
356
357 This function returns a non-zero value if the operation was successful
358 and the @code{getfs*} functions can be used to read the entries of the
359 file.
360 @end deftypefun
361
362 @comment fstab.h
363 @comment BSD
364 @deftypefun void endfsent (void)
365 This function makes sure that all resources acquired by a prior call to
366 @code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are
367 freed.
368 @end deftypefun
369
370 @comment fstab.h
371 @comment BSD
372 @deftypefun {struct fstab *} getfsent (void)
373 This function returns the next entry of the @file{fstab} file.  If this
374 is the first call to any of the functions handling @file{fstab} since
375 program start or the last call of @code{endfsent}, the file will be
376 opened.
377
378 The function returns a pointer to a variable of type @code{struct
379 fstab}.  This variable is shared by all threads and therefore this
380 function is not thread-safe.  If an error occurred @code{getfsent}
381 returns a @code{NULL} pointer.
382 @end deftypefun
383
384 @comment fstab.h
385 @comment BSD
386 @deftypefun {struct fstab *} getfsspec (const char *@var{name})
387 This function returns the next entry of the @file{fstab} file which has
388 a string equal to @var{name} pointed to by the @code{fs_spec} element.
389 Since there is normally exactly one entry for each special device it
390 makes no sense to call this function more than once for the same
391 argument.  If this is the first call to any of the functions handling
392 @file{fstab} since program start or the last call of @code{endfsent},
393 the file will be opened.
394
395 The function returns a pointer to a variable of type @code{struct
396 fstab}.  This variable is shared by all threads and therefore this
397 function is not thread-safe.  If an error occurred @code{getfsent}
398 returns a @code{NULL} pointer.
399 @end deftypefun
400
401 @comment fstab.h
402 @comment BSD
403 @deftypefun {struct fstab *} getfsfile (const char *@var{name})
404 This function returns the next entry of the @file{fstab} file which has
405 a string equal to @var{name} pointed to by the @code{fs_file} element.
406 Since there is normally exactly one entry for each mount point it
407 makes no sense to call this function more than once for the same
408 argument.  If this is the first call to any of the functions handling
409 @file{fstab} since program start or the last call of @code{endfsent},
410 the file will be opened.
411
412 The function returns a pointer to a variable of type @code{struct
413 fstab}.  This variable is shared by all threads and therefore this
414 function is not thread-safe.  If an error occurred @code{getfsent}
415 returns a @code{NULL} pointer.
416 @end deftypefun
417
418
419 @node mtab
420 @subsection The @file{mtab} file
421 The following functions and data structure access the @file{mtab} file.
422
423 @comment mntent.h
424 @comment BSD
425 @deftp {Data Type} {struct mntent}
426 This structure is used with the @code{getmntent}, @code{getmntent_t},
427 @code{addmntent}, and @code{hasmntopt} functions.
428
429 @table @code
430 @item char *mnt_fsname
431 This element contains a pointer to a string describing the name of the
432 special device from which the filesystem is mounted.  It corresponds to
433 the @code{fs_spec} element in @code{struct fstab}.
434
435 @item char *mnt_dir
436 This element points to a string describing the mount point of the
437 filesystem.  It corresponds to the @code{fs_file} element in
438 @code{struct fstab}.
439
440 @item char *mnt_type
441 @code{mnt_type} describes the filesystem type and is therefore
442 equivalent to @code{fs_vfstype} in @code{struct fstab}.  @file{mntent.h}
443 defines a few symbolic names for some of the values this string can have.
444 But since the kernel can support arbitrary filesystems it does not
445 make much sense to give them symbolic names.  If one knows the symbol
446 name one also knows the filesystem name.  Nevertheless here follows the
447 list of the symbols provided in @file{mntent.h}.
448
449 @vtable @code
450 @item MNTTYPE_IGNORE
451 This symbol expands to @code{"ignore"}.  The value is sometime used in
452 @file{fstab} files to make sure entries are not used without removing them.
453 @item MNTTYPE_NFS
454 Expands to @code{"nfs"}.  Using this macro sometimes could make sense
455 since it names the default NFS implementation, in case both version 2
456 and 3 are supported.
457 @item MNTTYPE_SWAP
458 This symbol expands to @code{"swap"}.  It names the special @file{fstab}
459 entry which names one of the possibly multiple swap partitions.
460 @end vtable
461
462 @item char *mnt_opts
463 The element contains a string describing the options used while mounting
464 the filesystem.  As for the equivalent element @code{fs_mntops} of
465 @code{struct fstab} it is best to use the function @code{getsubopt}
466 (@pxref{Suboptions}) to access the parts of this string.
467
468 The @file{mntent.h} file defines a number of macros with string values
469 which correspond to some of the options understood by the kernel.  There
470 might be many more options which are possible so it doesn't make much sense
471 to rely on these macros but to be consistent here is the list:
472
473 @vtable @code
474 @item MNTOPT_DEFAULTS
475 Expands to @code{"defaults"}.  This option should be used alone since it
476 indicates all values for the customizable values are chosen to be the
477 default.
478 @item MNTOPT_RO
479 Expands to @code{"ro"}.  See the @code{FSTAB_RO} value, it means the
480 filesystem is mounted read-only.
481 @item MNTOPT_RW
482 Expand to @code{"rw"}.  See the @code{FSTAB_RW} value, it means the
483 filesystem is mounted with read and write permissions.
484 @item MNTOPT_SUID
485 Expands to @code{"suid"}.  This means that the SUID bit (@pxref{How
486 Change Persona}) is respected when a program from the filesystem is
487 started.
488 @item MNTOPT_NOSUID
489 Expands to @code{"nosuid"}.  This is the opposite of @code{MNTOPT_SUID},
490 the SUID bit for all files from the filesystem is ignored.
491 @item MNTOPT_NOAUTO
492 Expands to @code{"noauto"}.  At startup time the @code{mount} program
493 will ignore this entry if it is started with the @code{-a} option to
494 mount all filesystems mentioned in the @file{fstab} file.
495 @end vtable
496
497 As for the @code{FSTAB_*} entries introduced above it is important to
498 use @code{strcmp} to check for equality.
499
500 @item mnt_freq
501 This elements corresponds to @code{fs_freq} and also specifies the
502 frequency in days in which dumps are made.
503
504 @item mnt_passno
505 This element is equivalent to @code{fs_passno} with the same meaning
506 which is uninteresting for all programs beside @code{dump}.
507 @end table
508 @end deftp
509
510 For accessing the @file{mtab} file there is again a set of three
511 functions to access all entries in a row.  Unlike the functions to
512 handle @file{fstab} these functions do not access a fixed file and there
513 is even a thread safe variant of the get function.  Beside this the GNU
514 libc contains functions to alter the file and test for specific options.
515
516 @comment mntent.h
517 @comment BSD
518 @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode})
519 The @code{setmntent} function prepares the file named @var{FILE} which
520 must be in the format of a @file{fstab} and @file{mtab} file for the
521 upcoming processing through the other functions of the family.  The
522 @var{mode} parameter can be chosen in the way the @var{opentype}
523 parameter for @code{fopen} (@pxref{Opening Streams}) can be chosen.  If
524 the file is opened for writing the file is also allowed to be empty.
525
526 If the file was successfully opened @code{setmntent} returns a file
527 descriptor for future use.  Otherwise the return value is @code{NULL}
528 and @code{errno} is set accordingly.
529 @end deftypefun
530
531 @comment mntent.h
532 @comment BSD
533 @deftypefun int endmntent (FILE *@var{stream})
534 This function takes for the @var{stream} parameter a file handle which
535 previously was returned from the @code{setmntent} call.
536 @code{endmntent} closes the stream and frees all resources.
537
538 The return value is @math{1} unless an error occurred in which case it
539 is @math{0}.
540 @end deftypefun
541
542 @comment mntent.h
543 @comment BSD
544 @deftypefun {struct mntent *} getmntent (FILE *@var{stream})
545 The @code{getmntent} function takes as the parameter a file handle
546 previously returned by successful call to @code{setmntent}.  It returns
547 a pointer to a static variable of type @code{struct mntent} which is
548 filled with the information from the next entry from the file currently
549 read.
550
551 The file format used prescribes the use of spaces or tab characters to
552 separate the fields.  This makes it harder to use name containing one of
553 these characters (e.g., mount points using spaces).  Therefore these
554 characters are encoded in the files and the @code{getmntent} function
555 takes care of the decoding while reading the entries back in.
556 @code{'\040'} is used to encode a space character, @code{'\012'} to
557 encode a tab character and @code{'\\'} to encode a backslash.
558
559 If there was an error or the end of the file is reached the return value
560 is @code{NULL}.
561
562 This function is not thread-safe since all calls to this function return
563 a pointer to the same static variable.  @code{getmntent_r} should be
564 used in situations where multiple threads access the file.
565 @end deftypefun
566
567 @comment mntent.h
568 @comment BSD
569 @deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mentent *@var{result}, char *@var{buffer}, int @var{bufsize})
570 The @code{getmntent_r} function is the reentrant variant of
571 @code{getmntent}.  It also returns the next entry from the file and
572 returns a pointer.  The actual variable the values are stored in is not
573 static, though.  Instead the function stores the values in the variable
574 pointed to by the @var{result} parameter.  Additional information (e.g.,
575 the strings pointed to by the elements of the result) are kept in the
576 buffer of size @var{bufsize} pointed to by @var{buffer}.
577
578 Escaped characters (space, tab, backslash) are converted back in the
579 same way as it happens for @code{getmentent}.
580
581 The function returns a @code{NULL} pointer in error cases.  Errors could be:
582 @itemize @bullet
583 @item
584 error while reading the file,
585 @item
586 end of file reached,
587 @item
588 @var{bufsize} is too small for reading a complete new entry.
589 @end itemize
590 @end deftypefun
591
592 @comment mntent.h
593 @comment BSD
594 @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt})
595 The @code{addmntent} function allows adding a new entry to the file
596 previously opened with @code{setmntent}.  The new entries are always
597 appended.  I.e., even if the position of the file descriptor is not at
598 the end of the file this function does not overwrite an existing entry
599 following the current position.
600
601 The implication of this is that to remove an entry from a file one has
602 to create a new file while leaving out the entry to be removed and after
603 closing the file remove the old one and rename the new file to the
604 chosen name.
605
606 This function takes care of spaces and tab characters in the names to be
607 written to the file.  It converts them and the backslash character into
608 the format describe in the @code{getmntent} description above.
609
610 This function returns @math{0} in case the operation was successful.
611 Otherwise the return value is @math{1} and @code{errno} is set
612 appropriately.
613 @end deftypefun
614
615 @comment mntent.h
616 @comment BSD
617 @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt})
618 This function can be used to check whether the string pointed to by the
619 @code{mnt_opts} element of the variable pointed to by @var{mnt} contains
620 the option @var{opt}.  If this is true a pointer to the beginning of the
621 option in the @code{mnt_opts} element is returned.  If no such option
622 exists the function returns @code{NULL}.
623
624 This function is useful to test whether a specific option is present but
625 when all options have to be processed one is better off with using the
626 @code{getsubopt} function to iterate over all options in the string.
627 @end deftypefun
628
629 @node Other Mount Information
630 @subsection Other (Non-libc) Sources of Mount Information
631
632 On a system with a Linux kernel and the @code{proc} filesystem, you can
633 get information on currently mounted filesystems from the file
634 @file{mounts} in the @code{proc} filesystem.  Its format is similar to
635 that of the @file{mtab} file, but represents what is truly mounted
636 without relying on facilities outside the kernel to keep @file{mtab} up
637 to date.
638
639
640 @node Mount/Unmount/Remount, , Mount Information, Filesystem Handling
641
642 This section describes the functions for mounting, unmounting, and
643 remounting filesystems.
644
645 Only the superuser can mount, unmount, or remount a filesystem.
646
647 These functions do not access the @file{fstab} and @file{mtab} files.  You
648 should maintain and use these separately.  @xref{Mount Information}.
649
650 The symbols in this section are declared in @file{sys/mount.h}.
651
652 @comment sys/mount.h
653 @comment SVID, BSD
654 @deftypefun {int} mount (const char *@var{special_file}, const char *@var{dir}, const char *@var{fstype}, unsigned long int @var{options}, const void *@var{data})
655
656 @code{mount} mounts or remounts a filesystem.  The two operations are
657 quite different and are merged rather unnnaturally into this one function.
658 The @code{MS_REMOUNT} option, explained below, determines whether
659 @code{mount} mounts or remounts.
660
661 For a mount, the filesystem on the block device represented by the
662 device special file named @var{special_file} gets mounted over the mount
663 point @var{dir}.  This means that the directory @var{dir} (along with any
664 files in it) is no longer visible; in its place (and still with the name
665 @var{dir}) is the root directory of the filesystem on the device.
666
667 As an exception, if the filesystem type (see below) is one which is not
668 based on a device (e.g. ``proc''), @code{mount} instantiates a
669 filesystem and mounts it over @var{dir} and ignores @var{special_file}.
670
671 For a remount, @var{dir} specifies the mount point where the filesystem
672 to be remounted is (and remains) mounted and @var{special_file} is
673 ignored.  Remounting a filesystem means changing the options that control
674 operations on the filesystem while it is mounted.  It does not mean
675 unmounting and mounting again.
676
677 For a mount, you must identify the type of the filesystem as
678 @var{fstype}.  This type tells the kernel how to access the filesystem
679 and can be thought of as the name of a filesystem driver.  The
680 acceptable values are system dependent.  On a system with a Linux kernel
681 and the @code{proc} filesystem, the list of possible values is in the
682 file @file{filesystems} in the @code{proc} filesystem (e.g. type
683 @kbd{cat /proc/filesystems} to see the list).  With a Linux kernel, the
684 types of filesystems that @code{mount} can mount, and their type names,
685 depends on what filesystem drivers are configured into the kernel or
686 loaded as loadable kernel modules.  An example of a common value for
687 @var{fstype} is @code{ext2}.
688
689 For a remount, @code{mount} ignores @var{fstype}.
690
691 @c This is traditionally called "rwflag" for historical reasons.
692 @c No point in confusing people today, though.
693 @var{options} specifies a variety of options that apply until the
694 filesystem in unmounted or remounted.  The precise meaning of an option
695 depends on the filesystem and with some filesystems, an option may have
696 no effect at all.  Furthermore, for some filesystems, some of these
697 options (but never @code{MS_RDONLY}) can be overridden for individual
698 file accesses via @code{ioctl}.
699
700 @var{options} is a bit string with bit fields defined using the
701 following mask and masked value macros:
702
703 @table @code
704 @item MS_MGC_MASK
705 This multibit field contains a magic number.  If it does not have the value
706 @code{MS_MGC_VAL}, @code{mount} assumes all the following bits are zero and
707 the @var{data} argument is a null string, regardless of their actual values.
708
709 @item MS_REMOUNT
710 This bit on means to remount the filesystem.  Off means to mount it.
711 @c There is a mask MS_RMT_MASK in mount.h that says only two of the options
712 @c can be reset by remount.  But the Linux kernel has it's own version of
713 @c MS_RMT_MASK that says they all can be reset.  As far as I can tell,
714 @c libc just passes the arguments straight through to the kernel.
715
716 @item MS_RDONLY
717 This bit on specifies that no writing to the filesystem shall be allowed
718 while it is mounted.  This cannot be overridden by @code{ioctl}.  This
719 option is available on nearly all filesystems.
720
721 @item S_IMMUTABLE
722 This bit on specifies that no writing to the files in the filesystem
723 shall be allowed while it is mounted.  This can be overridden for a
724 particular file access by a properly privileged call to @code{ioctl}.
725 This option is a relatively new invention and is not available on many
726 filesystems.
727
728 @item S_APPEND
729 This bit on specifies that the only file writing that shall be allowed
730 while the filesystem is mounted is appending.  Some filesystems allow
731 this to be overridden for a particular process by a properly privileged
732 call to @code{ioctl}.  This is a relatively new invention and is not
733 available on many filesystems.
734
735 @item MS_NOSUID
736 This bit on specifies that Setuid and Setgid permissions on files in the
737 filesystem shall be ignored while it is mounted.
738
739 @item MS_NOEXEC
740 This bit on specifies that no files in the filesystem shall be executed
741 while the filesystem is mounted.
742
743 @item MS_NODEV
744 This bit on specifies that no device special files in the filesystem
745 shall be accessible while the filesystem is mounted.
746
747 @item MS_SYNCHRONOUS
748 This bit on specifies that all writes to the filesystem while it is
749 mounted shall be synchronous; i.e. data shall be synced before each
750 write completes rather than held in the buffer cache.
751
752 @item MS_MANDLOCK
753 This bit on specifies that mandatory locks on files shall be permitted while
754 the filesystem is mounted.
755
756 @item MS_NOATIME
757 This bit on specifies that access times of files shall not be updated when
758 the files are accessed while the filesystem is mounted.
759
760 @item MS_NODIRATIME
761 This bit on specifies that access times of directories shall not be updated
762 when the directories are accessed while the filesystem in mounted.
763
764 @c there is also S_QUOTA Linux fs.h (mount.h still uses its former name
765 @c S_WRITE), but I can't see what it does.  Turns on quotas, I guess.
766
767 @end table
768
769 Any bits not covered by the above masks should be set off; otherwise,
770 results are undefined.
771
772 The meaning of @var{data} depends on the filesystem type and is controlled
773 entirely by the filesystem driver in the kernel.
774
775 Example:
776
777 @smallexample
778 @group
779 #include <sys/mount.h>
780
781 mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");
782
783 mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");
784
785 @end group
786 @end smallexample
787
788 Appropriate arguments for @code{mount} are conventionally recorded in
789 the @file{fstab} table.  @xref{Mount Information}.
790
791 The return value is zero if the mount or remount is successful.  Otherwise,
792 it is @code{-1} and @code{errno} is set appropriately.  The values of
793 @code{errno} are filesystem dependent, but here is a general list:
794
795 @table @code
796 @item EPERM
797 The process is not superuser.
798 @item ENODEV
799 The file system type @var{fstype} is not known to the kernel.
800 @item ENOTBLK
801 The file @var{dev} is not a block device special file.
802 @item EBUSY
803
804 @itemize
805
806 @item
807 The device is already mounted.
808
809 @item
810 The mount point is busy.  (E.g. it is some process' working directory or
811 has a filesystem mounted on it already).
812
813 @item
814 The request is to remount read-only, but there are files open for write.
815 @end itemize
816
817 @item EINVAL
818 @itemize
819
820 @item
821 A remount was attempted, but there is no filesystem mounted over the
822 specified mount point.
823
824 @item
825 The supposed filesystem has an invalid superblock.
826
827 @end itemize
828
829 @item EACCESS
830 @itemize
831
832 @item
833 The filesystem is inherently read-only (possibly due to a switch on the
834 device) and the process attempted to mount it read/write (by setting the
835 @code{MS_RDONLY} bit off).
836
837 @item
838 @var{special_file} or @var{dir} is not accessible due to file permissions.
839
840 @item
841 @var{special_file} is not accessible because it is in a filesystem that is
842 mounted with the @code{MS_NODEV} option.
843
844 @end itemize
845
846 @item EM_FILE
847 The table of dummy devices is full.  @code{mount} needs to create a
848 dummy device (aka ``unnamed'' device) if the filesystem being mounted is
849 not one that uses a device.
850
851 @end table
852
853 @end deftypefun
854
855
856 @comment sys/mount.h
857 @comment GNU
858 @deftypefun {int} umount2 (const char *@var{file}, int @var{flags})
859
860 @code{umount2} unmounts a filesystem.
861
862 You can identify the filesystem to unmount either by the device special
863 file that contains the filesystem or by the mount point.  The effect is
864 the same.  Specify either as the string @var{file}.
865
866 @var{flags} contains the one-bit field identified by the following
867 mask macro:
868
869 @table @code
870
871 @item MNT_FORCE
872 This bit on means to force the unmounting even if the filesystem is
873 busy, by making it unbusy first.  If the bit is off and the filesystem is
874 busy, @code{umount2} fails with @code{errno} = @code{EBUSY}.  Depending
875 on the filesystem, this may override all, some, or no busy conditions.
876
877 @end table
878
879 All other bits in @var{flags} should be set to zero; otherwise, the result
880 is undefined.
881
882 Example:
883
884 @smallexample
885 @group
886 #include <sys/mount.h>
887
888 umount2("/mnt", MNT_FORCE);
889
890 umount2("/dev/hdd1", 0);
891
892 @end group
893 @end smallexample
894
895 After the filesystem is unmounted, the directory that was the mount point
896 is visible, as are any files in it.
897
898 As part of unmounting, @code{umount2} syncs the filesystem.
899
900 If the unmounting is successful, the return value is zero.  Otherwise, it
901 is @code{-1} and @code{errno} is set accordingly:
902
903 @table @code
904 @item EPERM
905 The process is not superuser.
906 @item EBUSY
907 The filesystem cannot be unmounted because it is busy.  E.g. it contains
908 a directory that is some process's working directory or a file that some
909 process has open.  With some filesystems in some cases, you can avoid
910 this failure with the @code{MNT_FORCE} option.
911
912 @item EINVAL
913 @var{file} validly refers to a file, but that file is neither a mount
914 point nor a device special file of a currently mounted filesystem.
915
916 @end table
917
918 This function is not available on all systems.
919 @end deftypefun
920
921 @comment sys/mount.h
922 @comment SVID, GNU
923 @deftypefun {int} umount (const char *@var{file})
924
925 @code{umount} does the same thing as @code{umount2} with @var{flags} set
926 to zeroes.  It is more widely available than @code{umount2} but since it
927 lacks the possibility to forcefully unmount a filesystem is deprecated
928 when @code{umount2} is also available.
929 @end deftypefun