File Manager

FSRef vs. POSIX File Paths

In Carbon, there are three (modern) ways to specify a file / folder: FSRef, CFURLRef, and POSIX file paths.

FSRef

The preferred method for handling files is via FSRefs. An FSRef is an opaque structure that represents a file or folder. The functions used to access a file via FSRefs is detailed in the File Manager Reference [1].

CFURLRef

A CFURLRef is a reference-counted opaque pointer representing a URL string, and is toll-free bridged to the Cocoa class NSURL. There are CFURL APIs for converting a CFURLRef to or from an FSRef, a path as a CFStringRef, or a path as a sequence of bytes.

POSIX File Paths

An alternative, though not recommended, method for accessing files are POSIX file paths. In Mac OS X (as of 10.4.6), POSIX file paths are null terminated UTF8 character arrays. The current maximum length for a POSIX file path is 1024 bytes. This length is defined by the constant PATH_MAX in syslimits.h file.

Note that since POSIX file paths are null terminated, the maximum number of characters in a file path is 1023. If multibyte character are used, the maximum number of characters are decreased by an appropriate amount.

In most cases, the maximum length for POSIX file paths are not an issue. Most people simply do not nest their folders so deep and / or use such long names that they become an issue. However, in the rare case when a file's path name is longer than allowed, POSIX file paths will fail.

Differences and Conversion

Unlike POSIX file paths, FSRefs are not affected by maximum file path lengths. Thus an application using FSRefs will continue working where one relying on POSIX file paths may fail.

It is possible to convert between the two formats via the functions FSPathMakeRef() and FSRefMakePath(). FSPathMakeRef() will convert a POSIX file path into a FSRef, and FSRefMakePath() will extract a POSIX file path from an FSRef.

Note that FSRefMakePath() will return a POSIX file path even in the event that an FSRef is referring to a file whose POSIX file path is longer PATH_MAX. One use for this feature would be to display file paths in an application. The only requirement for getting these extended file paths is that FSRefMakePath() is passed a large enough buffer to contain the path.

Unfortunately, FSPathMakeRef() cannot handle POSIX file paths that are greater than PATH_MAX in size. If you attempt to use too large of a file path, the function will fail and return a value of pathTooLongErr.

Internally the Carbon File Manager uses short paths created from volfs (see QA1113 [2]). For testing purposes only, here's a code snippet that generates short paths from a FSRef [3].