src/include/eina_mmap.h

   1 #ifndef EINA_MMAP_H_
   2 #define EINA_MMAP_H_
   3
   4 /**
   5  * @addtogroup Eina_Mmap_Group Mmap Group
   6  *
   7  * @brief These functions provide helpers for safe mmap handling
   8  *
   9  * @{
  10  *
  11  * @since 1.1.0
  12  */
  13
  14 /**
  15  * @brief Enable or disable safe mmaped IO handling
  16  *
  17  * @param enabled The enabled state (to enable, pass #EINA_TRUE)
  18  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
  19  *
  20  * This enables (if possible on your platform) a signal handler for
  21  * SIGBUS, that replaces the "bad page" with a page of 0's (from /dev/zero)
  22  * if a SIGBUS occurs. This allows for safe mmap() of files that may truncate
  23  * or from files on devices with IO errors. Normally these cases will result
  24  * in a SIGBUS being delivered (and termination of your process), but
  25  * when "mmap safety" is enabled, this will not occur. Instead a page of
  26  * bytes of the value 0 will replace the "bad page", allowing the process
  27  * to continue and allow its own parsing error detection to safely abort
  28  * the operation without the process falling apart.
  29  *
  30  * If you disable mmap safety, the SIGBUS handler will be restored to its
  31  * default handler. Note that eina_file_map_all() and eina_file_map_new()
  32  * will automatically enable mmap safety as they provide an mmaped file IO
  33  * layer, and rely on mmap to not fail for any part of the file.
  34  *
  35  * If you set up your own SIGBUS handler, then this will effectively disable
  36  * the safe mmap handling and make you liable to crashes on IO to or from
  37  * such "damaged files" that would take down your process.
  38  *
  39  * @since 1.1.0
  40  */
  41 EAPI Eina_Bool
  42 eina_mmap_safety_enabled_set(Eina_Bool enabled);
  43
  44 /**
  45  * @brief Get the enabled state of mmap safety.
  46  *
  47  * @return The safety state (#EINA_TRUE if enabled)
  48  *
  49  * This returns the mmap safety state set by eina_mmap_safety_enabled_set().
  50  * See eina_mmap_safety_enabled_set() for more information.
  51  *
  52  * @since 1.1.0
  53  */
  54 EAPI Eina_Bool
  55 eina_mmap_safety_enabled_get(void);
  56
  57 /**
  58  * @}
  59  */
  60 #endif