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
.
Category | Functions |
---|---|
General | exists isDir isFile isSymlink rename thisExePath |
Directories | chdir dirEntries getcwd mkdir mkdirRecurse rmdir rmdirRecurse tempDir |
Files | append copy read readText remove slurp write |
Symlinks | symlink readLink |
Attributes | attrIsDir attrIsFile attrIsSymlink getAttributes getLinkAttributes getSize setAttributes |
Timestamp | getTimes getTimesWin setTimes timeLastModified |
Other | DirEntry FileException PreserveAttributes SpanMode |
std.stdio
for opening files and manipulating them via handles, and module std.path
for manipulating path strings. Exception thrown for file I/O errors.
OS error code.
Constructor which takes an error message.
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. |
Constructor which takes the error number (GetLastError in Windows, errno
in Posix).
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__ . |
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.
R name
| string or range of characters representing the file name |
size_t upTo
| if present, the maximum number of bytes to read |
FileException
on error.import std.utf : byChar; scope(exit) { assert(exists(deleteme)); remove(deleteme); } write(deleteme, "1234"); // deleteme is the name of a temporary file writeln(read(deleteme, 2)); // "12" writeln(read(deleteme.byChar)); // "1234" writeln((cast(const(ubyte)[])read(deleteme)).length); // 4
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.
R name
| string or range of characters representing the file name |
FileException
on file error, UTFException
on UTF decoding error.import std.exception : enforce; write(deleteme, "abc"); // deleteme is the name of a temporary file scope(exit) remove(deleteme); string content = readText(deleteme); enforce(content == "abc");
Write buffer
to file name
.
Creates the file if it does not already exist.
R name
| string or range of characters representing the file name |
void[] buffer
| data to be written to file |
FileException
on error. std.stdio.toFile
scope(exit) { assert(exists(deleteme)); remove(deleteme); } int[] a = [ 0, 1, 1, 2, 3, 5, 8 ]; write(deleteme, a); // deleteme is the name of a temporary file writeln(cast(int[])read(deleteme)); // a
Appends buffer
to file name
.
Creates the file if it does not already exist.
R name
| string or range of characters representing the file name |
void[] buffer
| data to be appended to file |
FileException
on error.scope(exit) { assert(exists(deleteme)); remove(deleteme); } int[] a = [ 0, 1, 1, 2, 3, 5, 8 ]; write(deleteme, a); // deleteme is the name of a temporary file int[] b = [ 13, 21 ]; append(deleteme, b); writeln(cast(int[])read(deleteme)); // a ~ b
Rename file from
to to
. If the target file exists, it is overwritten.
RF from
| string or range of characters representing the existing file name |
RT to
| string or range of characters representing the target file name |
FileException
on error.Delete file name
.
R name
| string or range of characters representing the file name |
FileException
on error.Get size of file name
in bytes.
R name
| string or range of characters representing the file name |
FileException
on error (e.g., file not found).Get the access and modified times of file or folder name
.
R 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. |
FileException
on error.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.
R 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. |
FileException
on error.Set access/modified times of file or folder name
.
R 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. |
FileException
on error.Returns the time that the given file was last modified.
FileException
if the given file does not exist.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.
R 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. |
if (timeLastModified(source) >= timeLastModified(target, SysTime.min)) { // must (re)build } else { // target is up-to-date }
Determine whether the given file (or directory) exists.
R name
| string or range of characters representing the file name |
true
if the file name specified as input existsReturns 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.
R name
| The file to get the attributes of. |
FileException
on error.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.
R name
| The file to get the symbolic link attributes of. |
FileException
on error.Set the attributes of the given file.
R name
| the file name |
uint attributes
| the attributes to set the file to |
FileException
if the given file does not exist.Returns whether the given file is a directory.
R name
| The path to the file. |
true
if name
specifies a directory FileException
if the given file does not exist. assert(!"/etc/fonts/fonts.conf".isDir); assert("/usr/share/include".isDir);
Returns whether the given file attributes are for a directory.
uint attributes
| The file attributes. |
true
if attributes
specifies a directory assert(!attrIsDir(getAttributes("/etc/fonts/fonts.conf"))); assert(!attrIsDir(getLinkAttributes("/etc/fonts/fonts.conf")));
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.
R name
| The path to the file. |
true
if name
specifies a file FileException
if the given file does not exist. assert("/etc/fonts/fonts.conf".isFile); assert(!"/usr/share/include".isFile);
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).
uint attributes
| The file attributes. |
true
if the given file attributes are for a file assert(attrIsFile(getAttributes("/etc/fonts/fonts.conf"))); assert(attrIsFile(getLinkAttributes("/etc/fonts/fonts.conf")));
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.
R name
| The path to the file. |
true
if name
is a symbolic link FileException
if the given file does not exist.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.
uint attributes
| The file attributes . |
true
if attributes
are for a symbolic link core.sys.posix.unistd.symlink("/etc/fonts/fonts.conf", "/tmp/alink"); assert(!getAttributes("/tmp/alink").isSymlink); assert(getLinkAttributes("/tmp/alink").isSymlink);
Change directory to pathname
.
FileException
on error.Make directory pathname
.
FileException
on Posix or WindowsException
on Windows if an error occured.Make directory and all parent directories as needed.
Does nothing if the directory specified by pathname
already exists.
FileException
on error.Remove directory pathname
.
R pathname
| Range or string specifying the directory name |
FileException
on error.This function is Posix-Only.
Creates a symbolic link (symlink).
RO original
| The file that is being linked. This is the target path that's stored in the symlink. A relative path is relative to the created symlink. |
RL link
| The symlink to create. A relative path is relative to the current working directory. |
FileException
on error (which includes if the symlink already exists).This function is Posix-Only.
Returns the path to the file pointed to by a symlink. Note that the path could be either relative or absolute depending on the symlink. If the path is relative, it's relative to the symlink, not the current working directory.
FileException
on error.Get the current working directory.
FileException
on error.Returns the full path of the current executable.
object
Info on a file, similar to what you'd get from stat on a Posix system.
Constructs a DirEntry
for the given file (or directory).
string path
| The file (or directory) to get a DirEntry for. |
FileException
if the file does not exist.Returns the path to the file represented by this DirEntry
.
auto de1 = DirEntry("/etc/fonts/fonts.conf"); assert(de1.name == "/etc/fonts/fonts.conf"); auto de2 = DirEntry("/usr/share/include"); assert(de2.name == "/usr/share/include");
Returns whether the file represented by this DirEntry
is a directory.
auto de1 = DirEntry("/etc/fonts/fonts.conf"); assert(!de1.isDir); auto de2 = DirEntry("/usr/share/include"); assert(de2.isDir);
Returns whether the file represented by this DirEntry
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
.
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 attributes
or statBuf
to get more information about a special file (see the stat man page for more details).
auto de1 = DirEntry("/etc/fonts/fonts.conf"); assert(de1.isFile); auto de2 = DirEntry("/usr/share/include"); assert(!de2.isFile);
Returns whether the file represented by this DirEntry
is a symbolic link.
On Windows, return true
when the file is either a symbolic link or a junction point.
Returns the size
of the the file represented by this DirEntry
in bytes.
This function is Windows-Only.
Returns the creation time of the file represented by this DirEntry
.
Returns the time that the file represented by this DirEntry
was last accessed.
Note that many file systems do not update the access time for files (generally for performance reasons), so there's a good chance that timeLastAccessed
will return the same value as timeLastModified
.
Returns the time that the file represented by this DirEntry
was last modified.
Returns the attributes of the file represented by this DirEntry
.
Note that the file attributes on Windows and Posix systems are completely different. On, Windows, they're what is returned by GetFileAttributes
GetFileAttributes Whereas, an Posix systems, they're the st_mode
value which is part of the stat
struct gotten by calling stat
.
On Posix systems, if the file represented by this DirEntry
is a symbolic link, then attributes are the attributes of the file pointed to by the symbolic link.
On Posix systems, if the file represented by this DirEntry
is a symbolic link, then linkAttributes
are the attributes of the symbolic link itself. Otherwise, linkAttributes
is identical to attributes
.
On Windows, linkAttributes
is identical to attributes
. It exists on Windows so that you don't have to special-case code for Windows when dealing with symbolic links.
This function is Posix-Only.
The stat
struct gotten from calling stat
.
Defaults to Yes.preserveAttributes
on Windows, and the opposite on all other platforms.
Copy file from
to file to
. File timestamps are preserved. File attributes are preserved, if preserve
equals Yes.preserveAttributes
. On Windows only Yes.preserveAttributes
(the default on Windows) is supported. If the target file exists, it is overwritten.
RF from
| string or range of characters representing the existing file name |
RT to
| string or range of characters representing the target file name |
PreserveAttributes preserve
| whether to preserve the file attributes |
FileException
on error.Remove directory and all of its content and subdirectories, recursively.
FileException
if there is an error (including if the given file is not a directory).Remove directory and all of its content and subdirectories, recursively.
FileException
if there is an error (including if the given file is not a directory).Dictates directory spanning policy for dirEntries (see below).
Only spans one directory.
Spans the directory in depth-first post-order, i.e. the content of any subdirectory is spanned before that subdirectory itself. Useful e.g. when recursively deleting files.
Spans the directory in depth-first pre-order, i.e. the content of any subdirectory is spanned right after that subdirectory itself.
Note that SpanMode.breadth
will not result in all directory members occurring before any subdirectory members, i.e. it is not true breadth-first traversal.
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 how the directory is traversed. The name of each iterated directory entry contains the absolute path.
string path
| The directory to iterate over. If empty, the current directory will be iterated. |
string pattern
| Optional string with wildcards, such as "*.d". When present, it is used to filter the results by their file name. The supported wildcard strings are described under std.path.globMatch . |
SpanMode mode
| Whether the directory's sub-directories should be iterated in depth-first port-order (depth ), depth-first pre-order (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. |
FileException
if the directory does not exist. // Iterate a directory in depth foreach (string name; dirEntries("destroy/me", SpanMode.depth)) { remove(name); } // Iterate the current 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 = dirEntries("", SpanMode.depth).filter!(f => f.name.endsWith(".d")); 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); } // 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);
std.file.listdir()
: string[] listdir(string pathname) { import std.algorithm; import std.array; import std.file; import std.path; return std.file.dirEntries(pathname, SpanMode.shallow) .filter!(a => a.isFile) .map!(a => std.path.baseName(a.name)) .array; } void main(string[] args) { import std.stdio; string[] files = listdir(args[1]); writefln("%s", files); }
Reads a file line by line and parses the line into a single value or a std.typecons.Tuple
of values depending on the length of Types
. The lines are parsed using the specified format
string. The format
string is passed to std.format.formattedRead
, and therefore must conform to the format string specification outlined in std.format
.
Types | the types that each of the elements in the line should be returned as |
string filename
| the name of the file to read |
char[] format
| the format string to use when reading |
std.typecons.Tuple
s. Exception
if the format
string is malformed. Also, throws Exception
if any of the lines in the file are not fully consumed by the call to std.format.formattedRead
. Meaning that no empty lines or lines with extra characters are allowed.import std.typecons : tuple; scope(exit) { assert(exists(deleteme)); remove(deleteme); } write(deleteme, "12 12.25\n345 1.125"); // deleteme is the name of a temporary file // Load file; each line is an int followed by comma, whitespace and a // double. auto a = slurp!(int, double)(deleteme, "%s %s"); writeln(a.length); // 2 writeln(a[0]); // tuple(12, 12.25) writeln(a[1]); // tuple(345, 1.125)
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:
TMPDIR
environment variable.TEMP
environment variable.TMP
environment variable./tmp
/var/tmp
/usr/tmp
tempDir
returns "."
on failure, representing the current working directory. tempDir
algorithm is inspired by Python's tempfile.tempdir
.
© 1999–2017 The D Language Foundation
Licensed under the Boost License 1.0.
https://dlang.org/phobos/std_file.html