# dmd.common.file

File utilities.

#### Discussion

Functions and objects dedicated to `file` I/O and management. TODO: Move here artifacts from places such as root/ so both the frontend and the backend have access to them.

#### Authors

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

#### License

Boost License 1.0

Source: common/file.d

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

Coverage: https://codecov.io/gh/dlang/dmd/src/master/src/dmd/common/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

  - `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 succeeds, returns `true`. Upon failure, prints a message to `stderr` and returns `false`. In all cases it closes the underlying file.

    #### Parameters

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

    #### Return Value

    `true` iff the operation was successful.

- `writeFile`

  #### Declaration

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

  Write a file, returning `true` on success.

- `touchFile`

  #### Declaration

  `nothrow bool `touchFile`(const char* `namez`);`

  Touch a file to current date