| blob | 815124ebc047a5ebe685ed0408674f0380e43087 |
1 .\" $NetBSD: mount.2,v 1.49 2011/11/18 21:04:21 christos Exp $
2 .\"
3 .\" Copyright (c) 1980, 1989, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)mount.2 8.3 (Berkeley) 5/24/95
31 .\"
32 .Dd November 18, 2011
33 .Dt MOUNT 2
34 .Os
35 .Sh NAME
36 .Nm mount ,
37 .Nm unmount
38 .Nd mount or dismount a file system
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In sys/param.h
43 .In sys/mount.h
44 .Ft int
45 .Fn mount "const char *type" "const char *dir" "int flags" "void *data" "size_t data_len"
46 .Ft int
47 .Fn unmount "const char *dir" "int flags"
48 .Sh DESCRIPTION
49 The
50 .Fn mount
51 function grafts
52 a file system object onto the system file tree
53 at the point
54 .Ar dir .
55 The argument
56 .Ar data
57 describes the file system object to be mounted, and is
58 .Ar data_len
59 bytes long.
60 The argument
61 .Ar type
62 tells the kernel how to interpret
63 .Ar data
64 (See
65 .Ar type
66 below).
67 The contents of the file system
68 become available through the new mount point
69 .Ar dir .
70 Any files in
71 .Ar dir
72 at the time
73 of a successful mount are swept under the carpet so to speak, and
74 are unavailable until the file system is unmounted.
75 .Pp
76 The following
77 .Ar flags
78 may be specified to
79 suppress default semantics which affect file system access.
80 .Bl -tag -width MNT_SYNCHRONOUS
81 .It Dv MNT_RDONLY
82 The file system should be treated as read-only;
83 even the super-user may not write on it.
84 .It Dv MNT_UNION
85 Union with underlying filesystem instead of obscuring it.
86 .It Dv MNT_HIDDEN
87 Cause the
88 .Xr df 1
89 program, and perhaps others, to, by default,
90 exclude this filesystem from its output.
91 .It Dv MNT_NOEXEC
92 Do not allow files to be executed from the file system.
93 .It Dv MNT_NOSUID
94 Do not honor setuid or setgid bits on files when executing them.
95 .It Dv MNT_NODEV
96 Do not interpret special files on the file system.
97 .It Dv MNT_NOCOREDUMP
98 Do not allow programs to dump core files on the file system.
99 .It Dv MNT_NOATIME
100 Never update access time in the file system.
101 .It Dv MNT_RELATIME
102 Update access time on write and change.
103 This helps programs that verify that the file has been read after written
104 to work.
105 .It Dv MNT_NODEVMTIME
106 Never update modification time of device files.
107 .It Dv MNT_SYMPERM
108 Recognize the permission of symbolic link when reading or traversing.
109 .It Dv MNT_SYNCHRONOUS
110 All I/O to the file system should be done synchronously.
111 This will slow I/O performance considerably, but
112 enhances overall filesystem reliability.
113 .It Dv MNT_ASYNC
114 All I/O to the file system should be done asynchronously.
115 This vastly improves I/O throughput,
116 but at a cost of making the filesystem likely to be
117 completely unrecoverable should the system crash while
118 unwritten data is pending in kernel buffers.
119 .It Dv MNT_LOG
120 Use a filesystem journal.
121 .Dv MNT_LOG
122 causes a journal (or log) to be created in the
123 filesystem, creating a record of meta-data writes to be
124 performed, allowing the actual writes to be deferred.
125 This improves performance in most cases.
126 .It MNT_EXTATTR
127 Enable extended attributes, if the filesystem supports them and
128 does not enable them by default.
129 Currently this is only the case for UFS1.
130 .El
131 .Pp
132 The
133 .Dv MNT_UPDATE ,
134 .Dv MNT_RELOAD ,
135 and
136 .Dv MNT_GETARGS
137 flags indicate that the mount command is being applied
138 to an already mounted file system.
139 The
140 .Dv MNT_UPDATE
141 flag allows the mount flags to be changed without requiring
142 that the file system be unmounted and remounted.
143 A conversion from read-write to read-only will fail if any files
144 are currently open for writing on the filesystem, unless the
145 .Dv MNT_FORCE
146 flag is also applied.
147 Some file systems may not allow all flags to be changed.
148 For example,
149 some file systems will not allow a change from read-write to read-only.
150 The
151 .Dv MNT_RELOAD
152 flag causes kernel filesystem data to be reloaded from
153 the filesystem device.
154 It is only permitted on filesystems mounted read-only.
155 Its purpose is to notify the system that the filesystem
156 data has been modified by some external process.
157 The
158 .Dv MNT_GETARGS
159 flag does not alter any of the mounted filesystem's properties,
160 but returns the filesystem-specific arguments for the currently mounted
161 filesystem.
162 .Pp
163 The
164 .Fa type
165 argument defines the type of the file system.
166 The types of file systems known to the system are defined in
167 .In sys/mount.h ,
168 and those supported by the current running kernel obtained
169 using
170 .Xr sysctl 8
171 to obtain the node
172 .\" .Bd -literal -offset indent
173 vfs.generic.fstypes.
174 .\" XXX from lite-2:
175 .\" The types of filesystems known to the system can be obtained with
176 .\" .Xr sysctl 8
177 .\" by using the command:
178 .\" .Bd -literal -offset indent
179 .\" sysctl vfs
180 .\" .Ed
181 .\" .Pp
182 .Fa data
183 is a pointer to a structure that contains the type
184 specific arguments to mount.
185 Some of the currently supported types of file systems and
186 their type specific data are:
187 .Pp
188 .Dv MOUNT_FFS
189 .Bd -literal -offset indent -compact
190 struct ufs_args {
191 char *fspec; /* block special file to mount */
192 };
193 .Ed
194 .Pp
195 .Dv MOUNT_NFS
196 .Bd -literal -offset indent -compact
197 struct nfs_args {
198 int version; /* args structure version */
199 struct sockaddr *addr; /* file server address */
200 int addrlen; /* length of address */
201 int sotype; /* Socket type */
202 int proto; /* and Protocol */
203 u_char *fh; /* File handle to be mounted */
204 int fhsize; /* Size, in bytes, of fh */
205 int flags; /* flags */
206 int wsize; /* write size in bytes */
207 int rsize; /* read size in bytes */
208 int readdirsize; /* readdir size in bytes */
209 int timeo; /* initial timeout in .1 secs */
210 int retrans; /* times to retry send */
211 int maxgrouplist; /* Max. size of group list */
212 int readahead; /* # of blocks to readahead */
213 int leaseterm; /* Term (sec) of lease */
214 int deadthresh; /* Retrans threshold */
215 char *hostname; /* server's name */
216 };
217 .Ed
218 .Pp
219 .Dv MOUNT_MFS
220 .Bd -literal -offset indent -compact
221 struct mfs_args {
222 char *fspec; /* name to export for statfs */
223 struct export_args30 pad; /* unused */
224 caddr_t base; /* base of file system in mem */
225 u_long size; /* size of file system */
226 };
227 .Ed
228 .\" XXX from lite-2:
229 .\" The format for these argument structures is described in the
230 .\" manual page for each filesystem.
231 .\" By convention filesystem manual pages are named
232 .\" by prefixing ``mount_'' to the name of the filesystem as returned by
233 .\" .Xr sysctl 8 .
234 .\" Thus the
235 .\" .Nm NFS
236 .\" filesystem is described by the
237 .\" .Xr mount_nfs 8
238 .\" manual page.
239 .Pp
240 The
241 .Fn unmount
242 function call disassociates the file system from the specified
243 mount point
244 .Fa dir .
245 .Pp
246 The
247 .Fa flags
248 argument may specify
249 .Dv MNT_FORCE
250 to specify that the file system should be forcibly unmounted even if files are
251 still active.
252 Active special devices continue to work,
253 but any further accesses to any other active files result in errors
254 even if the file system is later remounted.
255 .Sh RETURN VALUES
256 .Fn mount
257 returns the value 0 if the mount was successful,
258 the number of bytes written to
259 .Ar data
260 for
261 .Dv MNT_GETARGS ,
262 otherwise \-1 is returned and the variable
263 .Va errno
264 is set to indicate the error.
265 .Pp
266 .Fn unmount
267 returns the value 0 if the unmount succeeded; otherwise \-1 is returned
268 and the variable
269 .Va errno
270 is set to indicate the error.
271 .Sh ERRORS
272 .Fn mount
273 will fail when one of the following occurs:
274 .Bl -tag -width Er
275 .It Bq Er EBUSY
276 Another process currently holds a reference to
277 .Fa dir ,
278 or for an update from read-write to read-only
279 there are files on the filesystem open for writes.
280 .It Bq Er EFAULT
281 .Fa dir
282 points outside the process's allocated address space.
283 .It Bq Er ELOOP
284 Too many symbolic links were encountered in translating a pathname.
285 .It Bq Er ENAMETOOLONG
286 A component of a pathname exceeded
287 .Brq Dv NAME_MAX
288 characters, or an entire path name exceeded
289 .Brq Dv PATH_MAX
290 characters.
291 .It Bq Er ENOENT
292 A component of
293 .Fa dir
294 does not exist.
295 .It Bq Er ENOTDIR
296 A component of
297 .Ar name
298 is not a directory,
299 or a path prefix of
300 .Ar special
301 is not a directory.
302 .It Bq Er EPERM
303 The caller is not the super-user,
304 and ordinary user mounts are not permitted or
305 this particular request violates the rules.
306 .El
307 .Pp
308 The following errors can occur for a
309 .Em ufs
310 file system mount:
311 .Bl -tag -width Er
312 .It Bq Er EBUSY
313 .Ar Fspec
314 is already mounted.
315 .It Bq Er EFAULT
316 .Ar Fspec
317 points outside the process's allocated address space.
318 .It Bq Er EINVAL
319 The super block for the file system had a bad magic
320 number or an out of range block size.
321 .It Bq Er EIO
322 An I/O error occurred while reading the super block or
323 cylinder group information.
324 .It Bq Er EMFILE
325 No space remains in the mount table.
326 .It Bq Er ENODEV
327 A component of ufs_args
328 .Ar fspec
329 does not exist.
330 .It Bq Er ENOMEM
331 Not enough memory was available to read the cylinder
332 group information for the file system.
333 .It Bq Er ENOTBLK
334 .Ar Fspec
335 is not a block device.
336 .It Bq Er ENXIO
337 The major device number of
338 .Ar fspec
339 is out of range (this indicates no device driver exists
340 for the associated hardware).
341 .El
342 .Pp
343 The following errors can occur for a
344 .Em nfs
345 file system mount:
346 .Bl -tag -width Er
347 .It Bq Er EFAULT
348 Some part of the information described by nfs_args
349 points outside the process's allocated address space.
350 .It Bq Er ETIMEDOUT
351 .Em Nfs
352 timed out trying to contact the server.
353 .El
354 .Pp
355 The following errors can occur for a
356 .Em mfs
357 file system mount:
358 .Bl -tag -width Er
359 .It Bq Er EFAULT
360 .Em Name
361 points outside the process's allocated address space.
362 .It Bq Er EINVAL
363 The super block for the file system had a bad magic
364 number or an out of range block size.
365 .It Bq Er EIO
366 A paging error occurred while reading the super block or
367 cylinder group information.
368 .It Bq Er EMFILE
369 No space remains in the mount table.
370 .It Bq Er ENOMEM
371 Not enough memory was available to read the cylinder
372 group information for the file system.
373 .El
374 .Pp
375 .Fn unmount
376 may fail with one of the following errors:
377 .Bl -tag -width Er
378 .It Bq Er EBUSY
379 A process is holding a reference to a file located
380 on the file system.
381 .It Bq Er EFAULT
382 .Fa dir
383 points outside the process's allocated address space.
384 .It Bq Er EINVAL
385 The requested directory is not in the mount table.
386 .It Bq Er EIO
387 An I/O error occurred while writing cached file system information.
388 .It Bq Er ELOOP
389 Too many symbolic links were encountered in translating the pathname.
390 .It Bq Er ENAMETOOLONG
391 A component of a pathname exceeded
392 .Brq Dv NAME_MAX
393 characters, or an entire path name exceeded
394 .Brq Dv PATH_MAX
395 characters.
396 .It Bq Er ENOTDIR
397 A component of the path is not a directory.
398 .It Bq Er EPERM
399 The caller is not the super-user.
400 .El
401 .Pp
402 A
403 .Em ufs
404 or
405 .Em mfs
406 mount can also fail if the maximum number of file systems are currently
407 mounted.
408 .Sh SEE ALSO
409 .Xr df 1 ,
410 .Xr getvfsstat 2 ,
411 .Xr nfssvc 2 ,
412 .Xr getmntinfo 3 ,
413 .Xr symlink 7 ,
414 .Xr mount 8 ,
415 .Xr sysctl 8 ,
416 .Xr umount 8
417 .Sh HISTORY
418 The
419 .Fn mount
420 and
421 .Fn umount
422 (now
423 .Fn unmount )
424 function calls were all present in
425 .At v6 .
426 .Pp
427 Prior to
428 .Nx 4.0
429 the
430 .Nm
431 call was used to export NFS filesystems.
432 This is now done through
433 .Fn nfssvc .
434 .Pp
435 The
436 .Dv data_len
437 argument was added for
438 .Nx 5.0 .
439 .Sh BUGS
440 Some of the error codes need translation to more obvious messages.
441 .Pp
442 Far more filesystems are supported than those those listed.