Display the source code in std/stdio.d from which this page was generated on github.

If you spot a problem with this page, click here to create a Bugzilla issue.

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.

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.


						
				struct File
				;

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` (name, stdioOpenmode)	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 closed or not yet opened, returns `true`. 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 last used to initialize this `File`, if any.
`size`[get]	`ulong`	Returns the size of the file in bytes, ulong.max if file is not searchable or throws if the operation fails.
`tell`[get]	`ulong`	Calls ftell for the managed file handle, which returns the current value of the position indicator of the file handle.
`windowsHandle`[get]	`int`	Returns the underlying operating system `HANDLE` (Windows only).

Methods

Name	Description
`byChunk` (chunkSize)	Returns an input range set up to read from the file handle a chunk at a time.
`byLine` (keepTerminator, terminator)	Returns an input range set up to read from the file handle one line at a time.
`byLineCopy` (keepTerminator, terminator)	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.
`byRecord` (format)	Creates an input range set up to parse one line at a time from the file into a tuple.
`clearerr` ()	If the file is closed or not yet opened, succeeds vacuously. Otherwise, returns clearerr for the file handle.
`close` ()	If the file was closed or not yet opened, 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` (fd, stdioOpenmode)	First calls `detach` (throwing on failure), then attempts to associate the given file descriptor with the `File`, and sets the file's name to `null`.
`flush` ()	Flushes the C `FILE` buffers.
`getFP` ()	Returns the `FILE*` corresponding to this object.
`lock` (lockType, start, length)	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.
`lockingBinaryWriter` ()	Returns an output range that locks the file and allows fast writing to it.
`lockingTextWriter` ()	Output range which locks the file when created, and unlocks the file when it goes out of scope.
`opAssign` (rhs)	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` (name, stdioOpenmode)	Detaches from the current file (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` (command, stdioOpenmode)	Detaches from the current file (throwing on failure), and then runs a command by calling the C standard library function popen.
`rawRead` (buffer)	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` (buffer)	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` (data)	Reads formatted data from the file using `std.format.formattedRead`.
`readln` (terminator)	Read line from the file handle and return it as a specified type.
`readln` (buf, terminator)	Read line from the file handle and write it to `buf[]`, including terminating character.
`reopen` (name, stdioOpenmode)	Reuses the `File` object to either open a different file, or change the file mode. If `name` is `null`, the mode of the currently open file is changed; otherwise, a new file is opened, reusing the C `FILE*`. The function has the same semantics as in the C standard library freopen function.
`rewind` ()	Calls rewind for the file handle.
`seek` (offset, origin)	Calls fseek for the file handle to move its position indicator.
`setvbuf` (size, mode)	Calls setvbuf for the file handle.
`setvbuf` (buf, mode)	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` (lockType, start, length)	Attempts to lock the specified file segment. If both `start` and `length` are zero, the entire file is locked.
`unlock` (start, length)	Removes the lock over the specified file segment.
`windowsHandleOpen` (handle, stdioOpenmode)	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` (f)	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` (args)	Writes its arguments in text format to the file.
`writef` (args)	Writes its arguments in text format to the file, according to the format string fmt.
`writefln` (args)	Equivalent to `file.writef(fmt, args, '\n')`.
`writeln` (args)	Writes its arguments in text format to the file, followed by a newline.

Example

// test.d
import std.stdio;

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.