lib/libc/sys/mount.2

   1 .\" Copyright (c) 1980, 1989, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)mount.2     8.3 (Berkeley) 5/24/95
  29 .\" $FreeBSD: src/lib/libc/sys/mount.2,v 1.20.2.8 2003/01/17 22:02:42 joerg Exp $
  30 .\"
  31 .Dd May 24, 1995
  32 .Dt MOUNT 2
  33 .Os
  34 .Sh NAME
  35 .Nm mount ,
  36 .Nm unmount
  37 .Nd mount or dismount a filesystem
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/param.h
  42 .In sys/mount.h
  43 .Ft int
  44 .Fn mount "const char *type" "const char *dir" "int flags" "void *data"
  45 .Ft int
  46 .Fn unmount "const char *dir" "int flags"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn mount
  50 function grafts
  51 a filesystem object onto the system file tree
  52 at the point
  53 .Ar dir .
  54 The argument
  55 .Ar data
  56 describes the filesystem object to be mounted.
  57 The argument
  58 .Ar type
  59 tells the kernel how to interpret
  60 .Ar data
  61 (See
  62 .Ar type
  63 below).
  64 The contents of the filesystem
  65 become available through the new mount point
  66 .Ar dir .
  67 Any files in
  68 .Ar dir
  69 at the time
  70 of a successful mount are swept under the carpet so to speak, and
  71 are unavailable until the filesystem is unmounted.
  72 .Pp
  73 By default only the super-user may call the
  74 .Fn mount
  75 function.
  76 This restriction can be removed by setting the sysctl
  77 .Va vfs.usermount
  78 to a non-zero value.
  79 .Pp
  80 The following
  81 .Ar flags
  82 may be specified to
  83 suppress default semantics which affect filesystem access.
  84 .Bl -tag -width ".Dv MNT_SYNCHRONOUS"
  85 .It Dv MNT_RDONLY
  86 The filesystem should be treated as read-only;
  87 Even the super-user may not write on it.
  88 Specifying
  89 .Dv MNT_UPDATE
  90 without this option will upgrade a read-only filesystem to read/write.
  91 .It Dv MNT_NOEXEC
  92 Do not allow files to be executed from the filesystem.
  93 .It Dv MNT_NOSUID
  94 Do not honor setuid or setgid bits on files when executing them.
  95 This flag is set automatically when the caller is not the super-user.
  96 .It Dv MNT_NOATIME
  97 Disable update of file access times.
  98 .It Dv MNT_NODEV
  99 Do not interpret special files on the filesystem.
 100 This flag is set automatically when the caller is not the super-user.
 101 .It Dv MNT_SUIDDIR
 102 Directories with the SUID bit set chown new files to their own owner.
 103 .It Dv MNT_SYNCHRONOUS
 104 All I/O to the filesystem should be done synchronously.
 105 .It Dv MNT_ASYNC
 106 All I/O to the filesystem should be done asynchronously.
 107 .It Dv MNT_FORCE
 108 Force a read-write mount even if the filesystem appears to be unclean.
 109 Dangerous.
 110 .It Dv MNT_NOCLUSTERR
 111 Disable read clustering.
 112 .It Dv MNT_NOCLUSTERW
 113 Disable write clustering.
 114 .El
 115 .Pp
 116 The flag
 117 .Dv MNT_UPDATE
 118 indicates that the mount command is being applied
 119 to an already mounted filesystem.
 120 This allows the mount flags to be changed without requiring
 121 that the filesystem be unmounted and remounted.
 122 Some filesystems may not allow all flags to be changed.
 123 For example,
 124 many filesystems will not allow a change from read-write to read-only.
 125 .Pp
 126 The flag
 127 .Dv MNT_RELOAD
 128 causes the vfs subsystem to update its data structures pertaining to
 129 the specified already mounted filesystem.
 130 .Pp
 131 The
 132 .Fa type
 133 argument names the filesystem.
 134 The types of filesystems known to the system can be obtained with
 135 .Xr lsvfs 1 .
 136 .Pp
 137 .Fa Data
 138 is a pointer to a structure that contains the type
 139 specific arguments to mount.
 140 The format for these argument structures is described in the
 141 manual page for each filesystem.
 142 By convention filesystem manual pages are named
 143 by prefixing ``mount_'' to the name of the filesystem as returned by
 144 .Xr lsvfs 1 .
 145 Thus the
 146 .Nm NFS
 147 filesystem is described by the
 148 .Xr mount_nfs 8
 149 manual page.
 150 .Pp
 151 The
 152 .Fn unmount
 153 function call disassociates the filesystem from the specified
 154 mount point
 155 .Fa dir .
 156 .Pp
 157 The
 158 .Fa flags
 159 argument may specify
 160 .Dv MNT_FORCE
 161 to specify that the filesystem should be forcibly unmounted or made read-only
 162 (if
 163 .Dv MNT_UPDATE
 164 and
 165 .Dv MNT_RDONLY
 166 are also specified) even if files are still active.
 167 Active special devices continue to work,
 168 but any further accesses to any other active files result in errors
 169 even if the filesystem is later remounted.
 170 .Pp
 171 The
 172 .Dv MNT_SUIDDIR
 173 option requires the SUIDDIR option to have been compiled into the kernel
 174 to have any effect.
 175 See the
 176 .Xr mount 8
 177 and
 178 .Xr chmod 2
 179 pages for more information.
 180 .Sh RETURN VALUES
 181 .Rv -std
 182 .Sh ERRORS
 183 The
 184 .Fn mount
 185 function will fail when one of the following occurs:
 186 .Bl -tag -width Er
 187 .It Bq Er EPERM
 188 The caller is neither the super-user nor the owner of
 189 .Ar dir ,
 190 or
 191 .Ar dir
 192 belongs to a filesystem that does not support stacked mounts.
 193 .It Bq Er ENAMETOOLONG
 194 A component of a pathname exceeded 255 characters,
 195 or the entire length of a path name exceeded 1023 characters.
 196 .It Bq Er ELOOP
 197 Too many symbolic links were encountered in translating a pathname.
 198 .It Bq Er ENOENT
 199 A component of
 200 .Fa dir
 201 does not exist.
 202 .It Bq Er ENOTDIR
 203 A component of
 204 .Ar name
 205 is not a directory,
 206 or a path prefix of
 207 .Ar special
 208 is not a directory.
 209 .It Bq Er EBUSY
 210 Another process currently holds a reference to
 211 .Fa dir .
 212 .It Bq Er EFAULT
 213 .Fa Dir
 214 points outside the process's allocated address space.
 215 .El
 216 .Pp
 217 The following errors can occur for a
 218 .Em ufs
 219 filesystem mount:
 220 .Bl -tag -width Er
 221 .It Bq Er ENODEV
 222 A component of ufs_args
 223 .Ar fspec
 224 does not exist.
 225 .It Bq Er ENOTBLK
 226 .Ar Fspec
 227 is not a block device.
 228 .It Bq Er ENXIO
 229 The major device number of
 230 .Ar fspec
 231 is out of range (this indicates no device driver exists
 232 for the associated hardware).
 233 .It Bq Er EBUSY
 234 .Ar Fspec
 235 is already mounted.
 236 .It Bq Er EMFILE
 237 No space remains in the mount table.
 238 .It Bq Er EINVAL
 239 The super block for the filesystem had a bad magic
 240 number or an out of range block size.
 241 .It Bq Er ENOMEM
 242 Not enough memory was available to read the cylinder
 243 group information for the filesystem.
 244 .It Bq Er EIO
 245 An I/O error occurred while reading the super block or
 246 cylinder group information.
 247 .It Bq Er EFAULT
 248 .Ar Fspec
 249 points outside the process's allocated address space.
 250 .El
 251 .Pp
 252 The following errors can occur for a
 253 .Em nfs
 254 filesystem mount:
 255 .Bl -tag -width Er
 256 .It Bq Er ETIMEDOUT
 257 .Em Nfs
 258 timed out trying to contact the server.
 259 .It Bq Er EFAULT
 260 Some part of the information described by nfs_args
 261 points outside the process's allocated address space.
 262 .El
 263 .Pp
 264 The following errors can occur for a
 265 .Em mfs
 266 filesystem mount:
 267 .Bl -tag -width Er
 268 .It Bq Er EMFILE
 269 No space remains in the mount table.
 270 .It Bq Er EINVAL
 271 The super block for the filesystem had a bad magic
 272 number or an out of range block size.
 273 .It Bq Er ENOMEM
 274 Not enough memory was available to read the cylinder
 275 group information for the filesystem.
 276 .It Bq Er EIO
 277 A paging error occurred while reading the super block or
 278 cylinder group information.
 279 .It Bq Er EFAULT
 280 .Em Name
 281 points outside the process's allocated address space.
 282 .El
 283 .Pp
 284 The
 285 .Fn unmount
 286 function may fail with one of the following errors:
 287 .Bl -tag -width Er
 288 .It Bq Er EPERM
 289 The caller is neither the super-user nor the user who issued the corresponding
 290 .Fn mount
 291 call.
 292 .It Bq Er ENOTDIR
 293 A component of the path is not a directory.
 294 .It Bq Er ENAMETOOLONG
 295 A component of a pathname exceeded 255 characters,
 296 or an entire path name exceeded 1023 characters.
 297 .It Bq Er ELOOP
 298 Too many symbolic links were encountered in translating the pathname.
 299 .It Bq Er EINVAL
 300 The requested directory is not in the mount table.
 301 .It Bq Er EBUSY
 302 A process is holding a reference to a file located
 303 on the filesystem.
 304 .It Bq Er EIO
 305 An I/O error occurred while writing cached filesystem information.
 306 .It Bq Er EFAULT
 307 .Fa Dir
 308 points outside the process's allocated address space.
 309 .El
 310 .Pp
 311 A
 312 .Em ufs
 313 or
 314 .Em mfs
 315 mount can also fail if the maximum number of filesystems are currently
 316 mounted.
 317 .Sh SEE ALSO
 318 .Xr lsvfs 1 ,
 319 .Xr mountctl 2 ,
 320 .Xr mfs 8 ,
 321 .Xr mount 8 ,
 322 .Xr sysctl 8 ,
 323 .Xr umount 8
 324 .Sh HISTORY
 325 .Fn Mount
 326 and
 327 .Fn unmount
 328 function calls appeared in
 329 .At v6 .
 330 .Sh BUGS
 331 Some of the error codes need translation to more obvious messages.