File

Implements a means of reading and writing a generic file. Conduits are the primary means of accessing external data, and File extends the basic pattern by providing file-specific methods to set the file size, seek to a specific file position and so on.

Serial input and output is straightforward. In this example we copy a file directly to the console:

// open a file for reading
auto from = new File ("test.txt");

// stream directly to console
Stdout.copy (from);

And here we copy one file to another:

// open file for reading
auto from = new File ("test.txt");

// open another for writing
auto to = new File ("copy.txt", File.WriteCreate);

// copy file and close
to.copy.close;
from.close;

You can use InputStream.load() to load a file directly into memory:

auto file = new File ("test.txt");
auto content = file.load;
file.close;

Or use a convenience static function within File:

auto content = File.get ("test.txt");

A more explicit version with a similar result would be:

// open file for reading
auto file = new File ("test.txt");

// create an array to house the entire file
auto content = new char [file.length];

// read the file content. Return value is the number of bytes read
auto bytes = file.read (content);
file.close;

Conversely, one may write directly to a File like so:

// open file for writing
auto to = new File ("text.txt", File.WriteCreate);

// write an array of content to it
auto bytes = to.write (content);

There are equivalent static functions, File.set() and File.append(), which set or append file content respectively.

File can happily handle random I/O. Here we use seek() to relocate the file pointer:

// open a file for reading and writing
auto file = new File ("random.bin", File.ReadWriteCreate);

// write some data
file.write ("testing");

// rewind to file start
file.seek (0);

// read data back again
char[10] tmp;
auto bytes = file.read (tmp);

file.close;

Note that File is unbuffered by default - wrap an instance within ocean.io.stream.Buffered for buffered I/O.

Compile with -version=Win32SansUnicode to enable Win95 & Win32s file support.

class File : Device , Device.Seek, Device.Truncate {

import ocean.core.ExceptionDefinitions;;

import ocean.sys.CloseOnExec;;

static immutable

auto O_CLOEXEC;

alias read = Device.read;

alias write = Device.write;

Style ReadExisting;

static immutable

Style ReadShared;

static immutable

Style WriteExisting;

static immutable

Style WriteCreate;

static immutable

Style ReadWriteAppending;

static immutable

Style WriteAppending;

static immutable

Style ReadWriteExisting;

static immutable

Style ReadWriteCreate;

static immutable

Style ReadWriteOpen;

this(IOException exception);

this(cstring path, Style style, IOException exception);

Style style();

istring toString();

cstring path();

static void[] get(cstring path);

static void[] get(cstring path, void[] dst);

static void set(cstring path, const(void)[] content);

static void append(cstring path, const(void)[] content);

bool open(cstring path, Style style, int addflags, int access);

void open(cstring path, Style style);

void setFileHandle(int fd);

void truncate();

void truncate(long size);

long seek(long offset, Anchor anchor);

long position();

long length();

void sync();

void error(int error_code, istring func_name, istring msg, istring file, long line);

alias error = Conduit.error;

alias error = Device.error;

}

Constructors

this this(IOException exception): Create a File for use with open().
this this(cstring path, Style style, IOException exception): Create a File with the provided path and style.

Members

Aliases

error alias error = Conduit.error: Throw an IOException, with the provided message.
error alias error = Device.error: Throw an IOException noting the last error.
read alias read = Device.read: Undocumented in source.
write alias write = Device.write: Undocumented in source.

Classes

IOException class IOException: Exception class thrown on errors.

Enums

Access enum Access
Cache enum Cache
Open enum Open
Share enum Share

Functions

error void error(int error_code, istring func_name, istring msg, istring file, long line): Throw a potentially reusable IOException, with the provided message, function name and error code.
length long length(): Return the total length of this file.
open bool open(cstring path, Style style, int addflags, int access): Low level open for sub-classes that need to apply specific attributes.
open void open(cstring path, Style style): Open a file with the provided style.
path cstring path()
position long position(): Return the current file position.
seek long seek(long offset, Anchor anchor): Set the file seek position to the specified offset from the given anchor.
setFileHandle void setFileHandle(int fd): Wraps the already open file descriptor into a File instance.
style Style style(): Return the Style used for this file.
sync void sync(): Instructs the OS to flush it's internal buffers to the disk device.
toString istring toString(): Return the path used by this file.
truncate void truncate(): Set the file size to be that of the current seek position. The file must be writable for this to succeed.
truncate void truncate(long size): Set the file size to be the specified length. The file must be writable for this to succeed.

Static functions

append void append(cstring path, const(void)[] content): Convenience function to append content to a file.
get void[] get(cstring path): Convenience function to return the content of a file.
get void[] get(cstring path, void[] dst): Convenience function to return the content of a file.
set void set(cstring path, const(void)[] content): Convenience function to set file content and length to reflect the given array.

Static variables

O_CLOEXEC auto O_CLOEXEC;: Undocumented in source.
ReadExisting Style ReadExisting;: Read an existing file.
ReadShared Style ReadShared;: Read an existing file.
ReadWriteAppending Style ReadWriteAppending;: Read from the beginning, append at the end of the file.
ReadWriteCreate Style ReadWriteCreate;: Read & write on a clean file. Create if necessary.
ReadWriteExisting Style ReadWriteExisting;: Read and write an existing file.
ReadWriteOpen Style ReadWriteOpen;: Read and Write. Use existing file if present.
WriteAppending Style WriteAppending;: Write at the end of the file.
WriteCreate Style WriteCreate;: Write on a clean file. Create if necessary.
WriteExisting Style WriteExisting;: Write on an existing file. Do not create.

Structs

Style struct Style: Fits into 32 bits ...

Inherited Members

From Device

error alias error = Conduit.error: expose superclass definition also
error void error(): Throw an IOException noting the last error.
toString istring toString(): Return the name of this device.
bufferSize size_t bufferSize(): Return a preferred size for buffering conduit I/O.
setNonBlock void setNonBlock(): Sets the device in the non-blocking mode.
handle int handle;: Undocumented in source.
reopen void reopen(Handle handle): Allow adjustment of standard IO handles.
fileHandle Handle fileHandle()
detach void detach(): Release the underlying file.
read size_t read(void[] dst): Read a chunk of bytes from the file into the provided array
write size_t write(const(void)[] src): Write a chunk of bytes to the file from the provided array.
pread size_t pread(void[] dst, off_t offset): Read a chunk of bytes from the file from the given offset, into the provided array
pwrite size_t pwrite(const(void)[] src, off_t offset): Write a chunk of bytes to the file starting from the given offset, from the provided array

File

Constructors

Members

Aliases

Classes

Enums

Functions

Static functions

Static variables

Structs

Inherited Members

From Device

Meta

Source