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