/**

 * @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 */