PukABI documentation

Overview

PukABI is a dynamic ABI manager. It intercepts symbols using LD_PRELOAD to allow for a variety of features:

• replace a libc function with a user-supplied function;
• add hooks for locking with another thread library than libc pthread;
• add hooks for memory registration cache invalidation.

It may be used either by directly setting LD_PRELOAD or transparently through its integration with padico-launch.

It was formerly part of Puk and has been split, hence the name.

User API

PukABI intercepts several families of functions:

• fsys: file system functions. These are the function that work on a file descriptor (file and socket). They may be enable with configuration flag --enable-fsys.
• proc: process-related functions (spawn, exit, ...). They may be enabled with --enable-proc.
• mem: memory related function, such as malloc, free, calloc, realloc, mprotect, munmap, etc. Note that mmap needs both mem and fsys. These function may be enabled with --enable-mem.
• errno: errno-related functions (__errno_location, perror). These functions may be enabled with--enable-errno.
• sleep: sleep related functions (sleep, usleep, nanosleep). The configuration flag is--enable-sleep.
• file: all functions that use FILE*. The configuration flag is --enable-file.
• resolv: the resolver-related functions, such as gethostbyname, getaddrinfo. The configuration flag is --enable-resolv.

When in doubt, see Puk-ABI-symbols.h to check whether the symbol is intercepted or not. The list of intercepted symbols may be obtained using the script <prefix>/build/PukABI/puk-abi-getsymbols.sh (only available in build/, not installed).

For each intercepted symbol, several flavors of symbols are defined by PukABI:

• real, given by PUK_ABI_REAL(): this is the real symbol from libc.
• virtual, given by PUK_ABI_VIRTUAL(): it always calls the virtual symbol registered by user to override the libc. This is seldom wanted.
• wrap, given by PUK_ABI_WRAP(): this calls the real symbol, with hooks before and after, if set. These hooks may be used for locking (in case of userland multithreading library) or for memory registration cache invalidation, by tracking malloc/free.
• stub, given by PUK_ABI_STUB(): it calls the virtual symbol if it as been set, or the wrap symbol otherwise. For file descriptor related symbols, we track whether the file descriptor was created using a virtual or real symbol and continue with the same flavor.

When calling the symbol normally from C with the LD_PRELOAD installed, the stub flavor is called.

For reference API, see PukABI public API

A tool is provided to wrap existing libraries: elfwrap: a tool to wrap symbols in an already linked ELF. This is not needed by regular users and is used only internally by PadicoTM.

Installation

See README for PukABI