ADC Home > Reference Library > Technical Q&As > Darwin > File Management >

The "/.vol" directory and "volfs"

Q: When I run fs_usage against my Carbon application I see lots of accesses to items in the "/.vol" directory. What is this directory and why am I accessing it?

A: This directory is used as the mount point for the "volfs" file system. The "volfs" file system is a key component for supporting the Carbon File Manager APIs on top of the BSD file system. Historically, BSD systems only allow you to access a file or directory by its POSIX path. However, the Carbon File Manager API also allows you to access an item by its catalogue node ID (CNID, a file ID reference or a directory ID). "volfs" provides a bridge between these two models, allowing the Carbon File Manager APIs to work on top of the BSD file system.



WARNING:
Under no circumstances should your application construct paths within "/.vol". This area of the file system is reserved strictly for the Carbon File Manager. The structure of the "volfs" file system is likely to change in a future releases of Mac OS X. You must use the following description of the "volfs" path structure for debugging and performance analysis only.



Carbon's use of the "volfs" file system is as follows.

  • If you access an item via a <vRefNum>, <dirID>, and <name> tuple (often bundled together in an FSSpec), Carbon File Manager builds a path of the form:

    /.vol/<volumeID>/<dirID>/<name>
    where:
    • <volumeID> is the decimal representation of a 32 bit "volfs" volume identifier (Carbon maintains an internal table that maps the volume's vRefNum to this value),
    • <dirID> is the decimal representation of the directory ID, and
    • <name> is the UTF-8 representation of the item's name.
  • If you access an item via a <vRefNum> and <CNID> pair, Carbon File Manager builds a path of the form:

    /.vol/<volumeID>/<CNID>
    where:
    • <volumeID> is the decimal representation of a 32 bit "volfs" volume identifier as described above, and
    • <CNID> is the decimal representation of the catalogue node ID.
  • If you access an item via FSRef, Carbon File Manager builds a "volfs" path based on the private information held within the FSRef.

Once it has built this path, Carbon File Manager can use it to access the item directly, without having to build the actual POSIX path to the item. This saves time (because building a POSIX path is expensive) and allows you to access the item regardless of whether its full path has changed. For example, if you create an alias to a file, the Alias Manager stores a file ID reference within the alias. When you later resolve this alias, the Alias Manager uses "volfs" to access the file. This ensures that the alias still resolves even if the file's name or POSIX path has changed.

Not all file systems support "volfs". As of Mac OS X 10.1 the following file systems support "volfs":

  • HFS Plus
  • HFS
  • AppleShare
  • ISO-9660
  • UDF

and the following file systems don't:

  • UFS
  • NFS
  • DOS/FAT
  • CDDA
  • SMB
  • WebDAV

This list is likely to change over time.

If the file system does not support "volfs", Carbon File Manager uses other techniques to emulate catalogue node IDs on that file system. In general these techniques do not provide persistent CNIDs. For example, if you use the Finder to create an alias to a file on a UFS file system and then move the file to a different folder, the alias will not resolve.

If you're writing a VFS plug-in file system you can choose whether to support "volfs". If you do support "volfs" there are a number of things you must do.

  1. You must set the MNT_DOVOLFS flag in the mnt_flag field of your mount structure.
  2. You must support the getattrlist, setattrlist, and exchange operations in your vfsops.
  3. You must support the ability to lookup named forks in your lookup and cachedlookup entry points.
  4. You must implement the vget operation in your vfsops. Specifically, you must set the vfs_vget field of your vfsops structure to a routine that can map a CNID to a vnode.
  5. You must return a CNID in the va_fileid field of the vattr structure in your getattr vnodeop entry point. Your CNIDs should persist across successive mounts of the volume. If they don't, you should probably not support "volfs" and instead rely on Carbon File Manager to emulate CNIDs for you.
  6. In your getattrlist vnodeop entry point you must respond to the ATTR_CMN_OBJID and ATTR_CMN_OBJPERMANENTID attribute requests by setting the fid_objno field to a CNID.

You can learn more about the implementation of "volfs" by reading the comments in the following volfs_vnops.c file in the Darwin open source project (this link requires you to have an account, which you create by agreeing to the Apple Public Source License).

[Feb 14 2002]

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.