The read_file() function is called when the user requests a file to be read from the source image.

Declared in src/mess/tools/imgtool/library.h as

imgtoolerr_t (*read_file)(
    imgtool_partition *partition,
    const char *filename,
    const char *fork,
    imgtool_stream *destf
);

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

An imgtoolerr_t with the type of error that occurred or IMGTOOLERR_SUCCESS if no error occurred.

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

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