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

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

### Contents -

1. File management
2. Path handling
3. unix
   1. windows
   2. gnustep
   3. Portability
   4. Tilde substitution

- Software documentation for the NSDirectoryEnumerator class
- Software documentation for the NSFileManager class

# File management

## Path handling

The rules for path handling depend on the value in the `GNUSTEP_PATH_HANDLING` environment variable and, to some extent, on the platform on which the program is running.
The understood values of GNUSTEP_PATH_HANDLING are unix and windows. If GNUSTEP_PATH_HANDLING is any other value (or has not been set), GNUstep interprets this as meaning it should try to do-the-right-thing
In the default mode of operation the system is very tolerant of paths and allows you to work with both unix and windows style paths. The consequences of this are apparent in the path handling methods of NSString rather than in NSFileManager .

### unix

On all Unix platforms, Path components are separated by slashes and file names may contain any character other than slash.
The file names. and.. are special cases meaning current directory and the parent of the current directory respectively.
Multiple adjacent slash characters are treated as a single separator.

/
  An absolute path to the root directory.
/etc/motd
  An absolute path to the file named motd in the subdirectory etc of the root directory.
..
  A relative path to the parent of the current directory.
program.m
  A relative path to the file program.m in the current directory.
Source/program.m
  A relative path to the file program.m in the subdirectory Source of the current directory.
../GNUmakefile
  A relative path to the file GNUmakefile in the directory above the current directory.

### windows

On Microsoft Windows the native paths may be either UNC or drive-relative, so GNUstep supports both.
Either or both slash (/) and backslash (\) may be used as separators for path components in either type of name.
UNC paths follow the general form //host/share/path/file, but must at least contain the host and share parts, i.e. //host/share is a UNC path, but //host is not
Drive-relative names consist of an optional drive specifier (consisting of a single letter followed by a single colon) followed by an absolute or relative path.
In both forms, the names. and.. are refer to the current directory and the parent directory as in unix paths.

//host/share/file
  An absolute UNC path to a file called file in the top directory of the export point share on host.
C:
  A relative path to the current directory on drive C.
C:program.m
  A relative path to the file program.m on drive C.
C:\program.m
  An absolute path to the file program.m in the top level directory on drive C.
/Source\program.m
  A drive-relative path to program.m in the directory Source on the current drive.
\\name
  A drive-relative path to name in the top level directory on the current drive. The '\\' is treated as a single backslash as this is not a UNC name (there must be both a host and a share part in a UNC name).

### gnustep

In the default mode, GNUstep handles both unix and windows paths so it treats both slash (/) and backslash (\) as separators and understands the windows UNC and drive relative path roots.
However, it treats any path beginning with a slash (/) as an absolute path if running on a unix system.

### Portability

Attempting to pass absolute paths between applications working on different systems is fraught with difficulty... just don't do it.
Where paths need to be passed around (eg. in property lists or archives) you should pass relative paths and use a standard mechanism to construct an absolute path in the receiving application, for instance, appending the relative path to the home directory of a user.

- Use only the slash (/) as a path separator, not backslash (\).
- Never use a backslash (\) in a file name.
- Avoid colons in file names.
- Use no more than three letters in a path extension.

### Tilde substitution

GNUstep handles substitution of tilde (~) as follows:
If a path is just ~ or begins ~/ then the value returned by NSHomeDirectory() is substituted for the tilde.
If a path is of the form ~name or begins with a string like ~name/ then name is used as the argument to NSHomeDirectoryForUser() and the return value from that method (if non-nil) is used to replace the tilde.

# Software documentation for the NSDirectoryEnumerator class

## NSDirectoryEnumerator : NSEnumerator

> Declared in:
>   Foundation/NSFileManager.h

Availability: MacOS-X 10.0.0

This is a subclass of `NSEnumerator` which provides a full listing of all the files beneath a directory and its subdirectories. Instances can be obtained through [NSFileManager -enumeratorAtPath:] .

This implementation is optimized and performance should be comparable to the speed of standard Unix tools for large directories.

The order in which directory contents are enumerated is undefined, and in the current implementation the natural order of the underlying filesystem is used.

Method summary

- -directoryAttributes
- -fileAttributes
- -skipDescendents

### directoryAttributes

- (NSDictionary*) directoryAttributes;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
Returns a dictionary containing the attributes of the file currently being enumerated.
The contents of this dictionary are as produced by [NSFileManager -fileAttributesAtPath:traverseLink:]

### skipDescendents

- (void) skipDescendents;
Availability: MacOS-X 10.0.0
Informs the receiver that any descendents of the current directory should be skipped rather than enumerated. Use this to avoid enumerating the contents of directories you are not interested in.

# Software documentation for the NSFileManager class

## NSFileManager : NSObject

> Declared in:
>   Foundation/NSFileManager.h

Availability: MacOS-X 10.0.0
This is the main class for platform-independent management of the local filesystem, which allows you to read and save files, create/list directories, and move or delete files and directories. In addition to simply listing directories, you may obtain an NSDirectoryEnumerator instance for recursive directory contents enumeration.
Method summary

- +defaultManager
- -attributesOfFileSystemForPath:error:
- -attributesOfItemAtPath:error:
- -changeCurrentDirectoryPath:
- -changeFileAttributes:atPath:
- -componentsToDisplayForPath:
- -contentsAtPath:
- -contentsEqualAtPath:andPath:
- -contentsOfDirectoryAtPath:error:
- -contentsOfDirectoryAtURL:includingPropertiesForKeys:options:error:

### defaultManager

+ (NSFileManager*) defaultManager;
Availability: MacOS-X 10.0.0
Returns a shared default file manager which may be used throughout an application.

### attributesOfFileSystemForPath: error:

- (NSDictionary*) attributesOfFileSystemForPath: (NSString*)path error: (NSError**)error;
Availability: MacOS-X 10.5.0
Description forthcoming.

### attributesOfItemAtPath: error:

- (NSDictionary*) attributesOfItemAtPath: (NSString*)path error: (NSError**)error;
Availability: MacOS-X 10.5.0
If a file (or directory etc) exists at the specified path, and can be queried for its attributes, this method returns a dictionary containing the various attributes of that file. Otherwise `nil` is returned.
If an error occurs, error describes the problem. Pass NULL if you do not want error information.

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

- [NSDictionary(NSFileAttributes) -fileCreationDate]
- [NSDictionary(NSFileAttributes) -fileExtensionHidden]
- [NSDictionary(NSFileAttributes) -fileHFSCreatorCode]
- [NSDictionary(NSFileAttributes) -fileHFSTypeCode]
- [NSDictionary(NSFileAttributes) -fileIsAppendOnly]
- [NSDictionary(NSFileAttributes) -fileIsImmutable]
- [NSDictionary(NSFileAttributes) -fileSize]
- [NSDictionary(NSFileAttributes) -fileType]
- [NSDictionary(NSFileAttributes) -fileOwnerAccountName]
- [NSDictionary(NSFileAttributes) -fileOwnerAccountID]
- [NSDictionary(NSFileAttributes) -fileGroupOwnerAccountName]
- [NSDictionary(NSFileAttributes) -fileGroupOwnerAccountID]
- [NSDictionary(NSFileAttributes) -fileModificationDate]
- [NSDictionary(NSFileAttributes) -filePosixPermissions]
- [NSDictionary(NSFileAttributes) -fileSystemNumber]
- [NSDictionary(NSFileAttributes) -fileSystemFileNumber]

### changeCurrentDirectoryPath:

- (BOOL) changeCurrentDirectoryPath: (NSString*)path;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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 of the requested changes may have taken place.

### componentsToDisplayForPath:

- (NSArray*) componentsToDisplayForPath: (NSString*)path;
Availability: MacOS-X 10.0.0
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 to the user), and a parallel one returned by [NSString -pathComponents] (for path manipulation).

### contentsAtPath:

- (NSData*) contentsAtPath: (NSString*)path;
Availability: MacOS-X 10.0.0
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;
Availability: MacOS-X 10.0.0
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.

### contentsOfDirectoryAtPath: error:

- (NSArray*) contentsOfDirectoryAtPath: (NSString*)path error: (NSError**)error;
Availability: MacOS-X 10.5.0
Returns an array of NSStrings 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).

### contentsOfDirectoryAtURL: includingPropertiesForKeys: options: error:

- (NSArray*) contentsOfDirectoryAtURL: (NSURL*)url includingPropertiesForKeys: (NSArray*)keys options: (NSDirectoryEnumerationOptions)mask error: (NSError**)error;
Availability: MacOS-X 10.6.0
Returns an array of NSURL of the contents of the specified directory.

Up