Crate sysdir 

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

This crate exposes Rust bindings to the sysdir(3) library functions provided by libSystem.dylib on macOS, iOS, tvOS, and watchOS.

For more detailed documentation, refer to the sysdir(3) man page.

Platform Support

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

Note that this crate is completely empty on non-Apple platforms.

Linkage

sysdir(3) is provided by libSystem, which is linked into every binary on Apple platforms. This crate does not link to CoreFoundation, Foundation, or any other system libraries and frameworks.

Path Semantics

These bindings expose raw sysdir(3) search-path strings from Darwin. Returned values are not normalized filesystem paths:

• user-domain results may contain a literal ~ instead of an expanded home directory
• if NEXT_ROOT is set and honored by the process, many local, network, and system-domain results are prefixed by that directory
• callers should not assume returned values are valid UTF-8 if NEXT_ROOT contains non-UTF-8 bytes

Callers that intend to use these values with filesystem APIs should expand ~, account for NEXT_ROOT, and validate UTF-8 before opening or creating files.

Examples

use core::ffi::{c_char, CStr};

use sysdir::*;

let mut path = [0; PATH_MAX as usize];

let dir = sysdir_search_path_directory_t::SYSDIR_DIRECTORY_USER;
let domain_mask = SYSDIR_DOMAIN_MASK_LOCAL;

unsafe {
    let mut state = sysdir_start_search_path_enumeration(dir, domain_mask);
    loop {
        let path = path.as_mut_ptr().cast::<c_char>();
        state = sysdir_get_next_search_path_enumeration(state, path);
        if state == 0 {
            break;
        }
        let path = CStr::from_ptr(path);
        let bytes = path.to_bytes();
        // `sysdir(3)` may prefix local-domain results with `NEXT_ROOT`,
        // which can also introduce non-UTF-8 bytes.
        assert!(bytes.ends_with(b"/Users"));
    }
}

Modules

man

man page for sysdir(3).

Structs

sysdir_search_path_enumeration_stateiOS or macOS or tvOS or watchOS

Opaque type for holding sysdir enumeration state.

Enums

sysdir_search_path_directory_tiOS or macOS or tvOS or watchOS

Constants

PATH_MAXiOS or macOS or tvOS or watchOS

SYSDIR_DOMAIN_MASK_ALLiOS or macOS or tvOS or watchOS

SYSDIR_DOMAIN_MASK_LOCALiOS or macOS or tvOS or watchOS

SYSDIR_DOMAIN_MASK_NETWORKiOS or macOS or tvOS or watchOS

SYSDIR_DOMAIN_MASK_SYSTEMiOS or macOS or tvOS or watchOS

SYSDIR_DOMAIN_MASK_USERiOS or macOS or tvOS or watchOS

Functions

sysdir_get_next_search_path_enumeration^⚠

sysdir_start_search_path_enumeration^⚠

Type Aliases

sysdir_search_path_domain_mask_tiOS or macOS or tvOS or watchOS