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 {

static import ocean.core.ExceptionDefinitions;;

import ocean.sys.CloseOnExec;;

static immutable

auto O_CLOEXEC;

alias read = Device.read;

alias write = Device.write;

class IOException;

static immutable

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 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

Meta

Source

See Implementation

ocean io device File classes

File