# dmd.root.file

Read a `file` from disk and store it in memory.

#### Authors

Walter Bright, http://www.digitalmars.com

#### License

Boost License 1.0

Source: root/file.d

Documentation: https://dlang.org/phobos/dmd_root_file.html

Coverage: https://codecov.io/gh/dlang/dmd/src/master/src/dmd/root/file.d

- `FileMapping`

  #### Declaration

  `struct `FileMapping`(Datum);`

  Encapsulated management of a memory-mapped file.

  #### Parameters

  `Datum` | the mapped data type: Use a POD of size 1 for read/write mapping and a `const` version thereof for read-only mapping. Other primitive types should work, but have not been yet tested.

  - `this`

    #### Declaration

    `this(const char* `filename`);`

    Open ``filename`` and map it in memory. If `Datum` is `const`, opens for read-only and maps the content in memory; no error is issued if the file does not exist. This makes it easy to treat a non-existing file as empty.

    #### Discussion

    If `Datum` is mutable, opens for read/write (creates file if it does not exist) and fails fatally on any error.
    Due to quirks in `mmap`, if the file is empty, `handle` is valid but `data` is `null`. This state is valid and accounted for.

    #### Parameters

    `char* `filename`` | the name of the file to be mapped in memory

  - `filename`

    #### Declaration

    `const pure nothrow @nogc @safe const(char)* `filename`();`

    Returns the zero-terminated file name associated with the mapping. Can be saved beyond the lifetime of `this`.

  - `close`

    #### Declaration

    `void `close`();`

    Frees resources associated with this mapping. However, it does not deallocate the name. Reinitializes `this` as a fresh object that can be reused.

  - `discard`

    #### Declaration

    `bool `discard`();`

    Deletes the underlying file and frees all resources associated. Reinitializes `this` as a fresh object that can be reused.

    #### Discussion

    This function does not abort if the file cannot be deleted, but does print a message on `stderr` and returns `false` to the caller. The underlying rationale is to give the caller the option to continue execution if deleting the file is not important.

    #### Return Value

    `true` iff the file was successfully deleted. If the file was not deleted, prints a message to `stderr` and returns `false`.

  - `active`

    #### Declaration

    `const pure nothrow @nogc bool `active`();`

    Queries whether `this` is currently associated with a file.

    #### Return Value

    `true` iff there is an `active` mapping.

  - `length`

    #### Declaration

    `const pure nothrow @nogc @safe size_t `length`();`

    Queries the `length` of the file associated with this mapping. If not active, returns 0.

    #### Return Value

    the `length` of the file, or 0 if no file associated.

  - `opSlice`

    #### Declaration

    `pure nothrow @nogc @safe auto `opSlice`();`

    Get a slice to the contents of the entire file.

    #### Return Value

    the contents of the file. If not active, returns the `null` slice.

  - `resize`

    #### Declaration

    `pure void `resize`(size_t `size`);`

    Resizes the file and mapping to the specified ``size``.

    #### Parameters

    `size_t `size`` | new length requested

  - `moveToFile`

    #### Declaration

    `bool `moveToFile`(const char* `filename`);`

    Unconditionally and destructively moves the underlying file to ``filename``. If the operation succeds, returns `true`. Upon failure, prints a message to `stderr` and returns `false`.

    #### Parameters

    `char* `filename`` | zero-terminated name of the file to move to.

    #### Return Value

    `true` iff the operation was successful.

- `FileBuffer`

  #### Declaration

  `struct `FileBuffer`;`

  Owns a (rmem-managed) file buffer.

  - `extractSlice`

    #### Declaration

    `pure nothrow @nogc @safe ubyte[] `extractSlice`();`

    Transfers ownership of the buffer to the caller.

- `File`

  #### Declaration

  `struct `File`;`

  - `ReadResult`

    #### Declaration

    `struct `ReadResult`;`

    - `extractSlice`

      #### Declaration

      `pure nothrow @nogc @safe ubyte[] `extractSlice`();`

      Transfers ownership of the buffer to the caller.

    - `extractDataZ`

      #### Declaration

      `pure nothrow @nogc ubyte[] `extractDataZ`();`

      ditto Include the `null`-terminator at the end of the buffer in the returned array.

  - `read`

    #### Declaration

    `static nothrow ReadResult `read`(const(char)* `name`);
    static nothrow ReadResult `read`(const(char)[] `name`);`

    Read the full content of a file.

  - `write`

    #### Declaration

    `static nothrow bool `write`(const(char)* `name`, const void[] `data`);
    static nothrow bool `write`(const(char)[] `name`, const void[] `data`);
    static nothrow bool `write`(const(char)* `name`, const(void)* `data`, size_t `size`);`

    Write a file, returning `true` on success.

  - `remove`

    #### Declaration

    `static nothrow void `remove`(const(char)* `name`);`

    Delete a file.

  - `update`

    #### Declaration

    `static nothrow bool `update`(const(char)* `namez`, const void[] `data`);
    static nothrow bool `update`(const(char)[] `name`, const void[] `data`);
    static nothrow bool `update`(const(char)* `name`, const(void)* `data`, size_t `size`);`

    Update file

    #### Discussion

    If the file exists and is identical to what is to be written, merely `update` the timestamp on the file. Otherwise, write the file.
    The idea is writes are much slower than reads, and build systems often wind up generating identical files.

    #### Parameters

    `const(char)[] `name`` | `name` of file to `update`
    `void[] `data`` | updated contents of file

    #### Return Value

    `true` on success

  - `touch`

    #### Declaration

    `static nothrow bool `touch`(const char* `namez`);`

    Touch a file to current date

  - `size`

    #### Declaration

    `static nothrow ulong `size`(const char* `namez`);
    static nothrow ulong `size`(int `fd`);`

    Size of a file in bytes.

    #### Parameters

    `char* `namez`` | `null`-terminated filename

    #### Return Value

    `ulong.max` on any error, the length otherwise.