====== read_file() ======
----
The **read_file()** function is called when the user requests a file to be read from the source image.
===== Syntax =====
----
==== Declaration ====
Declared in ''src/mess/tools/imgtool/library.h'' as

<code>imgtoolerr_t (*read_file)(
    imgtool_partition *partition,
    const char *filename,
    const char *fork,
    imgtool_stream *destf
);</code>

==== Parameters ====
  * ''partition'' – Pointer to an [[imgtool_partition]] where the file is.
  * ''filename'' – Pointer to a string with the filename of the file the user wants to read.
  * ''fork'' – Pointer to a string with a resource fork. Only used for Macintosh filesystems.
  * ''destf'' – Pointer to an [[imgtool_stream]] to write the file data to.

==== Returns ====

An [[imgtoolerr_t]] with the type of error that occurred or ''IMGTOOLERR_SUCCESS'' if no error occurred.
===== Example =====
----
<code>imgtoolerr_t mymodule_read_file(
    imgtool_partition *partition,
    const char *filename,
    const char *fork,
    imgtool_stream *destf
) {
    imgtoolerr_t ret;
    imgtool_image *image = imgtool_partition_image(partition);
    int filesize, track, sector;
    UINT8 buffer[SECTOR_SIZE];
    directory_entry entry;

    ret = mymodule_get_directory_entry(image, filename, &entry);
    if (ret) return ret;

    filesize = entry.end_address - entry.start_address;
    track = entry.start_track;
    sector = entry.start_sector;

    while (filesize > 0) {
        int bytes_left;

        ret = mymodule_read_sector_data(image, track, sector, buffer);
        if (ret) return ret;

        /* detect sectors pointing to themselfs */
        if ((track  == pick_integer_le(buffer, DATA_SIZE, 1)) &&
            (sector == pick_integer_le(buffer, DATA_SIZE + 1, 1)))
            return IMGTOOLERR_CORRUPTIMAGE;

        /* load next track and sector values */
        track  = pick_integer_le(buffer, DATA_SIZE, 1);
        sector = pick_integer_le(buffer, DATA_SIZE + 1, 1);

        /* track 0 is invalid */
        if ((track == 0) && (filesize > DATA_SIZE))
            return IMGTOOLERR_CORRUPTIMAGE;

        /* write either DATA_SIZE or the remaining bytes */
    bytes_left = filesize > DATA_SIZE ? DATA_SIZE : filesize;

        if (stream_write(destf, buffer, bytes_left) != bytes_left)
            return IMGTOOLERR_WRITEERROR;

        filesize -= DATA_SIZE;
    }

    return IMGTOOLERR_SUCCESS;
}</code>

This is a simple example that doesn't use partitions.