If you are building a more elaborate iPhone application than just a button which farts or some colorful ball which moves out of your finger you will inevitably want to read and write some files in the iPhone filesystem.

Most of the file operations will start by creating a file manager, though some objects as NSArray and NSDictionary provide handy functions to directly read and write files.

NSFileManager

NSFileManager* fileManager = [NSFileManager defaultManager];

NSFileManager provides a load of handy methods, so it’s always good to check also the XCode documentation of the class.

First of all you will need to get your file’s location. Each application on the iPhone has its own Sandbox which provides you with several different folders to work with. Documents will be the place you want to save your content, read and write files, etc.

Since CocoaTouch conforms to a big extent with OS X, you need to query the filesystem for the current user’s folders. On a mac for example there will be different users like Peter, John, Grandma, etc. Each of them will have separate Documents folder located at a different path. On the iPhone (for the moment) there’s only one user, but you will still need to query the system for the current user’s locations.

As in this example:

NSFileManager* fileManager = [NSFileManager defaultManager];
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory , NSUserDomainMask, YES);
NSString* documentsDir = [paths objectAtIndex:0];

You can get a list of different locations, for reference have a look at the NSSearchPathDirectory definition:

enum {
   NSApplicationDirectory = 1,
   NSDemoApplicationDirectory,
   NSDeveloperApplicationDirectory,
   NSAdminApplicationDirectory,
   NSLibraryDirectory,
   NSDeveloperDirectory,
   NSUserDirectory,
   NSDocumentationDirectory,
   NSDocumentDirectory,
   NSCoreServiceDirectory,
   NSAutosavedInformationDirectory = 11,
   NSDesktopDirectory = 12,
   NSCachesDirectory = 13,
   NSApplicationSupportDirectory = 14,
   NSDownloadsDirectory = 15,
   NSInputMethodsDirectory = 16,
   NSMoviesDirectory = 17,
   NSMusicDirectory = 18,
   NSPicturesDirectory = 19,
   NSPrinterDescriptionDirectory = 20,
   NSSharedPublicDirectory = 21,
   NSPreferencePanesDirectory = 22,
   NSItemReplacementDirectory = 99,
   NSAllApplicationsDirectory = 100,
   NSAllLibrariesDirectory = 101
};
typedef NSUInteger NSSearchPathDirectory;

Once you have the directory path, you can just put yourself together the full file path:

NSString* myFilePath = [NSString stringWithFormat:@”%@/%@”, documentsDir, @”file.txt”];

Here is a list of few functions you might immediately need when dealing with files:

- (BOOL)isDeletableFileAtPath:(NSString *)path

Checks if the file at the given path can be deleted.

- (BOOL)isReadableFileAtPath:(NSString *)path

Checks if the file’s contents at the given path can be loaded.

- (BOOL)isWritableFileAtPath:(NSString *)path

Checks if the app can write at the specified file path.

- (BOOL)fileExistsAtPath:(NSString *)path

Checks if a file exists with the given file path.

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

Checks if a file exists with the given file path and you can specify it should be a normal file or a file directory.

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

Compares if two given files’ content is the same.

Enumerating trough a directory’s contents

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

Gives you an NSArray of all files found in the given directory path. The most simple way to read directory’s contents :

for (NSString* fileName in [fileManager contentsOfDirectoryAtPath: [[NSBundle mainBundle] resourcePath] error:nil]) {
NSLog(@”file: %@”, fileName);
}

This example will show you the contents of your app’s resources directory (eg. the files you bundle with your app)

Reading and Writing files

You can use NSData to hold the contents of a file you want to read or write:

NSData* data [fileManager contentesAtPath:filePath];
[fileManager createFileAtPath:filePath contents:data attributes:nil];

This way you should deal with the data format you are going to supply to NSData yourself. If your data is property list data: NSString, NSInteger, NSData, NSArray, etc. it is much easier to use the handy functions below.

Let’s say you have a list of values (or a tree of values) which can be stored as an xml file. In this case you can tell directly to your NSArray or NSDictionary to save it contents to a file, or read the contents of a file and populate itself.

NSArray* array = … some initialization …
[array writeToFile:myFilePath atomically:YES];
NSArray* newArray = [NSArray arrayWithContentsOfFile:myFilePath];
NSDictionary* dict = …some initialization …
[dict writeToFile:myFilePath atomically:YES];
NSDictionary* newDict = [NSDictionary dictionaryWithContentesOfFile:myFilePath];

Managing files

[fileManager moveItemAtPath:myPath toPath:myNewPath error:NULL];

Moves (or if you move to the same directory renames) a file.

[fileManager copyItemAtPath:myPath toPath:myNewPath error:NULL];

Copies a file to a new location.

[fileManager removeItemAtPath: myPath error:NULL];

Deletes the file from the file system.

This wraps up the overview of working with files.