Mac Developer Library

Developer

mount.h Reference

Options
Deployment Target:

On This Page

mount.h Reference

Included Headers

  • <sys/appleapiopts.h>

  • <sys/cdefs.h>

  • <sys/attr.h>

  • <sys/kernel_types.h>

  • <uuid/uuid.h>

Functions

  • Check if the filesystem associated with a mountpoint is marked ready for interaction with 64-bit user processes.

    Declaration

    int vfs_64bitready( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if filesystem is ready for 64-bit; 0 otherwise.

  • Determine the time-to-live of cached authorized credentials for files in this filesystem.

    Declaration

    int vfs_authcache_ttl( mount_t);

    Parameters

    mp

    Mount for which to check cache lifetime.

    Return Value

    Cache lifetime in seconds. CACHED_RIGHT_INFINITE_TTL indicates that credentials never expire.

    Discussion

    If a filesystem is set to allow caching credentials, the VFS layer can authorize previously-authorized actions from the same vfs_context_t without calling down to the filesystem (though it will not deny based on the cache).

  • Determine if a filesystem's authorization decisions occur remotely.

    Declaration

    int vfs_authopaque( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if filesystem authorization is controlled remotely, else 0.

  • Check if a filesystem is marked as having reliable remote VNOP_ACCESS support.

    Declaration

    int vfs_authopaqueaccess( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if VNOP_ACCESS is supported remotely, else 0.

  • "Busy" a mountpoint.

    Declaration

    int vfs_busy( mount_t, int);

    Parameters

    mp

    Mount to busy.

    flags

    LK_NOWAIT: fail with ENOENT if an unmount is in progress.

    Return Value

    0 for success, with a lock held; an error code otherwise, with no lock held.

    Discussion

    vfs_busy() will "busy" a mountpoint, preventing unmounts from taking off, by taking its reader-writer lock in a shared manner. If a mount is dead, it will fail; if an unmount is in progress, depending on flags, it will either fail immediately or block until the unmount completes (then failing if the unmount has succeeded, or potentially succeeding if unmounting failed). A successful vfs_busy() must be followed by a vfs_unbusy() to release the lock on the mount.

  • Remove time-to-live controls for cached credentials on a filesytem. Filesystems with remote authorization decisions (opaque) will still have KAUTH_VNODE_SEARCH rights cached for a default of CACHED_LOOKUP_RIGHT_TTL seconds.

    Declaration

    void vfs_clearauthcache_ttl( mount_t);

    Parameters

    mp

    Mount for which to clear cache lifetime.

    Return Value

    void.

  • Mark a filesystem as not having remote authorization decisions.

    Declaration

    void vfs_clearauthopaque( mount_t);

    Parameters

    mp

    Mount to mark.

    Return Value

    void.

  • Mark a filesystem as not having remote VNOP_ACCESS support.

    Declaration

    void vfs_clearauthopaqueaccess( mount_t);

    Parameters

    mp

    Mount to mark.

    Return Value

    void.

  • Mark a filesystem as not having remote VNOP_ACCESS support.

    Declaration

    void vfs_clearauthopaqueaccess( mount_t);

    Parameters

    mp

    Mount to mark.

    Return Value

    void.

  • Mark a filesystem as NOT supporting security controls beyond POSIX permissions.

    Declaration

    void vfs_clearextendedsecurity( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    void.

    Discussion

    Specific controls include ACLs, file owner UUIDs, and group UUIDs.

  • Clear flags on a mount.

    Declaration

    void vfs_clearflags( mount_t, uint64_t);

    Parameters

    mp

    Mount whose flags to set.

    flags

    Flags to deactivate. Must be in the bitwise "OR" of MNT_VISFLAGMASK and MNT_CMDFLAGS.

    Return Value

    void.

    Discussion

    Sets mount flags to the bitwise "AND" of their current value and the complement of the specified bits.

  • Get the block size of the device underlying a mount.

    Declaration

    int vfs_devblocksize( mount_t);

    Parameters

    mp

    Mount for which to get block size.

    Return Value

    Block size.

  • This function should not be called by kexts.

    Declaration

    void vfs_event_init( void); /* XXX We should not export this */

  • Post a kqueue-style event on a filesystem (EVFILT_FS).

    Declaration

    void vfs_event_signal( fsid_t *, u_int32_t, intptr_t);

    Parameters

    fsid

    Unused.

    event

    Events to post.

    data

    Unused.

    Return Value

    void.

  • Get the vnode corresponding to a file handle.

    Declaration

    int ( *vfs_fhtovp)( struct mount *mp, int fhlen, unsigned char *fhp, struct vnode **vpp, vfs_context_t context);

    Parameters

    mp

    Mount against which to look up file handle.

    fhlen

    Size of file handle structure, as returned by vfs_vptofh.

    fhp

    Pointer to handle.

    vpp

    Destination for vnode.

    ctx

    Context against which to authenticate the file-handle conversion.

    Return Value

    0 for success, else an error code.

    Discussion

    Filesystems can return handles to files which are independent of their (transient) vnode identities. vfs_thtovp converts that persistent handle back to a vnode. The vnode should be returned with an iocount which the caller will drop with vnode_put().

  • Retrieve mount flags.

    Declaration

    uint64_t vfs_flags( mount_t);

    Parameters

    mp

    Mount whose flags to grab.

    Return Value

    Flags.

    Discussion

    Results will be in the bitwise "OR" of MNT_VISFLAGMASK and MNT_CMDFLAGS.

  • Register a filesystem with VFS.

    Declaration

    int vfs_fsadd( struct vfs_fsentry *, vfstable_t *);

    Parameters

    vfe

    Filesystem information: table of vfs operations, list of vnode operation tables, filesystem type number (can be omitted with VFS_TBLNOTYPENUM flag), name, flags.

    handle

    Opaque handle which will be passed to vfs_fsremove.

    Return Value

    0 for success, else an error code.

    Discussion

    Typically called by a filesystem Kernel Extension when it is loaded.

  • Get filesystem-private mount data.

    Declaration

    void * vfs_fsprivate( mount_t);

    Parameters

    mp

    Mount for which to get private data.

    Return Value

    Private data.

    Discussion

    A filesystem generally has an internal mount structure which it attaches to the VFS-level mount structure as part of the mounting process.

  • Unregister a filesystem with VFS.

    Declaration

    int vfs_fsremove( vfstable_t);

    Parameters

    handle

    Handle which was returned by vfs_fsadd.

    Return Value

    0 for success, else an error code.

    Discussion

    Typically called by a filesystem Kernel Extension when it is unloaded.

  • Get filesystem attributes.

    Declaration

    int ( *vfs_getattr)( struct mount *mp, struct vfs_attr *, vfs_context_t context);

    Parameters

    mp

    Mount for which to get parameters.

    vfa

    Container for specifying which attributes are desired and which attributes the filesystem supports, as well as for returning results.

    ctx

    Context to authenticate for getting filesystem attributes.

    Return Value

    0 for success, else an error code.

    Discussion

    See VFSATTR_RETURN, VFSATTR_ACTIVE, VFSATTR_SET_SUPPORTED, VFSATTR_WANTED macros.

  • Generate a unique filesystem ID for a mount and store it in the mount structure.

    Declaration

    void vfs_getnewfsid( struct mount *);

    Parameters

    mp

    Mount to set an ID for.

    Return Value

    void.

    Discussion

    Filesystem IDs are returned as part of "struct statfs." This function is typically called as part of file-system specific mount code (i.e. through VFS_MOUNT).

  • Given a filesystem ID, look up a mount structure.

    Declaration

    mount_t vfs_getvfs( fsid_t *);

    Parameters

    fsid

    Filesystem ID to look up.

    Return Value

    Mountpoint if found, else NULL. Note unmounting mountpoints can be returned.

  • Prepare a filesystem for having instances mounted.

    Declaration

    int ( *vfs_init)( struct vfsconf *);

    Parameters

    vfsconf

    Configuration information. Currently, the only useful data are the filesystem name, typenum, and flags. The flags field will be either 0 or MNT_LOCAL. Many filesystems ignore this parameter.

    Return Value

    0 for success, else an error code.

    Discussion

    This routine is called once, before any particular instance of a filesystem is mounted; it allows the filesystem to initialize whatever global data structures are shared across all mounts. If this returns successfully, a filesystem should be ready to have instances mounted.

  • Set I/O attributes on a mountpoint based on device properties.

    Declaration

    int vfs_init_io_attributes( vnode_t, mount_t);

    Parameters

    devvp

    Block device vnode from which a filesystem is being mounted.

    mp

    Mountpoint whose I/O parameters to initialize.

    Return Value

    0 for success, else an error code.

  • Get I/O attributes associated with a mounpoint.

    Declaration

    void vfs_ioattr( mount_t, struct vfsioattr *);

    Parameters

    mp

    Mount for which to get attributes. If NULL, system defaults are filled into ioattrp.

    ioattrp

    Destination for results.

    Return Value

    void.

  • Determine if a forced unmount is in progress.

    Declaration

    int vfs_isforce( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if a request has been made to forcibly unmount, else 0.

    Discussion

    A forced unmount invalidates open files.

  • Determine if a filesystem is mounted read-only.

    Declaration

    int vfs_isrdonly( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if filesystem is mounted read-only, else 0.

  • Determine if a filesystem is mounted with writes enabled.

    Declaration

    int vfs_isrdwr( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if filesystem is mounted read-write, else 0.

  • Determine if a reload of filesystem data is in progress. This can only be the case for a read-only filesystem; all data is brought in from secondary storage.

    Declaration

    int vfs_isreload( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if a request has been made to reload data, else 0.

  • Determine if writes to a filesystem occur synchronously.

    Declaration

    int vfs_issynchronous( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if writes occur synchronously, else 0.

  • Determine if an unmount is in progress.

    Declaration

    int vfs_isunmount( mount_t mp);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if an unmount is in progress, else zero.

    Discussion

    This is an unsynchronized snapshot of the mount state. It should only be called if the mount is known to be valid, e.g. there are known to be live files on that volume.

  • Determine if a mount update is in progress.

    Declaration

    int vfs_isupdate( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if a mount update is in progress, 0 otherwise.

  • Determine if a filesystem is mounted read-only but a request has been made to upgrade to read-write.

    Declaration

    int vfs_iswriteupgrade( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    Nonzero if a request has been made to update from read-only to read-write, else 0.

  • Iterate over all mountpoints with a callback. Used, for example, by sync().

    Declaration

    int vfs_iterate( int, int (*)( struct mount *, void *), void *);

    Parameters

    flags

    Unused.

    callback

    Function which takes a mount and arbitrary passed-in "arg," and returns one of VFS_RETURNED_DONE or VFS_CLAIMED_DONE: end iteration and return success. VFS_RETURNED or VFS_CLAIMED: continue iterating. Anything else: continue iterating.

    arg

    Arbitrary data to pass to callback.

    Return Value

    0 for success, else an error code.

  • Get the maximum length of a symbolic link on a filesystem.

    Declaration

    uint32_t vfs_maxsymlen( mount_t);

    Parameters

    mp

    Mount from which to get symlink length cap.

    Return Value

    Max symlink length.

  • Perform filesystem-specific operations required for mounting.

    Declaration

    int ( *vfs_mount)( struct mount *mp, vnode_t devvp, user_addr_t data, vfs_context_t context);

    Parameters

    mp

    Mount structure for the newly mounted filesystem.

    devvp

    Device that the filesystem is mounted from.

    data

    Filesystem-specific data passed down from userspace.

    context

    Context to authenticate for mount.

    Return Value

    0 for success, else an error code. Once success is returned, the filesystem should be ready to go active; VFS will not ask again.

    Discussion

    Typical operations include setting the mount-specific data with vfs_setfsprivate(). Note that if a mount call fails, the filesystem must clean up any state it has constructed, because vfs-level mount code will not clean it up.

  • Check whether a given block device has a filesystem mounted on it.

    Declaration

    int vfs_mountedon( struct vnode *);

    Parameters

    vp

    The vnode to test.

    Return Value

    EBUSY if vnode is indeed the source of a filesystem; 0 if it is not.

    Discussion

    Note that this is NOT a check for a covered vnode (the directory upon which a filesystem is mounted)--it is a test for whether a block device is being used as the source of a filesystem. Note that a block device marked as being mounted on cannot be opened.

  • Copy filesystem name into a buffer.

    Declaration

    void vfs_name( mount_t, char *);

    Parameters

    mp

    Mount for which to get name.

    buffer

    Destination for name; length should be at least MFSNAMELEN.

    Return Value

    void.

    Discussion

    Get filesystem name; this refers to the filesystem type of which a mount is an instantiation, rather than a name specific to the mountpoint.

  • Manipulate quotas for a volume.

    Declaration

    int ( *vfs_quotactl)( struct mount *mp, int cmds, uid_t uid, caddr_t arg, vfs_context_t context);

    Parameters

    mp

    Mount for which to manipulate quotas.

    cmds

    Detailed in "quotactl" manual page.

    uid

    Detailed in "quotactl" manual page.

    arg

    Detailed in "quotactl" manual page.

    context

    Context to authenticate for changing quotas.

    Return Value

    0 for success, else an error code.

  • Get the root vnode of a filesystem.

    Declaration

    int ( *vfs_root)( struct mount *mp, struct vnode **vpp, vfs_context_t context);

    Parameters

    mp

    Mount for which to get the root.

    vpp

    Destination for root vnode.

    context

    Context to authenticate for getting the root.

    Return Value

    0 for success, else an error code.

    Discussion

    Upon success, should return with an iocount held on the root vnode which the caller will drop with vnode_put().

  • Set filesystem attributes.

    Declaration

    int ( *vfs_setattr)( struct mount *mp, struct vfs_attr *, vfs_context_t context);

    Parameters

    mp

    Mount on which to set attributes.

    vfa

    VFS attribute structure containing requested attributes to set and their values. Currently will only be called with f_vol_name set.

    context

    Context against which to authenticate attribute change.

    Return Value

    0 for success, else an error code.

    Discussion

    The other side of the vfs_getattr coin. Currently only called to set volume name.

  • Enable credential caching and set time-to-live of cached authorized credentials for files in this filesystem.

    Declaration

    void vfs_setauthcache_ttl( mount_t, int);

    Parameters

    mp

    Mount for which to set cache lifetime.

    Return Value

    void.

    Discussion

    If a filesystem is set to allow caching credentials, the VFS layer can authorize previously-authorized actions from the same vfs_context_t without calling down to the filesystem (though it will not deny based on the cache).

  • Mark a filesystem as having authorization decisions controlled remotely.

    Declaration

    void vfs_setauthopaque( mount_t);

    Parameters

    mp

    Mount to mark.

    Return Value

    void.

  • Mark a filesystem as having remote VNOP_ACCESS support.

    Declaration

    void vfs_setauthopaqueaccess( mount_t);

    Parameters

    mp

    Mount to mark.

    Return Value

    void.

  • Mark a filesystem as supporting security controls beyond POSIX permissions.

    Declaration

    void vfs_setextendedsecurity( mount_t);

    Parameters

    mp

    Mount to test.

    Return Value

    void.

    Discussion

    Specific controls include ACLs, file owner UUIDs, and group UUIDs.

  • Set flags on a mount.

    Declaration

    void vfs_setflags( mount_t, uint64_t);

    Parameters

    mp

    Mount whose flags to set.

    flags

    Flags to activate. Must be in the bitwise "OR" of MNT_VISFLAGMASK and MNT_CMDFLAGS.

    Return Value

    Flags.

    Discussion

    Sets mount flags to the bitwise "OR" of their current value and the specified bits. Often used by a filesystem as part of the mount process.

  • Set filesystem-private mount data.

    Declaration

    void vfs_setfsprivate( mount_t, void *mntdata);

    Parameters

    mp

    Mount for which to set private data.

    Return Value

    Void.

    Discussion

    A filesystem generally has an internal mount structure which it attaches to the VFS-level mount structure as part of the mounting process.

  • Set I/O attributes associated with a mounpoint.

    Declaration

    void vfs_setioattr( mount_t, struct vfsioattr *);

    Parameters

    mp

    Mount for which to set attributes.

    ioattrp

    Structure containing I/O parameters; all fields must be filled in.

    Return Value

    void.

  • Mark a filesystem as using VFS-level advisory locking support.

    Declaration

    void vfs_setlocklocal( mount_t);

    Parameters

    mp

    Mount to mark.

    Return Value

    void.

    Discussion

    Advisory locking operations will not call down to the filesystem if this flag is set.

  • Set the maximum length of a symbolic link on a filesystem.

    Declaration

    void vfs_setmaxsymlen( mount_t, uint32_t);

    Parameters

    mp

    Mount on which to set symlink length cap.

    symlen

    Length to set.

    Return Value

    Max symlink length.

  • Mark a mount as ready to be used.

    Declaration

    int ( *vfs_start)( struct mount *mp, int flags, vfs_context_t context);

    Parameters

    mp

    Mount structure being activated.

    flags

    Unused.

    context

    Context to authenticate for mount.

    Return Value

    Return value is ignored.

    Discussion

    After receiving this calldown, a filesystem will be hooked into the mount list and should expect calls down from the VFS layer.

  • Get information about filesystem status.

    Declaration

    struct vfsstatfs * vfs_statfs( mount_t);

    Parameters

    mp

    Mount for which to get vfsstatfs pointer.

    Return Value

    Pointer to vfsstatfs.

    Discussion

    Each filesystem has a struct vfsstatfs associated with it which is updated as events occur; this function returns a pointer to it. Note that the data in the structure will continue to change over time and also that it may be quite stale of vfs_update_vfsstat has not been called recently.

  • Flush all filesystem data to backing store.

    Declaration

    int ( *vfs_sync)( struct mount *mp, int waitfor, vfs_context_t context);

    Parameters

    mp

    Mountpoint to sync.

    waitfor

    MNT_WAIT: flush synchronously, waiting for all data to be written before returning. MNT_NOWAIT: start I/O but do not wait for it.

    ctx

    Context to authenticate for the sync.

    Return Value

    0 for success, else an error code.

    Discussion

    vfs_sync will be called as part of the sync() system call and during unmount.

  • Broad interface for querying and controlling filesystem.

    Declaration

    int ( * vfs_sysctl )( int *, u_int , user_addr_t, size_t *, user_addr_t, size_t, vfs_context_t context);

    Parameters

    context

    Context against which to authenticate command.

    Return Value

    0 for success, else an error code.

    Discussion

    VFS defines VFS_CTL_QUERY as a generic status request which is answered with the VQ_* macros in a "struct vfsquery." A filesystem may also define implementation-specific commands. See "man 3 sysctl" for the meaning of sysctl parameters.

  • Get (archaic) filesystem type number.

    Declaration

    int vfs_typenum( mount_t);

    Parameters

    mp

    Mount for which to get type number.

    Return Value

    Type number.

    Discussion

    Filesystem type numbers are an old construct; most filesystems just get a number assigned based on the order in which they are registered with the system.

  • "Unbusy" a mountpoint by releasing its read-write lock.

    Declaration

    void vfs_unbusy( mount_t);

    Parameters

    mp

    Mount to unbusy.

    Return Value

    void.

    Discussion

    A successful vfs_busy() must be followed by a vfs_unbusy() to release the lock on the mount.

  • Perform filesystem-specific cleanup as part of unmount.

    Declaration

    int ( *vfs_unmount)( struct mount *mp, int mntflags, vfs_context_t context);

    Parameters

    mp

    Mount structure to unmount.

    mntflags

    MNT_FORCE indicates that we wish to unmount even if there are active vnodes.

    context

    Context to authenticate for unmount.

    Return Value

    0 for success, else an error code.

    Discussion

    If the unmount downcall succeeds, VFS considers itself authorized to destroy all state related to the mount.

  • Find a filesystem by ID and unmount it.

    Declaration

    int vfs_unmountbyfsid( fsid_t *, int, vfs_context_t);

    Parameters

    fsid

    ID of filesystem to unmount, as found through (for example) statfs.

    flags

    MNT_FORCE: forcibly invalidate files open on the mount (though in-flight I/O operations will be allowed to complete).

    ctx

    Context against which to authenticate unmount operation.

    Return Value

    0 for succcess, nonero for failure.

  • Update cached filesystem status information in the VFS mount structure.

    Declaration

    int vfs_update_vfsstat( mount_t, vfs_context_t, int eventtype);

    Parameters

    mp

    Mount for which to update cached status information.

    ctx

    Context to authenticate against for call down to filesystem.

    eventtype

    VFS_USER_EVENT: need for update is driven by user-level request; perform additional authentication. VFS_KERNEL_EVENT: need for update is driven by in-kernel events. Skip extra authentication.

    Return Value

    0 for success, or an error code for authentication failure or problem with call to filesystem to request information.

    Discussion

    Each filesystem has a struct vfsstatfs associated with it which is updated as events occur; this function updates it so that the structure pointer returned by vfs_statfs() returns a pointer to fairly recent data.

  • Get a vnode by file id (inode number).

    Declaration

    int ( *vfs_vget)( struct mount *mp, ino64_t ino, struct vnode **vpp, vfs_context_t context);

    Parameters

    mp

    Mount against which to look up inode number.

    ino

    File ID for desired file, as found through a readdir.

    vpp

    Destination for vnode.

    Return Value

    0 for success, else an error code.

    Discussion

    This routine is chiefly used to build paths to vnodes. Result should be turned with an iocount that the caller will drop with vnode_put().

  • Get a persistent handle corresponding to a vnode.

    Declaration

    int ( *vfs_vptofh)( struct vnode *vp, int *fhlen, unsigned char *fhp, vfs_context_t context);

    Parameters

    mp

    Mount against which to convert the vnode to a handle.

    fhlen

    Size of buffer provided for handle; set to size of actual handle returned.

    fhp

    Pointer to buffer in which to place handle data.

    ctx

    Context against which to authenticate the file-handle request.

    Return Value

    0 for success, else an error code.