Class

NSFileManager

An object that provides a convenient interface to the contents of the file system.

Overview

An NSFileManager object lets you examine the contents of the file system and make changes to it. The NSFileManager class provides convenient access to a shared file manager object that is suitable for most types of file-related manipulations. A file manager object is typically your primary mode of interaction with the file system. You use it to locate, create, copy, and move files and directories. You also use it to get information about a file or directory or change some of its attributes.

When specifying the location of files, you can use either NSURL or NSString objects. The use of the NSURL class is generally preferred for specifying file-system items because they can convert path information to a more efficient representation internally. You can also obtain a bookmark from an NSURL object, which is similar to an alias and offers a more sure way of locating the file or directory later.

If you are moving, copying, linking, or removing files or directories, you can use a delegate in conjunction with a file manager object to manage those operations. The delegate’s role is to affirm the operation and to decide whether to proceed when errors occur. In macOS 10.7 and later, the delegate must conform to the NSFileManagerDelegate protocol.

In iOS 5.0 and later and in macOS 10.7 and later, NSFileManager includes methods for managing items stored in iCloud. Files and directories tagged for cloud storage are synced to iCloud so that they can be made available to the user’s iOS devices and Macintosh computers. Changes to an item in one location are propagated to all other locations to ensure the items stay in sync.

Threading Considerations

The methods of the shared NSFileManager object can be called from multiple threads safely. However, if you use a delegate to receive notifications about the status of move, copy, remove, and link operations, you should create a unique instance of the file manager object, assign your delegate to that object, and use that file manager to initiate your operations.

Topics

Creating a File Manager

init

Initializes a file manager object.

defaultManager

Returns the shared file manager object for the process.

Accessing User Directories

temporaryDirectory

Returns the temporary directory for the current user.

homeDirectoryForCurrentUser

Returns the home directory for the current user.

homeDirectoryForUser:

Returns the home directory for the specified user.

Locating System Directories

URLForDirectory:inDomain:appropriateForURL:create:error:

Locates and optionally creates the specified common directory in a domain.

URLsForDirectory:inDomains:

Returns an array of URLs for the specified common directory in the requested domains.

Locating Application Group Container Directories

containerURLForSecurityApplicationGroupIdentifier:

Returns the container directory associated with the specified security application group identifier.

Discovering Directory Contents

contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error:

Performs a shallow search of the specified directory and returns URLs for the contained items.

contentsOfDirectoryAtPath:error:

Performs a shallow search of the specified directory and returns the paths of any contained items.

enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:

Returns a directory enumerator object that can be used to perform a deep enumeration of the directory at the specified URL.

enumeratorAtPath:

Returns a directory enumerator object that can be used to perform a deep enumeration of the directory at the specified path.

NSDirectoryEnumerator

An NSDirectoryEnumerator object enumerates the contents of a directory, returning the pathnames of all files and directories contained within that directory. These pathnames are relative to the directory.

mountedVolumeURLsIncludingResourceValuesForKeys:options:

Returns an array of URLs that identify the mounted volumes available on the device.

subpathsOfDirectoryAtPath:error:

Performs a deep enumeration of the specified directory and returns the paths of all of the contained subdirectories.

subpathsAtPath:

Returns an array of strings identifying the paths for all items in the specified directory.

Creating and Deleting Items

createDirectoryAtURL:withIntermediateDirectories:attributes:error:

Creates a directory with the given attributes at the specified URL.

createDirectoryAtPath:withIntermediateDirectories:attributes:error:

Creates a directory with given attributes at the specified path.

createFileAtPath:contents:attributes:

Creates a file with the specified content and attributes at the given location.

removeItemAtURL:error:

Removes the file or directory at the specified URL.

removeItemAtPath:error:

Removes the file or directory at the specified path.

replaceItemAtURL:withItemAtURL:backupItemName:options:resultingItemURL:error:

Replaces the contents of the item at the specified URL in a manner that insures no data loss occurs.

Moving and Copying Items

copyItemAtURL:toURL:error:

Copies the file at the specified URL to a new location synchronously.

copyItemAtPath:toPath:error:

Copies the item at the specified path to a new location synchronously.

moveItemAtURL:toURL:error:

Moves the file or directory at the specified URL to a new location synchronously.

moveItemAtPath:toPath:error:

Moves the file or directory at the specified path to a new location synchronously.

Managing iCloud-Based Items

ubiquityIdentityToken

An opaque token that represents the current user’s iCloud identity

URLForUbiquityContainerIdentifier:

Returns the URL for the iCloud container associated with the specified identifier and establishes access to that container.

isUbiquitousItemAtURL:

Returns a Boolean indicating whether the item is targeted for storage in iCloud.

setUbiquitous:itemAtURL:destinationURL:error:

Sets whether the item at the specified URL should be stored in the cloud.

startDownloadingUbiquitousItemAtURL:error:

Starts downloading (if necessary) the specified item to the local system.

evictUbiquitousItemAtURL:error:

Removes the local copy of the specified cloud-based item.

URLForPublishingUbiquitousItemAtURL:expirationDate:error:

Returns a URL that can be emailed to users to allow them to download a copy of a cloud-based flat file item.

Creating Symbolic and Hard Links

createSymbolicLinkAtURL:withDestinationURL:error:

Creates a symbolic link at the specified URL that points to an item at the given URL.

createSymbolicLinkAtPath:withDestinationPath:error:

Creates a symbolic link that points to the specified destination.

linkItemAtURL:toURL:error:

Creates a hard link between the items at the specified URLs.

linkItemAtPath:toPath:error:

Creates a hard link between the items at the specified paths.

destinationOfSymbolicLinkAtPath:error:

Returns the path of the item pointed to by a symbolic link.

Determining Access to Files

fileExistsAtPath:

Returns a Boolean value that indicates whether a file or directory exists at a specified path.

fileExistsAtPath:isDirectory:

Returns a Boolean value that indicates whether a file or directory exists at a specified path. The isDirectory out parameter indicates whether the path points to a directory or a regular file.

isReadableFileAtPath:

Returns a Boolean value that indicates whether the invoking object appears able to read a specified file.

isWritableFileAtPath:

Returns a Boolean value that indicates whether the invoking object appears able to write to a specified file.

isExecutableFileAtPath:

Returns a Boolean value that indicates whether the operating system appears able to execute a specified file.

isDeletableFileAtPath:

Returns a Boolean value that indicates whether the invoking object appears able to delete a specified file.

Getting and Setting Attributes

componentsToDisplayForPath:

Returns an array of strings representing the user-visible components of a given path.

displayNameAtPath:

Returns the display name of the file or directory at a specified path.

attributesOfItemAtPath:error:

Returns the attributes of the item at a given path.

attributesOfFileSystemForPath:error:

Returns a dictionary that describes the attributes of the mounted file system on which a given path resides.

setAttributes:ofItemAtPath:error:

Sets the attributes of the specified file or directory.

Getting and Comparing File Contents

contentsAtPath:

Returns the contents of the file at the specified path.

contentsEqualAtPath:andPath:

Returns a Boolean value that indicates whether the files or directories in specified paths have the same contents.

Getting the Relationship Between Items

getRelationship:ofDirectoryAtURL:toItemAtURL:error:

Determines the type of relationship that exists between a directory and item.

getRelationship:ofDirectory:inDomain:toItemAtURL:error:

Determines the type of relationship that exists between a system directory and the specified item.

Converting File Paths to Strings

fileSystemRepresentationWithPath:

Returns a C-string representation of a given path that properly encodes Unicode strings for use by the file system.

stringWithFileSystemRepresentation:length:

Returns an NSString object whose contents are derived from the specified C-string path.

Managing the Delegate

delegate

The delegate of the file manager object.

Managing the Current Directory

changeCurrentDirectoryPath:

Changes the path of the current working directory to the specified path.

currentDirectoryPath

The path to the program’s current directory.

Deprecated Methods

copyPath:toPath:handler:

Copies the directory or file specified in a given path to a different location in the file system identified by another path.

Deprecated
movePath:toPath:handler:

Moves the directory or file specified by a given path to a different location in the file system identified by another path.

Deprecated
removeFileAtPath:handler:

Deletes the file, link, or directory (including, recursively, all subdirectories, files, and links in the directory) identified by a given path.

Deprecated
changeFileAttributes:atPath:

Changes the attributes of a given file or directory.

Deprecated
fileAttributesAtPath:traverseLink:

Returns a dictionary that describes the POSIX attributes of the file specified at a given.

Deprecated
fileSystemAttributesAtPath:

Returns a dictionary that describes the attributes of the mounted file system on which a given path resides.

Deprecated
directoryContentsAtPath:

Returns the directories and files (including symbolic links) contained in a given directory.

Deprecated
createDirectoryAtPath:attributes:

Creates a directory (without contents) at a given path with given attributes.

Deprecated
createSymbolicLinkAtPath:pathContent:

Creates a symbolic link identified by a given path that refers to a given location.

Deprecated
pathContentOfSymbolicLinkAtPath:

Returns the path of the directory or file that a symbolic link at a given path refers to.

Deprecated
linkPath:toPath:handler:

Creates a link from a source to a destination.

Deprecated
fileManager:shouldProceedAfterError:

An NSFileManager object sends this message to its handler for each error it encounters when copying, moving, removing, or linking files or directories.

Deprecated
fileManager:willProcessPath:

An NSFileManager object sends this message to a handler immediately before attempting to move, copy, rename, or delete, or before attempting to link to a given path.

Deprecated

Constants

NSVolumeEnumerationOptions

Options for enumerating mounted volumes with the mountedVolumeURLsIncludingResourceValuesForKeys:options: method.

NSDirectoryEnumerationOptions

Options for enumerating the contents of directories with the contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error: method.

NSSearchPathDirectory

These constants specify the location of a variety of directories by the URLsForDirectory:inDomains: and URLForDirectory:inDomain:appropriateForURL:create:error: NSFileManager methods.

NSSearchPathDomainMask

Search path domain constants specifying base locations for the NSSearchPathDirectory type. These constants are used by the URLsForDirectory:inDomains: and URLForDirectory:inDomain:appropriateForURL:create:error: NSFileManager methods.

NSFileAttributeKey

Keys in dictionaries used with methods listed in Getting and Setting Attributes.

NSFileAttributeType

These strings are the possible values for the NSFileType attribute key contained in the dictionary object returned by attributesOfItemAtPath:error:.

NSFileProtectionType

Specifies the values that can be associated with the NSFileProtectionKey key.

NSURLRelationship

Constants indicating the relationship between a directory and an item.

NSFoundationVersionWithFileManagerResourceForkSupport

The version of the Foundation framework in which NSFileManager first supported resource forks.

File Path Functions

NSFullUserName

Returns a string containing the full name of the current user.

NSHomeDirectory

Returns the path to either the user’s or application’s home directory, depending on the platform.

NSHomeDirectoryForUser

Returns the path to a given user’s home directory.

NSOpenStepRootDirectory

Returns the root directory of the user’s system.

NSSearchPathForDirectoriesInDomains

Creates a list of directory search paths.

NSTemporaryDirectory

Returns the path of the temporary directory for the current user.

NSUserName

Returns the logon name of the current user.

HFS File Type Functions

NSFileTypeForHFSTypeCode

Returns a string encoding a file type code.

NSHFSTypeCodeFromFileType

Returns a file type code.

NSHFSTypeOfFile

Returns a string encoding a file type.

Notifications

NSUbiquityIdentityDidChangeNotification

Sent after the iCloud (“ubiquity”) identity has changed.

Relationships

Inherits From

See Also

File System Operations

NSFileManagerDelegate

The interface a file manager's delegate uses to intervene during operations or if an error occurs.