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.