Phobos

Github Page

The D Programming Language

Utilities for manipulating files and scanning directories. Functions in this module handle files as a unit, e.g., read or write one file at a time. For opening files and manipulating them via handles refer to module std.stdio.

License
Boost License 1.0.
Authors
Walter Bright, Andrei Alexandrescu, Jonathan M Davis
Source:
std/file.d

class  FileException: object.Exception;

Exception thrown for file I/O errors.

immutable uint  errno;

OS error code.

pure @safe this(in char[] name, in char[] msg, string file = __FILE__, size_t line = __LINE__);

Constructor which takes an error message.

Parameters
char[] name Name of file for which the error occurred.
char[] msg Message describing the error.
string file The file where the error occurred.
size_t line The line where the error occurred.

@safe this(in char[] name, uint errno = .GetLastError(), string file = __FILE__, size_t line = __LINE__);

Constructor which takes the error number (GetLastError in Windows, errno in Posix).

Parameters
char[] name Name of file for which the error occurred.
uint errno The error number.
string file The file where the error occurred. Defaults to _FILE__.
size_t line The line where the error occurred. Defaults to _LINE__.

void[]  read(in char[] name, size_t upTo = size_t.max);

Read entire contents of file name and returns it as an untyped array. If the file size is larger than upTo, only upTo bytes are  read.

Example:
import std.file, std.stdio;
void main()
{
   auto bytes = cast(ubyte[]) read("filename", 5);
   if (bytes.length == 5)
       writefln("The fifth byte of the file is 0x%x", bytes[4]);
}
Returns
Untyped array of bytes read.
Throws
FileException on error.

S  readText(S = string)(in char[] name);

Read and validates (using std.utf.validate) a text file. S can be a type of array of characters of any width and constancy. No width conversion is performed; if the width of the characters in file name is different from the width of elements of S, validation will fail.

Returns
Array of characters read.
Throws
FileException on file error, UTFException on UTF decoding error.
Example:
enforce(system("echo abc>deleteme") == 0);
scope(exit) remove("deleteme");
enforce(chomp(readText("deleteme")) == "abc");

void  write(in char[] name, const void[] buffer);

Write buffer to file name.

Throws
FileException on error.
Example:
import std.file;
void main()
{
   int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];
   write("filename", a);
   assert(cast(int[]) read("filename") == a);
}

void  append(in char[] name, in void[] buffer);

Appends buffer to file name.

Throws
FileException on error.
Example:
import std.file;
void main()
{
   int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];
   write("filename", a);
   int[] b = [ 13, 21 ];
   append("filename", b);
   assert(cast(int[]) read("filename") == a ~ b);
}

void  rename(in char[] from, in char[] to);

Rename file from to to. If the target file exists, it is overwritten.

Throws
FileException on error.

void  remove(in char[] name);

Delete file name.

Throws
FileException on error.

ulong  getSize(in char[] name);

Get size of file name in bytes.

Throws
FileException on error (e.g., file not found).

void  getTimes(in char[] name, out SysTime accessTime, out SysTime modificationTime);

Get the access and modified times of file or folder name.

Parameters
char[] name File/Folder name to get times for.
SysTime accessTime Time the file/folder was last accessed.
SysTime modificationTime Time the file/folder was last modified.
Throws
FileException on error.

void  getTimesWin(in char[] name, out SysTime fileCreationTime, out SysTime fileAccessTime, out SysTime fileModificationTime);

This function is Windows-Only.

Get creation/access/modified times of file name.

This is the same as getTimes except that it also gives you the file creation time - which isn't possible on Posix systems.

Parameters
char[] name File name to get times for.
SysTime fileCreationTime Time the file was created.
SysTime fileAccessTime Time the file was last accessed.
SysTime fileModificationTime Time the file was last modified.
Throws
FileException on error.

void  setTimes(in char[] name, SysTime accessTime, SysTime modificationTime);

Set access/modified times of file or folder name.

Parameters
char[] name File/Folder name to get times for.
SysTime accessTime Time the file/folder was last accessed.
SysTime modificationTime Time the file/folder was last modified.
Throws
FileException on error.

SysTime  timeLastModified(in char[] name);

Returns the time that the given file was last modified.

Throws
FileException if the given file does not exist.

SysTime  timeLastModified(in char[] name, SysTime returnIfMissing);

Returns the time that the given file was last modified. If the file does not exist, returns returnIfMissing.

A frequent usage pattern occurs in build automation tools such as make or ant. To check whether file target must be rebuilt from file source (i.e., target is older than source or does not exist), use the comparison below. The code throws a FileException if source does not exist (as it should). On the other hand, the SysTime.min default makes a non-existing target seem infinitely old so the test correctly prompts building it.

Parameters
char[] name The name of the file to get the modification time for.
SysTime returnIfMissing The time to return if the given file does not exist.
Examples
if(timeLastModified(source) >= timeLastModified(target, SysTime.min))
{
    // must (re)build

}
else
{
    // target is up-to-date

}

@trusted bool  exists(in char[] name);

Returns whether the given file (or directory)  exists.

uint  getAttributes(in char[] name);

Returns the attributes of the given file.

Note that the file attributes on Windows and Posix systems are completely different. On Windows, they're what is returned by GetFileAttributes, whereas on Posix systems, they're the st_mode value which is part of the stat struct gotten by calling the stat function.

On Posix systems, if the given file is a symbolic link, then attributes are the attributes of the file pointed to by the symbolic link.

Parameters
char[] name The file to get the attributes of.
Throws
FileException on error.

uint  getLinkAttributes(in char[] name);

If the given file is a symbolic link, then this returns the attributes of the symbolic link itself rather than file that it points to. If the given file is not a symbolic link, then this function returns the same result as getAttributes.

On Windows,  getLinkAttributes is identical to getAttributes. It exists on Windows so that you don't have to special-case code for Windows when dealing with symbolic links.

Parameters
char[] name The file to get the symbolic link attributes of.
Throws
FileException on error.

@property bool  isDir(in char[] name);

Returns whether the given file is a directory.

Parameters
char[] name The path to the file.
Throws
FileException if the given file does not exist.
Examples
assert(!"/etc/fonts/fonts.conf".isDir);
assert("/usr/share/include".isDir);

nothrow bool  attrIsDir(uint attributes);

Returns whether the given file attributes are for a directory.

Parameters
uint attributes The file attributes.
Examples
assert(!attrIsDir(getAttributes("/etc/fonts/fonts.conf")));
assert(!attrIsDir(getLinkAttributes("/etc/fonts/fonts.conf")));

@property bool  isFile(in char[] name);

Returns whether the given file (or directory) is a file.

On Windows, if a file is not a directory, then it's a file. So, either  isFile or isDir will return true for any given file.

On Posix systems, if  isFile is true, that indicates that the file is a regular file (e.g. not a block not device). So, on Posix systems, it's possible for both  isFile and isDir to be false for a particular file (in which case, it's a special file). You can use getAttributes to get the attributes to figure out what type of special it is, or you can use DirEntry to get at its statBuf, which is the result from stat. In either case, see the man page for stat for more information.

Parameters
char[] name The path to the file.
Throws
FileException if the given file does not exist.
Examples
assert("/etc/fonts/fonts.conf".isFile);
assert(!"/usr/share/include".isFile);

nothrow bool  attrIsFile(uint attributes);

Returns whether the given file attributes are for a file.

On Windows, if a file is not a directory, it's a file. So, either  attrIsFile or attrIsDir will return true for the attributes of any given file.

On Posix systems, if  attrIsFile is true, that indicates that the file is a regular file (e.g. not a block not device). So, on Posix systems, it's possible for both  attrIsFile and attrIsDir to be false for a particular file (in which case, it's a special file). If a file is a special file, you can use the attributes to check what type of special file it is (see the man page for stat for more information).

Parameters
uint attributes The file attributes.
Examples
assert(attrIsFile(getAttributes("/etc/fonts/fonts.conf")));
assert(attrIsFile(getLinkAttributes("/etc/fonts/fonts.conf")));

bool  isSymlink(C)(const(C)[] name);

Returns whether the given file is a symbolic link.

On Windows, returns true when the file is either a symbolic link or a junction point.

Parameters
const(C)[] name The path to the file.
Throws
FileException if the given file does not exist.

nothrow bool  attrIsSymlink(uint attributes);

Returns whether the given file attributes are for a symbolic link.

On Windows, return true when the file is either a symbolic link or a junction point.

Parameters
uint attributes The file attributes.
Examples
core.sys.posix.unistd.symlink("/etc/fonts/fonts.conf", "/tmp/alink");

assert(!getAttributes("/tmp/alink").isSymlink);
assert(getLinkAttributes("/tmp/alink").isSymlink);

void  chdir(in char[] pathname);

Change directory to pathname.

Throws
FileException on error.

void  mkdir(in char[] pathname);

Make directory pathname.

Throws
FileException on error.

void  mkdirRecurse(in char[] pathname);

Make directory and all parent directories as needed.

Throws
FileException on error.

void  rmdir(in char[] pathname);

Remove directory pathname.

Throws
FileException on error.

string  getcwd();

Get current directory.

Throws
FileException on error.

@trusted string  thisExePath();

Returns the full path of the current executable.

Throws
std.object.Exception

void  copy(in char[] from, in char[] to);

Copy file from to file to. File timestamps are preserved. If the target file exists, it is overwritten.

Throws
FileException on error.

void  rmdirRecurse(in char[] pathname);

Remove directory and all of its content and subdirectories, recursively.

Throws
FileException if there is an error (including if the given file is not a directory).

void  rmdirRecurse(ref DirEntry de);
void  rmdirRecurse(DirEntry de);

Remove directory and all of its content and subdirectories, recursively.

Throws
FileException if there is an error (including if the given file is not a directory).

enum  SpanMode: int;

Dictates directory spanning policy for dirEntries (see below).

 shallow

Only spans one directory.

 depth

Spans the directory  depth-first, i.e. the content of any subdirectory is spanned before that subdirectory itself. Useful e.g. when recursively deleting files.

 breadth

Spans the directory  breadth-first, i.e. the content of any subdirectory is spanned right after that subdirectory itself.

auto  dirEntries(string path, SpanMode mode, bool followSymlink = true);

Returns an input range of DirEntry that lazily iterates a given directory, also provides two ways of foreach iteration. The iteration variable can be of type string if only the name is needed, or DirEntry if additional details are needed. The span mode dictates the how the directory is traversed. The name of the each directory entry iterated contains the absolute path.

Parameters
string path The directory to iterate over.
SpanMode mode Whether the directory's sub-directories should be iterated over depth-first (depth), breadth-first (breadth), or not at all (shallow).
bool followSymlink Whether symbolic links which point to directories should be treated as directories and their contents iterated over.
Throws
FileException if the directory does not exist.
Examples
// Iterate a directory in depth

foreach (string name; dirEntries("destroy/me", SpanMode.depth))
{
 remove(name);
}
// Iterate a directory in breadth

foreach (string name; dirEntries(".", SpanMode.breadth))
{
 writeln(name);
}
// Iterate a directory and get detailed info about it

foreach (DirEntry e; dirEntries("dmd-testing", SpanMode.breadth))
{
 writeln(e.name, "\t", e.size);
}
// Iterate over all *.d files in current directory and all its subdirectories

auto dFiles = filter!`endsWith(a.name,".d")`(dirEntries(".",SpanMode.depth));
foreach(d; dFiles)
    writeln(d.name);
// Hook it up with std.parallelism to compile them all in parallel:

foreach(d; parallel(dFiles, 1)) //passes by 1 file to each thread

{
    string cmd = "dmd -c "  ~ d.name;
    writeln(cmd);
    std.process.system(cmd);
}

auto  dirEntries(string path, string pattern, SpanMode mode, bool followSymlink = true);

Convenience wrapper for filtering file names with a glob pattern.

Parameters
string path The directory to iterate over.
string pattern String with wildcards, such as "*.d". The supported wildcard strings are described under std.path.globMatch.
SpanMode mode Whether the directory's sub-directories should be iterated over depth-first (depth), breadth-first (breadth), or not at all (shallow).
bool followSymlink Whether symbolic links which point to directories should be treated as directories and their contents iterated over.
Throws
FileException if the directory does not exist.
Examples
// Iterate over all D source files in current directory and all its

// subdirectories

auto dFiles = dirEntries(".","*.{d,di}",SpanMode.depth);
foreach(d; dFiles)
    writeln(d.name);

deprecated DirEntry  dirEntry(in char[] name);

Deprecated. It will be removed in July 2014. Please use DirEntry constructor directly instead.

Returns a DirEntry for the given file (or directory).

Parameters
char[] name The file (or directory) to get a DirEntry for.
Throws
FileException if the file does not exist.

Select!(Types.length == 1, Types[0][], Tuple!Types[])  slurp(Types...)(string filename, in char[] format);

Reads an entire file into an array.

Example:
// Load file; each line is an int followed by comma, whitespace and a

// double.

auto a = slurp!(int, double)("filename", "%s, %s");

@trusted string  tempDir();

Returns the path to a directory for temporary files.

On Windows, this function returns the result of calling the Windows API function GetTempPath.

On POSIX platforms, it searches through the following list of directories and returns the first one which is found to exist:

  1. The directory given by the TMPDIR environment variable.
  2. The directory given by the TEMP environment variable.
  3. The directory given by the TMP environment variable.
  4. /tmp
  5. /var/tmp
  6. /usr/tmp


On all platforms,  tempDir returns "." on failure, representing the current working directory.

The return value of the function is cached, so the procedures described above will only be performed the first time the function is called. All subsequent runs will return the same string, regardless of whether environment variables and directory structures have changed in the meantime.

The POSIX  tempDir algorithm is inspired by Python's tempfile.tempdir.