PATH
[previous] [table of contents] [next]
The NSSearchPathForDirectoriesInDomains function helps your application find resources in a Mac OS X (or YellowBox for WindowsTM) directory structure according to Mac OS X's standard paths and rules of precedence. See the preceding Search Paths section for a description of these conventions.
This section summarizes how to use NSSearchPathForDirectoriesInDomain; see the Functions section of the Foundation framework reference for a complete description. <<Function description not available yet.>>
NSSearchPathForDirectoriesInDomains takes an argument specifying the type of directory to be searched (Library, Applications, etc.), a second argument specifying the scope of the search (only in the user's home directory or in all standard directories, for example), and a flag that determines how the tilde chararcter ('~') is handled. The function returns an NSArray of paths. Here is the function prototype:
NSArray *NSSearchPathForDirectoriesInDomains(NSSearchPathDirectory directory, NSSearchPathDomainMask domainMask, BOOL expandTilde);
The directory argument can be any of these predefined values:
Argument |
Description |
NSApplicationDirectory |
Supported applications (such as /System/Applications) |
NSDemoApplicationDirectory |
Unsupported applications, demonstration versions (such as /System/Demos) |
NSDeveloperApplicationDirectory |
Developer applications (such as /System/Developer/Applications) |
NSAdminApplicationDirectory |
System and network administration applications (such as /System/Administration) |
NSLibraryDirectory |
Various user-visible documentation, support, and configuration files, resources (such as ~/Library) |
NSDeveloperDirectory |
Developer resources (such as /System/Developer) |
NSUserDirectory |
User home directories (such as /Local/Users/someuser) |
NSDocumentationDirectory |
Documentation (such as /System/Documentation) |
NSAllApplicationsDirectory |
All standard directories where applications can occur |
NSAllLibrariesDirectory |
All standard directories where resources can occur |
The domain argument can be any of these predefined values:
Value |
Description |
NSUserDomainMask |
User's home directory (for example, /Local/Users/steve) |
NSLocalDomainMask |
Location for applications and resources shared by users of this machine (for example, /Local) |
NSNetworkDomainMask |
Location for publicly available applications and resources shared over the local area network (/Network) |
NSSystemDomainMask |
Location for applications and resources provided by Apple (/System) |
NSAllDomainsMask |
All domains: all of the above and future items |
The domain values can be OR'd together to search a combination of domains, which will be searched according to the conventional search order. To search all domains, use NSAllDomainsMask.
The expandTilde flag controls how the tilde ('~') character is handled:
Value |
Description |
YES |
In returned paths, user's home directory is given explicitly (for example, /Local/Users/steve/Applications) |
NO |
In returned paths, user's home directory is represented by '~' (for example, ~/Applications) |
Here are some example invocations of the NSSearchPathForDirectoriesInDomains function and sample returned paths.
These examples assume a Mac OS X file system:
Invocation |
Returned Paths |
NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSAllDomainsMask, YES) |
/Network/Users/oz/tim/Library /Local/Library /Network/Library /System/Library |
NSSearchPathForDirectoriesInDomains(NSApplicationDirectory, NSUserDomainsMask, NO) |
~/Applications |
NSSearchPathForDirectoriesInDomains(NSAllApplicationsDirectory, NSSystemDomainsMask, NO) |
/System/Applications /System/Administration /System/Developer/Applications /System/Demos |
This example assumes a Windowstm file system:
Invocation |
Returned Paths |
NSSearchPathForDirectoriesInDomains(NSLibraryDirectory NSAllDomainsMask YES) |
D:/tim/Library C:/Apple/Local/Library C:/Apple/Library |
Notice that in the Windows example, NSSearchPathForDirectoriesInDomains prepends the installation root drive and directory ("C:/Apple") to the returned paths.