glib/gmappedfile.c

   1 /* GLIB - Library of useful routines for C programming
   2  * gmappedfile.c: Simplified wrapper around the mmap() function.
   3  *
   4  * Copyright 2005 Matthias Clasen
   5  *
   6  * SPDX-License-Identifier: LGPL-2.1-or-later
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 #include "config.h"
  23
  24 #include <errno.h>
  25 #include <sys/types.h>
  26 #include <sys/stat.h>
  27 #include <fcntl.h>
  28 #ifdef HAVE_MMAP
  29 #include <sys/mman.h>
  30 #endif
  31
  32 #include "glibconfig.h"
  33
  34 #ifdef G_OS_UNIX
  35 #include <unistd.h>
  36 #endif
  37
  38 #ifdef G_OS_WIN32
  39 #include <windows.h>
  40 #include <io.h>
  41
  42 #undef fstat
  43 #define fstat(a,b) _fstati64(a,b)
  44 #undef stat
  45 #define stat _stati64
  46
  47 #ifndef S_ISREG
  48 #define S_ISREG(m) (((m) & _S_IFMT) == _S_IFREG)
  49 #endif
  50
  51 #endif
  52
  53 #ifndef O_CLOEXEC
  54 #define O_CLOEXEC 0
  55 #endif
  56
  57 #include "gconvert.h"
  58 #include "gerror.h"
  59 #include "gfileutils.h"
  60 #include "gmappedfile.h"
  61 #include "gmem.h"
  62 #include "gmessages.h"
  63 #include "gstdio.h"
  64 #include "gstrfuncs.h"
  65 #include "gatomic.h"
  66
  67 #include "glibintl.h"
  68
  69
  70 #ifndef _O_BINARY
  71 #define _O_BINARY 0
  72 #endif
  73
  74 #ifndef MAP_FAILED
  75 #define MAP_FAILED ((void *) -1)
  76 #endif
  77
  78 /**
  79  * GMappedFile:
  80  *
  81  * The #GMappedFile represents a file mapping created with
  82  * g_mapped_file_new(). It has only private members and should
  83  * not be accessed directly.
  84  */
  85
  86 struct _GMappedFile
  87 {
  88   gchar *contents;
  89   gsize  length;
  90   gpointer free_func;
  91   int    ref_count;
  92 #ifdef G_OS_WIN32
  93   HANDLE mapping;
  94 #endif
  95 };
  96
  97 static void
  98 g_mapped_file_destroy (GMappedFile *file)
  99 {
 100   if (file->length)
 101     {
 102 #ifdef HAVE_MMAP
 103       munmap (file->contents, file->length);
 104 #endif
 105 #ifdef G_OS_WIN32
 106       UnmapViewOfFile (file->contents);
 107       CloseHandle (file->mapping);
 108 #endif
 109     }
 110
 111   g_slice_free (GMappedFile, file);
 112 }
 113
 114 static GMappedFile*
 115 mapped_file_new_from_fd (int           fd,
 116                          gboolean      writable,
 117                          const gchar  *filename,
 118                          GError      **error)
 119 {
 120   GMappedFile *file;
 121   struct stat st;
 122
 123   file = g_slice_new0 (GMappedFile);
 124   file->ref_count = 1;
 125   file->free_func = g_mapped_file_destroy;
 126
 127   if (fstat (fd, &st) == -1)
 128     {
 129       int save_errno = errno;
 130       gchar *display_filename = filename ? g_filename_display_name (filename) : NULL;
 131
 132       g_set_error (error,
 133                    G_FILE_ERROR,
 134                    g_file_error_from_errno (save_errno),
 135                    _("Failed to get attributes of file “%s%s%s%s”: fstat() failed: %s"),
 136                    display_filename ? display_filename : "fd",
 137                    display_filename ? "' " : "",
 138                    display_filename ? display_filename : "",
 139                    display_filename ? "'" : "",
 140                    g_strerror (save_errno));
 141       g_free (display_filename);
 142       goto out;
 143     }
 144
 145   /* mmap() on size 0 will fail with EINVAL, so we avoid calling mmap()
 146    * in that case -- but only if we have a regular file; we still want
 147    * attempts to mmap a character device to fail, for example.
 148    */
 149   if (st.st_size == 0 && S_ISREG (st.st_mode))
 150     {
 151       file->length = 0;
 152       file->contents = NULL;
 153       return file;
 154     }
 155
 156   file->contents = MAP_FAILED;
 157
 158 #ifdef HAVE_MMAP
 159   if (sizeof (st.st_size) > sizeof (gsize) && st.st_size > (off_t) G_MAXSIZE)
 160     {
 161       errno = EINVAL;
 162     }
 163   else
 164     {
 165       file->length = (gsize) st.st_size;
 166       file->contents = (gchar *) mmap (NULL,  file->length,
 167                                        writable ? PROT_READ|PROT_WRITE : PROT_READ,
 168                                        MAP_PRIVATE, fd, 0);
 169     }
 170 #endif
 171 #ifdef G_OS_WIN32
 172   file->length = st.st_size;
 173   file->mapping = CreateFileMapping ((HANDLE) _get_osfhandle (fd), NULL,
 174                                      writable ? PAGE_WRITECOPY : PAGE_READONLY,
 175                                      0, 0,
 176                                      NULL);
 177   if (file->mapping != NULL)
 178     {
 179       file->contents = MapViewOfFile (file->mapping,
 180                                       writable ? FILE_MAP_COPY : FILE_MAP_READ,
 181                                       0, 0,
 182                                       0);
 183       if (file->contents == NULL)
 184         {
 185           file->contents = MAP_FAILED;
 186           CloseHandle (file->mapping);
 187           file->mapping = NULL;
 188         }
 189     }
 190 #endif
 191
 192
 193   if (file->contents == MAP_FAILED)
 194     {
 195       int save_errno = errno;
 196       gchar *display_filename = filename ? g_filename_display_name (filename) : NULL;
 197
 198       g_set_error (error,
 199                    G_FILE_ERROR,
 200                    g_file_error_from_errno (save_errno),
 201                    _("Failed to map %s%s%s%s: mmap() failed: %s"),
 202                    display_filename ? display_filename : "fd",
 203                    display_filename ? "' " : "",
 204                    display_filename ? display_filename : "",
 205                    display_filename ? "'" : "",
 206                    g_strerror (save_errno));
 207       g_free (display_filename);
 208       goto out;
 209     }
 210
 211   return file;
 212
 213  out:
 214   g_slice_free (GMappedFile, file);
 215
 216   return NULL;
 217 }
 218
 219 /**
 220  * g_mapped_file_new:
 221  * @filename: (type filename): The path of the file to load, in the GLib
 222  *     filename encoding
 223  * @writable: whether the mapping should be writable
 224  * @error: return location for a #GError, or %NULL
 225  *
 226  * Maps a file into memory. On UNIX, this is using the mmap() function.
 227  *
 228  * If @writable is %TRUE, the mapped buffer may be modified, otherwise
 229  * it is an error to modify the mapped buffer. Modifications to the buffer
 230  * are not visible to other processes mapping the same file, and are not
 231  * written back to the file.
 232  *
 233  * Note that modifications of the underlying file might affect the contents
 234  * of the #GMappedFile. Therefore, mapping should only be used if the file
 235  * will not be modified, or if all modifications of the file are done
 236  * atomically (e.g. using g_file_set_contents()).
 237  *
 238  * If @filename is the name of an empty, regular file, the function
 239  * will successfully return an empty #GMappedFile. In other cases of
 240  * size 0 (e.g. device files such as /dev/null), @error will be set
 241  * to the #GFileError value %G_FILE_ERROR_INVAL.
 242  *
 243  * Returns: a newly allocated #GMappedFile which must be unref'd
 244  *    with g_mapped_file_unref(), or %NULL if the mapping failed.
 245  *
 246  * Since: 2.8
 247  */
 248 GMappedFile *
 249 g_mapped_file_new (const gchar  *filename,
 250                    gboolean      writable,
 251                    GError      **error)
 252 {
 253   GMappedFile *file;
 254   int fd;
 255
 256   g_return_val_if_fail (filename != NULL, NULL);
 257   g_return_val_if_fail (!error || *error == NULL, NULL);
 258
 259   fd = g_open (filename, (writable ? O_RDWR : O_RDONLY) | _O_BINARY | O_CLOEXEC, 0);
 260   if (fd == -1)
 261     {
 262       int save_errno = errno;
 263       gchar *display_filename = g_filename_display_name (filename);
 264
 265       g_set_error (error,
 266                    G_FILE_ERROR,
 267                    g_file_error_from_errno (save_errno),
 268                    _("Failed to open file “%s”: open() failed: %s"),
 269                    display_filename,
 270                    g_strerror (save_errno));
 271       g_free (display_filename);
 272       return NULL;
 273     }
 274
 275   file = mapped_file_new_from_fd (fd, writable, filename, error);
 276
 277   close (fd);
 278
 279   return file;
 280 }
 281
 282
 283 /**
 284  * g_mapped_file_new_from_fd:
 285  * @fd: The file descriptor of the file to load
 286  * @writable: whether the mapping should be writable
 287  * @error: return location for a #GError, or %NULL
 288  *
 289  * Maps a file into memory. On UNIX, this is using the mmap() function.
 290  *
 291  * If @writable is %TRUE, the mapped buffer may be modified, otherwise
 292  * it is an error to modify the mapped buffer. Modifications to the buffer
 293  * are not visible to other processes mapping the same file, and are not
 294  * written back to the file.
 295  *
 296  * Note that modifications of the underlying file might affect the contents
 297  * of the #GMappedFile. Therefore, mapping should only be used if the file
 298  * will not be modified, or if all modifications of the file are done
 299  * atomically (e.g. using g_file_set_contents()).
 300  *
 301  * Returns: a newly allocated #GMappedFile which must be unref'd
 302  *    with g_mapped_file_unref(), or %NULL if the mapping failed.
 303  *
 304  * Since: 2.32
 305  */
 306 GMappedFile *
 307 g_mapped_file_new_from_fd (gint          fd,
 308                            gboolean      writable,
 309                            GError      **error)
 310 {
 311   return mapped_file_new_from_fd (fd, writable, NULL, error);
 312 }
 313
 314 /**
 315  * g_mapped_file_get_length:
 316  * @file: a #GMappedFile
 317  *
 318  * Returns the length of the contents of a #GMappedFile.
 319  *
 320  * Returns: the length of the contents of @file.
 321  *
 322  * Since: 2.8
 323  */
 324 gsize
 325 g_mapped_file_get_length (GMappedFile *file)
 326 {
 327   g_return_val_if_fail (file != NULL, 0);
 328
 329   return file->length;
 330 }
 331
 332 /**
 333  * g_mapped_file_get_contents:
 334  * @file: a #GMappedFile
 335  *
 336  * Returns the contents of a #GMappedFile.
 337  *
 338  * Note that the contents may not be zero-terminated,
 339  * even if the #GMappedFile is backed by a text file.
 340  *
 341  * If the file is empty then %NULL is returned.
 342  *
 343  * Returns: the contents of @file, or %NULL.
 344  *
 345  * Since: 2.8
 346  */
 347 gchar *
 348 g_mapped_file_get_contents (GMappedFile *file)
 349 {
 350   g_return_val_if_fail (file != NULL, NULL);
 351
 352   return file->contents;
 353 }
 354
 355 /**
 356  * g_mapped_file_free:
 357  * @file: a #GMappedFile
 358  *
 359  * This call existed before #GMappedFile had refcounting and is currently
 360  * exactly the same as g_mapped_file_unref().
 361  *
 362  * Since: 2.8
 363  * Deprecated:2.22: Use g_mapped_file_unref() instead.
 364  */
 365 void
 366 g_mapped_file_free (GMappedFile *file)
 367 {
 368   g_mapped_file_unref (file);
 369 }
 370
 371 /**
 372  * g_mapped_file_ref:
 373  * @file: a #GMappedFile
 374  *
 375  * Increments the reference count of @file by one.  It is safe to call
 376  * this function from any thread.
 377  *
 378  * Returns: the passed in #GMappedFile.
 379  *
 380  * Since: 2.22
 381  **/
 382 GMappedFile *
 383 g_mapped_file_ref (GMappedFile *file)
 384 {
 385   g_return_val_if_fail (file != NULL, NULL);
 386
 387   g_atomic_int_inc (&file->ref_count);
 388
 389   return file;
 390 }
 391
 392 /**
 393  * g_mapped_file_unref:
 394  * @file: a #GMappedFile
 395  *
 396  * Decrements the reference count of @file by one.  If the reference count
 397  * drops to 0, unmaps the buffer of @file and frees it.
 398  *
 399  * It is safe to call this function from any thread.
 400  *
 401  * Since 2.22
 402  **/
 403 void
 404 g_mapped_file_unref (GMappedFile *file)
 405 {
 406   g_return_if_fail (file != NULL);
 407
 408   if (g_atomic_int_dec_and_test (&file->ref_count))
 409     g_mapped_file_destroy (file);
 410 }
 411
 412 /**
 413  * g_mapped_file_get_bytes:
 414  * @file: a #GMappedFile
 415  *
 416  * Creates a new #GBytes which references the data mapped from @file.
 417  * The mapped contents of the file must not be modified after creating this
 418  * bytes object, because a #GBytes should be immutable.
 419  *
 420  * Returns: (transfer full): A newly allocated #GBytes referencing data
 421  *     from @file
 422  *
 423  * Since: 2.34
 424  **/
 425 GBytes *
 426 g_mapped_file_get_bytes (GMappedFile *file)
 427 {
 428   g_return_val_if_fail (file != NULL, NULL);
 429
 430   return g_bytes_new_with_free_func (file->contents,
 431                                      file->length,
 432                                      (GDestroyNotify) g_mapped_file_unref,
 433                                      g_mapped_file_ref (file));
 434 }