NSFileManager Class Reference

Discussion

This method does not traverse a terminal symbolic link.

Discussion

All relative pathnames refer implicitly to the current working directory. Changing the current working directory affects only paths created in the current process.

Discussion

These components cannot be used for path operations and are only suitable for display to the user.

Discussion

As explained in App Sandbox Design Guide, groups of sandboxed apps that need to share files and other information can request a container directory as part of their entitlements. These directories are stored in ~/Library/Group Containers/.

When called with a valid group identifier, this method returns the location of that directory as an NSURL object. This method also creates the directory if it does not yet exist.

Discussion

If path1 and path2 are directories, the contents are the list of files and subdirectories each contains—contents of subdirectories are also compared. For files, this method checks to see if they’re the same file, then compares their size, and finally compares their contents. This method does not traverse symbolic links, but compares the links themselves.

Discussion

This method performs a shallow search of the directory and therefore does not traverse symbolic links or return the contents of any subdirectories. This method also does not return URLs for the current directory (“.”), parent directory (“..”), or resource forks (files that begin with “._”) but it does return other hidden files (files that begin with a period character). If you need to perform a deep enumeration, use the enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: method instead.

The order of the files in the returned array is undefined.

Discussion

This method performs a shallow search of the directory and therefore does not traverse symbolic links or return the contents of any subdirectories. This method also does not return URLs for the current directory (“.”), parent directory (“..”), or resource forks (files that begin with “._”) but it does return other hidden files (files that begin with a period character). If you need to perform a deep enumeration, use the enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: method instead.

The order of the files in the returned array is undefined.

Discussion

When copying items, the current process must have permission to read the file or directory at srcPath and write the parent directory of dstPath. If the item at srcPath is a directory, this method copies the directory and all of its contents, including any hidden files. If a file with the same name already exists at dstPath, this method aborts the copy attempt and returns an appropriate error. If the last component of srcPath is a symbolic link, only the link is copied to the new path.

Prior to copying an item, the file manager asks its delegate if it should actually do so for each item. It does this by calling the fileManager:shouldCopyItemAtURL:toURL: method; if that method is not implemented it calls the fileManager:shouldCopyItemAtPath:toPath: method instead. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager copies the given file or directory. If there is an error copying an item, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:copyingItemAtURL:toURL: or fileManager:shouldProceedAfterError:copyingItemAtPath:toPath: method to determine how to proceed.

Discussion

When copying items, the current process must have permission to read the file or directory at srcURL and write the parent directory of dstURL. If the item at srcURL is a directory, this method copies the directory and all of its contents, including any hidden files. If a file with the same name already exists at dstURL, this method aborts the copy attempt and returns an appropriate error. If the last component of srcURL is a symbolic link, only the link is copied to the new path.

Prior to copying each item, the file manager asks its delegate if it should actually do so. It does this by calling the fileManager:shouldCopyItemAtURL:toURL: method; if that method is not implemented (or the process is running in OS X 10.5 or earlier) it calls the fileManager:shouldCopyItemAtPath:toPath: method instead. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager proceeds to copy the file or directory. If there is an error copying an item, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:copyingItemAtURL:toURL: or fileManager:shouldProceedAfterError:copyingItemAtPath:toPath: method to determine how to proceed.

Discussion

If you specify nil for the attributes parameter, this method uses a default set of values for the owner, group, and permissions of any newly created directories in the path. Similarly, if you omit a specific attribute, the default value is used. The default values for newly created directories are as follows:

• Permissions are set according to the umask of the current process. For more information, see umask.

• The owner ID is set to the effective user ID of the process.

• The group ID is set to that of the parent directory.

Discussion

If you specify nil for the attributes parameter, this method uses a default set of values for the owner, group, and permissions of any newly created directories in the path. Similarly, if you omit a specific attribute, the default value is used. The default values for newly created directories are as follows:

• Permissions are set according to the umask of the current process. For more information, see umask.

• The owner ID is set to the effective user ID of the process.

• The group ID is set to that of the parent directory.

If you want to specify a relative path for url, you must set the current working directory before creating the corresponding NSURL object.

Discussion

If you specify nil for the attributes parameter, this method uses a default set of values for the owner, group, and permissions of any newly created directories in the path. Similarly, if you omit a specific attribute, the default value is used. The default values for newly created files are as follows:

• Permissions are set according to the umask of the current process. For more information, see umask.

• The owner ID is set to the effective user ID of the process.

• The group ID is set to that of the parent directory.

If a file already exists at path, this method overwrites the contents of that file if the current process has the appropriate privileges to do so.

Discussion

This method does not traverse symbolic links contained in destPath, making it possible to create symbolic links to locations that do not yet exist. Also, if the final path component in path is a symbolic link, that link is not followed.

Discussion

This method does not traverse symbolic links contained in destPath, making it possible to create symbolic links to locations that do not yet exist. Also, if the final path component in path is a symbolic link, that link is not followed.

Discussion

The string returned by this method is initialized to the current working directory; you can change the working directory by invoking changeCurrentDirectoryPath:.

Relative pathnames refer implicitly to the current directory. For example, if the current directory is /tmp, and the relative pathname reports/info.txt is specified, the resulting full pathname is /tmp/reports/info.txt.

Discussion

Display names are user-friendly names for files. They are typically used to localize standard file and directory names according to the user’s language settings. They may also reflect other modifications, such as the removal of filename extensions. Such modifications are used only when displaying the file or directory to the user and do not reflect the actual path to the item in the file system. For example, if the current user’s preferred language is French, the following code fragment logs the name Bibliothèque and not the name Library, which is the actual name of the directory.

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES);

if ([paths count] > 0)

{

    NSString *documentsDirectory = [paths objectAtIndex:0];

    NSFileManager *fileManager = [[NSFileManager alloc] init];

    NSString *displayNameAtPath = [fileManager displayNameAtPath:documentsDirectory];

    NSLog(@"%@", displayNameAtPath);

    [fileManager release];

}

Discussion

Because the enumeration is deep—that is, it lists the contents of all subdirectories—this enumerator object is useful for performing actions that involve large file-system subtrees. This method does not resolve symbolic links encountered in the traversal process, nor does it recurse through them if they point to a directory.

This code fragment enumerates the subdirectories and files under a user’s Documents directory and processes all files with an extension of .doc:

NSString *docsDir = [NSHomeDirectory() stringByAppendingPathComponent:  @"Documents"];

NSFileManager *localFileManager=[[NSFileManager alloc] init];

NSDirectoryEnumerator *dirEnum =

    [localFileManager enumeratorAtPath:docsDir];

NSString *file;

while ((file = [dirEnum nextObject])) {

    if ([[file pathExtension] isEqualToString: @"doc"]) {

        // process the document

        [self scanDocument: [docsDir stringByAppendingPathComponent:file]];

    }

}

[localFileManager release];

The NSDirectoryEnumerator class has methods for obtaining the attributes of the existing path and of the parent directory and for skipping descendants of the existing path.

Discussion

Because the enumeration is deep—that is, it lists the contents of all subdirectories—this enumerator object is useful for performing actions that involve large file-system subtrees. If the method is passed a directory on which another file system is mounted (a mount point), it traverses the mount point. This method does not resolve symbolic links encountered in the traversal process, nor does it recurse through them if they point to a directory.

The NSDirectoryEnumerator class has methods for skipping descendants of the existing path and for returning the number of levels deep the current object is in the directory hierarchy being enumerated (where the directory passed to enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: is considered to be level 0).

This code fragment enumerates a URL and its subdirectories, collecting the URLs of files (skips directories). It also demonstrates how to ignore the contents of specified directories, in this case directories named “_extras”.

-(void)scanURLIgnoringExtras:(NSURL *)directoryToScan

{

    // Create a local file manager instance

    NSFileManager *localFileManager=[[NSFileManager alloc] init];

    // Enumerate the directory (specified elsewhere in your code)

    // Request the two properties the method uses, name and isDirectory

    // Ignore hidden files

    // The errorHandler: parameter is set to nil. Typically you'd want to present a panel

    NSDirectoryEnumerator *dirEnumerator = [localFileManager enumeratorAtURL:directoryToScan

                        includingPropertiesForKeys:[NSArray arrayWithObjects:NSURLNameKey,

                                                    NSURLIsDirectoryKey,nil]

                        options:NSDirectoryEnumerationSkipsHiddenFiles

                        errorHandler:nil];

    // An array to store the all the enumerated file names in

    NSMutableArray *theArray=[NSMutableArray array];

    // Enumerate the dirEnumerator results, each value is stored in allURLs

    for (NSURL *theURL in dirEnumerator) {

        // Retrieve the file name. From NSURLNameKey, cached during the enumeration.

        NSString *fileName;

        [theURL getResourceValue:&fileName forKey:NSURLNameKey error:NULL];

        // Retrieve whether a directory. From NSURLIsDirectoryKey, also

        // cached during the enumeration.

        NSNumber *isDirectory;

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

        // Ignore files under the _extras directory

        if (([fileName caseInsensitiveCompare:@"_extras"]==NSOrderedSame) &&

            ([isDirectory boolValue]==YES))

        {

            [dirEnumerator skipDescendants];

        }

        else

        {

            // Add full path for non directories

            if ([isDirectory boolValue]==NO)

                [theArray addObject:theURL];

        }

    }

    // Do something with the path URLs.

    NSLog(@"theArray - %@",theArray);

    // Release the localFileManager.

    [localFileManager release];

}

Discussion

This method does not remove the item from the cloud. It removes only the local version. You can use this method to force iCloud to download a new version of the file or directory from the server.

To delete a file permanently from the user’s iCloud storage, use the regular NSFileManager routines for deleting files and directories. Remember that deleting items from iCloud cannot be undone. Once deleted, the item is gone forever.

Discussion

If the file at path is inaccessible to your app, perhaps because one or more parent directories are inaccessible, this method returns NO. If the final element in path specifies a symbolic link, this method traverses the link and returns YES or NO based on the existence of the file at the link destination.

Discussion

If the file at path is inaccessible to your app, perhaps because one or more parent directories are inaccessible, this method returns NO. If the final element in path specifies a symbolic link, this method traverses the link and returns YES or NO based on the existence of the file at the link destination.

If you need to further determine if path is a package, use the isFilePackageAtPath: method of NSWorkspace.

This example gets an array that identifies the fonts in the user's fonts directory:

NSArray *subpaths;

BOOL isDir;

NSArray *paths = NSSearchPathForDirectoriesInDomains

                     (NSLibraryDirectory, NSUserDomainMask, YES);

if ([paths count] == 1) {

    NSFileManager *fileManager = [[NSFileManager alloc] init];

    NSString *fontPath = [[paths objectAtIndex:0] stringByAppendingPathComponent:@"Fonts"];

    if ([fileManager fileExistsAtPath:fontPath isDirectory:&isDir] && isDir) {

        subpaths = [fileManager subpathsAtPath:fontPath];

// ...

[fileManager release];

Discussion

Use this method if your code calls system routines that expect C-string path arguments. If you use the C string beyond the scope of the current autorelease pool, you must copy it.

This method raises an exception if path is nil or contains the empty string. This method also throws an exception if the conversion of the string fails.

Discussion

In iOS and in OS X 10.5 and later you can use this method to create a specific file manager instance. You might do this in situations where you want to associate a delegate with the file manager to receive notifications about the status of file-related operations.

Discussion

For a directory or file to be deletable, the current process must either be able to write to the parent directory of path or it must have the same owner as the item at path. If path is a directory, every item contained in path must be deletable by the current process.

If the file at path is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns NO. If the item at path is a symbolic link, it is not traversed.

Discussion

If the file at path is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns NO. This method traverses symbolic links in the path. This method also uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is executable.

Discussion

If the file at path is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns NO. This method traverses symbolic links in the path. This method also uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is readable.

Discussion

This method reflects only whether the item should be stored in iCloud because a call was made to the setUbiquitous:itemAtURL:destinationURL:error: method with a value of YES for its flag parameter. This method does not reflect whether the file has actually been uploaded to any iCloud servers. To determine a file’s upload status, check the NSURLUbiquitousItemIsUploadedKey attribute of the corresponding NSURL object.

Discussion

If the file at path is inaccessible to your app, perhaps because it does not have search privileges for one or more parent directories, this method returns NO. This method traverses symbolic links in the path. This method also uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is writable.

Discussion

Use this method to create hard links between files in the current file system. If srcPath is a directory, this method creates a new directory at dstPath and then creates hard links for the items in that directory. If srcPath is (or contains) a symbolic link, the symbolic link is copied to the new location and not converted to a hard link.

Prior to linking each item, the file manager asks its delegate if it should actually create the link. It does this by calling the fileManager:shouldLinkItemAtURL:toURL: method; if that method is not implemented it calls the fileManager:shouldLinkItemAtPath:toPath: method instead. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager creates the hard link. If there is an error moving one out of several items, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:linkingItemAtURL:toURL: or fileManager:shouldProceedAfterError:linkingItemAtPath:toPath: method to determine how to proceed.

Discussion

Use this method to create hard links between files in the current file system. If srcURL is a directory, this method creates a new directory at srcURL and then creates hard links for the items in that directory. If srcURL is (or contains) a symbolic link, the symbolic link is copied and not converted to a hard link at dstURL.

Prior to linking each item, the file manager asks its delegate if it should actually create the link. It does this by calling the fileManager:shouldLinkItemAtURL:toURL: method; if that method is not implemented it calls the fileManager:shouldLinkItemAtPath:toPath: method instead. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager creates the hard link. If there is an error moving one out of several items, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:linkingItemAtURL:toURL: or fileManager:shouldProceedAfterError:linkingItemAtPath:toPath: method to determine how to proceed.

Discussion

This call may block if I/O is required to determine values for the requested propertyKeys.

Discussion

When moving items, the current process must have permission to read the item at srcPath and write the parent directory of dstPath. If the item at srcPath is a directory, this method moves the directory and all of its contents, including any hidden files. If an item with the same name already exists at dstPath, this method aborts the move attempt and returns an appropriate error. If the last component of srcPath is a symbolic link, only the link is moved to the new path; the item pointed to by the link remains at its current location.

Prior to moving the item, the file manager asks its delegate if it should actually move it. It does this by calling the fileManager:shouldMoveItemAtURL:toURL: method; if that method is not implemented it calls the fileManager:shouldMoveItemAtPath:toPath: method instead. If the item being moved is a directory, the file manager notifies the delegate only for the directory itself and not for any of its contents. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager moves the file. If there is an error moving one out of several items, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:movingItemAtURL:toURL: or fileManager:shouldProceedAfterError:movingItemAtPath:toPath: method to determine how to proceed.

If the source and destination of the move operation are not on the same volume, this method copies the item first and then removes it from its current location. This behavior may trigger additional delegate notifications related to copying and removing individual items.

Discussion

When moving items, the current process must have permission to read the item at srcURL and write the parent directory of dstURL. If the item at srcURL is a directory, this method moves the directory and all of its contents, including any hidden files. If an item with the same name already exists at dstURL, this method aborts the move attempt and returns an appropriate error. If the last component of srcURL is a symbolic link, only the link is moved to the new path; the item pointed to by the link remains at its current location.

Prior to moving the item, the file manager asks its delegate if it should actually move it. It does this by calling the fileManager:shouldMoveItemAtURL:toURL: method; if that method is not implemented it calls the fileManager:shouldMoveItemAtPath:toPath: method instead. If the item being moved is a directory, the file manager notifies the delegate only for the directory itself and not for any of its contents. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager moves the file. If there is an error moving one out of several items, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:movingItemAtURL:toURL: or fileManager:shouldProceedAfterError:movingItemAtPath:toPath: method to determine how to proceed.

If the source and destination of the move operation are not on the same volume, this method copies the item first and then removes it from its current location. This behavior may trigger additional delegate notifications related to copying and removing individual items.

Discussion

Prior to removing each item, the file manager asks its delegate if it should actually do so. It does this by calling the fileManager:shouldRemoveItemAtURL: method; if that method is not implemented (or the process is running in OS X 10.5 or earlier) it calls the fileManager:shouldRemoveItemAtPath: method instead. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager proceeds to remove the file or directory. If there is an error removing an item, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:removingItemAtURL: or fileManager:shouldProceedAfterError:removingItemAtPath: method to determine how to proceed.

Discussion

Prior to removing each item, the file manager asks its delegate if it should actually do so. It does this by calling the fileManager:shouldRemoveItemAtURL: method; if that method is not implemented (or the process is running in OS X 10.5 or earlier) it calls the fileManager:shouldRemoveItemAtPath: method instead. If the delegate method returns YES, or if the delegate does not implement the appropriate methods, the file manager proceeds to remove the file or directory. If there is an error removing an item, the file manager may also call the delegate’s fileManager:shouldProceedAfterError:removingItemAtURL: or fileManager:shouldProceedAfterError:removingItemAtPath: method to determine how to proceed.

Discussion

By default, the creation date, permissions, Finder label and color, and Spotlight comments of the original item will be preserved on the resulting item.

If an error occurs and the original item is not in the original location or a temporary location, the returned error object contains a user info dictionary with the NSFileOriginalItemLocationKey key. The value assigned to that key is an NSURL object with the location of the item. The error code is one of the file-related errors described in NSError Codes.

Discussion

As in the POSIX standard, the app either must own the file or directory or must be running as superuser for attribute changes to take effect. The method attempts to make all changes specified in attributes and ignores any rejection of an attempted modification. If the last component of the path is a symbolic link it is traversed.

The NSFilePosixPermissions value must be initialized with the code representing the POSIX file-permissions bit pattern. NSFileHFSCreatorCode and NSFileHFSTypeCode will only be heeded when path specifies a file.

Discussion

It is recommended that you assign a delegate only to file manager objects that you create explicitly using the alloc/init convention.

Discussion

Use this method to move a file from its current location to iCloud. For files located in an app’s sandbox, this involves physically removing the file from the sandbox container. (The system extends your app’s sandbox privileges to give it access to files it moves to iCloud.) You can also use this method to move files out of iCloud and back into a local directory.

Your app must have an active file presenter object configured to monitor the specified file or directory before calling this method. When you specify YES for the flag parameter, this method attempts to move the file or directory to the cloud and returns YES if it is successful. This method also notifies your file presenter of the new location of the file so that your app can continue to operate on it.

Discussion

If a cloud-based file or directory has not been downloaded yet, calling this method starts the download process. If the item exists locally, calling this method synchronizes the local copy with the version in the cloud.

For a given URL, you can determine if a file is downloaded by getting the value of the NSMetadataUbiquitousItemIsDownloadedKey key. You can also use related keys to determine the current progress in downloading the file.

Discussion

Use this method if your code receives paths as C strings from system routines.

Discussion

This method recurses the specified directory and its subdirectories. The method skips the “.” and “..” directories at each level of the recursion.

This method reveals every element of the subtree at path, including the contents of file packages (such as apps, nib files, and RTFD files). This code fragment gets the contents of /System/Library/Fonts after verifying that the directory exists:

BOOL isDir=NO;

NSArray *subpaths;

NSString *fontPath = @"/System/Library/Fonts";

NSFileManager *fileManager = [[NSFileManager alloc] init];

if ([fileManager fileExistsAtPath:fontPath isDirectory:&isDir] && isDir)

    subpaths = [fileManager subpathsAtPath:fontPath];

[fileManager release];

Discussion

This method recurses the specified directory and its subdirectories. The method skips the “.” and “..” directories at each level of the recursion.

Because this method recurses the directory’s contents, you might not want to use it in performance-critical code. Instead, consider using the enumeratorAtURL:includingPropertiesForKeys:options:errorHandler: or enumeratorAtPath: method to enumerate the directory contents yourself. Doing so gives you more control over the retrieval of items and more opportunities to abort the enumeration or perform other tasks at the same time.

Discussion

Use this method to determine if iCloud is currently available. Because this method returns relatively quickly, you can call it at launch time and you can call it from your app’s main thread.

You can use the token returned by this method, together with the NSUbiquityIdentityDidChangeNotification notification, to detect when the user logs in or out of iCloud and to detect changes to the active iCloud account. When the user logs in with a different iCloud account, the returned identity token changes and the system posts the notification. If you stored or archived the previous token, you compare that token to the newly obtained one using the isEqual: method to determine if the users are the same or different.

Calling this method does not establish access to your app’s ubiquity containers. To establish access to a ubiquity container, call the URLForUbiquityContainerIdentifier: method. In OS X, you can instead use an NSDocument object, which establishes access automatically.

Discussion

You typically use this method to locate one of the standard system directories, such as the Documents, Application Support or Caches directories. You can also use this method to create a new temporary directory for storing things like autosave files; to do so, specify NSItemReplacementDirectory for the directory parameter, NSUserDomainMask for the domain parameter, and a valid parent directory for the url parameter. After locating (or creating) the desired directory, this method returns the URL for that directory. If more than one appropriate directory exists in the specified domain, this method returns only the first one it finds.

Passing a directory and domain pair that makes no sense (for example NSDesktopDirectory and NSNetworkDomainMask) raises an exception.

Discussion

This method creates a snapshot of the specified file and places that copy in a temporary iCloud location where it can be accessed by other users using the returned URL. The snapshot reflects the contents of the file at the time the URL was generated and is not updated when subsequent changes are made to the original file in the user’s iCloud storage. The snapshot file remains available at the specified URL until the date specified in the outDate parameter, after which it is automatically deleted.

Your app must have access to the network for this call to succeed.

Discussion

You use this method to determine the location of your app’s ubiquity container directories and to configure your app’s initial iCloud access. The first time you call this method for a given ubiquity container, the system extends your app’s sandbox to include that container. In iOS, you must call this method at least once before trying to search for cloud-based files in the ubiquity container. If your app accesses multiple ubiquity containers, call this method once for each container. In OS X, you do not need to call this method if you use NSDocument-based objects, because the system then calls this method automatically.

You can use the URL returned by this method to build paths to files and directories within your app’s ubiquity container. Each app that syncs documents to the cloud must have at least one associated ubiquity container in which to put those files. This container can be unique to the app or shared by multiple apps.

In addition to writing to its own ubiquity container, an app can write to any container directory for which it has the appropriate permission. Each additional ubiquity container should be listed as an additional value in the com.apple.developer.ubiquity-container-identifiers entitlement array.

To learn how to view your development team’s unique <TEAM_ID> value, read “To view the team ID…” in Tools Workflow Guide for Mac.

Discussion

This method is intended to locate known and common directories in the system. For example, setting the directory to NSApplicationDirectory, will return the Applications directories in the requested domain. There are a number of common directories available in the NSSearchPathDirectory, including: NSDesktopDirectory, NSApplicationSupportDirectory, and many more.