Up

NSFileManager class reference

Authors

Mircea Oancea (mircea@jupiter.elcom.pub.ro)
Ovidiu Predescu (ovidiu@net-community.com)
Nicola Pero (n.pero@mi.flashnet.it)
Richard frith-Macdonald (rfm@gnu.org)

Version: 1.93

Date: 2003/07/31 23:49:31

Copyright: (C) 1997-2002 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSDirectoryEnumerator class
  2. Software documentation for the NSFileManager class
  3. Software documentation for the NSDictionary(NSFileAttributes) category
  4. Software documentation for the NSObject(NSFileManagerHandler) informal protocol

Software documentation for the NSDirectoryEnumerator class

NSDirectoryEnumerator : NSEnumerator

Declared in:
Foundation/NSFileManager.h
Standards:

NSDirectoryEnumerator implementation
The Objective-C interface hides a traditional C implementation. This was the only way I could get near the speed of standard unix tools for big directories.

Method summary

directoryAttributes

- (NSDictionary*) directoryAttributes;

Returns a dictionary containing the attributes of the directory at which enumeration started.
The contents of this dictionary are as produced by [NSFileManager -fileAttributesAtPath:traverseLink:]


fileAttributes

- (NSDictionary*) fileAttributes;

Returns a dictionary containing the attributes of the file currently being enumerated.
The contents of this dictionary are as produced by [NSFileManager -fileAttributesAtPath:traverseLink:]


initWithDirectoryPath:recurseIntoSubdirectories:followSymlinks:justContents:

- (id) initWithDirectoryPath: (NSString*)path recurseIntoSubdirectories: (BOOL)recurse followSymlinks: (BOOL)follow justContents: (BOOL)justContents;

Description forthcoming.


skipDescendents

- (void) skipDescendents;

Informs the receiver that any descendents of the current directory should be skipped rather than enumerated. Use this to avaoid enumerating the contents of directories you are not interested in.


Software documentation for the NSFileManager class

NSFileManager : NSObject

Declared in:
Foundation/NSFileManager.h
Standards:

This is the main class for management of the local filesystem.

Method summary

defaultManager

+ (NSFileManager*) defaultManager;

Returns a shared default file manager which may be used throughout an application.


changeCurrentDirectoryPath:

- (BOOL) changeCurrentDirectoryPath: (NSString*)path;

Changes the current directory used for all subsequent operations.
All non-absolute paths are interpreted relative to this directory.
The current directory is set on a per-task basis, so the current directory for other file manager instances will also be changed by this method.


changeFileAttributes:atPath:

- (BOOL) changeFileAttributes: (NSDictionary*)attributes atPath: (NSString*)path;

Change the attributes of the file at path to those specified.
Returns YES if all requested changes were made (or if the dictionary was nil or empty, so no changes were requested), NO otherwise.
On failure, some fo the requested changes may have taken place.


componentsToDisplayForPath:

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

Returns an array of path components suitably modified for display to the end user. This modification may render the returned strings unusable for path manipulation, so you should work with two arrays... one returned by this method (for display tio the user), and a parallel one returned by [NSString -pathComponents] (for path manipulation).


contentsAtPath:

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

Reads the file at path an returns its contents as an NSData object.
If an error occurs or if path specifies a directory etc then nil is returned.


contentsEqualAtPath:andPath:

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

Returns YES if the contents of the file or directory at path1 are the same as those at path2.
If path1 and path2 are files, this is a simple comparison. If they are directories, the contents of the files in those subdirectories are compared recursively.
Symbolic links are not followed.
A comparison checks first file identity, then size, then content.


copyPath:toPath:handler:

- (BOOL) copyPath: (NSString*)source toPath: (NSString*)destination handler: (id)handler;

Copies the file or directory at source to destination, using a handler object which should respond to [NSObject -fileManager:willProcessPath:] and [NSObject -fileManager:shouldProceedAfterError:] messages.


createDirectoryAtPath:attributes:

- (BOOL) createDirectoryAtPath: (NSString*)path attributes: (NSDictionary*)attributes;

Creates a new directory, and sets its attributes as specified.
Creates other directories in the path as necessary.
Returns YES on success, NO on failure.


createFileAtPath:contents:attributes:

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

Creates a new file, and sets its attributes as specified.
Initialises the file content with the specified data.
Returns YES on success, NO on failure.


createSymbolicLinkAtPath:pathContent:

- (BOOL) createSymbolicLinkAtPath: (NSString*)path pathContent: (NSString*)otherPath;

Creates a symbolic link at path which links to the location specified by otherPath.


currentDirectoryPath

- (NSString*) currentDirectoryPath;

Returns the current working directory used by all instance of the file manager in the current task.


directoryContentsAtPath:

- (NSArray*) directoryContentsAtPath: (NSString*)path;

Returns an array of the contents of the specified directory.
The listing does not recursively list subdirectories.
The special files '.' and '..' are not listed.
Indicates an error by returning nil (eg. if path is not a directory or it can't be read for some reason).


displayNameAtPath:

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

Returns the name of the file or directory at path. Converts it into a format for display to an end user. This may render it unusable as part of a file/path name.
For instance, if a user has elected not to see file extensions, this method may return filenames with the extension removed.
The default operation is to return the result of calling [NSString -lastPathComponent] on the path.


enumeratorAtPath:

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

Returns an enumerator which can be used to return each item with the directory at path in turn.
The enumeration is recursive... following all nested subdirectories.


fileAttributesAtPath:traverseLink:

- (NSDictionary*) fileAttributesAtPath: (NSString*)path traverseLink: (BOOL)flag;

If a file (or directory etc) exists at the specified path, and can be queriesd for its attributes, this method returns a dictionary containing the various attributes of that file. Otherwise nil is returned.
If the flag is NO and the file is a symbolic link, the attributes of the link itsself (rather than the file it points to) are returned.

The dictionary keys for attributes are -

NSFileAppendOnly
NSNumber... boolean
NSFileCreationDate
NSDate when the file was created (if supported)
NSFileDeviceIdentifier
NSNumber (identifies the device on which the file is stored)
NSFileExtensionHidden
NSNumber... boolean
NSFileGroupOwnerAccountName
NSString name of the file group
NSFileGroupOwnerAccountID
NSNumber ID of the file group
NSFileHFSCreatorCode
NSNumber not used
NSFileHFSTypeCode
NSNumber not used
NSFileImmutable
NSNumber... boolean
NSFileModificationDate
NSDate when the file was last modified
NSFileOwnerAccountName
NSString name of the file owner
NSFileOwnerAccountID
NSNumber ID of the file owner
NSFilePosixPermissions
NSNumber posix access permissions mask
NSFileReferenceCount
NSNumber number of links to this file
NSFileSize
NSNumber size of the file in bytes
NSFileSystemFileNumber
NSNumber the identifier for the file on the filesystem
NSFileSystemNumber
NSNumber the filesystem on which the file is stored
NSFileType
NSString the type of file

The NSDictionary class also has a set of accessor methods which enable you to get at file attribute information more efficiently than using the keys above to extract it. You should generally use the accessor methods where they are available.


fileExistsAtPath:

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

Returns YES if a file (or directory etc) exists at the specified path.


fileExistsAtPath:isDirectory:

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

Returns YES if a file (or directory etc) exists at the specified path.
If the isDirectory argument is not a nul pointer, stores a flag in the location it points to, to indicate whether the file is a directory or not.


fileSystemAttributesAtPath:

- (NSDictionary*) fileSystemAttributesAtPath: (NSString*)path;

Returns a dictionary containing the filesystem attributes for the specified path (or nil if the path is not valid).

NSFileSystemSize
NSNumber the size of the filesystem in bytes
NSFileSystemFreeSize
NSNumber the amount of unused space on the filesystem in bytes
NSFileSystemNodes
NSNumber the number of nodes in use to store files
NSFileSystemFreeNodes
NSNumber the number of nodes available to create files
NSFileSystemNumber
NSNumber the identifying number for the filesystem


fileSystemRepresentationWithPath:

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

Convert from OpenStep internal path format (unix-style) to a string in the local filesystem format, suitable for passing to system functions.
Under unix, this simply standardizes the path and converts to a C string.
Under windoze, this attempts to use local conventions to convert to a windows path. In GNUstep, the conventional unix syntax '~user/...' can be used to indicate a windoze drive specification by using the drive letter in place of the username, and the syntax '~@server/...' can be used to indicate a file located on the named windoze network server (the '~@' maps to the leading '//' in a windoze UNC path specification.


isDeletableFileAtPath:

- (BOOL) isDeletableFileAtPath: (NSString*)path;

Returns YES if a file (or directory etc) exists at the specified path and is deletable.


isExecutableFileAtPath:

- (BOOL) isExecutableFileAtPath: (NSString*)path;

Returns YES if a file (or directory etc) exists at the specified path and is executable (if a directory is executable, you can access its contents).


isReadableFileAtPath:

- (BOOL) isReadableFileAtPath: (NSString*)path;

Returns YES if a file (or directory etc) exists at the specified path and is readable.


isWritableFileAtPath:

- (BOOL) isWritableFileAtPath: (NSString*)path;

Returns YES if a file (or directory etc) exists at the specified path and is writable.


linkPath:toPath:handler:

- (BOOL) linkPath: (NSString*)source toPath: (NSString*)destination handler: (id)handler;

Links the file or directory at source to destination, using a handler object which should respond to [NSObject -fileManager:willProcessPath:] and [NSObject -fileManager:shouldProceedAfterError:] messages.

If the destination is a directory, the source path is linked into that directory, otherwise the destination must not exist, but its parent directory must exist and the source will be linked into the parent as the name specified by the destination.

If the source is a symbolic link, it is copied to the destination.
If the source is a directory, it is copied to the destination and its contents are linked into the new directory.
Otherwise, a hard link is made from the destination to the source.


movePath:toPath:handler:

- (BOOL) movePath: (NSString*)source toPath: (NSString*)destination handler: (id)handler;

Moves the file or directory at source to destination, using a handler object which should respond to [NSObject -fileManager:willProcessPath:] and [NSObject -fileManager:shouldProceedAfterError:] messages.


pathContentOfSymbolicLinkAtPath:

- (NSString*) pathContentOfSymbolicLinkAtPath: (NSString*)path;

Returns the name of the file or directory that the symbolic link at path points to.


removeFileAtPath:handler:

- (BOOL) removeFileAtPath: (NSString*)path handler: (id)handler;

Removes the file or directory at path, using a handler object which should respond to [NSObject -fileManager:willProcessPath:] and [NSObject -fileManager:shouldProceedAfterError:] messages.


stringWithFileSystemRepresentation:length:

- (NSString*) stringWithFileSystemRepresentation: (const char*)string length: (unsigned int)len;

This method converts from a local system specific filename representation to the internal OpenStep representation (unix-style). This should be used whenever a filename is read in from the local system.
In GNUstep, windoze drive specifiers are encoded in the internal path using the conventuional unix syntax of '~user/...' where the drive letter is used instead of a username.


subpathsAtPath:

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

Returns an array containing the (relative) paths of all the items in the directory at path.
The listing follows all subdirectories, so it can produce a very large array... use with care.


Software documentation for the NSDictionary(NSFileAttributes) category

NSDictionary(NSFileAttributes)

Declared in:
Foundation/NSFileManager.h
Standards:

Description forthcoming.

Method summary

fileCreationDate

- (NSDate*) fileCreationDate;

Return the file creation date attribute (or nil if not found).


fileExtensionHidden

- (BOOL) fileExtensionHidden;

Return the file extension hidden attribute (or NO if not found).


fileGroupOwnerAccountID

- (unsigned long) fileGroupOwnerAccountID;

Return the numeric value of the NSFileGroupOwnerAccountID attribute in the dictionary, or NSNotFound if the attribute is not present.


fileGroupOwnerAccountName

- (NSString*) fileGroupOwnerAccountName;

Return the file group owner account name attribute or nil if not present.


fileHFSCreatorCode

- (int) fileHFSCreatorCode;

Description forthcoming.


fileHFSTypeCode

- (int) fileHFSTypeCode;

Description forthcoming.


fileIsAppendOnly

- (BOOL) fileIsAppendOnly;

Return the file append only attribute (or NO if not found).


fileIsImmutable

- (BOOL) fileIsImmutable;

Return the file immutable attribute (or NO if not found).


fileModificationDate

- (NSDate*) fileModificationDate;

Return the file modification date attribute (or nil if not found)


fileOwnerAccountID

- (unsigned long) fileOwnerAccountID;

Return the numeric value of the NSFileOwnerAccountID attribute in the dictionary, or NSNotFound if the attribute is not present.


fileOwnerAccountName

- (NSString*) fileOwnerAccountName;

Return the file owner account name attribute or nil if not present.


filePosixPermissions

- (unsigned long) filePosixPermissions;

Return the file posix permissions attribute (or NSNotFound if the attribute is not present in the dictionary).


fileSize

- (unsigned long long) fileSize;

Return the size of the file, or NSNotFound if the file size attribute is not found in the dictionary.


fileSystemFileNumber

- (unsigned long) fileSystemFileNumber;

Return the file system file identification number attribute or NSNotFound if the attribute is not present in the dictionary).


fileSystemNumber

- (unsigned long) fileSystemNumber;

Return the file system number attribute (or NSNotFound if the attribute is not present in the dictionary).


fileType

- (NSString*) fileType;

Return the file type attribute or nil if not present.


Software documentation for the NSObject(NSFileManagerHandler) informal protocol

NSObject(NSFileManagerHandler)

Declared in:
Foundation/NSFileManager.h
Standards:

An informal protocol to which handler objects should conform if they wish to deal with copy and move operations performed by NSFileManager.

Method summary

fileManager:shouldProceedAfterError:

- (BOOL) fileManager: (NSFileManager*)fileManager shouldProceedAfterError: (NSDictionary*)errorDictionary;

When an error occurs during a copy or move operation, the file manager will send this message to the handler, and will use the return value to determine whether the operation should proceed. If the method returns YES then the operation will proceed after the error, if it returns NO then it will be aborted.

If the handler does not implement this method it will be treated as if it returns NO.

The error dictionary contains the following

Note that the FromPath is a GNUstep extension.

Also the FromPath and ToPath are filled in when appropriate. So when copying a file they will typically both have a value and when reading only FromPath.


fileManager:willProcessPath:

- (void) fileManager: (NSFileManager*)fileManager willProcessPath: (NSString*)path;

The file manager sends this method to the handler immediately before performing part of a directory move or copy operation. This provides the handler object with information it can use in the event of an error, to decide whether processing should proceed after the error.



Up