diff options
Diffstat (limited to 'src/lib/eina/eina_mmap.h')
| -rw-r--r-- | src/lib/eina/eina_mmap.h | 69 |
1 files changed, 38 insertions, 31 deletions
diff --git a/src/lib/eina/eina_mmap.h b/src/lib/eina/eina_mmap.h index 1d1d58c976..16f3044ffe 100644 --- a/src/lib/eina/eina_mmap.h +++ b/src/lib/eina/eina_mmap.h @@ -2,10 +2,11 @@ #define EINA_MMAP_H_ /** - * @addtogroup Eina_Mmap_Group Mmap Group - * @ingroup Eina + * @internal + * @defgroup Eina_Mmap_Group Mmap Group + * @ingroup Eina_Core_Group * - * @brief These functions provide helpers for safe mmap handling + * @brief This group discusses the functions that provide helpers for safe mmap handling. * * @{ * @@ -13,44 +14,50 @@ */ /** - * @brief Enable or disable safe mmaped IO handling - * - * @param enabled The enabled state (to enable, pass #EINA_TRUE) - * @return #EINA_TRUE on success, #EINA_FALSE on failure. - * - * This enables (if possible on your platform) a signal handler for - * SIGBUS, that replaces the "bad page" with a page of 0's (from /dev/zero) - * if a SIGBUS occurs. This allows for safe mmap() of files that may truncate - * or from files on devices with IO errors. Normally these cases will result - * in a SIGBUS being delivered (and termination of your process), but - * when "mmap safety" is enabled, this will not occur. Instead a page of - * bytes of the value 0 will replace the "bad page", allowing the process - * to continue and allow its own parsing error detection to safely abort - * the operation without the process falling apart. - * - * If you disable mmap safety, the SIGBUS handler will be restored to its - * default handler. Note that eina_file_map_all() and eina_file_map_new() - * will automatically enable mmap safety as they provide an mmaped file IO - * layer, and rely on mmap to not fail for any part of the file. - * - * If you set up your own SIGBUS handler, then this will effectively disable - * the safe mmap handling and make you liable to crashes on IO to or from - * such "damaged files" that would take down your process. + * @brief Enables or disables safe mmaped IO handling. + * + * @details This enables (if possible on your platform) a signal handler for + * SIGBUS, that replaces the "bad page" with a page of 0's (from /dev/zero) + * if a SIGBUS occurs. This allows for safe mmap() of files that may truncate + * or from files on devices with IO errors. Normally these cases result + * in a SIGBUS being delivered (and termination of your process), but + * when "mmap safety" is enabled, this does not occur. Instead a page of + * bytes of the value 0 replaces the "bad page", allowing the process + * to continue and allow its own parsing error detection to safely abort + * the operation without the process falling apart. * * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @remarks If you disable mmap safety, the SIGBUS handler is restored to its + * default handler. Note that eina_file_map_all() and eina_file_map_new() + * automatically enable mmap safety as they provide an mmaped file IO + * layer, and rely on mmap to not fail for any part of the file. + * + * @remarks If you set up your own SIGBUS handler, then this effectively disables + * the safe mmap handling and makes you liable to crashes on IO to or from + * such "damaged files" that would take down your process. + * + * @param[in] enabled The enabled state (to enable, pass @c EINA_TRUE) + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure + * */ EAPI Eina_Bool eina_mmap_safety_enabled_set(Eina_Bool enabled); /** - * @brief Get the enabled state of mmap safety. - * - * @return The safety state (#EINA_TRUE if enabled) + * @brief Gets the enabled state of mmap safety. * - * This returns the mmap safety state set by eina_mmap_safety_enabled_set(). - * See eina_mmap_safety_enabled_set() for more information. + * @details This returns the mmap safety state set by eina_mmap_safety_enabled_set(). * * @since 1.1.0 + * + * @since_tizen 2.3 + * + * @return The safety state (@c EINA_TRUE if enabled) + * + * @see eina_mmap_safety_enabled_set() */ EAPI Eina_Bool eina_mmap_safety_enabled_get(void); |