HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

d
dlmodadd(3C) dlmodadd(3C)
NAME
dlmodadd() - register information about dynamically generated functions
SYNOPSIS
cc [flag]... file...
-ldl [library]...
#include <dlfcn.h>
void* dlmodadd(void* associate_handle,
void *func_start,
size_t func_size,
void *linkage_ptr,
void *unwind_info);
Multithread Usage
This routine is thread-safe.
DESCRIPTION
dlmodadd() registers information about a dynamically generated function, which can be retrived
through dlmodinfo() . The dlmodremove()
interface can be used to remove the registered informa-
tion.
associate_handle is the module handle for an existing module with which the new function is associated.
When the dynamic loader is called from the new function, it will behave as if it had been called from the
associated module. This handle must be a handle returned by
dlopen() or dlget().
func_start is the starting address of the generated machine code for the function. It is NOT the address of
a function descriptor.
func_size is the size, in bytes, of the generated machine code.
linkage_ptr is the gp (global pointer) value to be used for the function. It could be the gp of the associated
module. It must be set to a valid value, even if the generated code doesn’t actually use gp, as it is required
at a minimum for following the personality routine pointer in the unwind information.
unwind_info is a pointer to the beginning of the unwind info block for the function. The unwind info block
contains the header word, unwind descriptors, personality routine pointer, and language-specific data, as
described in the Itanium-based system Software Conventions and Runtime Architecture document.
When
dlmodadd() is invoked to register information about a dynamically generated function, the
dynamic loader creates an unwind header and a single-entry unwind table for the function. The unwind
header is associated with the address range occupied by the dynamically generated function. The dlmo-
dadd()
routine returns a handle as identification of the newly-added function. Handles returned by
dlmodadd() share the same namespace as handles returned by dlopen()and dlget(), but they may
not be used in calls to dlclose(). A handle returned by dlmodadd() is treated by
dlsym() as if the
associated handle had been used instead. If
dlmodinfo() is called with an ip_value that belongs to a
function that has been registered with dlmodadd(), it returns the handle of the dynamically generated
function, as originally returned by dlmodadd(), along with a load_module_desc structure describing the
function. A load_module_desc for a dynamically generated function always has a
0 value in the phdr_base
field. The text_base, text_size, data_base, and data_size fields may be used for converting segment-relative
offsets to virtual addresses, but they may not be relied on to identify a range of memory belonging
exclusively to the function. The unwind_base field contains the address of the unwind header built for the
function. If a library is unloaded by
dlclose(), the unwind info for all dynamically generated functions
associated with the library being unloaded is also removed.
RETURN VALUE
If successful, dlmodadd() returns a handle as identification of the newly-added function. NULL is
returned otherwise.
ERRORS
If dlmodadd() fails, a subsequent call to dlerrno() returns one of the following values:
[RTLD_ERR_NO_MEMORY] Out of memory.
[RTLD_ERR_CANT_APPLY_RELOC]
Cannot apply relocation in library.
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−167