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