vfsmount(2)

NAME

vfsmount − mount a file system

SYNOPSIS

#include <sys/mount.h>

int vfsmount(

int type,
const char *dir,
int flags,
caddr_t data

);

DESCRIPTION

vfsmount() attaches a file system to a directory. After a successful return, references to directory dir refer to the root directory of the newly mounted file system. dir is a pointer to a null-terminated string containing a path name. dir must exist already, and must be a directory. dir cannot be a context-dependent file (see cdf(4)). Its old contents are inaccessible while the file system is mounted. vfsmount() differs from mount() (see mount(2)) in its ability to mount file system types other than just the UFS type.

type indicates the type of the file system. It must be one of the types described below. vfsmount() does not check that the file system is actually of type type; if type is incorrect, vfsmount() may cause the process to hang. To prevent such problems, statfsdev() (see statfsdev(3c)) should be called before vfsmount() to check the file system type, which statfsdev() places in the f_fsid[1] field of the statfs structure it returns.

The flags argument determines whether the file system can be written to (functionally identical to the rwflag argument in mount(2) in this regard). It also controls whether programs from the mounted file system are allowed to have set-uid execution. Physically write-protected and magnetic tape file systems must be mounted read-only. Failure to do so results in a return of −1 by vfsmount() and a value of EIO in errno. The following values for the flags argument are defined in <sys/mount.h>:

M_RDONLY Mount done as read-only.

M_NOSUID Execution of set-uid programs not permitted.

data is a pointer to a structure containing arguments specific to the value contained in type. The following values for types are defined in <sys/mount.h>:

MOUNT_UFS Mount a local HFS file system. data points to a structure of the following format:

struct ufs_args {
char *fspec;
};

fspec points to the name of the block special file that is to be mounted. This is identical in use and function to the first argument for mount(2).

MOUNT_CDFS Mount a local CD-ROM file system. data points to a structure of the following format:

struct cdfs_args {
char *fspec;
};

fspec points to the name of the block special file that is to be mounted.

NETWORKING FEATURES

NFS

An additional value for the type argument is supported.

MOUNT_NFS Mount an NFS file system. data points to a structure of the following format:

#include <nfs/nfs.h>
#include <netinet/in.h>

struct nfs_args {
   struct sockaddr_in *addr;
   fhandle_t           *fh;
   int      flags;
   int      wsize;
   int      rsize;
   int      timeo;
   int      retrans;
   char     *hostname;
   int      acregmin;
   int      acregmax;
   int      acdirmin;
   int      acdirmax;
};

Elements in the structure as as follows:

addr Points to a local socket address structure (see inet(7)), which is used by the system to communicate with the remote file server.

fh Points to a structure containing a file handle, an abstract data type that is used by the remote file server when serving an NFS request.

flags Bit map that sets options and indicates which of the following fields contain valid information. The following values of the bits are defined in <nfs/nfs.h>:

NFSMNT_SOFT Specify whether the mount is a soft mount or a hard mount. If set, the mount is soft and will cause requests to be retried retrans number of times. Otherwise, the mount is hard and requests will be tried forever.

NFSMNT_WSIZE Set the write size.

NFSMNT_RSIZE Set the read size.

NFSMNT_TIMEO Set the initial timeout value.

NFSMNT_RETRANS Set the number of request retries.

NFSMNT_HOSTNAME Set a hostname.

NFSMNT_INT Set the option to have interruptible I/O to the mounted file system.

NFSMNT_NODEVS Set the option to deny access to local devices via NFS device files. By default, access to local devices via NFS device files is allowed.

NFSMNT_IGNORE Mark the file system type as ignore in /etc/mnttab.

NFSMNT_NOAC Turn off attribute caching. By default NFS caches attributes of files and directories to speed up operations on NFS files by not always getting the attributes from the server. Names are also cached to speed up path name lookup. However it does allow modifications to files on the server to not be immediately detectable on the clients. Setting NFSMNT_NOAC turns off attribute caching and name lookup caching. NFS caches attributes for a length of time proportional to how much time has elapsed since the last modification. The time length is subject to acregmin, acregmax, acdirmin, and acdirmax described below.

NFSMNT_NOCTO Cached attributes are flushed when a NFS file is opened unless this option is specified. This option is useful where it is known that the files will not be changing as is the case for a CD-ROM drive.

NFSMNT_ACREGMIN Use the acregmin value. See acregmin below.

NFSMNT_ACDIRMIN Use the acdirmin value. See acdirmin below.

NFSMNT_ACREGMAX Use the acregmax value. See acregmax below.

NFSMNT_ACDIRMAX Use the acdirmax value. See acdirmax below.

wsize Can be used to advise the system about the maximum number of data bytes to use for a single outgoing protocol (such as UDP) message. This value must be greater than 0. Default wsize is 8192.

rsize Can be used to advise the system about the maximum number of data bytes to use for a single incoming protocol (such as UDP) message. This value must be greater than 0. Default rsize is 8192.

timeo Can be used to advise the system on the time to wait between NFS request retries. This is in units of 0.1 seconds. This value must be greater than 0. Default timeo is 7.

retrans Can be used to advise the system about the number of times the system will resend a request. This value must be 0 or greater. Default retrans is 4.

hostname A name for the file server that can be used when any messages are given concerning the server. The string can be of length from 0 to 32 characters.

acregmin can be used to advise the system the minimum number of seconds to cache attributes for a non-directory file. If this number is less than 0, it means to use the system defined maximum of 3600 seconds. The number specified can not be 0. If the number is greater than 3600, 3600 will be used. Default acregmin is 3. is ignored if NFSMNT_NOAC is specified.

acdirmin can be used to advise the system the minimum number of seconds to cache attributes for a directory. If this number is less than 0, it means to use the system defined maximum of 3600 seconds. The number specified can not be 0. If the number is greater than 3600, 3600 will be used. Default acdirmin is 30. acdirmin is ignored if NFSMNT_NOAC is specified.

acregmax can be used to advise the system the maximum number of seconds to cache attributes for a non-directory file. If this number is less than 0, it means to use the system defined maximum of 36000 seconds. The number specified cannot be 0. If the number is greater than 36000, 36000 is used. Default acregmax is 60. acregmax is ignored if NFSMNT_NOAC is specified.

acdirmax can be used to advise the system the maximum number of seconds to cache attributes for a directory. If this number is less than 0, it means to use the system defined maximum of 36000 seconds. The number specified cannot be 0. If the number is greater than 36000, 36000 will be used. Default acdirmax is 60. acdirmax is ignored if NFSMNT_NOAC is specified.

RETURN VALUE

Upon successful completion, vfsmount() returns a value of 0. Otherwise, no file system is mounted, a value of -1 is returned, and errno is set to indicate the error.

ERRORS

vfsmount() fails when one of the following occurs:

[EBUSY] dir is not a directory, or another process currently holds a reference to it.

[EBUSY] No space remains in the mount table.

[EBUSY] The super block for the file system had a bad magic number or an out-of-range block size.

[EBUSY] Not enough memory was available to read the cylinder group information for the file system.

[EFAULT] data or dir points outside the allocated address space of the process.

[EINVAL] dir is a context-dependent file (see cdf(4).

[EIO] An I/O error occurred while reading from or writing to the file system.

[EIO] An attempt was made to mount a physically write protected or magnetic tape file system as read-write.

[ELOOP] Too many symbolic links were encountered while translating the path name of file system referred to by data or dir.

[ENAMETOOLONG]
The path name of the file system referred to by data or dir is longer than PATH_MAX bytes, or the length of a component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect.

[ENOENT] The file system referred to by data or dir does not exist.

[ENOENT] The file system referred to by data does not exist.

[ENOTBLK] The file system referred to by data is not a block device. This message can occur only during a local mount.

[ENOTDIR] A component of the path prefix in dir is not a directory.

[ENOTDIR] A component of the path prefix of the file system referred to by data or dir is not a directory.

[ENXIO] The major device number of the file system referred to by data is out of range (indicating that no device driver exists for the associated hardware).

[EOPNOTSUPP] vfsmount() of a remote device was attempted.

[EPERM] The caller does not have appropriate privileges.

DEPENDENCIES

NFS: vfsmount() fails when one of the following occurs, and returns the error indicated:

[EFAULT] A pointer in the data structure points outside the process’s allocated address space.

[EINVAL] A value in a field of data is out of proper range.

[EREMOTE] An attempt was made to remotely mount a file system that was already mounted from another remote node.

See getfh(2), inet(7), and mountd(1M) for more information.

HP Clustered Environment:
vfsmount() of a local CDFS file system (MOUNT_CDFS) is not supported from a cluster client. Such a call returns an EINVAL error.

WARNINGS

Use of mount(1M) is preferred over vfsmount() because mount(1M) supports all mounting options that are available from vfsmount() directly, plus mount(1M) also maintains the /etc/mnttab file which lists what file systems are mounted.

In the HP Clustered environment, the spec and dir arguments should always be fully expanded pathnames.

AUTHOR

vfsmount() was developed by HP and Sun Microsystems, Inc.

Museum

Related Articles