Creating and Deleting Files and Directories

Creating and Replacing Files and Directories

IFile and IDirectory inherit creation options from IFileSystemEntity. You can use these options to specify creation behavior when instantiating an IFile or IDirectory object.

To automatically create a file or directory if it does not already exist, use the kCreateIfNeeded option:

IFile myFile(pathName, IFile::kCreateIfNeeded);
IDirectory myDir(pathName, IDirectory::kCreateIfNeeded);

To create a new file or directory only where one does not already exist, use the kCreateOnly option (Note: this will throw an IAlreadyExists exception if the file already exists):

IFile myNewFile(pathName, IFile::kCreateOnly);
IDirectory myNewDir(pathName, IDirectory::kCreateOnly);

To replace an existing file or directory, or create a new one if it does not already exist, use the kReplaceExisting option:

IFile myNewFile(pathName, IFile::kReplaceExisting);
IDirectory myNewDir(pathName, IDirectory::kReplaceExisting);

Creating a File or Directory and Intermediate Subdirectories

Except for kMustExist, the entity creation options will also cause any missing intermediate directories to be created. The following code will create the file file.txt if it does not already exist. It will also create the intermediate directories abc and xyz if needed:

IFile myFile(IHostPathName("abc/xyz/file.txt"),
    IFile::kCreateIfNeeded, IUnixPathNameParser());

The following code will create a directory named xyz in the subdirectory named sub. If sub does not exist, createDirectory will automatically create it too:

IDirectory newDir = dir.createDirectory("sub/xyz",
    IDirectory::kCreateOnly, IUnixPathNameParser());

Deleting a File or Directory

IFile and IDirectory inherit the deleteSelf member function from IFileSystemEntity.

To delete a physical file, call its deleteSelf member function:

IFile fileToKill(pathName);
fileToKill.deleteSelf();

To delete a physical directory, call its deleteSelf member function. By default, deleteSelf will only delete the directory if it is entirely empty. If the directory is not empty, deleteSelf will throw the exception IMustBeEmpty.

IDirectory dirToKill(pathName);
dirToKill.deleteSelf();

If the directory is not empty and you want to delete it and all of its contents, pass true to deleteSelf, overriding the default value (false) of deleteSelf's deleteChildren parameter.

dirToKill.deleteSelf(true); // Deletes all contents too!

Note: If any of the entities in the directory or any of their children cannot be deleted, deleteSelf deletes as many as it can and then throws the first exception that it encountered.

Deleting all Directory Contents

To recursively delete all the contents of a directory, but not the directory itself, call deleteAllContents. This method attempts to delete each member of the directory recursively.

aDirectory.deleteAllContents();

Note: If any of the entities in the directory or any of their children cannot be deleted, deleteAllContents deletes as many as it can and then throws the first exception that it encountered.

Creating Temporary Files and Directories

To create a directory or a file for storing temporary data, use IDirectory::createTemporary or IFile:createTemporary. These functions will create a new directory or a new file in the system-specific temporary directory. There are two versions of each of these functions: one to specify the name of the temporary entity, the other to generate the name automatically.

// create a 1K file with given name
IFile tempFile(IFile::createTemporary(fileName, 1024));

// create a zero-length file with given name
IFile tempFile(IFile::createTemporary(fileName));

// create a zero-length file with unique name
IFile tempFile(IFile::createTemporary());

// create a directory with given name
IDirectory tempDir(IDirectory::createTemporary(dirName));

// create a directory with unique name
IDirectory tempDir(IDirectory::createTemporary());

Temporary directories and files created in this way are not automatically deleted when their IDirectory or IFile instance goes out of scope. Nor are temporary files automatically deleted when they are closed. These entities are only "temporary" in the sense that they live in the system's temporary directory and that they are not guaranteed to survive a system reboot. You are still responsible for deleting a temporary IDirectory or IFile when you are finished using it.

You can call the temporary function on a file or directory entity to determine if the entity was constructed using the createTemporary function.

Introduction to the File System
Overview of File System Entities
Overview of Pathnames and Pathname Parsers
File System Exceptions

Instantiating a File System Entity from a Host-Specific Pathname
Instantiating a File System Entity from a Portable Pathname
Instantiating a File System Entity from Another Instance of the Same Entity Class
Using an Instance of IFileSystemEntity to Represent a File, Directory or Volume
Accessing the Attributes of Files, Directories and Volumes
Instantiating Host-Specific Pathnames and Pathname Parsers
Instantiating a Portable Pathname from a Host-Specific Pathname