Developer Documentation
PATH  Mac OS X Documentation > Mac OS X File System Conventions

[previous] [table of contents] [next]

NSSearchPathForDirectoriesInDomains

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

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

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 Argument

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)

Note: On some platforms, some combinations of arguments might return empty arrays. For instance, on Windowstm, the "network" domain is not currently supported. You should always check to make sure there is at least one item in the array before accessing the item. Also note that it's sometimes possible to get multiple values even when you expected one; in that case the first one is the best one to use.

 

Some Examples

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.

[next]