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