fdwalk should return 0 on an empty directory
[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 * Platform Type::               Determining operating system and basic
15                                   machine type
16 * Filesystem Handling::         Controlling/querying mounts
17 * System Parameters::           Getting and setting various system parameters
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 system on which your
28 program is running.  First, let's review the various ways computer systems
29 are named, which is a little complicated because of the history of the
30 development of the Internet.
31
32 Every Unix system (also known as a host) has a host name, whether it's
33 connected to a network or not.  In its simplest form, as used before
34 computer networks were an issue, it's just a word like @samp{chicken}.
35 @cindex host name
36
37 But any system attached to the Internet or any network like it conforms
38 to a more rigorous naming convention as part of the Domain Name System
39 (DNS).  In DNS, every host name is composed of two parts:
40 @cindex DNS
41 @cindex Domain Name System
42
43 @enumerate
44 @item
45 hostname
46 @cindex hostname
47 @item
48 domain name
49 @cindex domain name
50 @end enumerate
51
52 You will note that ``hostname'' looks a lot like ``host name'', but is
53 not the same thing, and that people often incorrectly refer to entire
54 host names as ``domain names.''
55
56 In DNS, the full host name is properly called the FQDN (Fully Qualified
57 Domain Name) and consists of the hostname, then a period, then the
58 domain name.  The domain name itself usually has multiple components
59 separated by periods.  So for example, a system's hostname may be
60 @samp{chicken} and its domain name might be @samp{ai.mit.edu}, so
61 its FQDN (which is its host name) is @samp{chicken.ai.mit.edu}.
62 @cindex FQDN
63
64 Adding to the confusion, though, is that DNS is not the only name space
65 in which a computer needs to be known.  Another name space is the
66 NIS (aka YP) name space.  For NIS purposes, there is another domain
67 name, which is called the NIS domain name or the YP domain name.  It
68 need not have anything to do with the DNS domain name.
69 @cindex YP
70 @cindex NIS
71 @cindex NIS domain name
72 @cindex YP domain name
73
74 Confusing things even more is the fact that in DNS, it is possible for
75 multiple FQDNs to refer to the same system.  However, there is always
76 exactly one of them that is the true host name, and it is called the
77 canonical FQDN.
78
79 In some contexts, the host name is called a ``node name.''
80
81 For more information on DNS host naming, @xref{Host Names}.
82
83 @pindex hostname
84 @pindex hostid
85 @pindex unistd.h
86 Prototypes for these functions appear in @file{unistd.h}.
87
88 The programs @code{hostname}, @code{hostid}, and @code{domainname} work
89 by calling these functions.
90
91 @comment unistd.h
92 @comment BSD
93 @deftypefun int gethostname (char *@var{name}, size_t @var{size})
94 This function returns the host name of the system on which it is called,
95 in the array @var{name}.  The @var{size} argument specifies the size of
96 this array, in bytes.  Note that this is @emph{not} the DNS hostname.
97 If the system participates in DNS, this is the FQDN (see above).
98
99 The return value is @code{0} on success and @code{-1} on failure.  In
100 the GNU C library, @code{gethostname} fails if @var{size} is not large
101 enough; then you can try again with a larger array.  The following
102 @code{errno} error condition is defined for this function:
103
104 @table @code
105 @item ENAMETOOLONG
106 The @var{size} argument is less than the size of the host name plus one.
107 @end table
108
109 @pindex sys/param.h
110 On some systems, there is a symbol for the maximum possible host name
111 length: @code{MAXHOSTNAMELEN}.  It is defined in @file{sys/param.h}.
112 But you can't count on this to exist, so it is cleaner to handle
113 failure and try again.
114
115 @code{gethostname} stores the beginning of the host name in @var{name}
116 even if the host name won't entirely fit.  For some purposes, a
117 truncated host name is good enough.  If it is, you can ignore the
118 error code.
119 @end deftypefun
120
121 @comment unistd.h
122 @comment BSD
123 @deftypefun int sethostname (const char *@var{name}, size_t @var{length})
124 The @code{sethostname} function sets the host name of the system that
125 calls it to @var{name}, a string with length @var{length}.  Only
126 privileged processes are permitted to do this.
127
128 Usually @code{sethostname} gets called just once, at system boot time.
129 Often, the program that calls it sets it to the value it finds in the
130 file @code{/etc/hostname}.
131 @cindex /etc/hostname
132
133 Be sure to set the host name to the full host name, not just the DNS
134 hostname (see above).
135
136 The return value is @code{0} on success and @code{-1} on failure.
137 The following @code{errno} error condition is defined for this function:
138
139 @table @code
140 @item EPERM
141 This process cannot set the host name because it is not privileged.
142 @end table
143 @end deftypefun
144
145 @comment unistd.h
146 @comment ???
147 @deftypefun int getdomainnname (char *@var{name}, size_t @var{length})
148 @cindex NIS domain name
149 @cindex YP domain name
150
151 @code{getdomainname} returns the NIS (aka YP) domain name of the system
152 on which it is called.  Note that this is not the more popular DNS
153 domain name.  Get that with @code{gethostname}.
154
155 The specifics of this function are analogous to @code{gethostname}, above.
156
157 @end deftypefun
158
159 @comment unistd.h
160 @comment ???
161 @deftypefun int setdomainname (const char *@var{name}, size_t @var{length})
162 @cindex NIS domain name
163 @cindex YP domain name
164
165 @code{getdomainname} sets the NIS (aka YP) domain name of the system
166 on which it is called.  Note that this is not the more popular DNS
167 domain name.  Set that with @code{sethostname}.
168
169 The specifics of this function are analogous to @code{sethostname}, above.
170
171 @end deftypefun
172
173 @comment unistd.h
174 @comment BSD
175 @deftypefun {long int} gethostid (void)
176 This function returns the ``host ID'' of the machine the program is
177 running on.  By convention, this is usually the primary Internet IP address
178 of that machine, converted to a @w{@code{long int}}.  However, on some
179 systems it is a meaningless but unique number which is hard-coded for
180 each machine.
181
182 This is not widely used.  It arose in BSD 4.2, but was dropped in BSD 4.4.
183 It is not required by POSIX.
184
185 The proper way to query the IP address is to use @code{gethostbyname}
186 on the results of @code{gethostname}.  For more information on IP addresses,
187 @xref{Host Addresses}.
188 @end deftypefun
189
190 @comment unistd.h
191 @comment BSD
192 @deftypefun int sethostid (long int @var{id})
193 The @code{sethostid} function sets the ``host ID'' of the host machine
194 to @var{id}.  Only privileged processes are permitted to do this.  Usually
195 it happens just once, at system boot time.
196
197 The proper way to establish the primary IP address of a system
198 is to configure the IP address resolver to associate that IP address with
199 the system's host name as returned by @code{gethostname}.  For example,
200 put a record for the system in @file{/etc/hosts}.
201
202 See @code{gethostid} above for more information on host ids.
203
204 The return value is @code{0} on success and @code{-1} on failure.
205 The following @code{errno} error conditions are defined for this function:
206
207 @table @code
208 @item EPERM
209 This process cannot set the host name because it is not privileged.
210
211 @item ENOSYS
212 The operating system does not support setting the host ID.  On some
213 systems, the host ID is a meaningless but unique number hard-coded for
214 each machine.
215 @end table
216 @end deftypefun
217
218 @node Platform Type
219 @section Platform Type Identification
220
221 You can use the @code{uname} function to find out some information about
222 the type of computer your program is running on.  This function and the
223 associated data type are declared in the header file
224 @file{sys/utsname.h}.
225 @pindex sys/utsname.h
226
227 As a bonus, @code{uname} also gives some information identifying the
228 particular system your program is running on.  This is the same information
229 which you can get with functions targetted to this purpose described in
230 @ref{Host Identification}.
231
232
233 @comment sys/utsname.h
234 @comment POSIX.1
235 @deftp {Data Type} {struct utsname}
236 The @code{utsname} structure is used to hold information returned
237 by the @code{uname} function.  It has the following members:
238
239 @table @code
240 @item char sysname[]
241 This is the name of the operating system in use.
242
243 @item char release[]
244 This is the current release level of the operating system implementation.
245
246 @item char version[]
247 This is the current version level within the release of the operating
248 system.
249
250 @item char machine[]
251 This is a description of the type of hardware that is in use.
252
253 Some systems provide a mechanism to interrogate the kernel directly for
254 this information.  On systems without such a mechanism, the GNU C
255 library fills in this field based on the configuration name that was
256 specified when building and installing the library.
257
258 GNU uses a three-part name to describe a system configuration; the three
259 parts are @var{cpu}, @var{manufacturer} and @var{system-type}, and they
260 are separated with dashes.  Any possible combination of three names is
261 potentially meaningful, but most such combinations are meaningless in
262 practice and even the meaningful ones are not necessarily supported by
263 any particular GNU program.
264
265 Since the value in @code{machine} is supposed to describe just the
266 hardware, it consists of the first two parts of the configuration name:
267 @samp{@var{cpu}-@var{manufacturer}}.  For example, it might be one of these:
268
269 @quotation
270 @code{"sparc-sun"},
271 @code{"i386-@var{anything}"},
272 @code{"m68k-hp"},
273 @code{"m68k-sony"},
274 @code{"m68k-sun"},
275 @code{"mips-dec"}
276 @end quotation
277
278 @item char nodename[]
279 This is the host name of this particular computer.  In the GNU C
280 library, the value is the same as that returned by @code{gethostname};
281 see @ref{Host Identification}.
282
283 @ gethostname() is implemented with a call to uname().
284
285 @item char domainname[]
286 This is the NIS or YP domain name.  It is the same value returned by
287 @code{getdomainname}; see @ref{Host Identification}.  This element
288 is a relatively recent invention and use of it is not as portable as
289 use of the rest of the structure.
290
291 @c getdomainname() is implemented with a call to uname().
292
293 @end table
294 @end deftp
295
296 @comment sys/utsname.h
297 @comment POSIX.1
298 @deftypefun int uname (struct utsname *@var{info})
299 The @code{uname} function fills in the structure pointed to by
300 @var{info} with information about the operating system and host machine.
301 A non-negative value indicates that the data was successfully stored.
302
303 @code{-1} as the value indicates an error.  The only error possible is
304 @code{EFAULT}, which we normally don't mention as it is always a
305 possibility.
306 @end deftypefun
307
308
309 @node Filesystem Handling
310 @section Controlling and Querying Mounts
311
312 All files are in filesystems, and before you can access any file, its
313 filesystem must be mounted.  Because of Unix's concept of
314 @emph{Everything is a file}, mounting of filesystems is central to doing
315 almost anything.  This section explains how to find out what filesystems
316 are currently mounted and what filesystems are available for mounting,
317 and how to change what is mounted.
318
319 The classic filesystem is the contents of a disk drive.  The concept is
320 considerably more abstract, though, and lots of things other than disk
321 drives can be mounted.
322
323 Some block devices don't correspond to traditional devices like disk
324 drives.  For example, a loop device is a block device whose driver uses
325 a regular file in another filesystem as its medium.  So if that regular
326 file contains appropriate data for a filesystem, you can by mounting the
327 loop device essentially mount a regular file.
328
329 Some filesystems aren't based on a device of any kind.  The ``proc''
330 filesystem, for example, contains files whose data is made up by the
331 filesystem driver on the fly whenever you ask for it.  And when you
332 write to it, the data you write causes changes in the system.  No data
333 gets stored.
334
335 @c It would be good to mention NFS mounts here.
336
337 @menu
338 * Mount Information::           What is or could be mounted?
339 * Mount-Unmount-Remount::       Controlling what is mounted and how
340 @end menu
341
342 @node Mount Information, Mount-Unmount-Remount, , Filesystem Handling
343 @subsection Mount Information
344
345 For some programs it is desirable and necessary to access information
346 about whether a certain filesystem is mounted and, if it is, where, or
347 simply to get lists of all the available filesystems.  The GNU libc
348 provides some functions to retrieve this information portably.
349
350 Traditionally Unix systems have a file named @file{/etc/fstab} which
351 describes all possibly mounted filesystems.  The @code{mount} program
352 uses this file to mount at startup time of the system all the
353 necessary filesystems.  The information about all the filesystems
354 actually mounted is normally kept in a file named either
355 @file{/var/run/mtab} or @file{/etc/mtab}.  Both files share the same
356 syntax and it is crucial that this syntax is followed all the time.
357 Therefore it is best to never directly write the files.  The functions
358 described in this section can do this and they also provide the
359 functionality to convert the external textual representation to the
360 internal representation.
361
362 Note that the @file{fstab} and @file{mtab} files are maintained on a
363 system by @emph{convention}.  It is possible for the files not to exist
364 or not to be consistent with what is really mounted or available to
365 mount, if the system's administration policy allows it.  But programs
366 that mount and unmount filesystems typically maintain and use these
367 files as described herein.
368
369 @vindex _PATH_FSTAB
370 @vindex _PATH_MNTTAB
371 @vindex _PATH_MOUNTED
372 @vindex FSTAB
373 @vindex MNTTAB
374 @vindex MOUNTED
375 The filenames given above should never be used directly.  The portable
376 way to handle these file is to use the macro @code{_PATH_FSTAB},
377 defined in @file{fstab.h}, or @code{_PATH_MNTTAB}, defined in
378 @file{mntent.h} and @file{paths.h}, for @file{fstab}; and the macro
379 @code{_PATH_MOUNTED}, also defined in @file{mntent.h} and
380 @file{paths.h}, for @file{mtab}.  There are also two alternate macro
381 names @code{FSTAB}, @code{MNTTAB}, and @code{MOUNTED} defined but
382 these names are deprecated and kept only for backward compatibility.
383 The names @code{_PATH_MNTTAB} and @code{_PATH_MOUNTED} should always be used.
384
385 @menu
386 * fstab::                       The @file{fstab} file
387 * mtab::                        The @file{mtab} file
388 * Other Mount Information::     Other (non-libc) sources of mount information
389 @end menu
390
391 @node fstab
392 @subsubsection The @file{fstab} file
393
394 The internal representation for entries of the file is @w{@code{struct
395 fstab}}, defined in @file{fstab.h}.
396
397 @comment fstab.h
398 @comment BSD
399 @deftp {Data Type} {struct fstab}
400 This structure is used with the @code{getfsent}, @code{getfsspec}, and
401 @code{getfsfile} functions.
402
403 @table @code
404 @item char *fs_spec
405 This element describes the device from which the filesystem is mounted.
406 Normally this is the name of a special device, such as a hard disk
407 partition, but it could also be a more or less generic string.  For
408 @dfn{NFS} it would be a hostname and directory name combination.
409
410 Even though the element is not declared @code{const} it shouldn't be
411 modified.  The missing @code{const} has historic reasons, since this
412 function predates @w{ISO C}.  The same is true for the other string
413 elements of this structure.
414
415 @item char *fs_file
416 This describes the mount point on the local system.  I.e., accessing any
417 file in this filesystem has implicitly or explicitly this string as a
418 prefix.
419
420 @item char *fs_vfstype
421 This is the type of the filesystem.  Depending on what the underlying
422 kernel understands it can be any string.
423
424 @item char *fs_mntops
425 This is a string containing options passed to the kernel with the
426 @code{mount} call.  Again, this can be almost anything.  There can be
427 more than one option, separated from the others by a comma.  Each option
428 consists of a name and an optional value part, introduced by an @code{=}
429 character.
430
431 If the value of this element must be processed it should ideally be done
432 using the @code{getsubopt} function; see @ref{Suboptions}.
433
434 @item const char *fs_type
435 This name is poorly chosen.  This element points to a string (possibly
436 in the @code{fs_mntops} string) which describes the modes with which the
437 filesystem is mounted.  @file{fstab} defines five macros to describe the
438 possible values:
439
440 @vtable @code
441 @item FSTAB_RW
442 The filesystems gets mounted with read and write enabled.
443 @item FSTAB_RQ
444 The filesystems gets mounted with read and write enabled.  Write access
445 is restricted by quotas.
446 @item FSTAB_RO
447 The filesystem gets mounted read-only.
448 @item FSTAB_SW
449 This is not a real filesystem, it is a swap device.
450 @item FSTAB_XX
451 This entry from the @file{fstab} file is totally ignored.
452 @end vtable
453
454 Testing for equality with these value must happen using @code{strcmp}
455 since these are all strings.  Comparing the pointer will probably always
456 fail.
457
458 @item int fs_freq
459 This element describes the dump frequency in days.
460
461 @item int fs_passno
462 This element describes the pass number on parallel dumps.  It is closely
463 related to the @code{dump} utility used on Unix systems.
464 @end table
465 @end deftp
466
467
468 To read the entire content of the of the @file{fstab} file the GNU libc
469 contains a set of three functions which are designed in the usual way.
470
471 @comment fstab.h
472 @comment BSD
473 @deftypefun int setfsent (void)
474 This function makes sure that the internal read pointer for the
475 @file{fstab} file is at the beginning of the file.  This is done by
476 either opening the file or resetting the read pointer.
477
478 Since the file handle is internal to the libc this function is not
479 thread-safe.
480
481 This function returns a non-zero value if the operation was successful
482 and the @code{getfs*} functions can be used to read the entries of the
483 file.
484 @end deftypefun
485
486 @comment fstab.h
487 @comment BSD
488 @deftypefun void endfsent (void)
489 This function makes sure that all resources acquired by a prior call to
490 @code{setfsent} (explicitly or implicitly by calling @code{getfsent}) are
491 freed.
492 @end deftypefun
493
494 @comment fstab.h
495 @comment BSD
496 @deftypefun {struct fstab *} getfsent (void)
497 This function returns the next entry of the @file{fstab} file.  If this
498 is the first call to any of the functions handling @file{fstab} since
499 program start or the last call of @code{endfsent}, the file will be
500 opened.
501
502 The function returns a pointer to a variable of type @code{struct
503 fstab}.  This variable is shared by all threads and therefore this
504 function is not thread-safe.  If an error occurred @code{getfsent}
505 returns a @code{NULL} pointer.
506 @end deftypefun
507
508 @comment fstab.h
509 @comment BSD
510 @deftypefun {struct fstab *} getfsspec (const char *@var{name})
511 This function returns the next entry of the @file{fstab} file which has
512 a string equal to @var{name} pointed to by the @code{fs_spec} element.
513 Since there is normally exactly one entry for each special device it
514 makes no sense to call this function more than once for the same
515 argument.  If this is the first call to any of the functions handling
516 @file{fstab} since program start or the last call of @code{endfsent},
517 the file will be opened.
518
519 The function returns a pointer to a variable of type @code{struct
520 fstab}.  This variable is shared by all threads and therefore this
521 function is not thread-safe.  If an error occurred @code{getfsent}
522 returns a @code{NULL} pointer.
523 @end deftypefun
524
525 @comment fstab.h
526 @comment BSD
527 @deftypefun {struct fstab *} getfsfile (const char *@var{name})
528 This function returns the next entry of the @file{fstab} file which has
529 a string equal to @var{name} pointed to by the @code{fs_file} element.
530 Since there is normally exactly one entry for each mount point it
531 makes no sense to call this function more than once for the same
532 argument.  If this is the first call to any of the functions handling
533 @file{fstab} since program start or the last call of @code{endfsent},
534 the file will be opened.
535
536 The function returns a pointer to a variable of type @code{struct
537 fstab}.  This variable is shared by all threads and therefore this
538 function is not thread-safe.  If an error occurred @code{getfsent}
539 returns a @code{NULL} pointer.
540 @end deftypefun
541
542
543 @node mtab
544 @subsubsection The @file{mtab} file
545 The following functions and data structure access the @file{mtab} file.
546
547 @comment mntent.h
548 @comment BSD
549 @deftp {Data Type} {struct mntent}
550 This structure is used with the @code{getmntent}, @code{getmntent_t},
551 @code{addmntent}, and @code{hasmntopt} functions.
552
553 @table @code
554 @item char *mnt_fsname
555 This element contains a pointer to a string describing the name of the
556 special device from which the filesystem is mounted.  It corresponds to
557 the @code{fs_spec} element in @code{struct fstab}.
558
559 @item char *mnt_dir
560 This element points to a string describing the mount point of the
561 filesystem.  It corresponds to the @code{fs_file} element in
562 @code{struct fstab}.
563
564 @item char *mnt_type
565 @code{mnt_type} describes the filesystem type and is therefore
566 equivalent to @code{fs_vfstype} in @code{struct fstab}.  @file{mntent.h}
567 defines a few symbolic names for some of the values this string can have.
568 But since the kernel can support arbitrary filesystems it does not
569 make much sense to give them symbolic names.  If one knows the symbol
570 name one also knows the filesystem name.  Nevertheless here follows the
571 list of the symbols provided in @file{mntent.h}.
572
573 @vtable @code
574 @item MNTTYPE_IGNORE
575 This symbol expands to @code{"ignore"}.  The value is sometime used in
576 @file{fstab} files to make sure entries are not used without removing them.
577 @item MNTTYPE_NFS
578 Expands to @code{"nfs"}.  Using this macro sometimes could make sense
579 since it names the default NFS implementation, in case both version 2
580 and 3 are supported.
581 @item MNTTYPE_SWAP
582 This symbol expands to @code{"swap"}.  It names the special @file{fstab}
583 entry which names one of the possibly multiple swap partitions.
584 @end vtable
585
586 @item char *mnt_opts
587 The element contains a string describing the options used while mounting
588 the filesystem.  As for the equivalent element @code{fs_mntops} of
589 @code{struct fstab} it is best to use the function @code{getsubopt}
590 (@pxref{Suboptions}) to access the parts of this string.
591
592 The @file{mntent.h} file defines a number of macros with string values
593 which correspond to some of the options understood by the kernel.  There
594 might be many more options which are possible so it doesn't make much sense
595 to rely on these macros but to be consistent here is the list:
596
597 @vtable @code
598 @item MNTOPT_DEFAULTS
599 Expands to @code{"defaults"}.  This option should be used alone since it
600 indicates all values for the customizable values are chosen to be the
601 default.
602 @item MNTOPT_RO
603 Expands to @code{"ro"}.  See the @code{FSTAB_RO} value, it means the
604 filesystem is mounted read-only.
605 @item MNTOPT_RW
606 Expand to @code{"rw"}.  See the @code{FSTAB_RW} value, it means the
607 filesystem is mounted with read and write permissions.
608 @item MNTOPT_SUID
609 Expands to @code{"suid"}.  This means that the SUID bit (@pxref{How
610 Change Persona}) is respected when a program from the filesystem is
611 started.
612 @item MNTOPT_NOSUID
613 Expands to @code{"nosuid"}.  This is the opposite of @code{MNTOPT_SUID},
614 the SUID bit for all files from the filesystem is ignored.
615 @item MNTOPT_NOAUTO
616 Expands to @code{"noauto"}.  At startup time the @code{mount} program
617 will ignore this entry if it is started with the @code{-a} option to
618 mount all filesystems mentioned in the @file{fstab} file.
619 @end vtable
620
621 As for the @code{FSTAB_*} entries introduced above it is important to
622 use @code{strcmp} to check for equality.
623
624 @item mnt_freq
625 This elements corresponds to @code{fs_freq} and also specifies the
626 frequency in days in which dumps are made.
627
628 @item mnt_passno
629 This element is equivalent to @code{fs_passno} with the same meaning
630 which is uninteresting for all programs beside @code{dump}.
631 @end table
632 @end deftp
633
634 For accessing the @file{mtab} file there is again a set of three
635 functions to access all entries in a row.  Unlike the functions to
636 handle @file{fstab} these functions do not access a fixed file and there
637 is even a thread safe variant of the get function.  Beside this the GNU
638 libc contains functions to alter the file and test for specific options.
639
640 @comment mntent.h
641 @comment BSD
642 @deftypefun {FILE *} setmntent (const char *@var{file}, const char *@var{mode})
643 The @code{setmntent} function prepares the file named @var{FILE} which
644 must be in the format of a @file{fstab} and @file{mtab} file for the
645 upcoming processing through the other functions of the family.  The
646 @var{mode} parameter can be chosen in the way the @var{opentype}
647 parameter for @code{fopen} (@pxref{Opening Streams}) can be chosen.  If
648 the file is opened for writing the file is also allowed to be empty.
649
650 If the file was successfully opened @code{setmntent} returns a file
651 descriptor for future use.  Otherwise the return value is @code{NULL}
652 and @code{errno} is set accordingly.
653 @end deftypefun
654
655 @comment mntent.h
656 @comment BSD
657 @deftypefun int endmntent (FILE *@var{stream})
658 This function takes for the @var{stream} parameter a file handle which
659 previously was returned from the @code{setmntent} call.
660 @code{endmntent} closes the stream and frees all resources.
661
662 The return value is @math{1} unless an error occurred in which case it
663 is @math{0}.
664 @end deftypefun
665
666 @comment mntent.h
667 @comment BSD
668 @deftypefun {struct mntent *} getmntent (FILE *@var{stream})
669 The @code{getmntent} function takes as the parameter a file handle
670 previously returned by successful call to @code{setmntent}.  It returns
671 a pointer to a static variable of type @code{struct mntent} which is
672 filled with the information from the next entry from the file currently
673 read.
674
675 The file format used prescribes the use of spaces or tab characters to
676 separate the fields.  This makes it harder to use name containing one
677 of these characters (e.g., mount points using spaces).  Therefore
678 these characters are encoded in the files and the @code{getmntent}
679 function takes care of the decoding while reading the entries back in.
680 @code{'\040'} is used to encode a space character, @code{'\011'} to
681 encode a tab character, @code{'\012'} to encode a newline character,
682 and @code{'\\'} to encode a backslash.
683
684 If there was an error or the end of the file is reached the return value
685 is @code{NULL}.
686
687 This function is not thread-safe since all calls to this function return
688 a pointer to the same static variable.  @code{getmntent_r} should be
689 used in situations where multiple threads access the file.
690 @end deftypefun
691
692 @comment mntent.h
693 @comment BSD
694 @deftypefun {struct mntent *} getmntent_r (FILE *@var{stream}, struct mentent *@var{result}, char *@var{buffer}, int @var{bufsize})
695 The @code{getmntent_r} function is the reentrant variant of
696 @code{getmntent}.  It also returns the next entry from the file and
697 returns a pointer.  The actual variable the values are stored in is not
698 static, though.  Instead the function stores the values in the variable
699 pointed to by the @var{result} parameter.  Additional information (e.g.,
700 the strings pointed to by the elements of the result) are kept in the
701 buffer of size @var{bufsize} pointed to by @var{buffer}.
702
703 Escaped characters (space, tab, backslash) are converted back in the
704 same way as it happens for @code{getmentent}.
705
706 The function returns a @code{NULL} pointer in error cases.  Errors could be:
707 @itemize @bullet
708 @item
709 error while reading the file,
710 @item
711 end of file reached,
712 @item
713 @var{bufsize} is too small for reading a complete new entry.
714 @end itemize
715 @end deftypefun
716
717 @comment mntent.h
718 @comment BSD
719 @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt})
720 The @code{addmntent} function allows adding a new entry to the file
721 previously opened with @code{setmntent}.  The new entries are always
722 appended.  I.e., even if the position of the file descriptor is not at
723 the end of the file this function does not overwrite an existing entry
724 following the current position.
725
726 The implication of this is that to remove an entry from a file one has
727 to create a new file while leaving out the entry to be removed and after
728 closing the file remove the old one and rename the new file to the
729 chosen name.
730
731 This function takes care of spaces and tab characters in the names to be
732 written to the file.  It converts them and the backslash character into
733 the format describe in the @code{getmntent} description above.
734
735 This function returns @math{0} in case the operation was successful.
736 Otherwise the return value is @math{1} and @code{errno} is set
737 appropriately.
738 @end deftypefun
739
740 @comment mntent.h
741 @comment BSD
742 @deftypefun {char *} hasmntopt (const struct mntent *@var{mnt}, const char *@var{opt})
743 This function can be used to check whether the string pointed to by the
744 @code{mnt_opts} element of the variable pointed to by @var{mnt} contains
745 the option @var{opt}.  If this is true a pointer to the beginning of the
746 option in the @code{mnt_opts} element is returned.  If no such option
747 exists the function returns @code{NULL}.
748
749 This function is useful to test whether a specific option is present but
750 when all options have to be processed one is better off with using the
751 @code{getsubopt} function to iterate over all options in the string.
752 @end deftypefun
753
754 @node Other Mount Information
755 @subsubsection Other (Non-libc) Sources of Mount Information
756
757 On a system with a Linux kernel and the @code{proc} filesystem, you can
758 get information on currently mounted filesystems from the file
759 @file{mounts} in the @code{proc} filesystem.  Its format is similar to
760 that of the @file{mtab} file, but represents what is truly mounted
761 without relying on facilities outside the kernel to keep @file{mtab} up
762 to date.
763
764
765 @node Mount-Unmount-Remount, , Mount Information, Filesystem Handling
766 @subsection Mount, Unmount, Remount
767
768 This section describes the functions for mounting, unmounting, and
769 remounting filesystems.
770
771 Only the superuser can mount, unmount, or remount a filesystem.
772
773 These functions do not access the @file{fstab} and @file{mtab} files.  You
774 should maintain and use these separately.  @xref{Mount Information}.
775
776 The symbols in this section are declared in @file{sys/mount.h}.
777
778 @comment sys/mount.h
779 @comment SVID, BSD
780 @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})
781
782 @code{mount} mounts or remounts a filesystem.  The two operations are
783 quite different and are merged rather unnaturally into this one function.
784 The @code{MS_REMOUNT} option, explained below, determines whether
785 @code{mount} mounts or remounts.
786
787 For a mount, the filesystem on the block device represented by the
788 device special file named @var{special_file} gets mounted over the mount
789 point @var{dir}.  This means that the directory @var{dir} (along with any
790 files in it) is no longer visible; in its place (and still with the name
791 @var{dir}) is the root directory of the filesystem on the device.
792
793 As an exception, if the filesystem type (see below) is one which is not
794 based on a device (e.g. ``proc''), @code{mount} instantiates a
795 filesystem and mounts it over @var{dir} and ignores @var{special_file}.
796
797 For a remount, @var{dir} specifies the mount point where the filesystem
798 to be remounted is (and remains) mounted and @var{special_file} is
799 ignored.  Remounting a filesystem means changing the options that control
800 operations on the filesystem while it is mounted.  It does not mean
801 unmounting and mounting again.
802
803 For a mount, you must identify the type of the filesystem as
804 @var{fstype}.  This type tells the kernel how to access the filesystem
805 and can be thought of as the name of a filesystem driver.  The
806 acceptable values are system dependent.  On a system with a Linux kernel
807 and the @code{proc} filesystem, the list of possible values is in the
808 file @file{filesystems} in the @code{proc} filesystem (e.g. type
809 @kbd{cat /proc/filesystems} to see the list).  With a Linux kernel, the
810 types of filesystems that @code{mount} can mount, and their type names,
811 depends on what filesystem drivers are configured into the kernel or
812 loaded as loadable kernel modules.  An example of a common value for
813 @var{fstype} is @code{ext2}.
814
815 For a remount, @code{mount} ignores @var{fstype}.
816
817 @c This is traditionally called "rwflag" for historical reasons.
818 @c No point in confusing people today, though.
819 @var{options} specifies a variety of options that apply until the
820 filesystem is unmounted or remounted.  The precise meaning of an option
821 depends on the filesystem and with some filesystems, an option may have
822 no effect at all.  Furthermore, for some filesystems, some of these
823 options (but never @code{MS_RDONLY}) can be overridden for individual
824 file accesses via @code{ioctl}.
825
826 @var{options} is a bit string with bit fields defined using the
827 following mask and masked value macros:
828
829 @table @code
830 @item MS_MGC_MASK
831 This multibit field contains a magic number.  If it does not have the value
832 @code{MS_MGC_VAL}, @code{mount} assumes all the following bits are zero and
833 the @var{data} argument is a null string, regardless of their actual values.
834
835 @item MS_REMOUNT
836 This bit on means to remount the filesystem.  Off means to mount it.
837 @c There is a mask MS_RMT_MASK in mount.h that says only two of the options
838 @c can be reset by remount.  But the Linux kernel has its own version of
839 @c MS_RMT_MASK that says they all can be reset.  As far as I can tell,
840 @c libc just passes the arguments straight through to the kernel.
841
842 @item MS_RDONLY
843 This bit on specifies that no writing to the filesystem shall be allowed
844 while it is mounted.  This cannot be overridden by @code{ioctl}.  This
845 option is available on nearly all filesystems.
846
847 @item S_IMMUTABLE
848 This bit on specifies that no writing to the files in the filesystem
849 shall be allowed while it is mounted.  This can be overridden for a
850 particular file access by a properly privileged call to @code{ioctl}.
851 This option is a relatively new invention and is not available on many
852 filesystems.
853
854 @item S_APPEND
855 This bit on specifies that the only file writing that shall be allowed
856 while the filesystem is mounted is appending.  Some filesystems allow
857 this to be overridden for a particular process by a properly privileged
858 call to @code{ioctl}.  This is a relatively new invention and is not
859 available on many filesystems.
860
861 @item MS_NOSUID
862 This bit on specifies that Setuid and Setgid permissions on files in the
863 filesystem shall be ignored while it is mounted.
864
865 @item MS_NOEXEC
866 This bit on specifies that no files in the filesystem shall be executed
867 while the filesystem is mounted.
868
869 @item MS_NODEV
870 This bit on specifies that no device special files in the filesystem
871 shall be accessible while the filesystem is mounted.
872
873 @item MS_SYNCHRONOUS
874 This bit on specifies that all writes to the filesystem while it is
875 mounted shall be synchronous; i.e., data shall be synced before each
876 write completes rather than held in the buffer cache.
877
878 @item MS_MANDLOCK
879 This bit on specifies that mandatory locks on files shall be permitted while
880 the filesystem is mounted.
881
882 @item MS_NOATIME
883 This bit on specifies that access times of files shall not be updated when
884 the files are accessed while the filesystem is mounted.
885
886 @item MS_NODIRATIME
887 This bit on specifies that access times of directories shall not be updated
888 when the directories are accessed while the filesystem in mounted.
889
890 @c there is also S_QUOTA Linux fs.h (mount.h still uses its former name
891 @c S_WRITE), but I can't see what it does.  Turns on quotas, I guess.
892
893 @end table
894
895 Any bits not covered by the above masks should be set off; otherwise,
896 results are undefined.
897
898 The meaning of @var{data} depends on the filesystem type and is controlled
899 entirely by the filesystem driver in the kernel.
900
901 Example:
902
903 @smallexample
904 @group
905 #include <sys/mount.h>
906
907 mount("/dev/hdb", "/cdrom", MS_MGC_VAL | MS_RDONLY | MS_NOSUID, "");
908
909 mount("/dev/hda2", "/mnt", MS_MGC_VAL | MS_REMOUNT, "");
910
911 @end group
912 @end smallexample
913
914 Appropriate arguments for @code{mount} are conventionally recorded in
915 the @file{fstab} table.  @xref{Mount Information}.
916
917 The return value is zero if the mount or remount is successful.  Otherwise,
918 it is @code{-1} and @code{errno} is set appropriately.  The values of
919 @code{errno} are filesystem dependent, but here is a general list:
920
921 @table @code
922 @item EPERM
923 The process is not superuser.
924 @item ENODEV
925 The file system type @var{fstype} is not known to the kernel.
926 @item ENOTBLK
927 The file @var{dev} is not a block device special file.
928 @item EBUSY
929
930 @itemize @bullet
931
932 @item
933 The device is already mounted.
934
935 @item
936 The mount point is busy.  (E.g. it is some process' working directory or
937 has a filesystem mounted on it already).
938
939 @item
940 The request is to remount read-only, but there are files open for write.
941 @end itemize
942
943 @item EINVAL
944 @itemize @bullet
945
946 @item
947 A remount was attempted, but there is no filesystem mounted over the
948 specified mount point.
949
950 @item
951 The supposed filesystem has an invalid superblock.
952
953 @end itemize
954
955 @item EACCES
956 @itemize @bullet
957
958 @item
959 The filesystem is inherently read-only (possibly due to a switch on the
960 device) and the process attempted to mount it read/write (by setting the
961 @code{MS_RDONLY} bit off).
962
963 @item
964 @var{special_file} or @var{dir} is not accessible due to file permissions.
965
966 @item
967 @var{special_file} is not accessible because it is in a filesystem that is
968 mounted with the @code{MS_NODEV} option.
969
970 @end itemize
971
972 @item EM_FILE
973 The table of dummy devices is full.  @code{mount} needs to create a
974 dummy device (aka ``unnamed'' device) if the filesystem being mounted is
975 not one that uses a device.
976
977 @end table
978
979 @end deftypefun
980
981
982 @comment sys/mount.h
983 @comment GNU
984 @deftypefun {int} umount2 (const char *@var{file}, int @var{flags})
985
986 @code{umount2} unmounts a filesystem.
987
988 You can identify the filesystem to unmount either by the device special
989 file that contains the filesystem or by the mount point.  The effect is
990 the same.  Specify either as the string @var{file}.
991
992 @var{flags} contains the one-bit field identified by the following
993 mask macro:
994
995 @table @code
996
997 @item MNT_FORCE
998 This bit on means to force the unmounting even if the filesystem is
999 busy, by making it unbusy first.  If the bit is off and the filesystem is
1000 busy, @code{umount2} fails with @code{errno} = @code{EBUSY}.  Depending
1001 on the filesystem, this may override all, some, or no busy conditions.
1002
1003 @end table
1004
1005 All other bits in @var{flags} should be set to zero; otherwise, the result
1006 is undefined.
1007
1008 Example:
1009
1010 @smallexample
1011 @group
1012 #include <sys/mount.h>
1013
1014 umount2("/mnt", MNT_FORCE);
1015
1016 umount2("/dev/hdd1", 0);
1017
1018 @end group
1019 @end smallexample
1020
1021 After the filesystem is unmounted, the directory that was the mount point
1022 is visible, as are any files in it.
1023
1024 As part of unmounting, @code{umount2} syncs the filesystem.
1025
1026 If the unmounting is successful, the return value is zero.  Otherwise, it
1027 is @code{-1} and @code{errno} is set accordingly:
1028
1029 @table @code
1030 @item EPERM
1031 The process is not superuser.
1032 @item EBUSY
1033 The filesystem cannot be unmounted because it is busy.  E.g. it contains
1034 a directory that is some process's working directory or a file that some
1035 process has open.  With some filesystems in some cases, you can avoid
1036 this failure with the @code{MNT_FORCE} option.
1037
1038 @item EINVAL
1039 @var{file} validly refers to a file, but that file is neither a mount
1040 point nor a device special file of a currently mounted filesystem.
1041
1042 @end table
1043
1044 This function is not available on all systems.
1045 @end deftypefun
1046
1047 @comment sys/mount.h
1048 @comment SVID, GNU
1049 @deftypefun {int} umount (const char *@var{file})
1050
1051 @code{umount} does the same thing as @code{umount2} with @var{flags} set
1052 to zeroes.  It is more widely available than @code{umount2} but since it
1053 lacks the possibility to forcefully unmount a filesystem is deprecated
1054 when @code{umount2} is also available.
1055 @end deftypefun
1056
1057
1058
1059 @node System Parameters
1060 @section System Parameters
1061
1062 This section describes the @code{sysctl} function, which gets and sets
1063 a variety of system parameters.
1064
1065 The symbols used in this section are declared in the file @file{sysctl.h}.
1066
1067 @comment sysctl.h
1068 @comment BSD
1069 @deftypefun int sysctl (int *@var{names}, int @var{nlen}, void *@var{oldval}, size_t *@var{oldlenp}, void *@var{newval}, size_t @var{newlen})
1070
1071 @code{sysctl} gets or sets a specified system parameter.  There are so
1072 many of these parameters that it is not practical to list them all here,
1073 but here are some examples:
1074
1075 @itemize @bullet
1076 @item network domain name
1077 @item paging parameters
1078 @item network Address Resolution Protocol timeout time
1079 @item maximum number of files that may be open
1080 @item root filesystem device
1081 @item when kernel was built
1082 @end itemize
1083
1084 The set of available parameters depends on the kernel configuration and
1085 can change while the system is running, particularly when you load and
1086 unload loadable kernel modules.
1087
1088 The system parameters with which @code{syslog} is concerned are arranged
1089 in a hierarchical structure like a hierarchical filesystem.  To identify
1090 a particular parameter, you specify a path through the structure in a
1091 way analogous to specifying the pathname of a file.  Each component of
1092 the path is specified by an integer and each of these integers has a
1093 macro defined for it by @file{sysctl.h}.  @var{names} is the path, in
1094 the form of an array of integers.  Each component of the path is one
1095 element of the array, in order.  @var{nlen} is the number of components
1096 in the path.
1097
1098 For example, the first component of the path for all the paging
1099 parameters is the value @code{CTL_VM}.  For the free page thresholds, the
1100 second component of the path is @code{VM_FREEPG}.  So to get the free
1101 page threshold values, make @var{names} an array containing the two
1102 elements @code{CTL_VM} and @code{VM_FREEPG} and make @var{nlen} = 2.
1103
1104
1105 The format of the value of a parameter depends on the parameter.
1106 Sometimes it is an integer; sometimes it is an ASCII string; sometimes
1107 it is an elaborate structure.  In the case of the free page thresholds
1108 used in the example above, the parameter value is a structure containing
1109 several integers.
1110
1111 In any case, you identify a place to return the parameter's value with
1112 @var{oldval} and specify the amount of storage available at that
1113 location as *@var{oldlenp}.  *@var{oldlenp} does double duty because it
1114 is also the output location that contains the actual length of the
1115 returned value.
1116
1117 If you don't want the parameter value returned, specify a null pointer
1118 for @var{oldval}.
1119
1120 To set the parameter, specify the address and length of the new value
1121 as @var{newval} and @var{newlen}.  If you don't want to set the parameter,
1122 specify a null pointer as @var{newval}.
1123
1124 If you get and set a parameter in the same @code{sysctl} call, the value
1125 returned is the value of the parameter before it was set.
1126
1127 Each system parameter has a set of permissions similar to the
1128 permissions for a file (including the permissions on directories in its
1129 path) that determine whether you may get or set it.  For the purposes of
1130 these permissions, every parameter is considered to be owned by the
1131 superuser and Group 0 so processes with that effective uid or gid may
1132 have more access to system parameters.  Unlike with files, the superuser
1133 does not invariably have full permission to all system parameters, because
1134 some of them are designed not to be changed ever.
1135
1136
1137 @code{sysctl} returns a zero return value if it succeeds.  Otherwise, it
1138 returns @code{-1} and sets @code{errno} appropriately.  Besides the
1139 failures that apply to all system calls, the following are the
1140 @code{errno} codes for all possible failures:
1141
1142 @table @code
1143 @item EPERM
1144 The process is not permitted to access one of the components of the
1145 path of the system parameter or is not permitted to access the system parameter
1146 itself in the way (read or write) that it requested.
1147 @c There is some indication in the Linux 2.2 code that the code is trying to
1148 @c return EACCES here, but the EACCES value never actually makes it to the
1149 @c user.
1150 @item ENOTDIR
1151 There is no system parameter corresponding to @var{name}.
1152 @item EFAULT
1153 @var{oldval} is not null, which means the process wanted to read the parameter,
1154 but *@var{oldlenp} is zero, so there is no place to return it.
1155 @item EINVAL
1156 @itemize @bullet
1157 @item
1158 The process attempted to set a system parameter to a value that is not valid
1159 for that parameter.
1160 @item
1161 The space provided for the return of the system parameter is not the right
1162 size for that parameter.
1163 @end itemize
1164 @item ENOMEM
1165 This value may be returned instead of the more correct @code{EINVAL} in some
1166 cases where the space provided for the return of the system parameter is too
1167 small.
1168
1169 @end table
1170
1171 @end deftypefun
1172
1173 If you have a Linux kernel with the @code{proc} filesystem, you can get
1174 and set most of the same parameters by reading and writing to files in
1175 the @code{sys} directory of the @code{proc} filesystem.  In the @code{sys}
1176 directory, the directory structure represents the hierarchical structure
1177 of the parameters.  E.g. you can display the free page thresholds with
1178 @smallexample
1179 cat /proc/sys/vm/freepages
1180 @end smallexample
1181 @c In Linux, the sysctl() and /proc instances of the parameter are created
1182 @c together.  The proc filesystem accesses the same data structure as
1183 @c sysctl(), which has special fields in it for /proc.  But it is still
1184 @c possible to create a sysctl-only parameter.
1185
1186 Some more traditional and more widely available, though less general,
1187 GNU C library functions for getting and setting some of the same system
1188 parameters are:
1189
1190 @itemize @bullet
1191 @item
1192 @code{getdomainname}, @code{setdomainname}
1193 @item
1194 @code{gethostname}, @code{sethostname} (@xref{Host Identification}.)
1195 @item
1196 @code{uname} (@xref{Platform Type}.)
1197 @item
1198 @code{bdflush}
1199 @end itemize