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 File type ensures safe manipulation, automatic file closing, and a lot of convenience.

The underlying FILE* handle is maintained in a reference-counted manner, such that as soon as the last File variable bound to a given 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 File 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 File object is empty. This is different from detach in that it always closes the file; consequently, all other File objects referring to the same handle will see a closed file henceforth.
detach Detaches from the underlying file. If the sole owner, calls close.
fdopen First calls detach (throwing on failure), and then attempts to associate the given file descriptor with the File. 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 start and length 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 detach (throwing on failure), and then attempts to open file name with mode stdioOpenmode. The mode has the same semantics as in the C standard library fopen function.
popen First calls detach (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 buf[], 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 start and length are zero, the entire file is locked.
unlock Removes the lock over the specified file segment.
windowsHandleOpen First calls detach (throwing on failure), and then attempts to associate the given Windows HANDLE with the File. The mode must be compatible with the access attributes of the handle. Windows only.
wrapFile Unsafe function that wraps an existing FILE*. The resulting File 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

License

Boost License 1.0.

Comments