sysdir(3) Library Functions Manual sysdir(3)

sysdir_start_search_path_enumeration, sysdir_get_next_search_path_enumeration — Enumeration of the filesystem paths for the various standard system directories where apps, resources, etc. get installed.

#include <sysdir.h>


sysdir_search_path_enumeration_state
sysdir_start_search_path_enumeration(sysdir_search_path_directory_t dir, sysdir_search_path_domain_mask_t domainMask);


sysdir_search_path_enumeration_state
sysdir_get_next_search_path_enumeration(sysdir_search_path_enumeration_state state, char *path);

The sysdir API returns the various standard system directories where apps, resources, etc. get installed. Because queries can return multiple directories, the API is in the form of an enumeration. The directories are returned in search path order: that is, the first place to look is returned first.

() begins enumeration of the filesystem paths for the specified directory and domain(s). The return value should be passed to one or more calls to sysdir_get_next_search_path_enumeration() to obtain the filesystem path and continue the enumeration.

() returns a filesystem path for the directory and domain(s) specified by the state value returned by sysdir_start_search_path_enumeration(). Subsequent calls to sysdir_get_next_search_path_enumeration() should pass the state value returned by the previous call to continue the enumeration in each domain. A state value of zero will be returned when all domains have been enumerated.

The path buffer that is passed to () will be filled with a null-terminated string, possibly containing as many as PATH_MAX-1 characters.

Some directory paths returned may not exist on the filesystem.

Some combinations of dir and domainMask may return no directory paths.

Directory paths returned in the user domain will contain "~" to refer to the user's directory.

The environment variable NEXT_ROOT is prepended as necessary to the returned directory paths. NEXT_ROOT is ignored if the process is setuid or is code signed with entitlements.

The following sysdir_search_path_directory constants are defined:

SYSDIR_DIRECTORY_APPLICATION
Supported applications (Applications)
SYSDIR_DIRECTORY_DEMO_APPLICATION
Unsupported applications and demonstration versions (Applications/Demos)
SYSDIR_DIRECTORY_DEVELOPER_APPLICATION
Developer applications (Developer/Applications) Deprecated: As of Xcode 4.3, there is no longer a Developer Application directory directory; instead, Xcode.app is a self-contained application that gets installed in the user's Applications directory, by default, although it can be put anywhere.
SYSDIR_DIRECTORY_ADMIN_APPLICATION
System and network administration applications (Applications/Utilities)
SYSDIR_DIRECTORY_LIBRARY
Various user-visible documentation, support, and configuration files, resources (Library)
SYSDIR_DIRECTORY_DEVELOPER
Developer resources (Developer) Deprecated: As of Xcode 4.3, there is no longer a Developer directory; instead, Xcode.app is a self-contained application that gets installed in the user's Applications directory, by default, although it can be put anywhere.
SYSDIR_DIRECTORY_USER
User home directories (Users)
SYSDIR_DIRECTORY_DOCUMENTATION
Location of documentation (Library/Documentation)
SYSDIR_DIRECTORY_DOCUMENT
Location of documents (Documents)
SYSDIR_DIRECTORY_CORESERVICE
Location of core services (Library/CoreServices)
SYSDIR_DIRECTORY_AUTOSAVED_INFORMATION
Location of user's autosaved documents (Library/Autosave Information)
SYSDIR_DIRECTORY_DESKTOP
Location of user's desktop directory (Desktop)
SYSDIR_DIRECTORY_CACHES
Location of discardable cache files (Library/Caches)
SYSDIR_DIRECTORY_APPLICATION_SUPPORT
Location of application support files (Library/Application Support)
SYSDIR_DIRECTORY_DOWNLOADS
Location of user's downloads directory (Downloads)
SYSDIR_DIRECTORY_INPUT_METHODS
Location of input methods (Library/Input Methods)
SYSDIR_DIRECTORY_MOVIES
Location of user's Movies directory (Movies)
SYSDIR_DIRECTORY_MUSIC
Location of user's Music directory (Music)
SYSDIR_DIRECTORY_PICTURES
Location of user's Pictures directory (Pictures)
SYSDIR_DIRECTORY_PRINTER_DESCRIPTION
Location of system's PPDs directory (Library/Printers/PPDs)
SYSDIR_DIRECTORY_SHARED_PUBLIC
Location of user's Public sharing directory (Public)
SYSDIR_DIRECTORY_PREFERENCE_PANES
Location of the PreferencePanes directory for use with System Preferences (Library/PreferencePanes)
SYSDIR_DIRECTORY_ALL_APPLICATIONS
All directories where applications can occur (/Applications, ~/Applications, /Applications/Utilities, etc)
SYSDIR_DIRECTORY_ALL_LIBRARIES
All directories where resources can occur (/Library, ~/Library, /Network/Library, etc)

The following sysdir_search_path_domain_mask constants are defined:

SYSDIR_DOMAIN_MASK_USER
The user's home directory -- the place to install user's personal items (~)
SYSDIR_DOMAIN_MASK_LOCAL
Local to the current machine -- the place to install items available to everyone on this machine
SYSDIR_DOMAIN_MASK_NETWORK
Publically available location in the local area network -- the place to install items available on the network
SYSDIR_DOMAIN_MASK_SYSTEM
Provided by Apple -- can't be modified
SYSDIR_DOMAIN_MASK_ALL
All domains -- all of the above and future domains

The following environment variable affects the execution of sysdir_get_next_search_path_enumeration:

If the NEXT_ROOT environment variable is set and the current process is not tainted by uid or gid changes, NEXT_ROOT is prepended as necessary to the returned directory paths. NEXT_ROOT is ignored if the process is setuid or is code signed with entitlements.

#include <limits.h>
#include <sysdir.h>

char path[PATH_MAX];
sysdir_search_path_enumeration_state state = sysdir_start_search_path_enumeration(dir, domainMask);
while ( (state = sysdir_get_next_search_path_enumeration(state, path)) != 0 ) {
    // Handle directory path
}

The sysdir API first appeared in OS X 10.12, iOS 10, watchOS 3 and tvOS 10 replacing the deprecated NSSystemDirectories(3) API.

December 22, 2015 Darwin