/**
 * @file text_mmap.c
 *
 * Map a text file, ensuring the text always has an ending NUL byte.
 *
 * @addtogroup autoopts
 * @{
 */
/*
 *  This file is part of AutoOpts, a companion to AutoGen.
 *  AutoOpts is free software.
 *  AutoOpts is Copyright (C) 1992-2015 by Bruce Korb - all rights reserved
 *
 *  AutoOpts is available under any one of two licenses.  The license
 *  in use must be one of these two and the choice is under the control
 *  of the user of the license.
 *
 *   The GNU Lesser General Public License, version 3 or later
 *      See the files "COPYING.lgplv3" and "COPYING.gplv3"
 *
 *   The Modified Berkeley Software Distribution License
 *      See the file "COPYING.mbsd"
 *
 *  These files have the following sha256 sums:
 *
 *  8584710e9b04216a394078dc156b781d0b47e1729104d666658aecef8ee32e95  COPYING.gplv3
 *  4379e7444a0e2ce2b12dd6f5a52a27a4d02d39d247901d3285c88cf0d37f477b  COPYING.lgplv3
 *  13aa749a5b0a454917a944ed8fffc530b784f5ead522b1aacaf4ec8aa55a6239  COPYING.mbsd
 */
#if defined(HAVE_MMAP)
#  ifndef      MAP_ANONYMOUS
#    ifdef     MAP_ANON
#      define  MAP_ANONYMOUS   MAP_ANON
#    endif
#  endif

#  if ! defined(MAP_ANONYMOUS) && ! defined(HAVE_DEV_ZERO)
     /*
      * We must have either /dev/zero or anonymous mapping for
      * this to work.
      */
#    undef HAVE_MMAP

#  else
#    ifdef _SC_PAGESIZE
#      define GETPAGESIZE() sysconf(_SC_PAGESIZE)
#    else
#      define GETPAGESIZE() getpagesize()
#    endif
#  endif
#endif

/*
 *  Some weird systems require that a specifically invalid FD number
 *  get passed in as an argument value.  Which value is that?  Well,
 *  as everybody knows, if open(2) fails, it returns -1, so that must
 *  be the value.  :)
 */
#define AO_INVALID_FD  -1

#define FILE_WRITABLE(_prt,_flg) \
        (   (_prt & PROT_WRITE) \
         && ((_flg & (MAP_SHARED|MAP_PRIVATE)) == MAP_SHARED))
#define MAP_FAILED_PTR (VOIDP(MAP_FAILED))

/**
 * Load the contents of a text file.  There are two separate implementations,
 * depending up on whether mmap(3) is available.
 *
 *  If not available, malloc the file length plus one byte.  Read it in
 *  and NUL terminate.
 *
 *  If available, first check to see if the text file size is a multiple of a
 *  page size.  If it is, map the file size plus an extra page from either
 *  anonymous memory or from /dev/zero.  Then map the file text on top of the
 *  first pages of the anonymous/zero pages.  Otherwise, just map the file
 *  because there will be NUL bytes provided at the end.
 *
 * @param mapinfo a structure holding everything we need to know
 *        about the mapping.
 *
 * @param pzFile name of the file, for error reporting.
 */
static void
load_text_file(tmap_info_t * mapinfo, char const * pzFile)
{
#if ! defined(HAVE_MMAP)
    mapinfo->txt_data = AGALOC(mapinfo->txt_size+1, "file text");
    if (mapinfo->txt_data == NULL) {
        mapinfo->txt_errno = ENOMEM;
        return;
    }

    {
        size_t sz = mapinfo->txt_size;
        char * pz = mapinfo->txt_data;

        while (sz > 0) {
            ssize_t rdct = read(mapinfo->txt_fd, pz, sz);
            if (rdct <= 0) {
                mapinfo->txt_errno = errno;
                fserr_warn("libopts", "read", pzFile);
                free(mapinfo->txt_data);
                return;
            }

            pz += rdct;
            sz -= rdct;
        }

        *pz = NUL;
    }

    mapinfo->txt_errno   = 0;

#else /* HAVE mmap */
    size_t const pgsz = (size_t)GETPAGESIZE();
    void * map_addr   = NULL;

    (void)pzFile;

    mapinfo->txt_full_size = (mapinfo->txt_size + pgsz) & ~(pgsz - 1);
    if (mapinfo->txt_full_size == (mapinfo->txt_size + pgsz)) {
        /*
         * The text is a multiple of a page boundary.  We must map an
         * extra page so the text ends with a NUL.
         */
#if defined(MAP_ANONYMOUS)
        map_addr = mmap(NULL, mapinfo->txt_full_size, PROT_READ|PROT_WRITE,
                        MAP_ANONYMOUS|MAP_PRIVATE, AO_INVALID_FD, 0);
#else
        mapinfo->txt_zero_fd = open("/dev/zero", O_RDONLY);

        if (mapinfo->txt_zero_fd == AO_INVALID_FD) {
            mapinfo->txt_errno = errno;
            return;
        }
        map_addr = mmap(NULL, mapinfo->txt_full_size, PROT_READ|PROT_WRITE,
                        MAP_PRIVATE, mapinfo->txt_zero_fd, 0);
#endif
        if (map_addr == MAP_FAILED_PTR) {
            mapinfo->txt_errno = errno;
            return;
        }
        mapinfo->txt_flags |= MAP_FIXED;
    }

    mapinfo->txt_data =
        mmap(map_addr, mapinfo->txt_size, mapinfo->txt_prot,
             mapinfo->txt_flags, mapinfo->txt_fd, 0);

    if (mapinfo->txt_data == MAP_FAILED_PTR)
        mapinfo->txt_errno = errno;
#endif /* HAVE_MMAP */
}

/**
 * Make sure all the parameters are correct:  we have a file name that
 * is a text file that we can read.
 *
 * @param fname the text file to map
 * @param prot  the memory protections requested (read/write/etc.)
 * @param flags mmap flags
 * @param mapinfo a structure holding everything we need to know
 *        about the mapping.
 */
static void
validate_mmap(char const * fname, int prot, int flags, tmap_info_t * mapinfo)
{
    memset(mapinfo, 0, sizeof(*mapinfo));
#if defined(HAVE_MMAP) && ! defined(MAP_ANONYMOUS)
    mapinfo->txt_zero_fd = AO_INVALID_FD;
#endif
    mapinfo->txt_fd      = AO_INVALID_FD;
    mapinfo->txt_prot    = prot;
    mapinfo->txt_flags   = flags;

    /*
     *  Map mmap flags and protections into open flags and do the open.
     */
    {
        /*
         *  See if we will be updating the file.  If we can alter the memory
         *  and if we share the data and we are *not* copy-on-writing the data,
         *  then our updates will show in the file, so we must open with
         *  write access.
         */
        int o_flag = FILE_WRITABLE(prot, flags) ? O_RDWR : O_RDONLY;

        /*
         *  If you're not sharing the file and you are writing to it,
         *  then don't let anyone else have access to the file.
         */
        if (((flags & MAP_SHARED) == 0) && (prot & PROT_WRITE))
            o_flag |= O_EXCL;

        mapinfo->txt_fd = open(fname, o_flag);
        if (mapinfo->txt_fd < 0) {
            mapinfo->txt_errno = errno;
            mapinfo->txt_fd = AO_INVALID_FD;
            return;
        }
    }

    /*
     *  Make sure we can stat the regular file.  Save the file size.
     */
    {
        struct stat sb;
        if (fstat(mapinfo->txt_fd, &sb) != 0) {
            mapinfo->txt_errno = errno;
            close(mapinfo->txt_fd);
            return;
        }

        if (! S_ISREG(sb.st_mode)) {
            mapinfo->txt_errno = errno = EINVAL;
            close(mapinfo->txt_fd);
            return;
        }

        mapinfo->txt_size = (size_t)sb.st_size;
    }

    if (mapinfo->txt_fd == AO_INVALID_FD)
        mapinfo->txt_errno = errno;
}

/**
 * Close any files opened by the mapping.
 *
 * @param mi a structure holding everything we need to know about the map.
 */
static void
close_mmap_files(tmap_info_t * mi)
{
    if (mi->txt_fd == AO_INVALID_FD)
        return;

    close(mi->txt_fd);
    mi->txt_fd = AO_INVALID_FD;

#if defined(HAVE_MMAP) && ! defined(MAP_ANONYMOUS)
    if (mi->txt_zero_fd == AO_INVALID_FD)
        return;

    close(mi->txt_zero_fd);
    mi->txt_zero_fd = AO_INVALID_FD;
#endif
}

/*=export_func  text_mmap
 * private:
 *
 * what:  map a text file with terminating NUL
 *
 * arg:   char const *,  pzFile,  name of the file to map
 * arg:   int,           prot,    mmap protections (see mmap(2))
 * arg:   int,           flags,   mmap flags (see mmap(2))
 * arg:   tmap_info_t *, mapinfo, returned info about the mapping
 *
 * ret-type:   void *
 * ret-desc:   The mmaped data address
 *
 * doc:
 *
 * This routine will mmap a file into memory ensuring that there is at least
 * one @file{NUL} character following the file data.  It will return the
 * address where the file contents have been mapped into memory.  If there is a
 * problem, then it will return @code{MAP_FAILED} and set @code{errno}
 * appropriately.
 *
 * The named file does not exist, @code{stat(2)} will set @code{errno} as it
 * will.  If the file is not a regular file, @code{errno} will be
 * @code{EINVAL}.  At that point, @code{open(2)} is attempted with the access
 * bits set appropriately for the requested @code{mmap(2)} protections and flag
 * bits.  On failure, @code{errno} will be set according to the documentation
 * for @code{open(2)}.  If @code{mmap(2)} fails, @code{errno} will be set as
 * that routine sets it.  If @code{text_mmap} works to this point, a valid
 * address will be returned, but there may still be ``issues''.
 *
 * If the file size is not an even multiple of the system page size, then
 * @code{text_map} will return at this point and @code{errno} will be zero.
 * Otherwise, an anonymous map is attempted.  If not available, then an attempt
 * is made to @code{mmap(2)} @file{/dev/zero}.  If any of these fail, the
 * address of the file's data is returned, bug @code{no} @file{NUL} characters
 * are mapped after the end of the data.
 *
 * see: mmap(2), open(2), stat(2)
 *
 * err: Any error code issued by mmap(2), open(2), stat(2) is possible.
 *      Additionally, if the specified file is not a regular file, then
 *      errno will be set to @code{EINVAL}.
 *
 * example:
 * #include <mylib.h>
 * tmap_info_t mi;
 * int no_nul;
 * void * data = text_mmap("file", PROT_WRITE, MAP_PRIVATE, &mi);
 * if (data == MAP_FAILED) return;
 * no_nul = (mi.txt_size == mi.txt_full_size);
 * << use the data >>
 * text_munmap(&mi);
=*/
void *
text_mmap(char const * pzFile, int prot, int flags, tmap_info_t * mi)
{
    validate_mmap(pzFile, prot, flags, mi);
    if (mi->txt_errno != 0)
        return MAP_FAILED_PTR;

    load_text_file(mi, pzFile);

    if (mi->txt_errno == 0)
        return mi->txt_data;

    close_mmap_files(mi);

    errno = mi->txt_errno;
    mi->txt_data = MAP_FAILED_PTR;
    return mi->txt_data;
}


/*=export_func  text_munmap
 * private:
 *
 * what:  unmap the data mapped in by text_mmap
 *
 * arg:   tmap_info_t *, mapinfo, info about the mapping
 *
 * ret-type:   int
 * ret-desc:   -1 or 0.  @code{errno} will have the error code.
 *
 * doc:
 *
 * This routine will unmap the data mapped in with @code{text_mmap} and close
 * the associated file descriptors opened by that function.
 *
 * see: munmap(2), close(2)
 *
 * err: Any error code issued by munmap(2) or close(2) is possible.
=*/
int
text_munmap(tmap_info_t * mi)
{
    errno = 0;

#ifdef HAVE_MMAP
    (void)munmap(mi->txt_data, mi->txt_full_size);

#else  /* don't HAVE_MMAP */
    /*
     *  IF the memory is writable *AND* it is not private (copy-on-write)
     *     *AND* the memory is "sharable" (seen by other processes)
     *  THEN rewrite the data.  Emulate mmap visibility.
     */
    if (   FILE_WRITABLE(mi->txt_prot, mi->txt_flags)
        && (lseek(mi->txt_fd, 0, SEEK_SET) >= 0) ) {
        write(mi->txt_fd, mi->txt_data, mi->txt_size);
    }

    free(mi->txt_data);
#endif /* HAVE_MMAP */

    mi->txt_errno = errno;
    close_mmap_files(mi);

    return mi->txt_errno;
}

/** @}
 *
 * Local Variables:
 * mode: C
 * c-file-style: "stroustrup"
 * indent-tabs-mode: nil
 * End:
 * end of autoopts/text_mmap.c */