Specifying the Path to a File or Directory

The preferred way to specify the location of a file or directory is to use the NSURL class. Although the NSString class has many methods related to path creation, URLs offer a more robust way to locate files and directories. For apps that also work with network resources, URLs also mean that you can use one type of object to manage items located on a local file system or on a network server.

For most URLs, you build the URL by concatenating directory and file names together using the appropriate NSURL methods until you have the path to the item. A URL built in that way is referred to as a path-based URL because it stores the names needed to traverse the directory hierarchy to locate the item. (You also build string-based paths by concatenating directory and file-names together, with the results stored in a slightly different format than that used by the NSURL class.) In addition to path-based URLs, you can also create a file reference URL, which identifies the location of the file or directory using a unique ID.

All of the following entries are valid references to a file called MyFile.txt in a user’s Documents directory:

Path-based URL: file://localhost/Users/steve/Documents/MyFile.txt

File reference URL: file:///.file/id=6571367.2773272/

String-based path: /Users/steve/Documents/MyFile.txt

You create URL objects using the NSURL methods and convert them to file reference URLs only when needed. Path-based URLs are easier to manipulate, easier to debug, and are generally preferred by classes such as NSFileManager. An advantage of file reference URLs is that they are less fragile than path-based URLs while your app is running. If the user moves a file in the Finder, any path-based URLs that refer to the file immediately become invalid and must be updated to the new path. However, as long as the file moved to another location on the same disk, its unique ID does not change and any file reference URLs remain valid.

Of course, there are still times when you might need to use strings to refer to a file. Fortunately, the NSURL class provides methods to convert path-based URLs to and from NSString objects. You might use a string-based path when presenting that path to the user or when calling a system routine that accepts strings instead of URLs. The conversion between NSURL objects and NSString objects is done using the NSURL class’s method absoluteString.

Because NSURL and NSString describe only the location of a file or directory, you can create them before the actual file or directory exists. Neither class attempts to validate the actual existence of the file or directory you specify. In fact, you must create the path to a nonexistent file or directory before you can create it on disk.

If you have an NSURL object that refers to an actual file or directory on disk, and you want to get the user visible name of the volume on which it resides, you use the method getResourceValue:forKey:error: in a two step process:

• Use the NSURLVolumeURLKey constant to obtain the volume URL from the resource URL.

• Use the NSURLLocalizedNameKey constant to obtain the user visible volume name from the volume URL.

Use the NSURLLocalizedNameKey constant rather than the NSURLNameKey constant. Using NSURLNameKey returns the name of the volume in the file system, which may not be the same as the user visible name. Listing 2-1 demonstrates this process for the current user’s home directory.

Listing 2-1  Obtaining the user visible volume name for a resource URL

NSURL *url = [NSURL fileURLWithPath:NSHomeDirectory()];

NSURL *volumeURL = nil;

NSString *volumeName = nil;

if ([url getResourceValue:&volumeURL forKey:NSURLVolumeURLKey error:nil]) {

    if ([volumeURL getResourceValue:&volumeName forKey:NSURLLocalizedNameKey error:nil]) {

        NSLog(@"The volume name is: %@", volumeName);

    }

}

For more information about the methods you use to create and manipulate URLs and strings, see NSURL Class Reference and NSString Class Reference.

Asking the User to Locate an Item

In macOS, user interactions with the file system should always be through the standard Open and Save panels. Because these panels involve interrupting the user, use them only in a limited number of situations:

• To open user documents

• To ask the user where to save a new document

• To associate user files (or directories of files) with an open window

Never use the Open and Save panels to access any files that your app created and uses internally. Support files, caches, and app-generated data files should be placed in one of the standard directories dedicated to app-specific files.

For information on how to present and customize the Open and Save panels, see Using the Open and Save Panels.

Locating Items in Your App Bundle

Apps that need to locate resource files inside their bundle directory (or inside another known bundle) must do so using an NSBundle object. Bundles eliminate the need for your app to remember the location of individual files by organizing those files in a specific way. The methods of the NSBundle class understand that organization and use it to locate your app’s resources on demand. The advantage of this technique is that you can generally rearrange the contents of your bundle without rewriting the code you use to access it. Bundles also take advantage of the current user’s language settings to locate an appropriately localized version of a resource file.

The following code shows how to retrieve a URL object for an image named MyImage.png that is located in the app’s main bundle. This code determines only the location of the file; it does not open the file. You would pass the returned URL to a method of the NSImage class to load the image from disk so that you could use it.

NSURL* url = [[NSBundle mainBundle] URLForResource:@"MyImage" withExtension:@"png"];

For more information about bundles, including how to locate items in a bundle, see Bundle Programming Guide. For specific information about loading and using resources in your app, see Resource Programming Guide.

Locating Items in the Standard Directories

When you need to locate a file in one of the standard directories, use the system frameworks to locate the directory first and then use the resulting URL to build a path to the file. The Foundation framework includes several options for locating the standard system directories. By using these methods, the paths will be correct whether your app is sandboxed or not:

• The URLsForDirectory:inDomains: method of the NSFileManager class returns a directory’s location packaged in an NSURL object. The directory to search for is an NSSearchPathDirectory constant. These constants provide URLs for the user’s home directory, as well as most of the standard directories.

• The NSSearchPathForDirectoriesInDomains function behaves like the URLsForDirectory:inDomains: method but returns the directory’s location as a string-based path. Use the URLsForDirectory:inDomains: method instead.

• The NSHomeDirectory function returns the path to either the user’s or app’s home directory. (Which home directory is returned depends on the platform and whether the app is in a sandbox.) When an app is sandboxed the home directory points to the app’s sandbox, otherwise it points to the User’s home directory on the file system. If constructing a file to a subdirectory of a user’s home directory, consider using the URLsForDirectory:inDomains: method instead.

You can use the URL or path-based string you receive from the preceding routines to build new objects with the locations of the files you want. Both the NSURL and NSString classes provide path-related methods for adding and removing path components and making changes to the path in general. Listing 2-2 shows an example that searches for the standard Application Support directory and creates a new URL for a directory containing the app’s data files.

Listing 2-2  Creating a URL for an item in the app support directory

- (NSURL*)applicationDataDirectory {

    NSFileManager* sharedFM = [NSFileManager defaultManager];

    NSArray* possibleURLs = [sharedFM URLsForDirectory:NSApplicationSupportDirectory

                                 inDomains:NSUserDomainMask];

    NSURL* appSupportDir = nil;

    NSURL* appDirectory = nil;

    if ([possibleURLs count] >= 1) {

        // Use the first directory (if multiple are returned)

        appSupportDir = [possibleURLs objectAtIndex:0];

    }

    // If a valid app support directory exists, add the

    // app's bundle ID to it to specify the final directory.

    if (appSupportDir) {

        NSString* appBundleID = [[NSBundle mainBundle] bundleIdentifier];

        appDirectory = [appSupportDir URLByAppendingPathComponent:appBundleID];

    }

    return appDirectory;

}

Locating Files Using Bookmarks

If you want to save the location of a file persistently, use the bookmark capabilities of NSURL. A bookmark is an opaque data structure, enclosed in an NSData object, that describes the location of a file. Whereas path- and file reference URLs are potentially fragile between launches of your app, a bookmark can usually be used to re-create a URL to a file even in cases where the file was moved or renamed.

To create a bookmark for an existing URL, use the bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: method of NSURL. Specifying the NSURLBookmarkCreationSuitableForBookmarkFile option creates an NSData object suitable for saving to disk. Listing 2-3 shows a simple example implementation that uses this method to create a bookmark data object.

Listing 2-3  Converting a URL to a persistent form

- (NSData*)bookmarkForURL:(NSURL*)url {

    NSError* theError = nil;

    NSData* bookmark = [url bookmarkDataWithOptions:NSURLBookmarkCreationSuitableForBookmarkFile

                                            includingResourceValuesForKeys:nil

                                            relativeToURL:nil

                                            error:&theError];

    if (theError || (bookmark == nil)) {

        // Handle any errors.

        return nil;

    }

    return bookmark;

}

If you write the persistent bookmark data to disk using the writeBookmarkData:toURL:options:error: method of NSURL, what the system creates on disk is an alias file. Aliases are similar to symbolic links but are implemented differently. Normally, users create aliases from the Finder when they want to create links to files elsewhere on the system.

To transform a bookmark data object back into a URL, use the URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error: method of NSURL. Listing 2-4 shows the process for converting a bookmark back into a URL.

Listing 2-4  Returning a persistent bookmark to its URL form

- (NSURL*)urlForBookmark:(NSData*)bookmark {

    BOOL bookmarkIsStale = NO;

    NSError* theError = nil;

    NSURL* bookmarkURL = [NSURL URLByResolvingBookmarkData:bookmark

                                            options:NSURLBookmarkResolutionWithoutUI

                                            relativeToURL:nil

                                            bookmarkDataIsStale:&bookmarkIsStale

                                            error:&theError];

    if (bookmarkIsStale || (theError != nil)) {

        // Handle any errors

        return nil;

    }

    return bookmarkURL;

}

The Core Foundation framework provides a set of C-based functions that parallel the bookmark interface provided by NSURL. For more information about using those functions, see CFURL Reference.

Enumerating a Directory One File at a Time

Enumerating a directory one file at a time is recommended when you want to search for a specific file and stop enumerating when you find it. File-by-file enumeration uses the NSDirectoryEnumerator class, which defines the methods for retrieving items. Because NSDirectoryEnumerator itself is an abstract class, however, you do not create instances of it directly. Instead, you use either the enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: or the enumeratorAtPath: method of NSFileManager object to obtain a concrete instance of the class for use in your enumeration.

Enumerator objects return the paths of all files and directories contained within the enumerated directory. Because enumerations are recursive and cross device boundaries, the number of files and directories returned may be more than what is present in the starting directory. You can skip the contents of any directory you are not interested in by calling the enumerator object’s skipDescendents method. Enumerator objects do not resolve symbolic links or attempt to traverse symbolic links that point to directories.

Listing 2-5 shows how to use the enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: method to list all the user-visible subdirectories of a given directory, noting whether they are directories or file packages. The keys array tells the enumerator object to prefetch and cache information for each item. Prefetching this information improves efficiency by touching the disk only once. The options argument specifies that the enumeration should not list the contents of file packages and hidden files. The error handler is a block object that returns a Boolean value. If the block returns YES, the enumeration continues after the error; if it returns NO, the enumeration stops.

Listing 2-5  Enumerating the contents of a directory

NSURL *directoryURL = <#An NSURL object that contains a reference to a directory#>;

NSArray *keys = [NSArray arrayWithObjects:

    NSURLIsDirectoryKey, NSURLIsPackageKey, NSURLLocalizedNameKey, nil];

NSDirectoryEnumerator *enumerator = [[NSFileManager defaultManager]

                                     enumeratorAtURL:directoryURL

                                     includingPropertiesForKeys:keys

                                     options:(NSDirectoryEnumerationSkipsPackageDescendants |

                                              NSDirectoryEnumerationSkipsHiddenFiles)

                                     errorHandler:^(NSURL *url, NSError *error) {

                                         // Handle the error.

                                         // Return YES if the enumeration should continue after the error.

                                         return <#YES or NO#>;

                                     }];

for (NSURL *url in enumerator) {

    // Error checking is omitted for clarity.

    NSNumber *isDirectory = nil;

    [url getResourceValue:&isDirectory forKey:NSURLIsDirectoryKey error:NULL];

    if ([isDirectory boolValue]) {

        NSString *localizedName = nil;

        [url getResourceValue:&localizedName forKey:NSURLLocalizedNameKey error:NULL];

        NSNumber *isPackage = nil;

        [url getResourceValue:&isPackage forKey:NSURLIsPackageKey error:NULL];

        if ([isPackage boolValue]) {

            NSLog(@"Package at %@", localizedName);

        }

        else {

            NSLog(@"Directory at %@", localizedName);

        }

    }

}

You can use other methods declared by NSDirectoryEnumerator to determine attributes of files during the enumeration—both of the parent directory and the current file or directory—and to control recursion into subdirectories. The code in Listing 2-6 enumerates the contents of a directory and lists files that have been modified within the last 24 hours; if, however, it comes across RTFD file packages, it skips recursion into them.

Listing 2-6  Looking for files that have been modified recently

NSString *directoryPath = <#Get a path to a directory#>;

NSDirectoryEnumerator *directoryEnumerator = [[NSFileManager defaultManager] enumeratorAtPath:directoryPath];

NSDate *yesterday = [NSDate dateWithTimeIntervalSinceNow:(-60*60*24)];

for (NSString *path in directoryEnumerator) {

    if ([[path pathExtension] isEqualToString:@"rtfd"]) {

        // Don't enumerate this directory.

        [directoryEnumerator skipDescendents];

    }

    else {

        NSDictionary *attributes = [directoryEnumerator fileAttributes];

        NSDate *lastModificationDate = [attributes objectForKey:NSFileModificationDate];

        if ([yesterday earlierDate:lastModificationDate] == yesterday) {

            NSLog(@"%@ was modified within the last 24 hours", path);

        }

    }

}

Getting the Contents of a Directory in a Single Batch Operation

If you know that you want to look at every item in a directory, you can retrieve a snapshot of the items and iterate over them at your convenience. Retrieving the contents of a directory in a batch operation is not the most efficient way to enumerate a directory, because the file manager must walk the entire directory contents every time. However, if you plan to look at all the items anyway, it is a much simpler way to retrieve the items.

There are two options for doing a batch enumeration of a directory using NSFileManager:

• To perform a shallow enumeration, use the contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error: or contentsOfDirectoryAtPath:error: method.

• To perform a deep enumeration and return only subdirectories, use the subpathsOfDirectoryAtPath:error: method.

Listing 2-7 shows an example that uses the contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error: method to enumerate the contents of a directory. One of the benefits of using URLs is that you can also efficiently retrieve additional information about each item. This example retrieves the localized name, creation date, and type information for each item in the directory and stores that information in the corresponding NSURL object. When the method returns, you can proceed to iterate over the items in the array variable and do what you need with them.

Listing 2-7  Retrieving the list of items in a directory all at once

NSURL *url = <#A URL for a directory#>;

NSError *error = nil;

NSArray *properties = [NSArray arrayWithObjects: NSURLLocalizedNameKey,

                          NSURLCreationDateKey, NSURLLocalizedTypeDescriptionKey, nil];

NSArray *array = [[NSFileManager defaultManager]

                   contentsOfDirectoryAtURL:url

                   includingPropertiesForKeys:properties

                   options:(NSDirectoryEnumerationSkipsHiddenFiles)

                   error:&error];

if (array == nil) {

    // Handle the error

}

Perform File Operations Lazily

Operations involving the file system should be performed only when they are absolutely necessary. Accessing the file system usually takes a lot of time relative to other computer-wide tasks. So make sure you really need to access the disk before you do. Specifically:

• Write data to disk only when you have something valuable to save. The definition of what is valuable is different for each app but should generally involve information that the user provides explicitly. For example, if your app creates some default data structures at launch time, do not save those structures to disk unless the user changes them.

• Read data from disk only when you need it. In other words, load data that you need for your user interface now but do not load an entire file just to get one small piece of data from that file. For custom file formats, use file mapping or read only the few chunks of a file that you need to present your user interface. Read any remaining chunks as needed in response to user interactions with the data. For structured data formats, use Core Data to manage and optimize the reading of data for you.

Use Secure Coding Practices

There are several principles you can follow to help ensure that you do not have file-based security vulnerabilities in your program:

• Check the result codes for any functions or methods you call. Result codes are there to let you know that there is a problem, so do pay attention to them. For example, if you try to delete a directory that you think is empty and get an error code, you might find that the directory is not empty after all.

• When working in a directory to which your process does not have exclusive access, you must check to make sure a file does not exist before you create it. You must also verify that the file you intend to read from or write to is the same file you created.

• Whenever possible use routines that operate on file descriptors rather than pathnames. In this way you can be sure you’re always dealing with the same file.

• Intentionally create files as a separate step from opening them so that you can verify that you are opening a file you created rather than one that already existed

• Know whether the function you are calling follows symbolic links. For example, the lstat function gives you the status of a file regardless of whether it’s a normal file or a symbolic link, but the stat function follows symbolic links and, if the specified file was a symbolic link, returns the status of the linked-to file. Therefore, if you use the stat function, you might be accessing a different file than you expected.

• Before you read a file, make sure that file has the owner and permissions you expect. Be prepared to fail gracefully (rather than hanging) if it does not.

• Set your process’ file code creation mask (umask) to restrict access to files created by your process. The umask is a bitmask that alters the default permissions of a new file. You do not reset the umask for your app, your process inherits the umask from its parent process. For more information about setting the umask, see the umask(2) man page.

For additional tips and coding practices, see Race Conditions and Secure File Operations in Secure Coding Guide.

Assume Case Sensitivity for Paths

When searching or comparing filenames, always assume that the underlying file system is case sensitive. macOS supports many file systems that use case to differentiate between files. Even on file systems (such as APFS and HFS+) that support case insensitivity, there are still times when case may be used to compare filenames. For example, the NSBundle class and CFBundle APIs consider case when searching bundle directories for named resources.

Include Filename Extensions for New Files

All files should have a filename extension that reflects the type of content contained in the file. Filename extensions help the system determine how to open files and also make it easier to exchange files with other computers or other platforms. For example, network transfer programs often use filename extensions to determine the best way to to transfer files between computers.

Use Display Names When Presenting Items

Whenever you need to present the name of a file or directory in your user interface, always use the item’s display name. Using the display name ensures that what your app presents matches what the Finder and other apps are presenting. For example, if your app shows the path to a file, using the display name ensures that the path is localized in accordance with the current user’s language settings.

For more information about display names, see Files and Directories Can Have Alternate Names.

Accessing Files Safely from Background Threads

In general, the objects and functions used to access and manipulate files can be used from any thread of your app. However, as with all threaded programming, make sure you manipulate files safely from your background threads:

• Avoid using the same file descriptor from multiple threads. Doing so could cause each thread to disrupt the state of the other.

• Always use file coordinators to access files. File coordinators provide notifications when other threads in your program (or other processes) access the same file. You can use these notifications to clean up your local data structures or perform other relevant tasks.

• Create a unique instance of NSFileManager for each thread when copying, moving, linking, or deleting files. Although most file manager operations are thread-safe, operations involving a delegate require a unique instance of NSFileManager, especially if you are performing those operations on background threads.