Read Me About FSMegaInfo
========================
1.0

This tool is designed to help folks who are implementing a plug-in file system (VFS plug-ins) on Mac OS X.
You can use it to print information about various file system objects (volumes, directories, and files).
This allows you to compare the information on your volume with the information returned by canonical Apple file systems, such as HFS Plus, AppleShare, and MS-DOS/FAT.
The sample exercises the following areas of functionality:

o BSD -- access, stat, lstat, statfs, lstatfs, getfsstat, getdirentries, readdir, fts, listxattr, getxattr, pathconf, getattrlist

o File Manager -- FSGetVolumeInfo, FSGetVolumeParms, PBHGetVolParms [1], FSGetVolumeMountInfo, PBGetVolMountInfo [1], FSCopyDiskIDForVolume, FSCopyURLForVolume, FSGetCatalogInfo, FSGetCatalogInfoBulk, PBDTGetComment [1]

o Alias Manager -- GetAliasInfo [1], FSCopyAliasInfo

o Folder Manager -- FSFindFolder

o Disk Arbitration -- DADiskCopyDescription

Notes:
[1] These commands are unavailable when run as a 64-bit program because the underlying routines are not available to 64-bit code.

The sample is designed to run on Mac OS X 10.4 and later (I tested in on 10.4.11 and 10.5 on both Intel- and PowerPC-based computers).
(This fork has also been tested on 10.6)
You could port it to older versions of Mac OS X, although that would require disabling a number of the printing options.
This is because they print information that is not available on older systems.

Packing List
------------
The sample contains the following items:

o Read Me About FSMegaInfo.txt -- This document.
o FSMegaInfo.c -- The program's main.
o Command.h, Command.c -- A module containing common infrastructure for all commands.
o FieldPrinter.h, FieldPrinter.c -- A module to print various data types.

o AliasManager.c -- Code for the Alias Manager commands.
o BSD.h, BSD.c -- Code for the BSD commands.
o BSDAttrList.c -- Even more BSD code, this time focused on getattrlist and its ilk.
o DiskArb.c -- Code for the Disk Arbitration commands.
o FileManager.c -- Code for the File Manager commands.
o FolderManager.c -- Code for the Disk Arbitration commands.

o FSMegaInfo.xcodeproj -- An Xcode project for the program.
o build -- A directory containing a compiled version of the program.

o Tests -- A directory containing test code.

Using the Sample
----------------
To use the sample, just run it from the command line.
This prints out a list of available commands.
You can use the "help" command to get help on a specific command.
For example:

$ build/Debug/FSMegaInfo help stat
usage: FSMegaInfo [globalOptions] stat itemPath
       Print information from stat.

You can then run the command:

$ build/Debug/FSMegaInfo stat /
stat '/'
    st_dev     = 0x0e000002 (major=14, minor=2, disk0s2)
    st_ino     = 2
    st_mode    = 0x000041fd (drwxrwxr-x)
    st_nlink   = 44
    st_uid     = 0 (root)
    st_gid     = 0 (wheel)
    st_rdev    = 0x00000000 (major=0, minor=0, console)
    st_atime   = 1202937884.0 (Wed Feb 13 21:24:44 2008)
    st_mtime   = 1202935492.0 (Wed Feb 13 20:44:52 2008)
    st_ctime   = 1202935492.0 (Wed Feb 13 20:44:52 2008)
    st_size    = 1564 (1 KB)
    st_blocks  = 0
    st_blksize = 4096
    st_flags   = 0x00000000
    st_gen     = 0

If you specify the "-v" flag, you get a more verbose output.
For example, in the "stat" command, "-v" prints each of the flags symbolically:

$ build/Debug/FSMegaInfo -v stat /
stat '/'
    st_dev     = 0x0e000002 (major=14, minor=2, disk0s2)
    [...]
    st_flags   = 0x00000000
        UF_NODUMP    = NO
        UF_IMMUTABLE = NO
        UF_APPEND    = NO
        UF_OPAQUE    = NO
        SF_ARCHIVED  = NO
        SF_IMMUTABLE = NO
        SF_APPEND    = NO
    st_gen     = 0

On Mac OS X 10.5 and later, you can access the 32-bit version of the program using <x-man-page://1/arch>.
For example, on an 64-bit capable Intel-based computer, the "GetAliasInfo" command will not work by default.
This is because the program runs as 64-bit and the underlying function, GetAliasInfo, is not available in 64-bit.

$ build/Debug/FSMegaInfo GetAliasInfo /
usage: FSMegaInfo [globalOptions] command...
[...]

You can force the program to run as 32-bit using "arch".

$ arch -i386 build/Debug/FSMegaInfo GetAliasInfo /
    asiZoneName   = ''
    asiServerName = ''
    asiVolumeName = 'Guy Smiley'
    Path Elements
        [0]     = 'Guy Smiley'

Building the Sample
-------------------
The sample was originally built using Xcode 3.0 on Mac OS X 10.5.1.
(This fork built using Xcode 3.2.6 on Mac OS X 10.6.8)
To build the code, open the project and choose Build from the Build menu.
This will build the "FSMegaInfo" tool in the "build" directory.

How it Works
------------
While the code for the tool is long and complex, its basic operation is NOT.
It simply calls a specific API routine (for example, "stat") and prints the results.
There is a lot of infrastructure to make it easy to supply arguments to the API routine, and to pretty print the results.

Credits and Version History
---------------------------
If you find any problems with this sample, or any suggestions for extra commands, please mail <dts@apple.com> and I will see what I can do.

1.0 (Feb 2008) was the first shipping version.

Share and Enjoy.

Apple Developer Technical Support
Networking, Communications, Hardware

15 Feb 2008