NSFileManager Class Reference

Instance Methods

attributesOfFileSystemForPath:error:

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

- (NSDictionary *)attributesOfFileSystemForPath:(NSString *)path error:(NSError **)error

Parameters

path

Any pathname within the mounted file system.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

This method does not traverse a terminal symbolic link.

See Also

• – attributesOfItemAtPath:error:
• – setAttributes:ofItemAtPath:error:

attributesOfItemAtPath:error:

Returns the attributes of the item at a given path.

- (NSDictionary *)attributesOfItemAtPath:(NSString *)path error:(NSError **)error

Parameters

path

The path of a file or directory.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Special Considerations

As a convenience, NSDictionary provides a set of methods (declared as a category in NSFileManager.h) for quickly and efficiently obtaining attribute information from the returned dictionary: fileGroupOwnerAccountName, fileModificationDate, fileOwnerAccountName, filePosixPermissions, fileSize, fileSystemFileNumber, fileSystemNumber, and fileType.

In Mac OS X v 10.6 and earlier, if the last component of the path is a symbolic link (the value of the NSFileType key in the attributes dictionary is NSFileTypeSymbolicLink), it will be traversed. This behavior may change in a future version of the Mac OS X.

See Also

• – setAttributes:ofItemAtPath:error:

Related Sample Code

• ImageBrowserViewAppearance
• SourceView

changeCurrentDirectoryPath:

Changes the path of the current directory for the current process to a given path.

- (BOOL)changeCurrentDirectoryPath:(NSString *)path

Parameters

path

The path of the directory to which to change.

Discussion

All relative pathnames refer implicitly to the current working directory. The current working directory is stored per process.

See Also

• – currentDirectoryPath
• – fileExistsAtPath:isDirectory:
• – contentsOfDirectoryAtPath:error:
• – createDirectoryAtPath:withIntermediateDirectories:attributes:error:

componentsToDisplayForPath:

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

- (NSArray *)componentsToDisplayForPath:(NSString *)path

Parameters

path

A pathname.

Discussion

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

Related Sample Code

• QTAudioExtractionPanel

contentsAtPath:

Returns as an NSData object the contents of the file at at given path.

- (NSData *)contentsAtPath:(NSString *)path

Parameters

path

The path of a file.

See Also

• – contentsEqualAtPath:andPath:
• – createFileAtPath:contents:attributes:

contentsEqualAtPath:andPath:

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

- (BOOL)contentsEqualAtPath:(NSString *)path1 andPath:(NSString *)path2

Parameters

path1

The path of a file or directory to compare with the contents of path2.

path2

The path of a file or directory to compare with the contents of path1.

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.

See Also

• – contentsAtPath:

contentsOfDirectoryAtPath:error:

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

- (NSArray *)contentsOfDirectoryAtPath:(NSString *)path error:(NSError **)error

Parameters

path

A path to a directory.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

The search is shallow and therefore does not return the contents of any subdirectories. This returned array does not contain strings for the current directory (“.”), parent directory (“..”), or resource forks (begin with “._”) and does not traverse symbolic links.

See Also

• – currentDirectoryPath
• – fileExistsAtPath:isDirectory:
• – enumeratorAtPath:
• – subpathsAtPath:

Related Sample Code

• DesktopImage
• FunHouse
• ImageBrowserViewAppearance
• ImageKitDemo
• OutlineView

contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error:

Returns the contents of a directory.

- (NSArray *)contentsOfDirectoryAtURL:(NSURL *)url includingPropertiesForKeys:(NSArray *)keys options:(NSDirectoryEnumerationOptions)mask error:(NSError **)error

Parameters

url

The location of the directory for which you want an enumeration.

keys

On input, an array of property keys for which you would like the corresponding values. These specify the file properties that are pre-fetched for each of the files in the directory.

When an array is specified for this parameter, the specified property values are pre-fetched and cached with each enumerated URL. The property keys that can be requested are listed in he property keys that can be requested are listed in Common File System Resource Keys)

mask

Options for the enumeration. Because this method only performs shallow enumeration only the NSDirectoryEnumerationSkipsHiddenFiles option should be used.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

This method always does a shallow enumeration of the specified directory (i.e. it always acts as if NSDirectoryEnumerationSkipsSubdirectoryDescendants has been specified). If you need to perform a deep enumeration, use enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:].

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

See Also

• – contentsOfDirectoryAtPath:error:

Related Sample Code

• AnimatedTableView

copyItemAtPath:toPath:error:

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

- (BOOL)copyItemAtPath:(NSString *)srcPath toPath:(NSString *)dstPath error:(NSError **)error

Parameters

srcPath

The path of a file or directory.

dstPath

The path of a file or directory.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

If srcPath is a file, the method creates a file at dstPath that holds the exact contents of the original file (this includes BSD special files). If srcPath is a directory, the method creates a new directory at dstPath and recursively populates it with duplicates of the files and directories contained in srcPath, preserving all links. The file specified in srcPath must exist, while dstPath must not exist prior to the operation. When a file is being copied, the destination path must end in a filename—there is no implicit adoption of the source filename. Symbolic links are not traversed but are themselves copied. File or directory attributes—that is, metadata such as owner and group numbers, file permissions, and modification date—are also copied.

NSFileManager sends your delegate fileManager:shouldCopyItemAtPath:toPath: when it begins a copy operation. If the delegate returns YES, NSFileManager attempts to copy the item. If the delegate returns NO, the copyItemAtPath:toPath:error: function does not copy the item.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:copyingItemAtPath:toPath: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the copyItemAtPath:toPath:error: function terminates and passes the error back in the error parameter.

See Also

• – copyItemAtURL:toURL:error:
• – fileManager:shouldCopyItemAtPath:toPath:
• – fileManager:shouldProceedAfterError:copyingItemAtPath:toPath:
• – linkItemAtPath:toPath:error:
• – moveItemAtPath:toPath:error:
• – removeItemAtPath:error:

Related Sample Code

• FunHouse

copyItemAtURL:toURL:error:

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

- (BOOL)copyItemAtURL:(NSURL *)srcURL toURL:(NSURL *)dstURL error:(NSError **)error

Parameters

srcURL

The URL of a file or directory.

dstURL

The URL of a file or directory.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

If srcURL is a file, the method creates a file at dstURL that holds the exact contents of the original file (this includes BSD special files). If srcURL is a directory, the method creates a new directory at dstURL and recursively populates it with duplicates of the files and directories contained in srcURL, preserving all links. The file specified in srcURL must exist, while dstURL must not exist prior to the operation. When a file is being copied, the destination URL must end in a filename—there is no implicit adoption of the source filename. Symbolic links are not traversed but are themselves copied. File or directory attributes—that is, metadata such as owner and group numbers, file permissions, and modification date—are also copied.

NSFileManager sends your delegate fileManager:shouldCopyItemAtURL:toURL: when it begins a copy operation. If the delegate returns YES, NSFileManager attempts to copy the item. If the delegate returns NO, the copyItemAtURL:toURL:error: function does not copy the item.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:copyingItemAtURL:toURL: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the copyItemAtURL:toURL:error: function terminates and passes the error back in the error parameter.

See Also

• – copyItemAtPath:toPath:error:
• – fileManager:shouldCopyItemAtURL:toURL:
• – fileManager:shouldProceedAfterError:copyingItemAtURL:toURL:
• – linkItemAtPath:toPath:error:
• – moveItemAtPath:toPath:error:
• – removeItemAtPath:error:

createDirectoryAtPath:withIntermediateDirectories:attributes:error:

Creates a directory with given attributes at a specified path.

- (BOOL)createDirectoryAtPath:(NSString *)path withIntermediateDirectories:(BOOL)createIntermediates attributes:(NSDictionary *)attributes error:(NSError **)error

Parameters

path

The path at which to create the new directory. The directory to be created must not yet exist.

createIntermediates

If YES, then the method will also create any necessary intermediate directories; if NO, then the method fails if any parent of the directory to be created does not exist. In addition, if you pass NO for this parameter, the directory must not exist at the time this call is made.

attributes

The file attributes for the new directory. The attributes you can set are owner and group numbers, file permissions, and modification date. If you specify nil for attributes, the directory is created according to the umask of the process. The “Constants” section lists the global constants used as keys in the attributes dictionary. Some of the keys, such as NSFileHFSCreatorCode and NSFileHFSTypeCode, do not apply to directories.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

See Also

• – changeCurrentDirectoryPath:
• – setAttributes:ofItemAtPath:error:
• – createFileAtPath:contents:attributes:
• – currentDirectoryPath

Related Sample Code

• From A View to A Movie
• From A View to A Picture
• FunHouse
• SimpleStickies
• StickiesWithCoreData

createFileAtPath:contents:attributes:

Creates a file at a given path that has given attributes and contents.

- (BOOL)createFileAtPath:(NSString *)path contents:(NSData *)contents attributes:(NSDictionary *)attributes

Parameters

path

The path for the new file.

contents

The contents for the new file.

attributes

A dictionary that describes the attributes of the new file. The file attributes you can set are owner and group numbers, file permissions, and modification date. “File Attribute Keys” lists the global constants used as keys in the attributes dictionary. If you specify nil for attributes, the file is given a default set of attributes.

Discussion

If a file already exists at path, then if the file can be overwritten (subject to user privileges) it will be.

See Also

• – contentsAtPath:
• – setAttributes:ofItemAtPath:error:
• – setAttributes:ofItemAtPath:error:
• – attributesOfItemAtPath:error:

Related Sample Code

• Core Data HTML Store
• CustomAtomicStoreSubclass
• TimelineToTC

createSymbolicLinkAtPath:withDestinationPath:error:

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

- (BOOL)createSymbolicLinkAtPath:(NSString *)path withDestinationPath:(NSString *)destPath error:(NSError **)error

Parameters

path

The path for a symbolic link.

destPath

The path to which path should refer.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

Creates a symbolic link identified by path that refers to the location destPath in the file system.

This method does not traverse a terminal symbolic link.

See Also

• – destinationOfSymbolicLinkAtPath:error:
• – linkItemAtPath:toPath:error:

currentDirectoryPath

Returns the path of the program’s current directory.

- (NSString *)currentDirectoryPath

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.

See Also

• – changeCurrentDirectoryPath:
• – createDirectoryAtPath:withIntermediateDirectories:attributes:error:

Related Sample Code

• GLUT

delegate

Returns the delegate for the receiver.

- (id)delegate

destinationOfSymbolicLinkAtPath:error:

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

- (NSString *)destinationOfSymbolicLinkAtPath:(NSString *)path error:(NSError **)error

Parameters

path

The path of a file or directory.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

See Also

• – createSymbolicLinkAtPath:withDestinationPath:error:

displayNameAtPath:

Returns the name of the file or directory at a given path in a localized form appropriate for presentation to the user.

- (NSString *)displayNameAtPath:(NSString *)path

Parameters

path

The path of a file or directory.

Discussion

The returned value is localized where appropriate. For example, if you have selected French as your preferred language, the following code fragment logs “Bibliothèque”:

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

if ([paths count] > 0)

{

    NSString *documentsDirectory = [paths objectAtIndex:0];

    NSFileManager *fileManager = [NSFileManager defaultManager];

    NSString *displayNameAtPath = [fileManager displayNameAtPath:documentsDirectory];

    NSLog(@"%@", displayNameAtPath);

}

See Also

• – lastPathComponent (NSString)

Related Sample Code

• AlbumToSlideshow
• AutomatorHandsOn
• ComplexBrowser
• Quartz Composer WWDC 2005 TextEdit
• SourceView

enumeratorAtPath:

Creates and returns an NSDirectoryEnumerator object that enumerates the contents of the directory at a given path.

- (NSDirectoryEnumerator *)enumeratorAtPath:(NSString *)path

Parameters

path

The path of the directory to enumerate.

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 *file;

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

NSDirectoryEnumerator *dirEnum =

    [[NSFileManager defaultManager] enumeratorAtPath:docsDir];

while (file = [dirEnum nextObject]) {

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

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

    }

}

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.

See Also

• – currentDirectoryPath
• – attributesOfItemAtPath:error:
• – contentsOfDirectoryAtPath:error:
• – subpathsAtPath:
• – enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:

Related Sample Code

• BundleLoader
• DeskPictAppDockMenu
• MovieAssembler
• NSOperationSample
• SimpleScriptingPlugin

enumeratorAtURL:includingPropertiesForKeys:options:errorHandler:

Creates and returns a directory enumerator object that enumerates the contents of the directory at a given URL.

- (NSDirectoryEnumerator *)enumeratorAtURL:(NSURL *)url includingPropertiesForKeys:(NSArray *)keys options:(NSDirectoryEnumerationOptions)mask errorHandler:(BOOL (^)(NSURL *url, NSError *error))handler

Parameters

url

The location of the directory for which you want an enumeration.

keys

On input, an array of property keys for which you would like the corresponding values. On output, the property values corresponding to those keys. Specify NULL for this array if you do not want any property values. The property keys that can be requested are listed in Foundation/NSURL.h (see NSURL Class Reference).

When an array is specified for this parameter, the specified property values are pre-fetched and cached with each enumerated URL.

mask

Options for the enumeration. See “Directory Enumeration Options.”

handler

The optional 'errorHandler' block argument is invoked when an error occurs. Parameters to the block are the URL on which an error occurred and the error. When the error handler returns YES, enumeration continues if possible. Enumeration stops immediately when the error handler returns NO.

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.

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

NSURL *url;

NSURL *docsDir = [[NSFileManager defaultManager]

                   initFileURLWithPath:([NSHomeDirectory()

                   stringByAppendingPathComponent:  @"Documents"])

                   keys:NULL mask:NULL handler:NULL];

NSDirectoryEnumerator *dirEnum =

    [[NSFileManager defaultManager] enumeratorAtURL:docsDir];

while (file = [dirEnum nextObject]) {

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

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

    }

}

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).

See Also

• – enumeratorAtPath:

fileExistsAtPath:

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

- (BOOL)fileExistsAtPath:(NSString *)path

Parameters

path

The path of a file or directory. If path begins with a tilde (~), it must first be expanded with stringByExpandingTildeInPath, or this method returns NO.

Discussion

Attempting to predicate behavior based on the current state of the file system or a particular file on the file system is not recommended. Doing so can cause odd behavior in the case of file system race conditions. It's far better to attempt an operation (such as loading a file or creating a directory), check for errors, and handle any error gracefully than it is to try to figure out ahead of time whether the operation will succeed. For more information on file system race conditions, see Avoiding Race Conditions and Insecure File Operations in Secure Coding Guide.

See Also

• – fileExistsAtPath:isDirectory:

Related Sample Code

• CoreRecipes
• From A View to A Movie
• QTCoreVideo201
• QTKitCreateMovie
• Quartz Composer WWDC 2005 TextEdit

fileExistsAtPath:isDirectory:

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

- (BOOL)fileExistsAtPath:(NSString *)path isDirectory:(BOOL *)isDirectory

Parameters

path

The path of a file or directory. If path begins with a tilde (~), it must first be expanded with stringByExpandingTildeInPath, or this method will return NO.

isDirectory

Upon return, contains YES if path is a directory or if the final path element is a symbolic link that points to a directory, otherwise contains NO. If path doesn’t exist, the return value is undefined. Pass NULL if you do not need this information.

Discussion

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

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 defaultManager];

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

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

        subpaths = [fileManager subpathsAtPath:fontPath];

// ...

See Also

• – fileExistsAtPath:

Related Sample Code

• CocoaSlides
• DesktopImage
• From A View to A Movie
• ImageKitDemo
• LSMSmartCategorizer

fileSystemRepresentationWithPath:

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

- (const char *)fileSystemRepresentationWithPath:(NSString *)path

Parameters

path

A file path.

Discussion

If you need the C string beyond the scope of your autorelease pool, you must copy it. This method raises an exception upon error. Use this method if your code calls system routines that expect C-string path arguments.

See Also

• – stringWithFileSystemRepresentation:length:

init

Returns an initialized NSFileManager instance.

- init

Discussion

In Mac OS X v 10.5 and earlier sending the init message was undefined. In Mac OS X 10.6 and later it will initialize the receiver.

isDeletableFileAtPath:

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

- (BOOL)isDeletableFileAtPath:(NSString *)path

Parameters

path

A file path.

Discussion

For a directory or file to be able to be deleted, either the parent directory of path must be writable or its owner must be the same as the owner of the application process. If path is a directory, every item contained in path must be able to be deleted.

This method does not traverse symbolic links.

isExecutableFileAtPath:

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

- (BOOL)isExecutableFileAtPath:(NSString *)path

Parameters

path

A file path.

Discussion

This method traverses symbolic links. This method uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is executable.

isReadableFileAtPath:

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

- (BOOL)isReadableFileAtPath:(NSString *)path

Parameters

path

A file path.

Discussion

This method traverses symbolic links. This method uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is readable.

Related Sample Code

• From A View to A Movie
• From A View to A Picture
• QTCoreVideo201
• QTQuartzPlayer

isWritableFileAtPath:

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

- (BOOL)isWritableFileAtPath:(NSString *)path

Parameters

path

A file path.

Discussion

This method traverses symbolic links. This method uses the real user ID and group ID, as opposed to the effective user and group IDs, to determine if the file is writable.

linkItemAtPath:toPath:error:

Creates a hard link from a source to a destination identified by a path.

- (BOOL)linkItemAtPath:(NSString *)srcPath toPath:(NSString *)dstPath error:(NSError **)error

Parameters

srcPath

A path that identifies a source file.

The file or link specified by srcPath must exist. srcPath must not identify a directory.

dstPath

A path that identifies a destination file or directory on the same filesystem as srcPath.

The destination should not yet exist. The destination path must end in a filename; there is no implicit adoption of the source filename.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

If pathname srcPath identifies a file, this method hard-links the file specified in dstPath to it.

Amongst other reasons (such as the disk being full, permissions problems, and so on), this method will fail if:

• srcPath doesn't point to any file in the file system;

• srcPath points to an existing symbolic link, but the symbolic link is “broken" (it doesn't in turn point to an existing regular file in the file system);

• srcPath points to a directory;

• The computer has more than one file system (such as extra partitions, mounted disk images, or network volumes), and srcPath and dstPath specify paths in different file systems.

NSFileManager sends your delegate fileManager:shouldLinkItemAtPath:toPath: when it begins a hard-link operation. If the delegate returns YES, NSFileManager attempts to hard-link the item. If the delegate returns NO, the linkItemAtPath:toPath:error: function does not hard-link the item.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:linkingItemAtPath:toPath: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the linkItemAtPath:toPath:error: function terminates and passes the error back in the error parameter.

See Also

• – linkItemAtURL:toURL:error:
• – fileManager:shouldLinkItemAtPath:toPath:
• – fileManager:shouldProceedAfterError:linkingItemAtPath:toPath:
• – createSymbolicLinkAtPath:withDestinationPath:error:
• – copyItemAtPath:toPath:error:
• – moveItemAtPath:toPath:error:
• – removeItemAtPath:error:

linkItemAtURL:toURL:error:

Creates a hard link from a source to a destination identified by a URL.

- (BOOL)linkItemAtURL:(NSURL *)srcURL toURL:(NSURL *)dstURL error:(NSError **)error

Parameters

srcURL

A URL that identifies a source file.

The file or link specified by srcURL must exist. srcURL must not identify a directory.

dstURL

A URL that identifies a destination file or directory on the same filesystem as srcURL.

The destination should not yet exist. The destination URL must end in a filename; there is no implicit adoption of the source filename.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

If srcURL identifies a file, this method hard-links the file specified in dstURL to it. If srcURL is a symbolic link, this method copies it to dstURL instead of creating a hard link. Symbolic links in srcURL are not traversed.

Amongst other reasons (such as the disk being full, permissions problems, and so on), this method will fail if:

• srcURL doesn't point to any file in the file system;

• srcURL points to an existing symbolic link, but the symbolic link is “broken" (it doesn't in turn point to an existing regular file in the file system);

• srcURL points to a directory;

• The computer has more than one file system (such as extra partitions, mounted disk images, or network volumes), and srcURL and dstURL specify URLs in different file systems.

NSFileManager sends your delegate fileManager:shouldLinkItemAtURL:toURL: when it begins a hard-link operation. If the delegate returns YES, NSFileManager attempts to hard-link the item. If the delegate returns NO, the linkItemAtURL:toURL:error: function does not hard-link the item.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:linkingItemAtURL:toURL: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the linkItemAtURL:toURL:error: function terminates and passes the error back in the error parameter.

See Also

• – linkItemAtPath:toPath:error:
• – fileManager:shouldLinkItemAtURL:toURL:
• – fileManager:shouldProceedAfterError:linkingItemAtURL:toURL:
• – createSymbolicLinkAtPath:withDestinationPath:error:
• – copyItemAtURL:toURL:error:
• – moveItemAtURL:toURL:error:
• – removeItemAtURL:error:

mountedVolumeURLsIncludingResourceValuesForKeys:options:

Returns the mounted volumes available on the computer.

- (NSArray *)mountedVolumeURLsIncludingResourceValuesForKeys:(NSArray *)propertyKeys options:(NSVolumeEnumerationOptions)options

Parameters

propertyKeys

On input, an array of property keys for which the corresponding resource values should be pre-fetched. Specify NULL for this array if you do not want any resource values. The property keys that can be requested are listed in Common File System Resource Keys.

options

Option flags for the enumeration. See “Mounted Volume Enumeration Options.”

Discussion

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

moveItemAtPath:toPath:error:

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

- (BOOL)moveItemAtPath:(NSString *)srcPath toPath:(NSString *)dstPath error:(NSError **)error

Parameters

srcPath

The path of a file or directory to move. srcPath must exist.

dstPath

The path to which the file or directory at srcPath is to be moved. destination must not yet exist. The destination path must end in a directory name or filename; there is no implicit adoption of the source name.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

If the source path and the destination path are not on the same device, NSFileManager performs a copy to the destination path and removes the original. If the copy does not succeed, this method returns an error and NSFileManager removes the incomplete copy, leaving the original in place.

NSFileManager sends your delegate fileManager:shouldMoveItemAtPath:toPath: when it begins a move operation. If the delegate returns YES, NSFileManager attempts to move the item. If the delegate returns NO, the moveItemAtPath:toPath:error: function does not move the item.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:movingItemAtPath:toPath: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the moveItemAtPath:toPath:error: function terminates and passes the error back in the error parameter.

See Also

• – moveItemAtURL:toURL:error:
• – fileManager:shouldMoveItemAtPath:toPath:
• – copyItemAtPath:toPath:error:
• – linkItemAtPath:toPath:error:
• – removeItemAtPath:error:

moveItemAtURL:toURL:error:

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

- (BOOL)moveItemAtURL:(NSURL *)srcURL toURL:(NSURL *)dstURL error:(NSError **)error

Parameters

srcURL

The URL of a file or directory to move. srcURL must exist.

dstURL

The URL to which the file or directory at srcURL is to be moved. destination must not yet exist. The destination URL must end in a directory name or filename; there is no implicit adoption of the source name.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

If the source path and the destination path are not on the same device, NSFileManager performs a copy to the destination path and removes the original. If the copy does not succeed, this method returns an error and NSFileManager removes the incomplete copy, leaving the original in place.

NSFileManager sends your delegate fileManager:shouldMoveItemAtURL:toURL: when it begins a move operation. If the delegate returns YES, NSFileManager attempts to move the item. If the delegate returns NO, the moveItemAtURL:toURL:error: function does not move the item.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:movingItemAtURL:toURL: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the moveItemAtURL:toURL:error: function terminates and passes the error back in the error parameter.

See Also

• – moveItemAtPath:toPath:error:
• – fileManager:shouldMoveItemAtURL:toURL:
• – copyItemAtURL:toURL:error:
• – linkItemAtURL:toURL:error:
• – removeItemAtURL:error:

removeItemAtPath:error:

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

- (BOOL)removeItemAtPath:(NSString *)path error:(NSError **)error

Parameters

path

The path of a file, link, or directory to delete. The value must not be "." or "..".

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

Since the removal of directory contents is so thorough and final, be careful when using this method. If you specify "." or ".." for path an NSInvalidArgumentException exception is raised. This method does not traverse symbolic links.

NSFileManager sends your delegate fileManager:shouldRemoveItemAtPath: when it begins a delete operation. If the delegate returns YES, NSFileManager attempts to delete the item. If the delegate returns NO, the removeItemAtPath:error: function does not delete the item and, if the item is a directory, no children of that item are deleted either.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:removingItemAtPath: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the removeItemAtPath:error: function terminates and passes the error back in the error parameter.

See Also

• – removeItemAtURL:error:
• – copyItemAtPath:toPath:error:
• – linkItemAtPath:toPath:error:
• – moveItemAtPath:toPath:error:
• – fileManager:shouldRemoveItemAtPath:
• – fileManager:shouldProceedAfterError:removingItemAtPath:
• – removeItemAtPath:error:

Related Sample Code

• URL CacheInfo

removeItemAtURL:error:

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

- (BOOL)removeItemAtURL:(NSURL *)URL error:(NSError **)error

Parameters

URL

The URL of a file, link, or directory to delete. The value must not be "." or "..".

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

Since the removal of directory contents is so thorough and final, be careful when using this method. If you specify "." or ".." for URL an NSInvalidArgumentException exception is raised. This method does not traverse symbolic links.

NSFileManager sends your delegate fileManager:shouldRemoveItemAtURL: when it begins a delete operation. If the delegate returns YES, NSFileManager attempts to delete the item. If the delegate returns NO, the removeItemAtURL:error: function does not delete the item and, if the item is a directory, no children of that item are deleted either.

NSFileManager sends your delegate fileManager:shouldProceedAfterError:removingItemAtURL: when it encounters any error in processing. If the delegate returns YES, then NSFileManager proceeds as if no error had occurred. If it returns NO, the removeItemAtURL:error: function terminates and passes the error back in the error parameter.

See Also

• – removeItemAtPath:error:
• – copyItemAtPath:toPath:error:
• – linkItemAtPath:toPath:error:
• – moveItemAtPath:toPath:error:
• – fileManager:shouldRemoveItemAtPath:
• – fileManager:shouldProceedAfterError:removingItemAtPath:
• – removeItemAtPath:error:

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

Replaces the contents specified by the first URL with the contents of the second URL in a manner that insures no data loss occurs.

- (BOOL)replaceItemAtURL:(NSURL *)originalItemURL withItemAtURL:(NSURL *)newItemURL backupItemName:(NSString *)backupItemName options:(NSFileManagerItemReplacementOptions)options resultingItemURL:(NSURL **)resultingURL error:(NSError **)error

Parameters

originalItemURL

The item being replaced.

newItemURL

The item which will replace the originalItemURL. This item should be placed in a temporary directory as provided by the OS, or in a uniquely named directory placed in the same directory as the original item if the temporary directory is not available.

backupItemName

Optional. If provided, this name will be used to create a backup of the original item.

The backup is placed in the same directory as the original item. If an error occurs during the creation of the backup item, the operation will fail. If there is already an item with the same name as the backup item, that item will be removed.

The backup item will be removed in the event of success unless the NSFileManagerItemReplacementWithoutDeletingBackupItem option is provided in options.

options

Specifies the options used in the replacement. Passing 0 provides the default behavior which uses only the metadata from the new item. The values in “NSFileManagerItemReplacementOptions” are also valid and can be combined using the C-bitwise OR operator. Typically 0 is passed.

resultingURL

This URL will be set to the URL which points at the new item. resultingURL may be the same as originalItemURL if the replacement could be made without having to create a new filesystem object. resultingURL may be different than originalItemURL if the replacement could not be made without having to create a new object (e.g. going from an rtf document to an rtfd requires the creation of a new item - in this case, resultingURL would locate the newly-created rtfd).

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

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 in replacing a filesystem item and the original item has been left in neither the original location nor the temporary location, the NSError returned will contain a user info dictionary with the NSFileOriginalItemLocationKey key and its value will be an NSURL instance which locates the item. The error code is one of the various NSFile* errors already present in NSError Codes.

setAttributes:ofItemAtPath:error:

Sets the attributes of a given file or directory.

- (BOOL)setAttributes:(NSDictionary *)attributes ofItemAtPath:(NSString *)path error:(NSError **)error

Parameters

attributes

A dictionary containing as keys the attributes to set for path and as values the corresponding value for the attribute. You can set the following attributes: NSFileBusy, NSFileCreationDate, NSFileExtensionHidden, NSFileGroupOwnerAccountID, NSFileGroupOwnerAccountName, NSFileHFSCreatorCode, NSFileHFSTypeCode, NSFileImmutable, NSFileModificationDate, NSFileOwnerAccountID, NSFileOwnerAccountName, NSFilePosixPermissions. You can change single attributes or any combination of attributes; you need not specify keys for all attributes.

path

The path of a file or directory.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

As in the POSIX standard, the application 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.

See Also

• – attributesOfItemAtPath:error:

setDelegate:

Sets the delegate for the receiver.

- (void)setDelegate:(id)delegate

Parameters

delegate

The delegate for the receiver.

stringWithFileSystemRepresentation:length:

Returns an NSString object converted from the C-string representation of a pathname in the current file system.

- (NSString *)stringWithFileSystemRepresentation:(const char *)string length:(NSUInteger)len

Parameters

string

A C string representation of a pathname.

len

The number of characters in string.

Discussion

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

See Also

• – fileSystemRepresentationWithPath:

Related Sample Code

• ZipBrowser

subpathsAtPath:

Returns an array that contains (as NSString objects) the contents of the directory identified by a given path.

- (NSArray *)subpathsAtPath:(NSString *)path

Parameters

path

The path of the directory to list.

Discussion

This list of directory contents goes very deep and hence is very useful for large file-system subtrees. The method skips “.” and “..”.

This method reveals every element of the subtree at path, including the contents of file packages (such as applications, 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 defaultManager];

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

    subpaths = [fileManager subpathsAtPath:fontPath];

Special Considerations

On Mac OS X v10.5 and later, use subpathsOfDirectoryAtPath:error: instead.

See Also

• – subpathsOfDirectoryAtPath:error:
• – contentsOfDirectoryAtPath:error:
• – enumeratorAtPath:

subpathsOfDirectoryAtPath:error:

Returns an array that contains the filenames of the items in the directory specified by a given path and all its subdirectories recursively.

- (NSArray *)subpathsOfDirectoryAtPath:(NSString *)path error:(NSError **)error

Parameters

path

The path of the directory to list.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

This list of directory contents goes very deep and hence is very useful for large file-system subtrees. The method skips “.” and “..”.

See Also

• – subpathsAtPath:
• – contentsOfDirectoryAtPath:error:
• – enumeratorAtPath:

URLForDirectory:inDomain:appropriateForURL:create:error:

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

- (NSURL *)URLForDirectory:(NSSearchPathDirectory)directory inDomain:(NSSearchPathDomainMask)domain appropriateForURL:(NSURL *)url create:(BOOL)shouldCreate error:(NSError **)error

Parameters

directory

The search path directory. The supported values are described in NSSearchPathDirectory.

domain

The domain specifies where the search should occur. The constants are specified by NSSearchPathDomainMask. Note: You may not pass the NSAllDomainsMask.

url

If not NULL, and directory is NSItemReplacementDirectory the appropriate temporary directory will be located. If the URL is located on another machine, the temporary directory will be on the other machine. If the URL is local, the temporary directory will be local.

shouldCreate

YES if the directory should be created if it doesn’t exist, otherwise NO.

error

If an error occurs, upon return contains an NSError object that describes the problem. Pass NULL if you do not want error information.

Discussion

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

URLsForDirectory:inDomains:

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

- (NSArray *)URLsForDirectory:(NSSearchPathDirectory)directory inDomains:(NSSearchPathDomainMask)domainMask

Parameters

directory

The search path directory. The supported values are described in NSSearchPathDirectory.

domainMask

The domain specifies where the search should occur. The constants are specified by NSSearchPathDomainMask.

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.