libdwarf: Section allocation: malloc or mmap

libdwarf

Loading...
Searching...
No Matches
Functions
Section allocation: malloc or mmap

## Functions
DW_API enum Dwarf_Sec_Alloc_Pref | dwarf_set_load_preference (enum Dwarf_Sec_Alloc_Pref dw_load_preference)
| Set/Retrieve section allocation preference.
DW_API int | dwarf_get_mmap_count (Dwarf_Debug dw_dbg, Dwarf_Unsigned *dw_mmap_count, Dwarf_Unsigned *dw_mmap_size, Dwarf_Unsigned *dw_malloc_count, Dwarf_Unsigned *dw_malloc_size)
| Retrieve count of mmap/malloc sections.

## Detailed Description

Functions related to the choice of malloc/read or mmap for object section memory allocation.

The default allocation preference is malloc().

The shell environment variable DWARF_WHICH_ALLOC is also involved at runtime but it only applies to reading Elf object files.. If the value is 'malloc' then use of read/malloc is preferred. If the value is 'mmap' then use of mmap is preferred (Example: 'export DWARF_WHICH_ALLOC=mmap'). Otherwise, the environment value is checked and ignored.

If present and valid this environment variable takes precedence over dwarf_set_load_preference().

## Function Documentation

## ◆ dwarf_get_mmap_count()

DW_API int dwarf_get_mmap_count | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned * | dw_mmap_count,
|  | Dwarf_Unsigned * | dw_mmap_size,
|  | Dwarf_Unsigned * | dw_malloc_count,
|  | Dwarf_Unsigned * | dw_malloc_size )

Retrieve count of mmap/malloc sections.

Since
  {0.12.0}

Note that compressed section contents will be expanded into a malloc/read section in all cases.

Parameters

  dw_dbg | A valid open Dwarf_Debug.
  dw_mmap_count | On success the number of sections allocated with mmap is returned. If null passed in the argument is ignored.
  dw_mmap_size | On success the size total in bytes of sections allocated with mmap is returned. If null passed in the argument is ignored.
  dw_malloc_count | On success the number of sections read/allocated with read/malloc is returned. If null passed in the argument is ignored. On success the number of sections allocated with malloc/read is returned.
  dw_malloc_size | On success the total size in bytes of sections with malloc/read is returned. If null passed in the argument is ignored. On success the number of sections read/allocated with read/malloc is returned.

Returns
  On success returns DW_DLV_OK and sets the counts and total size through the respective non-null pointer arguments. If dw_dbg is invalid or NULL the function returns DW_DLV_ERROR. Never returns DW_DLV_NO_ENTRY.

## ◆ dwarf_set_load_preference()

DW_API enum Dwarf_Sec_Alloc_Pref dwarf_set_load_preference | ( | enum Dwarf_Sec_Alloc_Pref | dw_load_preference | ) |

Set/Retrieve section allocation preference.

Since
  {0.12.0}

By default object file sections are loaded using malloc and read (Dwarf_Alloc_Malloc). This works everywhere and works well on all but gigantic object files.

The preference of Dwarf_Alloc_Mmap does not guarantee mmap will be used for object section data, but does cause mmap() to be used when possible.

In 0.12.0 mmap() is only usable on Elf object files.

dw_load_preference is one of Dwarf_Alloc_Malloc (1) Dwarf_Alloc_Mmap (2)

Must be called before calling a dwarf_init*() to be effective in a dwarf_init*(). The value is remembered for subsequent dwarf_init*() in the library runtime being executed.

Parameters

  dw_load_preference | If passed in Dwarf_Alloc_Mmap then future calls to any dwarf_init*() function will use mmap to load object sections if possible. If passed in Dwarf_Alloc_Malloc then future calls to any dwarf_init*() function will use mmap to load sections. Any other value passed in dw_load_preference is ignored.

Returns
  Always returns the value before dw_load_preference applied, of this runtime global preference.