View source code
Display the source code in std/stdio.d from which this page was generated on
github.
Improve this page
Quickly fork, edit online, and submit a pull request for this page.
Requires a signed-in GitHub account. This works well for small changes.
If you'd like to make larger changes you may want to consider using
local clone.
Page wiki
View or edit the community-maintained wiki page associated with this page.
Struct std.stdio.File
Encapsulates a FILE*
. Generally D does not attempt to provide
thin wrappers over equivalent functions in the C standard library, but
manipulating FILE*
values directly is unsafe and error
-prone in
many ways. The
type ensures safe manipulation, automatic
file closing, and a lot of convenience.
File
The underlying FILE*
handle is maintained in a reference-counted
manner, such that as soon as the last
variable bound to a
given File
FILE*
goes out of scope, the underlying FILE*
is
automatically closed.
Constructors
Name | Description |
---|---|
this
|
Constructor taking the name of the file to open and the open mode .
|
Properties
Name | Type | Description |
---|---|---|
eof
[get]
|
bool |
Returns true if the file is at end (see feof).
|
error
[get]
|
bool |
If the file is not opened, returns false . Otherwise, returns
ferror for
the file handle.
|
fileno
[get]
|
int |
Returns the file number corresponding to this object .
|
isOpen
[get]
|
bool |
Returns true if the file is opened.
|
name
[get]
|
string |
Returns the name of the last opened file, if any.
If a was created with tmpfile and wrapFile
it has no name .
|
size
[get]
|
ulong |
Get the size of the file, ulong.max if file is not searchable, but still throws if an actual error occurs.
|
tell
[get]
|
ulong |
Calls ftell for the managed file handle. |
windowsHandle
[get]
|
int |
Returns the underlying operating system HANDLE (Windows only).
|
Methods
Name | Description |
---|---|
byChunk
|
Returns an input range set up to read from the file handle a chunk at a time. |
byLine
|
Returns an input range set up to read from the file handle one line at a time. |
byLineCopy
|
Returns an input range set up to read from the file handle one line
at a time. Each line will be newly allocated. front will cache
its value to allow repeated calls without unnecessary allocations.
|
clearerr
|
If the file is not opened, succeeds vacuously. Otherwise, returns clearerr for the file handle. |
close
|
If the file was unopened, succeeds vacuously. Otherwise closes the
file (by calling fclose),
throwing on error . Even if an exception is thrown, afterwards the object is empty. This is different from in that it
always closes the file; consequently, all other objects
referring to the same handle will see a closed file henceforth.
|
detach
|
Detaches from the underlying file. If the sole owner, calls .
|
fdopen
|
First calls (throwing on failure), and then attempts to
associate the given file descriptor with the . The mode must
be compatible with the mode of the file descriptor.
|
flush
|
Flushes the C FILE buffers.
|
getFP
|
Returns the FILE* corresponding to this object .
|
lock
|
Locks the specified file segment. If the file segment is already locked
by another process, waits until the existing lock is released.
If both and are zero, the entire file is locked.
|
lockingTextWriter
|
Returns an output range that locks the file and allows fast writing to it. |
opAssign
|
Assigns a file to another. The target of the assignment gets detached from whatever file it was attached to, and attaches itself to the new file. |
open
|
First calls (throwing on failure), and then attempts to
open file with mode . The mode has the
same semantics as in the C standard library fopen function.
|
popen
|
First calls (throwing on failure), and then runs a command
by calling the C standard library function popen.
|
rawRead
|
Calls fread for the
file handle. The number of items to read and the size of
each item is inferred from the size and type of the input array, respectively.
|
rawWrite
|
Calls fwrite for the file
handle. The number of items to write and the size of each
item is inferred from the size and type of the input array, respectively. An
error is thrown if the buffer could not be written in its entirety.
|
readf
|
Read data from the file according to the specified
format specifier using
std.format.formattedRead.
|
readln
|
Read line from the file handle and write it to , including
terminating character.
|
readln
|
Read line from the file handle and return it as a specified type. |
rewind
|
Calls rewind for the file handle. |
seek
|
Calls fseek for the file handle. |
setvbuf
|
Calls setvbuf for the file handle. |
setvbuf
|
Calls setvbuf for the file handle. |
sync
|
Forces any data buffered by the OS to be written to disk.
Call flush before calling this function to flush the C FILE buffers first.
|
tmpfile
|
Returns a temporary file by calling tmpfile.
Note that the created file has no name .
|
tryLock
|
Attempts to lock the specified file segment.
If both and are zero, the entire file is locked.
|
unlock
|
Removes the lock over the specified file segment.
|
windowsHandleOpen
|
First calls (throwing on failure), and then attempts to
associate the given Windows HANDLE with the . The mode must
be compatible with the access attributes of the handle . Windows only.
|
wrapFile
|
Unsafe function that wraps an existing FILE* . The resulting never takes the initiative in closing the file.
Note that the created file has no name
|
write
|
Writes its arguments in text format to the file. |
writef
|
Writes its arguments in text format to the file, according to the format in the first argument. |
writefln
|
Writes its arguments in text format to the file, according to the format in the first argument, followed by a newline. |
writeln
|
Writes its arguments in text format to the file, followed by a newline. |
Example
// test.d
void main(string[] args)
{
auto f = File("test.txt", "w"); // open for writing
f.write("Hello");
if (args.length > 1)
{
auto g = f; // now g and f write to the same file
// internal reference count is 2
g.write(", ", args[1]);
// g exits scope, reference count decreases to 1
}
f.writeln("!");
// f exits scope, reference count falls to zero,
// underlying FILE*
is closed.
}
% rdmd test.d Jimmy % cat test.txt Hello, Jimmy! % _
Authors
Walter Bright, Andrei Alexandrescu, Alex Rønne Petersen