src/libopts/text_mmap.c

   1 /**
   2  * @file text_mmap.c
   3  *
   4  * Map a text file, ensuring the text always has an ending NUL byte.
   5  *
   6  * Time-stamp:      "2012-01-29 09:40:21 bkorb"
   7  *
   8  *  This file is part of AutoOpts, a companion to AutoGen.
   9  *  AutoOpts is free software.
  10  *  AutoOpts is Copyright (c) 1992-2012 by Bruce Korb - all rights reserved
  11  *
  12  *  AutoOpts is available under any one of two licenses.  The license
  13  *  in use must be one of these two and the choice is under the control
  14  *  of the user of the license.
  15  *
  16  *   The GNU Lesser General Public License, version 3 or later
  17  *      See the files "COPYING.lgplv3" and "COPYING.gplv3"
  18  *
  19  *   The Modified Berkeley Software Distribution License
  20  *      See the file "COPYING.mbsd"
  21  *
  22  *  These files have the following md5sums:
  23  *
  24  *  43b91e8ca915626ed3818ffb1b71248b pkg/libopts/COPYING.gplv3
  25  *  06a1a2e4760c90ea5e1dad8dfaac4d39 pkg/libopts/COPYING.lgplv3
  26  *  66a5cedaf62c4b2637025f049f9b826f pkg/libopts/COPYING.mbsd
  27  */
  28 #if defined(HAVE_MMAP)
  29 #  ifndef      MAP_ANONYMOUS
  30 #    ifdef     MAP_ANON
  31 #      define  MAP_ANONYMOUS   MAP_ANON
  32 #    endif
  33 #  endif
  34
  35 #  if ! defined(MAP_ANONYMOUS) && ! defined(HAVE_DEV_ZERO)
  36      /*
  37       * We must have either /dev/zero or anonymous mapping for
  38       * this to work.
  39       */
  40 #    undef HAVE_MMAP
  41
  42 #  else
  43 #    ifdef _SC_PAGESIZE
  44 #      define GETPAGESIZE() sysconf(_SC_PAGESIZE)
  45 #    else
  46 #      define GETPAGESIZE() getpagesize()
  47 #    endif
  48 #  endif
  49 #endif
  50
  51 /*
  52  *  Some weird systems require that a specifically invalid FD number
  53  *  get passed in as an argument value.  Which value is that?  Well,
  54  *  as everybody knows, if open(2) fails, it returns -1, so that must
  55  *  be the value.  :)
  56  */
  57 #define AO_INVALID_FD  -1
  58
  59 #define FILE_WRITABLE(_prt,_flg) \
  60         (   (_prt & PROT_WRITE) \
  61          && ((_flg & (MAP_SHARED|MAP_PRIVATE)) == MAP_SHARED))
  62 #define MAP_FAILED_PTR ((void*)MAP_FAILED)
  63
  64 /**
  65  * Load the contents of a text file.  There are two separate implementations,
  66  * depending up on whether mmap(3) is available.
  67  *
  68  *  If not available, malloc the file length plus one byte.  Read it in
  69  *  and NUL terminate.
  70  *
  71  *  If available, first check to see if the text file size is a multiple of a
  72  *  page size.  If it is, map the file size plus an extra page from either
  73  *  anonymous memory or from /dev/zero.  Then map the file text on top of the
  74  *  first pages of the anonymous/zero pages.  Otherwise, just map the file
  75  *  because there will be NUL bytes provided at the end.
  76  *
  77  * @param mapinfo a structure holding everything we need to know
  78  *        about the mapping.
  79  *
  80  * @param pzFile name of the file, for error reporting.
  81  */
  82 static void
  83 load_text_file(tmap_info_t * mapinfo, char const * pzFile)
  84 {
  85 #if ! defined(HAVE_MMAP)
  86     mapinfo->txt_data = AGALOC(mapinfo->txt_size+1, "file text");
  87     if (mapinfo->txt_data == NULL) {
  88         mapinfo->txt_errno = ENOMEM;
  89         return;
  90     }
  91
  92     {
  93         size_t sz = mapinfo->txt_size;
  94         char*  pz = mapinfo->txt_data;
  95
  96         while (sz > 0) {
  97             ssize_t rdct = read(mapinfo->txt_fd, pz, sz);
  98             if (rdct <= 0) {
  99                 mapinfo->txt_errno = errno;
 100                 fprintf(stderr, zFSErrReadFile,
 101                         errno, strerror(errno), pzFile);
 102                 free(mapinfo->txt_data);
 103                 return;
 104             }
 105
 106             pz += rdct;
 107             sz -= rdct;
 108         }
 109
 110         *pz = NUL;
 111     }
 112
 113     mapinfo->txt_errno   = 0;
 114
 115 #else /* HAVE mmap */
 116     size_t const pgsz = GETPAGESIZE();
 117     void * map_addr   = NULL;
 118
 119     (void)pzFile;
 120
 121     mapinfo->txt_full_size = (mapinfo->txt_size + pgsz) & ~(pgsz - 1);
 122     if (mapinfo->txt_full_size == (mapinfo->txt_size + pgsz)) {
 123         /*
 124          * The text is a multiple of a page boundary.  We must map an
 125          * extra page so the text ends with a NUL.
 126          */
 127 #if defined(MAP_ANONYMOUS)
 128         map_addr = mmap(NULL, mapinfo->txt_full_size, PROT_READ|PROT_WRITE,
 129                         MAP_ANONYMOUS|MAP_PRIVATE, AO_INVALID_FD, 0);
 130 #else
 131         mapinfo->txt_zero_fd = open("/dev/zero", O_RDONLY);
 132
 133         if (mapinfo->txt_zero_fd == AO_INVALID_FD) {
 134             mapinfo->txt_errno = errno;
 135             return;
 136         }
 137         map_addr = mmap(NULL, mapinfo->txt_full_size, PROT_READ|PROT_WRITE,
 138                         MAP_PRIVATE, mapinfo->txt_zero_fd, 0);
 139 #endif
 140         if (map_addr == MAP_FAILED_PTR) {
 141             mapinfo->txt_errno = errno;
 142             return;
 143         }
 144         mapinfo->txt_flags |= MAP_FIXED;
 145     }
 146
 147     mapinfo->txt_data =
 148         mmap(map_addr, mapinfo->txt_size, mapinfo->txt_prot,
 149              mapinfo->txt_flags, mapinfo->txt_fd, 0);
 150
 151     if (mapinfo->txt_data == MAP_FAILED_PTR)
 152         mapinfo->txt_errno = errno;
 153 #endif /* HAVE_MMAP */
 154 }
 155
 156 /**
 157  * Make sure all the parameters are correct:  we have a file name that
 158  * is a text file that we can read.
 159  *
 160  * @param fname the text file to map
 161  * @param prot  the memory protections requested (read/write/etc.)
 162  * @param flags mmap flags
 163  * @param mapinfo a structure holding everything we need to know
 164  *        about the mapping.
 165  */
 166 static void
 167 validate_mmap(char const * fname, int prot, int flags, tmap_info_t * mapinfo)
 168 {
 169     memset(mapinfo, 0, sizeof(*mapinfo));
 170 #if defined(HAVE_MMAP) && ! defined(MAP_ANONYMOUS)
 171     mapinfo->txt_zero_fd = AO_INVALID_FD;
 172 #endif
 173     mapinfo->txt_fd      = AO_INVALID_FD;
 174     mapinfo->txt_prot    = prot;
 175     mapinfo->txt_flags   = flags;
 176
 177     /*
 178      *  Make sure we can stat the regular file.  Save the file size.
 179      */
 180     {
 181         struct stat sb;
 182         if (stat(fname, &sb) != 0) {
 183             mapinfo->txt_errno = errno;
 184             return;
 185         }
 186
 187         if (! S_ISREG(sb.st_mode)) {
 188             mapinfo->txt_errno = errno = EINVAL;
 189             return;
 190         }
 191
 192         mapinfo->txt_size = sb.st_size;
 193     }
 194
 195     /*
 196      *  Map mmap flags and protections into open flags and do the open.
 197      */
 198     {
 199         /*
 200          *  See if we will be updating the file.  If we can alter the memory
 201          *  and if we share the data and we are *not* copy-on-writing the data,
 202          *  then our updates will show in the file, so we must open with
 203          *  write access.
 204          */
 205         int o_flag = FILE_WRITABLE(prot, flags) ? O_RDWR : O_RDONLY;
 206
 207         /*
 208          *  If you're not sharing the file and you are writing to it,
 209          *  then don't let anyone else have access to the file.
 210          */
 211         if (((flags & MAP_SHARED) == 0) && (prot & PROT_WRITE))
 212             o_flag |= O_EXCL;
 213
 214         mapinfo->txt_fd = open(fname, o_flag);
 215     }
 216
 217     if (mapinfo->txt_fd == AO_INVALID_FD)
 218         mapinfo->txt_errno = errno;
 219 }
 220
 221 /**
 222  * Close any files opened by the mapping.
 223  *
 224  * @param mi a structure holding everything we need to know about the map.
 225  */
 226 static void
 227 close_mmap_files(tmap_info_t * mi)
 228 {
 229     if (mi->txt_fd == AO_INVALID_FD)
 230         return;
 231
 232     close(mi->txt_fd);
 233     mi->txt_fd = AO_INVALID_FD;
 234
 235 #if ! defined(MAP_ANONYMOUS)
 236     if (mi->txt_zero_fd == AO_INVALID_FD)
 237         return;
 238
 239     close(mi->txt_zero_fd);
 240     mi->txt_zero_fd = AO_INVALID_FD;
 241 #endif
 242 }
 243
 244 /*=export_func  text_mmap
 245  * private:
 246  *
 247  * what:  map a text file with terminating NUL
 248  *
 249  * arg:   char const*,  pzFile,  name of the file to map
 250  * arg:   int,          prot,    mmap protections (see mmap(2))
 251  * arg:   int,          flags,   mmap flags (see mmap(2))
 252  * arg:   tmap_info_t*, mapinfo, returned info about the mapping
 253  *
 254  * ret-type:   void*
 255  * ret-desc:   The mmaped data address
 256  *
 257  * doc:
 258  *
 259  * This routine will mmap a file into memory ensuring that there is at least
 260  * one @file{NUL} character following the file data.  It will return the
 261  * address where the file contents have been mapped into memory.  If there is a
 262  * problem, then it will return @code{MAP_FAILED} and set @code{errno}
 263  * appropriately.
 264  *
 265  * The named file does not exist, @code{stat(2)} will set @code{errno} as it
 266  * will.  If the file is not a regular file, @code{errno} will be
 267  * @code{EINVAL}.  At that point, @code{open(2)} is attempted with the access
 268  * bits set appropriately for the requested @code{mmap(2)} protections and flag
 269  * bits.  On failure, @code{errno} will be set according to the documentation
 270  * for @code{open(2)}.  If @code{mmap(2)} fails, @code{errno} will be set as
 271  * that routine sets it.  If @code{text_mmap} works to this point, a valid
 272  * address will be returned, but there may still be ``issues''.
 273  *
 274  * If the file size is not an even multiple of the system page size, then
 275  * @code{text_map} will return at this point and @code{errno} will be zero.
 276  * Otherwise, an anonymous map is attempted.  If not available, then an attempt
 277  * is made to @code{mmap(2)} @file{/dev/zero}.  If any of these fail, the
 278  * address of the file's data is returned, bug @code{no} @file{NUL} characters
 279  * are mapped after the end of the data.
 280  *
 281  * see: mmap(2), open(2), stat(2)
 282  *
 283  * err: Any error code issued by mmap(2), open(2), stat(2) is possible.
 284  *      Additionally, if the specified file is not a regular file, then
 285  *      errno will be set to @code{EINVAL}.
 286  *
 287  * example:
 288  * #include <mylib.h>
 289  * tmap_info_t mi;
 290  * int no_nul;
 291  * void* data = text_mmap("file", PROT_WRITE, MAP_PRIVATE, &mi);
 292  * if (data == MAP_FAILED) return;
 293  * no_nul = (mi.txt_size == mi.txt_full_size);
 294  * << use the data >>
 295  * text_munmap(&mi);
 296 =*/
 297 void *
 298 text_mmap(char const * pzFile, int prot, int flags, tmap_info_t * mi)
 299 {
 300     validate_mmap(pzFile, prot, flags, mi);
 301     if (mi->txt_errno != 0)
 302         return MAP_FAILED_PTR;
 303
 304     load_text_file(mi, pzFile);
 305
 306     if (mi->txt_errno == 0)
 307         return mi->txt_data;
 308
 309     close_mmap_files(mi);
 310
 311     errno = mi->txt_errno;
 312     mi->txt_data = MAP_FAILED_PTR;
 313     return mi->txt_data;
 314 }
 315
 316
 317 /*=export_func  text_munmap
 318  * private:
 319  *
 320  * what:  unmap the data mapped in by text_mmap
 321  *
 322  * arg:   tmap_info_t*, mapinfo, info about the mapping
 323  *
 324  * ret-type:   int
 325  * ret-desc:   -1 or 0.  @code{errno} will have the error code.
 326  *
 327  * doc:
 328  *
 329  * This routine will unmap the data mapped in with @code{text_mmap} and close
 330  * the associated file descriptors opened by that function.
 331  *
 332  * see: munmap(2), close(2)
 333  *
 334  * err: Any error code issued by munmap(2) or close(2) is possible.
 335 =*/
 336 int
 337 text_munmap(tmap_info_t * mi)
 338 {
 339     errno = 0;
 340
 341 #ifdef HAVE_MMAP
 342     (void)munmap(mi->txt_data, mi->txt_full_size);
 343
 344 #else  /* don't HAVE_MMAP */
 345     /*
 346      *  IF the memory is writable *AND* it is not private (copy-on-write)
 347      *     *AND* the memory is "sharable" (seen by other processes)
 348      *  THEN rewrite the data.  Emulate mmap visibility.
 349      */
 350     if (   FILE_WRITABLE(mi->txt_prot, mi->txt_flags)
 351         && (lseek(mi->txt_fd, 0, SEEK_SET) >= 0) ) {
 352         write(mi->txt_fd, mi->txt_data, mi->txt_size);
 353     }
 354
 355     free(mi->txt_data);
 356 #endif /* HAVE_MMAP */
 357
 358     mi->txt_errno = errno;
 359     close_mmap_files(mi);
 360
 361     return mi->txt_errno;
 362 }
 363
 364 /*
 365  * Local Variables:
 366  * mode: C
 367  * c-file-style: "stroustrup"
 368  * indent-tabs-mode: nil
 369  * End:
 370  * end of autoopts/text_mmap.c */