Working with Directories in Objective-C

A key element of gaining proficiency in any programming language involves the ability to work with files and file systems. The level of difficulty in working with files varies from very easy to hard, depending on the programming language concerned. The C programming language, on which Objective-C is based, tended to make file handling a little hard relative to the standards of today's programmer friendly object oriented languages. The good news for Objective-C developers is that the Foundation Framework includes a number of classes designed specifically to make the task of working with files and directories as straightforward as possible.

In this chapter we will look at these classes and provide examples of how use them to perform some basic directory operations from within an Objective-C program. In Working with Files in Objective-C we will take a close look at working with files using these classes.

<google>IOSBOX</google> The Foundation Framework provides three classes that are indispensable when it comes to working with files and directories:

• NSFileManager - The NSFileManager class can be used to perform basic file and directory operations such as creating, moving, reading and writing files and reading and setting file attributes. In addition, this class provides methods for, amongst other tasks, identifying the current working directory, changing to a new directory, creating directories and listing the contents of a directory.

• NSFileHandle - The NSFileHandle class is provided for performing lower level operations on files, such as seeking to a specific position in a file and reading and writing a file's contents by a specified number of byte chunks and appending data to an existing file.

• NSData - The NSData class provides a useful storage buffer into which the contents of a file may be read, or from which data may be written to a file.

When using the above classes, pathnames are defined using the UNIX convention. As such each component of a path is separated by a forward slash (/). Paths that do not begin with a slash are interpreted to be relative to a current working directory. For example, if the current working directory is /home/objc and the path name is myapp/example.m then the file is considered to have a full pathname of /home/objc/myapp/example.m.

In addition, the home directory of the current user can be represented using the tilde (~) character. For example the pathname ~/example.m references a file named example.m located in the home directory of the current user. The home directory of another user may be referenced by prefixing the user name with a ~. For example, ~john/demo.m references a file located in the home directory of a user named john.

The NSFileManager class contains a class method named defaultManager that is used to obtain a reference to the application’s default file manager instance:

NSFileManager *filemgr;
filemgr = [NSFileManager defaultManager];

In the above example we have declared a variable named filemgr to point to an object of type NSFileManager, and then requested a pointer to the application’s file manager and assigned it to the variable. Having obtained the object reference we can begin to use it to work with files and directories.

The current working directory may be identified using the currentDirectoryPath instance method of our NSFileManager object. The current path is returned from the method in the form of an NSString object:

NSFileManager *filemgr;
NSString *currentpath;

filemgr = [NSFileManager defaultManager];

currentpath = [filemgr currentDirectoryPath];

NSLog (@"Current directory is %@", currentpath);

The current working directory of a running Objective-C program can be changed with a call to the changeCurrentDirectoryPath method. The destination directory path is passed as an argument to the instance method in the form of an NSString object. Note that this method returns a boolean YES or NO result to indicate if the requested directory change was successful for not:

NSFileManager *filemgr;
NSString *currentpath;

filemgr = [NSFileManager defaultManager];

currentpath = [filemgr currentDirectoryPath];

NSLog (@"Current directory is %@", currentpath);

if ([filemgr changeCurrentDirectoryPath: @"/temp/mydir"] == NO)
        NSLog (@"Cannot change directory.");

currentpath = [filemgr currentDirectoryPath];

NSLog (@"Current directory is %@", currentpath);

A new directory is created using the createDirectoryAtURL instance method, this time passing through the through the pathname of the new directory as an argument in the form of an NSURL object. This method also takes additional arguments in the form of a set of attributes for the new directory and a Boolean value indicating whether or not intermediate directories should be created if they do not already exist. Specifying nil will use the default attributes:

NSFileManager *filemgr;

filemgr = [NSFileManager defaultManager];
NSURL *newDir = [NSURL fileURLWithPath:@"/tmp/mynewdir"];
[filemgr createDirectoryAtURL: newDir withIntermediateDirectories:YES attributes: nil error:nil];

The createDirectoryAtURL method returns a Boolean result indicating the success or otherwise of the operation.

An existing directory may be removed from the file system using the removeItemAtPath method, passing though the path of the directory to be removed as an argument:

NSFileManager *filemgr;

filemgr = [NSFileManager defaultManager];

[filemgr removeItemAtPath: @"/tmp/mynewdir" handler: nil];

An existing file or directory may be moved (also known as renaming) using the moveItemAtURL method. This method takes the source and destination pathnames as arguments in the form of NSURL objects and requires that the destination path not already exist. If the target exists, a boolean NO result is returned by the method to indicate failure of the operation:

NSFileManager *filemgr;

filemgr = [NSFileManager defaultManager];

NSURL *oldDir = [NSURL fileURLWithPath:@"/tmp/mynewdir"];
NSURL *newDir = [NSURL fileURLWithPath:@"/tmp/mynewdir2"];

[filemgr moveItemAtURL: oldDir toURL: newDir error: nil];

A listing of the files contained within a specified directory can be obtained using the contentsOfDirectoryAtPath method. This method takes the directory pathname as an argument and returns an NSArray object containing the names of the files and sub-directories in that directory:

NSFileManager *filemgr;
NSString *currentpath;
NSArray *filelist;
int count;
int i;

filemgr = [NSFileManager defaultManager];

filelist = [filemgr contentsOfDirectoryAtPath: @"/tmp" error: nil];

count = [filelist count];

for (i = 0; i < count; i++)
        NSLog (@"%@", [filelist objectAtIndex: i]);

When executed as part of a program, the above code excerpt will display a listing of all the files located in the /tmp directory.

The attributes of a file or directory can be obtained using the attributesOfItemAtPath method. This takes as arguments the path of the directory and an optional NSError object into which information about any errors will be placed (may be specified as NULL if this information is not required). The results are returned in the form of an NSDictionary dictionary object (for details of working with dictionary objects refer to Objective-C Dictionary Objects). The keys for this dictionary are as follows: <google>ADSDAQBOX_FLOW</google> NSFileType
NSFileTypeDirectory
NSFileTypeRegular
NSFileTypeSymbolicLink
NSFileTypeSocket
NSFileTypeCharacterSpecial
NSFileTypeBlockSpecial
NSFileTypeUnknown
NSFileSize
NSFileModificationDate
NSFileReferenceCount
NSFileDeviceIdentifier
NSFileOwnerAccountName
NSFileGroupOwnerAccountName
NSFilePosixPermissions
NSFileSystemNumber
NSFileSystemFileNumber
NSFileExtensionHidden
NSFileHFSCreatorCode
NSFileHFSTypeCode
NSFileImmutable
NSFileAppendOnly
NSFileCreationDate
NSFileOwnerAccountID
NSFileGroupOwnerAccountID

For example, we can extract the creation date, file type and POSIX permissions for the /tmp directory using the following code excerpt:

NSFileManager *filemgr;
NSDictionary *attribs;

filemgr = [NSFileManager defaultManager];

attribs = [filemgr attributesOfItemAtPath: @"/tmp" error: NULL];

NSLog (@"Created on %@", [attribs objectForKey: NSFileCreationDate]);
NSLog (@"File type %@", [attribs objectForKey: NSFileType]);
NSLog (@"POSIX Permissions %@", [attribs objectForKey: NSFilePosixPermissions]);

When executed on a Mac OS X system, we can expect to see the following output (note that /tmp on a Mac OS X system is a symbolic link to private/tmp):

Created on 2009-01-14 07:34:32 -0500
File type NSFileTypeSymbolicLink
POSIX Permissions 493