Mac OS X Reference Library Data Management: File Management NSFileManager Class ReferenceA method identified as deprecated has been superseded and may become unsupported in the future.
Changes the attributes of a given file or directory. (Deprecated in Mac OS X v10.5. Use setAttributes:ofItemAtPath:error: instead.)
- (BOOL)changeFileAttributes:(NSDictionary *)attributes atPath:(NSString *)path
A dictionary containing as keys the attributes to set for path and as values the corresponding value for the attribute. You can set following: 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.
For the NSFilePosixPermissions value, specify a file mode from the OR’d permission bit masks defined in sys/stat.h. See the man page for the chmod function (man 2 chmod) for an explanation.
A path to a file or directory.
YES if all changes succeed. If any change fails, returns NO, but it is undefined whether any changes actually occurred.
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.
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.
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use setAttributes:ofItemAtPath:error: instead.
NSFileManager.hCopies the directory or file specified in a given path to a different location in the file system identified by another path. (Deprecated in Mac OS X v10.5. Use copyItemAtPath:toPath:error: instead.)
- (BOOL)copyPath:(NSString *)source toPath:(NSString *)destination handler:(id)handler
The location of the source file.
The location to which to copy the file specified by source.
An object that responds to the callback messages fileManager:willProcessPath: and fileManager:shouldProceedAfterError:. You can specify nil for handler; if you do so and an error occurs, the method automatically returns NO.
YES if the copy operation is successful. If the operation is not successful, but the callback handler of fileManager:shouldProceedAfterError: returns YES, copyPath:toPath:handler: also returns YES. Otherwise this method returns NO. The method also attempts to make the attributes of the directory or file at destination identical to source, but ignores any failure at this attempt.
If source is a file, the method creates a file at destination that holds the exact contents of the original file (this includes BSD special files). If source is a directory, the method creates a new directory at destination and recursively populates it with duplicates of the files and directories contained in source, preserving all links. The file specified in source must exist, while destination 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.
The handler callback mechanism is similar to delegation. NSFileManager sends fileManager:willProcessPath: when it begins a copy, move, remove, or link operation. It sends fileManager:shouldProceedAfterError: when it encounters any error in processing.
This code fragment verifies that the file to be copied exists and then copies that file to the user’s ~/Library/Reports directory:
NSString *source = @"/tmp/quarterly_report.rtf"; |
NSString *destination = [[[NSHomeDirectory() |
stringByAppendingPathComponent:@"Library"] |
stringByAppendingPathComponent:@"Reports"] |
stringByAppendingPathComponent:@"new_quarterly_report.rtf"]; |
NSFileManager *fileManager = [NSFileManager defaultManager]; |
if ([fileManager fileExistsAtPath:source]) { |
[fileManager copyPath:source toPath:destination handler:nil]; |
} |
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use copyItemAtPath:toPath:error: instead.
– linkItemAtPath:toPath:error:– moveItemAtPath:toPath:error:– fileManager:shouldProceedAfterError:– removeItemAtPath:error:– fileManager:willProcessPath:NSFileManager.hCreates a directory (without contents) at a given path with given attributes. (Deprecated in Mac OS X v10.5. Use createDirectoryAtPath:withIntermediateDirectories:attributes:error: instead.)
- (BOOL)createDirectoryAtPath:(NSString *)path attributes:(NSDictionary *)attributes
The path at which to create the new directory. The directory to be created must not yet exist, but its parent directory must exist.
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, default values for these attributes are set (particularly write access for the creator and read access for others). 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.
YES if the operation was successful, otherwise NO.
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use createDirectoryAtPath:withIntermediateDirectories:attributes:error: instead.
– createDirectoryAtPath:withIntermediateDirectories:attributes:error:– changeCurrentDirectoryPath:– setAttributes:ofItemAtPath:error:– createFileAtPath:contents:attributes:– currentDirectoryPathNSFileManager.hCreates a symbolic link identified by a given path that refers to a given location. (Deprecated in Mac OS X v10.5. Use createSymbolicLinkAtPath:withDestinationPath:error: instead.)
- (BOOL)createSymbolicLinkAtPath:(NSString *)path pathContent:(NSString *)otherPath
The path for a symbolic link.
The path to which path should refer.
YES if the operation is successful, otherwise NO. Returns NO if a file, directory, or symbolic link identical to path already exists.
Creates a symbolic link identified by path that refers to the location otherPath in the file system.
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use createSymbolicLinkAtPath:withDestinationPath:error: instead.
– createSymbolicLinkAtPath:withDestinationPath:error:– destinationOfSymbolicLinkAtPath:error:– linkItemAtPath:toPath:error:NSFileManager.hReturns the directories and files (including symbolic links) contained in a given directory. (Deprecated in Mac OS X v10.5. Use contentsOfDirectoryAtPath:error: instead.)
- (NSArray *)directoryContentsAtPath:(NSString *)path
A path to a directory.
An array of NSString objects identifying the directories and files (including symbolic links) contained in path. Returns an empty array if the directory exists but has no contents. Returns nil if the directory specified at path does not exist or there is some other error accessing it.
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.
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use contentsOfDirectoryAtPath:error: instead.
– contentsOfDirectoryAtPath:error:– currentDirectoryPath– fileExistsAtPath:isDirectory:– enumeratorAtPath:– subpathsAtPath:NSFileManager.hReturns a dictionary that describes the POSIX attributes of the file specified at a given. (Deprecated in Mac OS X v10.5. Use attributesOfItemAtPath:error: instead.)
- (NSDictionary *)fileAttributesAtPath:(NSString *)path traverseLink:(BOOL)flag
A file path.
If path is not a symbolic link, this parameter has no effect. If path is a symbolic link, then:
If YES the attributes of the linked-to file are returned, or if the link points to a nonexistent file the method returns nil.
If NO, the attributes of the symbolic link are returned.
An NSDictionary object that describes the POSIX attributes of the file specified at path. The keys in the dictionary are described in “File Attribute Keys”. If there is no item at path, returns nil.
This code example gets several attributes of a file and logs them.
NSFileManager *fileManager = [NSFileManager defaultManager]; |
NSString *path = @"/tmp/List"; |
NSDictionary *fileAttributes = [fileManager fileAttributesAtPath:path traverseLink:YES]; |
if (fileAttributes != nil) { |
NSNumber *fileSize; |
NSString *fileOwner; |
NSDate *fileModDate; |
if (fileSize = [fileAttributes objectForKey:NSFileSize]) { |
NSLog(@"File size: %qi\n", [fileSize unsignedLongLongValue]); |
} |
if (fileOwner = [fileAttributes objectForKey:NSFileOwnerAccountName]) { |
NSLog(@"Owner: %@\n", fileOwner); |
} |
if (fileModDate = [fileAttributes objectForKey:NSFileModificationDate]) { |
NSLog(@"Modification date: %@\n", fileModDate); |
} |
} |
else { |
NSLog(@"Path (%@) is invalid.", path); |
} |
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. For example, you could rewrite the file modification statement in the code example above as:
if (fileModDate = [fileAttributes fileModificationDate]) |
NSLog(@"Modification date: %@\n", fileModDate); |
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use attributesOfItemAtPath:error: instead.
NSFileManager.hReturns a dictionary that describes the attributes of the mounted file system on which a given path resides. (Deprecated in Mac OS X v10.5. Use attributesOfFileSystemForPath:error: instead.)
- (NSDictionary *)fileSystemAttributesAtPath:(NSString *)path
Any pathname within the mounted file system.
An NSDictionary object that describes the attributes of the mounted file system on which path resides. See “File-System Attribute Keys” for a description of the keys available in the dictionary.
The following code example checks to see if there’s sufficient space on the file system before adding a new file to it:
NSData *contents = [myImage TIFFRepresentation]; |
NSFileManager *fileManager = [NSFileManager defaultManager]; |
NSString *path = ...; |
NSString *fileName = ...; |
NSDictionary *fsAttributes = |
[fileManager fileSystemAttributesAtPath:path]; |
if ([[fsAttributes objectForKey:NSFileSystemFreeSize] unsignedLongLongValue] > |
[contents length]) |
[fileManager createFileAtPath:[path stringByAppendingPathComponent:fileName] |
contents:contents attributes:nil]; |
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use attributesOfFileSystemForPath:error: instead.
– attributesOfFileSystemForPath:error:– attributesOfItemAtPath:error:– setAttributes:ofItemAtPath:error:NSFileManager.hCreates a link from a source to a destination. (Deprecated in Mac OS X v10.5. Use linkItemAtPath:toPath:error: instead.)
- (BOOL)linkPath:(NSString *)source toPath:(NSString *)destination handler:(id)handler
A path that identifies a source file or directory.
The file, link, or directory specified by source must exist.
A path that identifies a destination file or directory.
The destination should not yet exist. The destination path must end in a filename; there is no implicit adoption of the source filename.
An object that responds to the callback messages fileManager:willProcessPath: and fileManager:shouldProceedAfterError:. You can specify nil for handler; if you do so and an error occurs, the method automatically returns NO.
YES if the link operation is successful. If the operation is not successful, but the handler method fileManager:shouldProceedAfterError: returns YES, also returns YES. Otherwise returns NO.
The handler callback mechanism is similar to delegation. NSFileManager sends fileManager:willProcessPath: when it begins a copy, move, remove, or link operation. It sends fileManager:shouldProceedAfterError: when it encounters any error in processing
This code fragment verifies the pathname typed in a text field (documentFileField) and then links the file to the user’s Documents directory:
NSString *source = [documentFileField stringValue]; |
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES); |
if ([paths count] > 0) |
{ |
NSString *documentsDirectory = [paths objectAtIndex:0]; |
NSString *documentFileName = [source lastPathComponent]; |
NSString *destination = [documentsDirectory stringByAppendingPathComponent:documentFileName]; |
NSFileManager *fileManager = [NSFileManager defaultManager]; |
if ([fileManager fileExistsAtPath:source]) |
{ |
[fileManager linkPath:source toPath:destination handler:self]; |
} |
} |
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use linkItemAtPath:toPath:error: instead.
– linkItemAtPath:toPath:error:– copyItemAtPath:toPath:error:– createSymbolicLinkAtPath:withDestinationPath:error:– moveItemAtPath:toPath:error:– fileManager:shouldProceedAfterError:– removeItemAtPath:error:– fileManager:willProcessPath:NSFileManager.hMoves the directory or file specified by a given path to a different location in the file system identified by another path. (Deprecated in Mac OS X v10.5. Use moveItemAtPath:toPath:error: instead.)
- (BOOL)movePath:(NSString *)source toPath:(NSString *)destination handler:(id)handler
The path of a file or directory to move. source must exist.
The path to which source is moved. destination must not yet exist. The destination path must end in a filename; there is no implicit adoption of the source filename.
An object that responds to the callback messages fileManager:willProcessPath: and fileManager:shouldProceedAfterError:. You can specify nil for handler; if you do so and an error occurs, the method automatically returns NO.
YES if the move operation is successful. If the operation is not successful, but the handler method fileManager:shouldProceedAfterError: returns YES, movePath:toPath:handler: also returns YES; otherwise returns NO.
If source is a file, the method creates a file at destination that holds the exact contents of the original file and then deletes the original file. If source is a directory, movePath:toPath:handler: creates a new directory at destination and recursively populates it with duplicates of the files and directories contained in source. It then deletes the old directory and its contents. Symbolic links are not traversed, however links are preserved. File or directory attributes—that is, metadata such as owner and group numbers, file permissions, and modification date—are also moved.
The handler callback mechanism is similar to delegation. NSFileManager sends fileManager:willProcessPath: when it begins a copy, move, remove, or link operation. It sends fileManager:shouldProceedAfterError: when it encounters any error in processing.
If a failure in a move operation occurs, either the preexisting path or the new path remains intact, but not both.
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use moveItemAtPath:toPath:error: instead.
– moveItemAtPath:toPath:error:– copyItemAtPath:toPath:error:– linkItemAtPath:toPath:error:– removeItemAtPath:error:– fileManager:shouldProceedAfterError:– fileManager:willProcessPath:NSFileManager.hReturns the path of the directory or file that a symbolic link at a given path refers to. (Deprecated in Mac OS X v10.5. Use destinationOfSymbolicLinkAtPath:error: instead.)
- (NSString *)pathContentOfSymbolicLinkAtPath:(NSString *)path
The path of a symbolic link.
The path of the directory or file to which the symbolic link path refers, or nil upon failure. If the symbolic link is specified as a relative path, that relative path is returned.
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use destinationOfSymbolicLinkAtPath:error: instead.
NSFileManager.hDeletes the file, link, or directory (including, recursively, all subdirectories, files, and links in the directory) identified by a given path. (Deprecated in Mac OS X v10.5. Use removeItemAtPath:error: instead.)
- (BOOL)removeFileAtPath:(NSString *)path handler:(id)handler
The path of a file, link, or directory to delete. The value must not be "." or "..".
An object that responds to the callback messages fileManager:willProcessPath: and fileManager:shouldProceedAfterError:. You can specify nil for handler; if you do so and an error occurs, the deletion stops and the method automatically returns NO.
YES if the removal operation is successful. If the operation is not successful, but the handler method fileManager:shouldProceedAfterError: returns YES, also returns YES; otherwise returns NO.
This callback mechanism provided by handler is similar to delegation. NSFileManager sends fileManager:willProcessPath: when it begins a copy, move, remove, or link operation. It sends fileManager:shouldProceedAfterError: when it encounters any error in processing.
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.
Because this method does not return error information, it has been deprecated as of Mac OS X v10.5. Use removeItemAtPath:error: instead.
– removeItemAtPath:error:– copyItemAtPath:toPath:error:– linkItemAtPath:toPath:error:– moveItemAtPath:toPath:error:– fileManager:shouldProceedAfterError:– fileManager:willProcessPath:NSFileManager.hAn NSFileManager object sends this message to its handler for each error it encounters when copying, moving, removing, or linking files or directories. (Deprecated in Mac OS X v10.5. See delegate methods for copy, move, remove, and link methods.)
- (BOOL)fileManager:(NSFileManager *)manager shouldProceedAfterError:(NSDictionary *)errorInfo
The file manager that sent this message.
A dictionary that contains two or three pieces of information (all NSString objects) related to the error:
Key | Value |
|---|---|
| The path related to the error (usually the source path) |
| A description of the error |
| The destination path (not all errors) |
YES if the operation (which is often continuous within a loop) should proceed, otherwise NO.
An NSFileManager object, manager, sends this message for each error it encounters when copying, moving, removing, or linking files or directories. The return value is passed back to the invoker of copyPath:toPath:handler:, movePath:toPath:handler:, removeFileAtPath:handler:, or linkPath:toPath:handler:. If an error occurs and your handler has not implemented this method, the invoking method automatically returns NO.
The following implementation of fileManager:shouldProceedAfterError: displays the error string in an alert dialog and leaves it to the user whether to proceed or stop:
-(BOOL)fileManager:(NSFileManager *)manager |
shouldProceedAfterError:(NSDictionary *)errorInfo |
{ |
int result; |
result = NSRunAlertPanel(@"Gumby App", @"File operation error: |
%@ with file: %@", @"Proceed", @"Stop", NULL, |
[errorInfo objectForKey:@"Error"], |
[errorInfo objectForKey:@"Path"]); |
if (result == NSAlertDefaultReturn) |
return YES; |
else |
return NO; |
} |
The copyPath:toPath:handler:, movePath:toPath:handler:, removeFileAtPath:handler:, and linkPath:toPath:handler: methods have all been deprecated as of Mac OS X v10.5. Instead, you can call the setDelegate: method to specify a delegate that can receive a variety of messages, including messages that replace those described in this section. See the descriptions of the delegate methods in this document for details.
NSFileManager.hAn 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 in Mac OS X v10.5. See delegate methods for copy, move, link, and remove methods.)
- (void)fileManager:(NSFileManager *)manager willProcessPath:(NSString *)path
The NSFileManager object that sent this message.
The path or a file or directory that manager is about to attempt to move, copy, rename, delete, or link to.
You can implement this method in your handler to monitor file operations.
The copyPath:toPath:handler:, movePath:toPath:handler:, removeFileAtPath:handler:, and linkPath:toPath:handler: methods have all been deprecated as of Mac OS X v10.5. Instead, you can call the setDelegate: method to specify a delegate that can receive a variety of messages, including messages that replace those described in this section. See the descriptions of the delegate methods in this document for details.
NSFileManager.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-11-17)
Mac OS X Reference Library Data Management: File Management NSFileManager Class Reference