libFaultOrdering(3)

NAME
libFaultOrdering - a runtime debugging library using page faults to determine per-module page utilization

DESCRIPTION
libFaultOrdering utilizes dyld's library notification callback to vm_protect the __TEXT pages of libraries as they're loaded to be non-executable and installs an exception handler to catch the faults. When a fault occurs, libFaultOrdering restores executable privileges to the page and records the fault address, allowing the library's user to see what symbol was first utilized on the __TEXT page.

To use this library, insert it into a process at launch via: DYLD_INSERT_LIBRARIES=/usr/local/lib/libFaultOrdering.dylib

Note: this will only work for processes that are not considered "restricted" by dyld due to being setuid(), utilizing private entitlements, or running with library validation enabled.

Upon a successful exit() (i.e. not SIGKILL), this library will print out statistics on how many __TEXT pages were faulted in an ascii-art form like so:

      Module: leaks - 0x10f067000 (31 pages)
      19/31 faulted (61.29%) with 5 discontiguous ranges
      [xxx--xxxxxxx---xx------x-xxxxxx]

In the printed summaries like the one above, each 'x' represents a VM page that was faulted, and each '-' represents a page that was not.

ENVIRONMENT OPTIONS:

VERBOSE_FAULTS=1
    The first time a __TEXT page is faulted in, print the symbol which caused the fault.

ORDER_FILE_OUTPUT_DIR=<path>
    Append the faulted symbols to an order file located at "<path>/<module-name>.order" If this path does not already exist for a given module, it will not be created, and the file will be treated as append-only. Uniquing/merging symbols in the append-only order file is left as an exercise to the user and will likely require ~20-80 re-link cycles to get a fairly good ordering as only the first symbol on each page is reported when the page is first faulted in.

DYLD_SHARED_REGION=avoid
    As libraries in dyld's shared region can't be vm_protected to selectively remove executable privileges, usage of this environment variable can allow gathering statistics of libraries that would normally be loaded from the dyld(1) shared cache by forcing dyld to attempt to load them from disk if possible.

EXAMPLE USAGE
VERBOSE_FAULTS=1 DYLD_INSERT_LIBRARIES=/usr/local/lib/libFaultOrdering.dylib /Applications/Calculator.app/Contents/MacOS/Calculator

SEE ALSO
dyld(1) libgmalloc(3)