| blob | da131fde456e4dcf5cd5b1aefde1c28cb41c230b |
1 .\" $NetBSD: mount.2,v 1.45 2010/05/31 12:16:20 njoly 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 April 10, 2009
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_NODEVMTIME
102 Never update modification time of device files.
103 .It Dv MNT_SYMPERM
104 Recognize the permission of symbolic link when reading or traversing.
105 .It Dv MNT_SYNCHRONOUS
106 All I/O to the file system should be done synchronously.
107 This will slow I/O performance considerably, but
108 enhances overall filesystem reliability.
109 .It Dv MNT_ASYNC
110 All I/O to the file system should be done asynchronously.
111 This vastly improves I/O throughput,
112 but at a cost of making the filesystem likely to be
113 completely unrecoverable should the system crash while
114 unwritten data is pending in kernel buffers.
115 .It Dv MNT_LOG
116 Use a filesystem journal.
117 .Dv MNT_LOG
118 causes a journal (or log) to be created in the
119 filesystem, creating a record of meta-data writes to be
120 performed, allowing the actual writes to be deferred.
121 This improves performance in most cases.
122 .El
123 .Pp
124 The
125 .Dv MNT_UPDATE ,
126 .Dv MNT_RELOAD ,
127 and
128 .Dv MNT_GETARGS
129 flags indicate that the mount command is being applied
130 to an already mounted file system.
131 The
132 .Dv MNT_UPDATE
133 flag allows the mount flags to be changed without requiring
134 that the file system be unmounted and remounted.
135 A conversion from read-write to read-only will fail if any files
136 are currently open for writing on the filesystem, unless the
137 .Dv MNT_FORCE
138 flag is also applied.
139 Some file systems may not allow all flags to be changed.
140 For example,
141 some file systems will not allow a change from read-write to read-only.
142 The
143 .Dv MNT_RELOAD
144 flag causes kernel filesystem data to be reloaded from
145 the filesystem device.
146 It is only permitted on filesystems mounted read-only.
147 Its purpose is to notify the system that the filesystem
148 data has been modified by some external process.
149 The
150 .Dv MNT_GETARGS
151 flag does not alter any of the mounted filesystem's properties,
152 but returns the filesystem-specific arguments for the currently mounted
153 filesystem.
154 .Pp
155 The
156 .Fa type
157 argument defines the type of the file system.
158 The types of file systems known to the system are defined in
159 .In sys/mount.h ,
160 and those supported by the current running kernel obtained
161 using
162 .Xr sysctl 8
163 to obtain the node
164 .\" .Bd -literal -offset indent
165 vfs.generic.fstypes.
166 .\" XXX from lite-2:
167 .\" The types of filesystems known to the system can be obtained with
168 .\" .Xr sysctl 8
169 .\" by using the command:
170 .\" .Bd -literal -offset indent
171 .\" sysctl vfs
172 .\" .Ed
173 .\" .Pp
174 .Fa data
175 is a pointer to a structure that contains the type
176 specific arguments to mount.
177 Some of the currently supported types of file systems and
178 their type specific data are:
179 .Pp
180 .Dv MOUNT_FFS
181 .Bd -literal -offset indent -compact
182 struct ufs_args {
183 char *fspec; /* block special file to mount */
184 };
185 .Ed
186 .Pp
187 .Dv MOUNT_NFS
188 .Bd -literal -offset indent -compact
189 struct nfs_args {
190 int version; /* args structure version */
191 struct sockaddr *addr; /* file server address */
192 int addrlen; /* length of address */
193 int sotype; /* Socket type */
194 int proto; /* and Protocol */
195 u_char *fh; /* File handle to be mounted */
196 int fhsize; /* Size, in bytes, of fh */
197 int flags; /* flags */
198 int wsize; /* write size in bytes */
199 int rsize; /* read size in bytes */
200 int readdirsize; /* readdir size in bytes */
201 int timeo; /* initial timeout in .1 secs */
202 int retrans; /* times to retry send */
203 int maxgrouplist; /* Max. size of group list */
204 int readahead; /* # of blocks to readahead */
205 int leaseterm; /* Term (sec) of lease */
206 int deadthresh; /* Retrans threshold */
207 char *hostname; /* server's name */
208 };
209 .Ed
210 .Pp
211 .Dv MOUNT_MFS
212 .Bd -literal -offset indent -compact
213 struct mfs_args {
214 char *fspec; /* name to export for statfs */
215 struct export_args30 pad; /* unused */
216 caddr_t base; /* base of file system in mem */
217 u_long size; /* size of file system */
218 };
219 .Ed
220 .\" XXX from lite-2:
221 .\" The format for these argument structures is described in the
222 .\" manual page for each filesystem.
223 .\" By convention filesystem manual pages are named
224 .\" by prefixing ``mount_'' to the name of the filesystem as returned by
225 .\" .Xr sysctl 8 .
226 .\" Thus the
227 .\" .Nm NFS
228 .\" filesystem is described by the
229 .\" .Xr mount_nfs 8
230 .\" manual page.
231 .Pp
232 The
233 .Fn unmount
234 function call disassociates the file system from the specified
235 mount point
236 .Fa dir .
237 .Pp
238 The
239 .Fa flags
240 argument may specify
241 .Dv MNT_FORCE
242 to specify that the file system should be forcibly unmounted even if files are
243 still active.
244 Active special devices continue to work,
245 but any further accesses to any other active files result in errors
246 even if the file system is later remounted.
247 .Sh RETURN VALUES
248 .Fn mount
249 returns the value 0 if the mount was successful,
250 the number of bytes written to
251 .Ar data
252 for
253 .Dv MNT_GETARGS ,
254 otherwise \-1 is returned and the variable
255 .Va errno
256 is set to indicate the error.
257 .Pp
258 .Fn unmount
259 returns the value 0 if the unmount succeeded; otherwise \-1 is returned
260 and the variable
261 .Va errno
262 is set to indicate the error.
263 .Sh ERRORS
264 .Fn mount
265 will fail when one of the following occurs:
266 .Bl -tag -width Er
267 .It Bq Er EBUSY
268 Another process currently holds a reference to
269 .Fa dir ,
270 or for an update from read-write to read-only
271 there are files on the filesystem open for writes.
272 .It Bq Er EFAULT
273 .Fa dir
274 points outside the process's allocated address space.
275 .It Bq Er ELOOP
276 Too many symbolic links were encountered in translating a pathname.
277 .It Bq Er ENAMETOOLONG
278 A component of a pathname exceeded
279 .Brq Dv NAME_MAX
280 characters, or an entire path name exceeded
281 .Brq Dv PATH_MAX
282 characters.
283 .It Bq Er ENOENT
284 A component of
285 .Fa dir
286 does not exist.
287 .It Bq Er ENOTDIR
288 A component of
289 .Ar name
290 is not a directory,
291 or a path prefix of
292 .Ar special
293 is not a directory.
294 .It Bq Er EPERM
295 The caller is not the super-user,
296 and ordinary user mounts are not permitted or
297 this particular request violates the rules.
298 .El
299 .Pp
300 The following errors can occur for a
301 .Em ufs
302 file system mount:
303 .Bl -tag -width Er
304 .It Bq Er EBUSY
305 .Ar Fspec
306 is already mounted.
307 .It Bq Er EFAULT
308 .Ar Fspec
309 points outside the process's allocated address space.
310 .It Bq Er EINVAL
311 The super block for the file system had a bad magic
312 number or an out of range block size.
313 .It Bq Er EIO
314 An I/O error occurred while reading the super block or
315 cylinder group information.
316 .It Bq Er EMFILE
317 No space remains in the mount table.
318 .It Bq Er ENODEV
319 A component of ufs_args
320 .Ar fspec
321 does not exist.
322 .It Bq Er ENOMEM
323 Not enough memory was available to read the cylinder
324 group information for the file system.
325 .It Bq Er ENOTBLK
326 .Ar Fspec
327 is not a block device.
328 .It Bq Er ENXIO
329 The major device number of
330 .Ar fspec
331 is out of range (this indicates no device driver exists
332 for the associated hardware).
333 .El
334 .Pp
335 The following errors can occur for a
336 .Em nfs
337 file system mount:
338 .Bl -tag -width Er
339 .It Bq Er EFAULT
340 Some part of the information described by nfs_args
341 points outside the process's allocated address space.
342 .It Bq Er ETIMEDOUT
343 .Em Nfs
344 timed out trying to contact the server.
345 .El
346 .Pp
347 The following errors can occur for a
348 .Em mfs
349 file system mount:
350 .Bl -tag -width Er
351 .It Bq Er EFAULT
352 .Em Name
353 points outside the process's allocated address space.
354 .It Bq Er EINVAL
355 The super block for the file system had a bad magic
356 number or an out of range block size.
357 .It Bq Er EIO
358 A paging error occurred while reading the super block or
359 cylinder group information.
360 .It Bq Er EMFILE
361 No space remains in the mount table.
362 .It Bq Er ENOMEM
363 Not enough memory was available to read the cylinder
364 group information for the file system.
365 .El
366 .Pp
367 .Fn unmount
368 may fail with one of the following errors:
369 .Bl -tag -width Er
370 .It Bq Er EBUSY
371 A process is holding a reference to a file located
372 on the file system.
373 .It Bq Er EFAULT
374 .Fa dir
375 points outside the process's allocated address space.
376 .It Bq Er EINVAL
377 The requested directory is not in the mount table.
378 .It Bq Er EIO
379 An I/O error occurred while writing cached file system information.
380 .It Bq Er ELOOP
381 Too many symbolic links were encountered in translating the pathname.
382 .It Bq Er ENAMETOOLONG
383 A component of a pathname exceeded
384 .Brq Dv NAME_MAX
385 characters, or an entire path name exceeded
386 .Brq Dv PATH_MAX
387 characters.
388 .It Bq Er ENOTDIR
389 A component of the path is not a directory.
390 .It Bq Er EPERM
391 The caller is not the super-user.
392 .El
393 .Pp
394 A
395 .Em ufs
396 or
397 .Em mfs
398 mount can also fail if the maximum number of file systems are currently
399 mounted.
400 .Sh SEE ALSO
401 .Xr df 1 ,
402 .Xr getvfsstat 2 ,
403 .Xr nfssvc 2 ,
404 .Xr getmntinfo 3 ,
405 .Xr symlink 7 ,
406 .Xr mount 8 ,
407 .Xr sysctl 8 ,
408 .Xr umount 8
409 .Sh HISTORY
410 The
411 .Fn mount
412 and
413 .Fn umount
414 (now
415 .Fn unmount )
416 function calls were all present in
417 .At v6 .
418 .Pp
419 Prior to
420 .Nx 4.0
421 the
422 .Nm
423 call was used to export NFS filesystems.
424 This is now done through
425 .Fn nfssvc .
426 .Pp
427 The
428 .Dv data_len
429 argument was added for
430 .Nx 5.0 .
431 .Sh BUGS
432 Some of the error codes need translation to more obvious messages.
433 .Pp
434 Far more filesystems are supported than those those listed.