mio.c

Go to the documentation of this file.

/*
 *  MIO, an I/O abstraction layer replicating C file I/O API.
 *  Copyright (C) 2010  Colomban Wendling <ban@herbesfolles.org>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 */
 
#ifndef READTAGS_DSL
#include "general.h"  /* must always come first */
 
#include "routines.h"
#include "debug.h"
#else
 
#if defined (HAVE_CONFIG_H)
#include <config.h>
#endif
 
#ifdef HAVE_STDBOOL_H
#include <stdbool.h>
#endif
#endif  /* READTAGS_DSL */
 
#include "mio.h"
 
#include <stdarg.h>
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <stdlib.h>
#include <limits.h>
 
#ifdef READTAGS_DSL
#define xMalloc(n,Type)    (Type *)eMalloc((size_t)(n) * sizeof (Type))
#define xRealloc(p,n,Type) (Type *)eRealloc((p), (n) * sizeof (Type))
 
static void *eMalloc (const size_t size)
{
    void *buffer = malloc (size);
 
    if (buffer == NULL)
    {
        fprintf(stderr, "out of memory");
        abort ();
    }
 
    return buffer;
}
 
static void *eRealloc (void *const ptr, const size_t size)
{
    void *buffer;
    if (ptr == NULL)
        buffer = eMalloc (size);
    else
    {
        buffer = realloc (ptr, size);
        if (buffer == NULL)
        {
            fprintf(stderr, "out of memory");
            abort ();
        }
    }
    return buffer;
}
 
static void eFree (void *const ptr)
{
    free (ptr);
}
#define eFreeNoNullCheck eFree
 
#  define Assert(c) do {} while(0)
#  define AssertNotReached() do {} while(0)
#endif  /* READTAGS_DSL */
 
/* minimal reallocation chunk size */
#define MIO_CHUNK_SIZE 4096
 
#define MAX(a, b)  (((a) > (b)) ? (a) : (b))
 
 
/**
 * SECTION:mio
 * @short_description: The MIO object
 * @include: mio/mio.h
 *
 * The #MIO object replicates the C file I/O API with support of both standard
 * file based operations and in-memory operations. Its goal is to ease the port
 * of an application that uses C file I/O API to perform in-memory operations.
 *
 * A #MIO object is created using mio_new_file(), mio_new_memory() or mio_new_mio(),
 * depending on whether you want file or in-memory operations.
 * Its life is managed by reference counting. Just after calling one of functions
 * for creating, the count is 1. mio_ref() increments the counter. mio_unref()
 * decrements it. When the counter becomes 0, the #MIO object will be destroyed
 * in mio_unref(). There is also some other convenient API to create file-based
 * #MIO objects for more complex cases, such as mio_new_file_full() and
 * mio_new_fp().
 *
 * Once the #MIO object is created, you can perform standard I/O operations on
 * it transparently without the need to care about the effective underlying
 * operations.
 *
 * The I/O API is almost exactly a replication of the standard C file I/O API
 * with the significant difference that the first parameter is always the #MIO
 * object to work on.
 */
 
 
typedef struct _MIOUserData MIOUserData;
struct _MIOUserData {
    void *d;
    MIODestroyNotify f;
};
 
/**
 * MIO:
 *
 * An object representing a #MIO stream. No assumptions should be made about
 * what compose this object, and none of its fields should be accessed directly.
 */
struct _MIO {
    /*< private >*/
    MIOType type;
    unsigned int refcount;
    union {
        struct {
            FILE *fp;
            MIOFCloseFunc close_func;
        } file;
        struct {
            unsigned char *buf;
            int ungetch;
            size_t pos;
            size_t size;
            size_t allocated_size;
            MIOReallocFunc realloc_func;
            MIODestroyNotify free_func;
            bool error;
            bool eof;
        } mem;
    } impl;
    MIOUserData udata;
};
 
 
/**
 * mio_new_file_full:
 * @filename: Filename to open, passed as-is to @open_func as the first argument
 * @mode: Mode in which open the file, passed as-is to @open_func as the second
 *        argument
 * @open_func: A function with the fopen() semantic to use to open the file
 * @close_func: A function with the fclose() semantic to close the file when
 *              the #MIO object is destroyed, or %NULL not to close the #FILE
 *              object
 *
 * Creates a new #MIO object working on a file, from a filename and an opening
 * function. See also mio_new_file().
 *
 * This function is generally overkill and mio_new_file() should often be used
 * instead, but it allows to specify a custom function to open a file, as well
 * as a close function. The former is useful e.g. if you need to wrap fopen()
 * for some reason (like filename encoding conversion for example), and the
 * latter allows you both to match your custom open function and to choose
 * whether the underlying #FILE object should or not be closed when mio_unref()
 * is called on the returned object.
 *
 * Free-function: mio_unref()
 *
 * Returns: A new #MIO on success, or %NULL on failure.
 */
MIO *mio_new_file_full (const char *filename,
                        const char *mode,
                        MIOFOpenFunc open_func,
                        MIOFCloseFunc close_func)
{
    MIO *mio;
 
    /* we need to create the MIO object first, because we may not be able to close
     * the opened file if the user passed NULL as the close function, which means
     * that everything must succeed if we've opened the file successfully */
    mio = xMalloc (1, MIO);
    if (mio)
    {
        FILE *fp = open_func (filename, mode);
 
        if (! fp)
        {
            eFree (mio);
            mio = NULL;
        }
        else
        {
            mio->type = MIO_TYPE_FILE;
            mio->impl.file.fp = fp;
            mio->impl.file.close_func = close_func;
            mio->refcount = 1;
            mio->udata.d = NULL;
            mio->udata.f = NULL;
        }
    }
 
    return mio;
}
 
/**
 * mio_new_file:
 * @filename: Filename to open, same as the fopen()'s first argument
 * @mode: Mode in which open the file, fopen()'s second argument
 *
 * Creates a new #MIO object working on a file from a filename; wrapping
 * fopen().
 * This function simply calls mio_new_file_full() with the libc's fopen() and
 * fclose() functions.
 *
 * Free-function: mio_unref()
 *
 * Returns: A new #MIO on success, or %NULL on failure.
 */
MIO *mio_new_file (const char *filename, const char *mode)
{
    return mio_new_file_full (filename, mode, fopen, fclose);
}
 
/**
 * mio_new_fp:
 * @fp: An opened #FILE object
 * @close_func: (allow-none): Function used to close @fp when the #MIO object
 *              gets destroyed, or %NULL not to close the #FILE object
 *
 * Creates a new #MIO object working on a file, from an already opened #FILE
 * object.
 *
 * <example>
 * <title>Typical use of this function</title>
 * <programlisting>
 * MIO *mio = mio_new_fp (fp, fclose);
 * </programlisting>
 * </example>
 *
 * Free-function: mio_unref()
 *
 * Returns: A new #MIO on success or %NULL on failure.
 */
MIO *mio_new_fp (FILE *fp, MIOFCloseFunc close_func)
{
    MIO *mio;
 
    if (!fp)
        return NULL;
 
    mio = xMalloc (1, MIO);
    if (mio)
    {
        mio->type = MIO_TYPE_FILE;
        mio->impl.file.fp = fp;
        mio->impl.file.close_func = close_func;
        mio->refcount = 1;
        mio->udata.d = NULL;
        mio->udata.f = NULL;
    }
 
    return mio;
}
 
/**
 * mio_new_memory:
 * @data: Initial data (may be %NULL)
 * @size: Length of @data in bytes
 * @realloc_func: A function with the realloc() semantic used to grow the
 *                buffer, or %NULL to disable buffer growing
 * @free_func: A function with the free() semantic to destroy the data together
 *             with the object, or %NULL not to destroy the data
 *
 * Creates a new #MIO object working on memory.
 *
 * To allow the buffer to grow, you must provide a @realloc_func, otherwise
 * trying to write after the end of the current data will fail.
 *
 * If you want the buffer to be freed together with the #MIO object, you must
 * give a @free_func; otherwise the data will still live after #MIO object
 * termination.
 *
 * <example>
 * <title>Basic creation of a non-growable, freeable #MIO object</title>
 * <programlisting>
 * MIO *mio = mio_new_memory (data, size, NULL, g_free);
 * </programlisting>
 * </example>
 *
 * <example>
 * <title>Basic creation of an empty growable and freeable #MIO object</title>
 * <programlisting>
 * MIO *mio = mio_new_memory (NULL, 0, g_try_realloc, g_free);
 * </programlisting>
 * </example>
 *
 * Free-function: mio_unref()
 *
 * Returns: A new #MIO on success, or %NULL on failure.
 */
MIO *mio_new_memory (unsigned char *data,
                     size_t size,
                     MIOReallocFunc realloc_func,
                     MIODestroyNotify free_func)
{
    MIO *mio;
 
    mio = xMalloc (1, MIO);
    if (mio)
    {
        mio->type = MIO_TYPE_MEMORY;
        mio->impl.mem.buf = data;
        mio->impl.mem.ungetch = EOF;
        mio->impl.mem.pos = 0;
        mio->impl.mem.size = size;
        mio->impl.mem.allocated_size = size;
        mio->impl.mem.realloc_func = realloc_func;
        mio->impl.mem.free_func = free_func;
        mio->impl.mem.eof = false;
        mio->impl.mem.error = false;
        mio->refcount = 1;
        mio->udata.d = NULL;
        mio->udata.f = NULL;
    }
 
    return mio;
}
 
/**
 * mio_new_mio:
 * @base: The original mio
 * @start: stream offset of the @base where new mio starts
 * @size: the length of the data copied from @base to new mio
 *
 * Creates a new #MIO object by copying data from existing #MIO (@base).
 * The range for copying is given with @start and @size.
 * Copying data at the range from @start to the end of @base is
 * done if -1 is given as @size.
 *
 * If @size is larger than the length from @start to the end of
 * @base, %NULL is returned.
 *
 * The function doesn't move the file position of @base.
 *
 * Free-function: mio_unref()
 *
 */
 
MIO *mio_new_mio (MIO *base, long start, long size)
{
    unsigned char *data;
    long original_pos;
    MIO *submio;
    size_t r;
 
    original_pos = mio_tell (base);
 
    if (size == -1)
    {
        long end;
 
        if (mio_seek (base, 0, SEEK_END) != 0)
            return NULL;
        end = mio_tell (base);
        Assert (end >= start);
        size = end - start;
    }
 
    if (mio_seek (base, start, SEEK_SET) != 0)
        return NULL;
 
    data = xMalloc (size, unsigned char);
    r= mio_read (base, data, 1, size);
    mio_seek (base, original_pos, SEEK_SET);
 
    if (r != size)
        goto cleanup;
 
    submio = mio_new_memory (data, size, eRealloc, eFreeNoNullCheck);
    if (! submio)
        goto cleanup;
 
    return submio;
 
cleanup:
    eFree (data);
    return NULL;
}
 
/**
 * mio_ref:
 * @mio: A #MIO object
 *
 * Increments the reference counter of a #MIO.
 *
 * Returns: passed @mio.
 */
MIO *mio_ref        (MIO *mio)
{
    mio->refcount++;
    return mio;
}
 
/**
 * mio_file_get_fp:
 * @mio: A #MIO object
 *
 * Gets the underlying #FILE object associated with a #MIO file stream.
 *
 * <warning><para>The returned object may become invalid after a call to
 * mio_unref() if the stream was configured to close the file when
 * destroyed.</para></warning>
 *
 * Returns: The underlying #FILE object of the given stream, or %NULL if the
 *          stream is not a file stream.
 */
FILE *mio_file_get_fp (MIO *mio)
{
    FILE *fp = NULL;
 
    if (mio->type == MIO_TYPE_FILE)
        fp = mio->impl.file.fp;
 
    return fp;
}
 
/**
 * mio_memory_get_data:
 * @mio: A #MIO object
 * @size: (allow-none) (out): Return location for the length of the returned
 *        memory, or %NULL
 *
 * Gets the underlying memory buffer associated with a #MIO memory stream.
 *
 * <warning><para>The returned pointer and size may become invalid after a
 * successful write on the stream or after a call to mio_unref() if the stream
 * was configured to free the memory when destroyed.</para></warning>
 *
 * Returns: The memory buffer of the given #MIO stream, or %NULL if the stream
 *          is not a memory stream.
 */
unsigned char *mio_memory_get_data (MIO *mio, size_t *size)
{
    unsigned char *ptr = NULL;
 
    if (mio->type == MIO_TYPE_MEMORY)
    {
        ptr = mio->impl.mem.buf;
        if (size)
            *size = mio->impl.mem.size;
    }
 
    return ptr;
}
 
/**
 * mio_unref:
 * @mio: A #MIO object
 *
 * Decrements the reference counter of a #MIO and destroys the #MIO
 * object if its counter becomes 0.
 *
 * Returns: Error code obtained from the registered MIOFCloseFunc or 0 on success.
 */
int mio_unref (MIO *mio)
{
    int rv = 0;
 
    if (mio)
    {
        if (--mio->refcount)
            return 0;
 
        if (mio->udata.d && mio->udata.f)
            mio->udata.f (mio->udata.d);
 
        if (mio->type == MIO_TYPE_FILE)
        {
            if (mio->impl.file.close_func)
                rv = mio->impl.file.close_func (mio->impl.file.fp);
            mio->impl.file.close_func = NULL;
            mio->impl.file.fp = NULL;
        }
        else if (mio->type == MIO_TYPE_MEMORY)
        {
            if (mio->impl.mem.free_func)
                mio->impl.mem.free_func (mio->impl.mem.buf);
            mio->impl.mem.buf = NULL;
            mio->impl.mem.pos = 0;
            mio->impl.mem.size = 0;
            mio->impl.mem.allocated_size = 0;
            mio->impl.mem.realloc_func = NULL;
            mio->impl.mem.free_func = NULL;
            mio->impl.mem.eof = false;
            mio->impl.mem.error = false;
        }
        else
            AssertNotReached ();
 
        eFree (mio);
    }
 
    return rv;
}
 
/**
 * mio_read:
 * @mio: A #MIO object
 * @ptr: Pointer to the memory to fill with the read data
 * @size: Size of each block to read
 * @nmemb: Number o blocks to read
 *
 * Reads raw data from a #MIO stream. This function behave the same as fread().
 *
 * Returns: The number of actually read blocks. If an error occurs or if the
 *          end of the stream is reached, the return value may be smaller than
 *          the requested block count, or even 0. This function doesn't
 *          distinguish between end-of-stream and an error, you should then use
 *          mio_eof() and mio_error() to determine which occurred.
 */
size_t mio_read (MIO *mio,
                 void *ptr_,
                 size_t size,
                 size_t nmemb)
{
    if (mio->type == MIO_TYPE_FILE)
        return fread (ptr_, size, nmemb, mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        size_t n_read = 0;
 
        if (size != 0 && nmemb != 0)
        {
            size_t size_avail = mio->impl.mem.size - mio->impl.mem.pos;
            size_t copy_bytes = size * nmemb;
            unsigned char *ptr = ptr_;
 
            if (size_avail < copy_bytes)
                copy_bytes = size_avail;
 
            if (copy_bytes > 0)
            {
                n_read = copy_bytes / size;
 
                if (mio->impl.mem.ungetch != EOF)
                {
                    *ptr = (unsigned char) mio->impl.mem.ungetch;
                    mio->impl.mem.ungetch = EOF;
                    copy_bytes--;
                    mio->impl.mem.pos++;
                    ptr++;
                }
 
                memcpy (ptr, &mio->impl.mem.buf[mio->impl.mem.pos], copy_bytes);
                mio->impl.mem.pos += copy_bytes;
            }
            if (mio->impl.mem.pos >= mio->impl.mem.size)
                mio->impl.mem.eof = true;
        }
 
        return n_read;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/*
 * mem_try_resize:
 * @mio: A #MIO object of the type %MIO_TYPE_MEMORY
 * @new_size: Requested new size
 *
 * Tries to resize the underlying buffer of an in-memory #MIO object.
 * This supports both growing and shrinking.
 *
 * Returns: %true on success, %false otherwise.
 */
static int mem_try_resize (MIO *mio, size_t new_size)
{
    int success = false;
 
    if (mio->impl.mem.realloc_func)
    {
        if (new_size == ULONG_MAX)
        {
#ifdef EOVERFLOW
            errno = EOVERFLOW;
#endif
        }
        else
        {
            if (new_size > mio->impl.mem.size)
            {
                if (new_size <= mio->impl.mem.allocated_size)
                {
                    mio->impl.mem.size = new_size;
                    success = true;
                }
                else
                {
                    size_t newsize;
                    unsigned char *newbuf;
 
                    newsize = MAX (mio->impl.mem.allocated_size + MIO_CHUNK_SIZE,
                                   new_size);
                    newbuf = mio->impl.mem.realloc_func (mio->impl.mem.buf, newsize);
                    if (newbuf)
                    {
                        mio->impl.mem.buf = newbuf;
                        mio->impl.mem.allocated_size = newsize;
                        mio->impl.mem.size = new_size;
                        success = true;
                    }
                }
            }
            else
            {
                unsigned char *newbuf;
 
                newbuf = mio->impl.mem.realloc_func (mio->impl.mem.buf, new_size);
                if (newbuf || new_size == 0)
                {
                    mio->impl.mem.buf = newbuf;
                    mio->impl.mem.allocated_size = new_size;
                    mio->impl.mem.size = new_size;
                    success = true;
                }
            }
        }
    }
 
    return success;
}
 
int mio_try_resize (MIO *mio, size_t new_size)
{
    return mem_try_resize (mio, new_size);
}
 
/*
 * mem_try_ensure_space:
 * @mio: A #MIO object
 * @n: Requested size from the current (cursor) position
 *
 * Tries to ensure there is enough space for @n bytes to be written from the
 * current cursor position.
 *
 * Returns: %true if there is enough space, %false otherwise.
 */
static int mem_try_ensure_space (MIO *mio, size_t n)
{
    int success = true;
 
    if (mio->impl.mem.pos + n > mio->impl.mem.size)
        success = mem_try_resize (mio, mio->impl.mem.pos + n);
 
    return success;
}
 
/**
 * mio_write:
 * @mio: A #MIO object
 * @ptr: Pointer to the memory to write on the stream
 * @size: Size of each block to write
 * @nmemb: Number of block to write
 *
 * Writes raw data to a #MIO stream. This function behaves the same as fwrite().
 *
 * Returns: The number of blocks actually written to the stream. This might be
 *          smaller than the requested count if a write error occurs.
 */
size_t mio_write (MIO *mio,
                  const void *ptr,
                  size_t size,
                  size_t nmemb)
{
    if (mio->type == MIO_TYPE_FILE)
        return fwrite (ptr, size, nmemb, mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        size_t n_written = 0;
 
        if (size != 0 && nmemb != 0)
        {
            if (mem_try_ensure_space (mio, size * nmemb))
            {
                memcpy (&mio->impl.mem.buf[mio->impl.mem.pos], ptr, size * nmemb);
                mio->impl.mem.pos += size * nmemb;
                n_written = nmemb;
            }
        }
 
        return n_written;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_putc:
 * @mio: A #MIO object
 * @c: The character to write
 *
 * Writes a character to a #MIO stream. This function behaves the same as
 * fputc().
 *
 * Returns: The written character, or %EOF on error.
 */
int mio_putc (MIO *mio, int c)
{
    if (mio->type == MIO_TYPE_FILE)
        return fputc (c, mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        int rv = EOF;
 
        if (mem_try_ensure_space (mio, 1))
        {
            mio->impl.mem.buf[mio->impl.mem.pos] = (unsigned char)c;
            mio->impl.mem.pos++;
            rv = (int)((unsigned char)c);
        }
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_puts:
 * @mio: A #MIO object
 * @s: The string to write
 *
 * Writes a string to a #MIO object. This function behaves the same as fputs().
 *
 * Returns: A non-negative integer on success or %EOF on failure.
 */
int mio_puts (MIO *mio, const char *s)
{
    if (mio->type == MIO_TYPE_FILE)
        return fputs (s, mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        int rv = EOF;
        size_t len;
 
        len = strlen (s);
        if (mem_try_ensure_space (mio, len))
        {
            memcpy (&mio->impl.mem.buf[mio->impl.mem.pos], s, len);
            mio->impl.mem.pos += len;
            rv = 1;
        }
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_vprintf:
 * @mio: A #MIO object
 * @format: A printf format string
 * @ap: The variadic argument list for the format
 *
 * Writes a formatted string into a #MIO stream. This function behaves the same
 * as vfprintf().
 *
 * Returns: The number of bytes written in the stream, or a negative value on
 *          failure.
 */
int mio_vprintf (MIO *mio, const char *format, va_list ap)
{
    if (mio->type == MIO_TYPE_FILE)
        return vfprintf (mio->impl.file.fp, format, ap);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        int rv = -1;
        size_t n;
        size_t old_pos;
        size_t old_size;
        va_list ap_copy;
        char dummy;
 
        old_pos = mio->impl.mem.pos;
        old_size = mio->impl.mem.size;
        va_copy (ap_copy, ap);
        /* compute the size we will need into the buffer */
        n = vsnprintf (&dummy, 1, format, ap_copy) + 1;
        va_end (ap_copy);
        if (mem_try_ensure_space (mio, n))
        {
            unsigned char c;
 
            /* backup character at n+1 that will be overwritten by a \0 ... */
            c = mio->impl.mem.buf[mio->impl.mem.pos + (n - 1)];
            rv = vsprintf ((char *)&mio->impl.mem.buf[mio->impl.mem.pos], format, ap);
            /* ...and restore it */
            mio->impl.mem.buf[mio->impl.mem.pos + (n - 1)] = c;
            if (rv >= 0 && (size_t)rv == (n - 1))
            {
                /* re-compute the actual size since we might have allocated one byte
                 * more than needed */
                mio->impl.mem.size = MAX (old_size, old_pos + (unsigned int)rv);
                mio->impl.mem.pos += (unsigned int)rv;
            }
            else
            {
                mio->impl.mem.size = old_size;
                rv = -1;
            }
        }
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_printf:
 * @mio: A #MIO object
 * @format: A print format string
 * @...: Arguments of the format
 *
 * Writes a formatted string to a #MIO stream. This function behaves the same as
 * fprintf().
 *
 * Returns: The number of bytes written to the stream, or a negative value on
 *          failure.
 */
int mio_printf (MIO *mio, const char *format, ...)
{
    int rv;
    va_list ap;
 
    va_start (ap, format);
    rv = mio_vprintf (mio, format, ap);
    va_end (ap);
 
    return rv;
}
 
/**
 * mio_getc:
 * @mio: A #MIO object
 *
 * Gets the current character from a #MIO stream. This function behaves the same
 * as fgetc().
 *
 * Returns: The read character as a #int, or %EOF on error.
 */
int mio_getc (MIO *mio)
{
    if (mio->type == MIO_TYPE_FILE)
        return fgetc (mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        int rv = EOF;
 
        if (mio->impl.mem.ungetch != EOF)
        {
            rv = mio->impl.mem.ungetch;
            mio->impl.mem.ungetch = EOF;
            mio->impl.mem.pos++;
        }
        else if (mio->impl.mem.pos < mio->impl.mem.size)
        {
            rv = mio->impl.mem.buf[mio->impl.mem.pos];
            mio->impl.mem.pos++;
        }
        else
            mio->impl.mem.eof = true;
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_ungetc:
 * @mio: A #MIO object
 * @ch: Character to put back in the stream
 *
 * Puts a character back in a #MIO stream. This function behaves the sames as
 * ungetc().
 *
 * <warning><para>It is only guaranteed that one character can be but back at a
 * time, even if the implementation may allow more.</para></warning>
 * <warning><para>Using this function while the stream cursor is at offset 0 is
 * not guaranteed to function properly. As the C99 standard says, it is "an
 * obsolescent feature".</para></warning>
 *
 * Returns: The character put back, or %EOF on error.
 */
int mio_ungetc (MIO *mio, int ch)
{
    if (mio->type == MIO_TYPE_FILE)
        return ungetc (ch, mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        int rv = EOF;
 
        if (ch != EOF && mio->impl.mem.ungetch == EOF)
        {
            rv = mio->impl.mem.ungetch = ch;
            mio->impl.mem.pos--;
            mio->impl.mem.eof = false;
        }
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_gets:
 * @mio: A #MIO object
 * @s: A string to fill with the read data
 * @size: The maximum number of bytes to read
 *
 * Reads a string from a #MIO stream, stopping after the first new-line
 * character or at the end of the stream. This function behaves the same as
 * fgets().
 *
 * Returns: @s on success, %NULL otherwise.
 */
char *mio_gets (MIO *mio, char *s, size_t size)
{
    if (mio->type == MIO_TYPE_FILE)
        return fgets (s, (int)size, mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        char *rv = NULL;
 
        if (size > 0)
        {
            size_t i = 0;
            bool newline = false;
            /* Avoiding dereference inside the for loop below improves
             * performance so we do it here. */
            size_t pos = mio->impl.mem.pos;
            size_t buf_size = mio->impl.mem.size;
            unsigned char *buf = mio->impl.mem.buf;
 
            if (mio->impl.mem.ungetch != EOF)
            {
                s[i] = (char)mio->impl.mem.ungetch;
                mio->impl.mem.ungetch = EOF;
                pos++;
                i++;
            }
            for (; pos < buf_size && i < (size - 1); i++)
            {
                s[i] = (char)buf[pos];
                pos++;
                if (s[i] == '\n')
                {
                    i++;
                    newline = true;
                    break;
                }
            }
            if (i > 0)
            {
                s[i] = 0;
                rv = s;
            }
            if (!newline && pos >= buf_size)
                mio->impl.mem.eof = true;
            mio->impl.mem.pos = pos;
            mio->impl.mem.size = buf_size;
        }
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_clearerr:
 * @mio: A #MIO object
 *
 * Clears the error and end-of-stream indicators of a #MIO stream. This function
 * behaves the same as clearerr().
 */
void mio_clearerr (MIO *mio)
{
    if (mio->type == MIO_TYPE_FILE)
        clearerr (mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        mio->impl.mem.error = false;
        mio->impl.mem.eof = false;
    }
    else
        AssertNotReached ();
}
 
/**
 * mio_eof:
 * @mio: A #MIO object
 *
 * Checks whether the end-of-stream indicator of a #MIO stream is set. This
 * function behaves the same as feof().
 *
 * Returns: A non-null value if the stream reached its end, 0 otherwise.
 */
int mio_eof (MIO *mio)
{
    if (mio->type == MIO_TYPE_FILE)
        return feof (mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
        return mio->impl.mem.eof != false;
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_error:
 * @mio: A #MIO object
 *
 * Checks whether the error indicator of a #MIO stream is set. This function
 * behaves the same as ferror().
 *
 * Returns: A non-null value if the stream have an error set, 0 otherwise.
 */
int mio_error (MIO *mio)
{
    if (mio->type == MIO_TYPE_FILE)
        return ferror (mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
        return mio->impl.mem.error != false;
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_seek:
 * @mio: A #MIO object
 * @offset: Offset of the new place, from @whence
 * @whence: Move origin. SEEK_SET moves relative to the start of the stream,
 *          SEEK_CUR from the current position and SEEK_SET from the end of the
 *          stream.
 *
 * Sets the cursor position on a #MIO stream. This functions behaves the same as
 * fseek(). See also mio_tell() and mio_setpos().
 *
 * Returns: 0 on success, -1 otherwise, in which case errno should be set to
 *          indicate the error.
 */
int mio_seek (MIO *mio, long offset, int whence)
{
    if (mio->type == MIO_TYPE_FILE)
        return fseek (mio->impl.file.fp, offset, whence);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        /* FIXME: should we support seeking out of bounds like lseek() seems to do? */
        int rv = -1;
 
        switch (whence)
        {
            case SEEK_SET:
                if (offset < 0 || (size_t)offset > mio->impl.mem.size)
                    errno = EINVAL;
                else
                {
                    mio->impl.mem.pos = (size_t)offset;
                    rv = 0;
                }
                break;
 
            case SEEK_CUR:
                if ((offset < 0 && (size_t)-offset > mio->impl.mem.pos) ||
                    mio->impl.mem.pos + (size_t)offset > mio->impl.mem.size)
                {
                    errno = EINVAL;
                }
                else
                {
                    mio->impl.mem.pos = (size_t)(mio->impl.mem.pos + offset);
                    rv = 0;
                }
                break;
 
            case SEEK_END:
                if (offset > 0 || (size_t)-offset > mio->impl.mem.size)
                    errno = EINVAL;
                else
                {
                    mio->impl.mem.pos = mio->impl.mem.size - (size_t)-offset;
                    rv = 0;
                }
                break;
 
            default:
                errno = EINVAL;
        }
        if (rv == 0)
        {
            mio->impl.mem.eof = false;
            mio->impl.mem.ungetch = EOF;
        }
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
 
}
 
/**
 * mio_tell:
 * @mio: A #MIO object
 *
 * Gets the current cursor position of a #MIO stream. This function behaves the
 * same as ftell().
 *
 * Returns: The current offset from the start of the stream, or -1 or error, in
 *          which case errno is set to indicate the error.
 */
long mio_tell (MIO *mio)
{
    if (mio->type == MIO_TYPE_FILE)
        return ftell (mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        long rv = -1;
 
        if (mio->impl.mem.pos > LONG_MAX)
        {
#ifdef EOVERFLOW
            errno = EOVERFLOW;
#endif
        }
        else
            rv = (long)mio->impl.mem.pos;
 
        return rv;
    }
    else
    {
        AssertNotReached ();
        return 0;
    }
}
 
/**
 * mio_rewind:
 * @mio: A #MIO object
 *
 * Resets the cursor position to 0, and also the end-of-stream and the error
 * indicators of a #MIO stream.
 * See also mio_seek() and mio_clearerr().
 */
void mio_rewind (MIO *mio)
{
    if (mio->type == MIO_TYPE_FILE)
        rewind (mio->impl.file.fp);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        mio->impl.mem.pos = 0;
        mio->impl.mem.ungetch = EOF;
        mio->impl.mem.eof = false;
        mio->impl.mem.error = false;
    }
    else
        AssertNotReached ();
}
 
/**
 * mio_getpos:
 * @mio: A #MIO stream
 * @pos: (out): A #MIOPos object to fill-in
 *
 * Stores the current position (and maybe other informations about the stream
 * state) of a #MIO stream in order to restore it later with mio_setpos(). This
 * function behaves the same as fgetpos().
 *
 * Returns: 0 on success, -1 otherwise, in which case errno is set to indicate
 *          the error.
 */
int mio_getpos (MIO *mio, MIOPos *pos)
{
    int rv = -1;
 
    pos->type = mio->type;
    if (mio->type == MIO_TYPE_FILE)
        rv = fgetpos (mio->impl.file.fp, &pos->impl.file);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        rv = -1;
 
        if (mio->impl.mem.pos == (size_t)-1)
        {
            /* this happens if ungetc() was called at the start of the stream */
#ifdef EIO
            errno = EIO;
#endif
        }
        else
        {
            pos->impl.mem = mio->impl.mem.pos;
            rv = 0;
        }
    }
    else
        AssertNotReached();
 
#ifdef MIO_DEBUG
    if (rv != -1)
    {
        pos->tag = mio;
    }
#endif /* MIO_DEBUG */
 
    return rv;
}
 
/**
 * mio_setpos:
 * @mio: A #MIO object
 * @pos: (in): A #MIOPos object filled-in by a previous call of mio_getpos() on
 *       the same stream
 *
 * Restores the position and state indicators of a #MIO stream previously saved
 * by mio_getpos().
 *
 * <warning><para>The #MIOPos object must have been initialized by a previous
 * call to mio_getpos() on the same stream.</para></warning>
 *
 * Returns: 0 on success, -1 otherwise, in which case errno is set to indicate
 *          the error.
 */
int mio_setpos (MIO *mio, MIOPos *pos)
{
    int rv = -1;
 
#ifdef MIO_DEBUG
    if (pos->tag != mio)
    {
        g_critical ("mio_setpos((MIO*)%p, (MIOPos*)%p): "
                    "Given MIOPos was not set by a previous call to mio_getpos() "
                    "on the same MIO object, which means there is a bug in "
                    "someone's code.",
                    (void *)mio, (void *)pos);
        errno = EINVAL;
        return -1;
    }
#endif /* MIO_DEBUG */
 
    if (mio->type == MIO_TYPE_FILE)
        rv = fsetpos (mio->impl.file.fp, &pos->impl.file);
    else if (mio->type == MIO_TYPE_MEMORY)
    {
        rv = -1;
 
        if (pos->impl.mem > mio->impl.mem.size)
            errno = EINVAL;
        else
        {
            mio->impl.mem.ungetch = EOF;
            mio->impl.mem.pos = pos->impl.mem;
            rv = 0;
        }
    }
    else
        AssertNotReached ();
 
    return rv;
}
 
/**
 * mio_flush:
 * @mio: A #MIO object
 *
 * Forces a write of all user-space buffered data for the given output or update
 * stream via the stream's underlying write function. Only applicable when using
 * FILE back-end.
 *
 * Returns: 0 on success, error code otherwise.
 */
int mio_flush (MIO *mio)
{
    if (mio->type == MIO_TYPE_FILE)
        return fflush (mio->impl.file.fp);
    return 0;
}
 
 
/**
 * mio_attach_user_data:
 * @mio: A #MIO object
 * @user_data: a pointer to any data object
 * @user_data_free_func: a call back function to destroy the data object passed as @user_data
 *
 * Attach any data object to a #MIO object. Attached data can be got with
 * mio_get_user_data(). The attached data is destroyed when new data is attached to
 * the #MIO object, or #the MIO object itself is destroyed. For destroying the data
 * @user_data_free_func is used.
 *
 */
 
void  mio_attach_user_data (MIO *mio, void *user_data, MIODestroyNotify user_data_free_func)
{
    if (mio->udata.d && mio->udata.f)
        mio->udata.f (mio->udata.d);
 
    mio->udata.d = user_data;
    mio->udata.f = user_data_free_func;
}
 
/**
 * mio_get_user_data:
 * @mio: A #MIO object
 *
 * Returns: user data attached with mio_attach_user_data() to a #MIO object.
 *
 */
void *mio_get_user_data (MIO *mio)
{
    return mio->udata.d;
}