IO Streams

Github Page

IO Streams
License
Boost License 1.0.
Authors
Jason White
Description:
This module provides a low-level file  stream class.
Synopsis:
// Open a new file in read/write mode. Throws an exception if the file exists.
auto f = File("myfile", FileFlags.readWriteNew);

// Write an arbitrary array to the stream.
f.write("Hello world!");

// Seek to the beginning.
f.position = 0;

// Read in 5 bytes.
char buf[5];
f.read(buf);
assert(buf == "Hello");

struct  FileBase;

A cross-platform wrapper around low-level file operations.

alias  Handle = int;

Platform-specific file handle. On Posix systems, this is the file descriptor 

int
. On Windows, this is a 
HANDLE
.

enum Handle  InvalidHandle;

Platform-specific file handle. On Posix systems, this is the file descriptor 

int
. On Windows, this is a 
HANDLE
.

this(string name, FileFlags flags = FileFlags.readExisting);

Opens or creates a file by name. By default, an existing file is opened in read-only mode.

Parameters
string name Path to the file to open.
FileFlags flags How to open the file.
Example:
// Create a brand-new file and write to it. Throws an exception if the
// file already exists. The file is automatically closed when it falls
// out of scope.
auto f = File("filename", FileFlags.writeNew);
f.write("Hello world!");

this(Handle h);

Takes control of a file handle.

It is assumed that we have exclusive control over the file handle and will be closed upon destruction as usual. If non-exclusive control is desired, use dup instead.

This function is useful in a couple of situations:

  • The file must be opened with special flags that cannot be obtained via FileFlags
  • A special file handle must be opened (e.g., stdout, a pipe).

Parameters
Handle h The handle to assume control over. For Posix, this is a file descriptor (int). For Windows, this is an object handle ( HANDLE).

F  dup(F = File)(Handle h);

Duplicates the given platform-specific file handle. This is useful for taking non-exclusive control over a file handle.

void  close();

Closes the stream if it is open. Otherwise, it does nothing.

pure nothrow @property Handle  handle();

Returns the internal file  handle. On POSIX, this is a file descriptor. On Windows, this is an object  handle.

@property bool  isOpen();

Returns true if the file is open.

size_t  read(scope ubyte[] buf);

Reads data from the file.

Parameters
ubyte[] buf The buffer to  read the data into. The length of the buffer specifies how much data should be  read.
Returns
The number of bytes that were  read. 0 indicates that the end of the file has been reached.

size_t  readv(size_t StackSize = 32)(scope ubyte[][] bufs...);

Vectorized read.

Parameters
ubyte[][] bufs The buffers to read the data into. The length of each buffer specifies how much data should be read.
Returns
The number of bytes that were read. 0 indicates that the end of the file has been reached.

size_t  write(in ubyte[] data);

Writes data to the file.

Parameters
ubyte[] data The data to  write to the file. The length of the slice indicates how much data should be written.
Returns
The number of bytes that were written.

size_t  writev(size_t StackSize = 32)(in ubyte[][] bufs...);

Vectorized write.

Parameters
ubyte[][] bufs The buffers to write the data from. The length of each buffer specifies how much data should be written.
Returns
The number of bytes that were written.

long  seekTo(long offset, From from = From.start);

Seeks relative to a position.

Parameters
long offset Offset relative to a reference point.
From from Optional reference point.

@property long  length();

Gets the size of the file.

Example:
auto f = File("foobar", FileFlags.writeEmpty);
f.write("test");
assert(f.length == 4);

@property void  length(long len);

Sets the  length of the file. This can be used to truncate or extend the  length of the file. If the file is extended, the new segment is not guaranteed to be initialized to zeros.

Example:
auto f = File("foobar", FileFlags.writeEmpty);
f.length = 42;
assert(f.length == 42);

@property bool  isTerminal();

Checks if the file refers to a terminal.

Example:
assert(stdin.isTerminal);
assert(stderr.isTerminal);
assert(stdout.isTerminal);
assert(!File("test", FileFlags.writeAlways).isTerminal);

void  lock(LockType lockType = LockType.readWrite, long start = 0, long length = (long).max);

Locks the specified file segment. If the file segment is already locked by another process, waits until the existing  lock is released.

Note that this is a per-process  lock. This locking mechanism should not be used for thread-level synchronization. For that, use the synchronized statement.

bool  tryLock(LockType lockType = LockType.readWrite, long start = 0, long length = (long).max);

Like lock, but returns false immediately if the lock is held by another process. Returns true if the specified region in the file was successfully locked.

void  sync();

Syncs all modified cached data of the file to disk. This includes data written to the file as well as meta data (e.g., last modified time, last access time).