Linker and Libraries Guide

Debugger Exported Interface

This section describes the various interfaces exported by the /usr/lib/librtld_db.so.1 audit library. It is broken down into functional groups.

Agent Manipulation Interfaces

rd_init()

This function establishes the rtld-debugger version requirements. The base version is defined as RD_VERSION1. The current version is always defined by RD_VERSION.

rd_err_e rd_init(int version);

Version RD_VERSION2, added in the Solaris 8 10/00 release, extends the rd_loadobj_t structure. See the rl_flags, rl_bend and rl_dynamic fields in Scanning Loadable Objects.

Version RD_VERSION3, added in the Solaris 8 01/01 release, extends the rd_plt_info_t structure. See the pi_baddr and pi_flags fields in Procedure Linkage Table Skipping.

If the version requirement of the controlling process is greater than the rtld-debugger interface available, then RD_NOCAPAB is returned.

rd_new()

This function creates a new exported interface agent.

rd_agent_t * rd_new(struct ps_prochandle * php);

php is a cookie created by the controlling process to identify the target process. This cookie is used by the imported interface offered by the controlling process to maintain context, and is opaque to the rtld-debugger interface.

rd_reset()

This function resets the information within the agent based off the same ps_prochandle structure given to rd_new().

rd_err_e rd_reset(struct rd_agent * rdap);

This function is called when a target process is restarted.

rd_delete()

This function deletes an agent and frees any state associated with it.

void rd_delete(struct rd_agent * rdap);

Error Handling

The following error states can be returned by the rtld-debugger interface (defined in rtld_db.h).

typedef enum {
        RD_ERR,
        RD_OK,
        RD_NOCAPAB,
        RD_DBERR,
        RD_NOBASE,
        RD_NODYNAM,
        RD_NOMAPS
} rd_err_e;

The following interfaces can be used to gather the error information.

rd_errstr()

This function returns a descriptive error string describing the error code rderr.

char * rd_errstr(rd_err_e rderr);

rd_log()

This function turns logging on (1) or off (0).

void rd_log(const int onoff);

When logging is turned on, the imported interface function ps_plog() provided by the controlling process, is called with more detailed diagnostic information.

Scanning Loadable Objects

You can obtain information for each object maintained on the runtime linkers link-map is achieved by using the following structure, defined in rtld_db.h.

typedef struct rd_loadobj {
        psaddr_t        rl_nameaddr;
        unsigned        rl_flags;
        psaddr_t        rl_base;
        psaddr_t        rl_data_base;
        unsigned        rl_lmident;
        psaddr_t        rl_refnameaddr;
        psaddr_t        rl_plt_base;
        unsigned        rl_plt_size;
        psaddr_t        rl_bend;
        psaddr_t        rl_padstart;
        psaddr_t        rl_padend;
        psaddt_t        rl_dynamic;
} rd_loadobj_t;

Notice that all addresses given in this structure, including string pointers, are addresses in the target process and not in the address space of the controlling process itself.

rl_nameaddr: A pointer to a string that contains the name of the dynamic object.
rl_flags: With revision RD_VERSION2, dynamically loaded relocatable objects are identified with RD_FLG_MEM_OBJECT.
rl_base: The base address of the dynamic object.
rl_data_base: The base address of the data segment of the dynamic object.
rl_lmident: The link-map identifier (see Establishing a Namespace).
rl_refnameaddr: If the dynamic object is a standard filter, then this points to the name of the filtees.
rl_plt_base, rl_plt_size: These elements are present for backward compatibility and are currently unused.
rl_bend: The end address of the object (text + data + bss). With revision RD_VERSION2, a dynamically loaded relocatable object will cause this element to point to the end of the created object, which will include its section headers.
rl_padstart: The base address of the padding before the dynamic object (refer to Dynamic Object Padding).
rl_padend: The base address of the padding after the dynamic object (refer to Dynamic Object Padding).
rl_dynamic: This field, added with RD_VERSION2, provides the base address of the object's dynamic section, which allows reference to such entries as DT_CHECKSUM (see Table 7–32).

The rd_loadobj_iter() routine uses this object data structure to access information from the runtime linker's link-map lists.

rd_loadobj_iter()

This function iterates over all dynamic objects currently loaded in the target process.

typedef int rl_iter_f(const rd_loadobj_t *, void *);
 
rd_err_e rd_loadobj_iter(rd_agent_t * rap, rl_iter_f * cb,
        void * clnt_data);

On each iteration the imported function specified by cb is called. clnt_data can be used to pass data to the cb call. Information about each object is returned by means of a pointer to a volatile (stack allocated) rd_loadobj_t structure.

Return codes from the cb routine are examined by rd_loadobj_iter() and have the following meaning.

1 – continue processing link-maps.
0 – stop processing link-maps and return control to the controlling process.

rd_loadobj_iter() returns RD_OK on success. A return of RD_NOMAPS indicates the runtime linker has not yet loaded the initial link-maps.

Event Notification

A controlling process can track certain events that occur within the scope of the runtime linker that. These events are:

RD_PREINIT: The runtime linker has loaded and relocated all the dynamic objects and is about to start calling the .init sections of each object loaded.
RD_POSTINIT: The runtime linker has finished calling all of the .init sections and is about to transfer control to the primary executable.
RD_DLACTIVITY: The runtime linker has been invoked to either load or unload a dynamic object.

These events can be monitored using the following interface, defined in sys/link.h and rtld_db.h.

typedef enum {
        RD_NONE = 0,
        RD_PREINIT,
        RD_POSTINIT,
        RD_DLACTIVITY
} rd_event_e;
 
/*
 * Ways that the event notification can take place:
 */
typedef enum {
        RD_NOTIFY_BPT,
        RD_NOTIFY_AUTOBPT,
        RD_NOTIFY_SYSCALL
} rd_notify_e;
 
/*
 * Information on ways that the event notification can take place:
 */
typedef struct rd_notify {
        rd_notify_e     type;
        union {
                psaddr_t        bptaddr;
                long            syscallno;
        } u;
} rd_notify_t;

The following functions track events.

rd_event_enable()

This function enables (1) or disables (0) event monitoring.

rd_err_e rd_event_enable(struct rd_agent * rdap, int onoff);

Note –

Presently, for performance reasons, the runtime linker ignores event disabling. The controlling process should not assume that a given break-point can not be reached because of the last call to this routine.

rd_event_addr()

This function specifies how the controlling program is notified of a given event.

rd_err_e rd_event_addr(rd_agent_t * rdap, rd_event_e event,
        rd_notify_t * notify);

Depending on the event type, the notification of the controlling process takes place by calling a benign, cheap system call that is identified by notify->u.syscallno, or executing a break point at the address specified by notify->u.bptaddr. The controlling process is responsible for tracing the system call or place the actual break-point.

When an event has occurred, additional information can be obtained by this interface, defined in rtld_db.h.

typedef enum {
        RD_NOSTATE = 0,
        RD_CONSISTENT,
        RD_ADD,
        RD_DELETE
} rd_state_e;
 
typedef struct rd_event_msg {
        rd_event_e      type;
        union {
                rd_state_e      state;
        } u;
} rd_event_msg_t;

The rd_state_e values are:

RD_NOSTATE: There is no additional state information available.
RD_CONSISTANT: The link-maps are in a stable state and can be examined.
RD_ADD: A dynamic object is in the process of being loaded and the link-maps are not in a stable state. They should not be examined until the RD_CONSISTANT state is reached.
RD_DELETE: A dynamic object is in the process of being deleted and the link-maps are not in a stable state. They should not be examined until the RD_CONSISTANT state is reached.

The rd_event_getmsg() function is used to obtain this event state information.

rd_event_getmsg()

This function provides additional information concerning an event.

rd_err_e rd_event_getmsg(struct rd_agent * rdap, rd_event_msg_t * msg);

The following table shows the possible state for each of the different event types.

`RD_PREINIT`	`RD_POSTINIT`	`RD_DLACTIVITY`
`RD_NOSTATE`	`RD_NOSTATE`	`RD_CONSISTANT`
		`RD_ADD`
		`RD_DELETE`

Procedure Linkage Table Skipping

The rtld-debugger interface enables a controlling process to skip over procedure linkage table entries. When a controlling process, such as a debugger, is asked to step into a function for the first time, the procedure linkage table processing, causes control to be passed to the runtime linker to search for the function definition.

The following interface enables a controlling process to step over the runtime linker's procedure linkage table processing. The controlling process can determine when a procedure linkage table entry is encountered based on external information provided in the ELF file.

Once a target process has stepped into a procedure linkage table entry, the process calls the rd_plt_resolution() interface.

rd_plt_resolution()

This function returns the resolution state of the current procedure linkage table entry and information on how to skip it.

rd_err_e rd_plt_resolution(rd_agent_t * rdap, paddr_t pc,
        lwpid_t lwpid, paddr_t plt_base, rd_plt_info_t * rpi);

pc represents the first instruction of the procedure linkage table entry. lwpid provides the lwp identifier and plt_base provides the base address of the procedure linkage table. These three variables provide information sufficient for various architectures to process the procedure linkage table.

rpi provides detailed information regarding the procedure linkage table entry as defined in the following data structure, defined in rtld_db.h.

typedef enum {
        RD_RESOLVE_NONE,
        RD_RESOLVE_STEP,
        RD_RESOLVE_TARGET,
        RD_RESOLVE_TARGET_STEP
} rd_skip_e;
 
typedef struct rd_plt_info {
        rd_skip_e       pi_skip_method;
        long            pi_nstep;
        psaddr_t        pi_target;
        psaddr_t        pi_baddr;
        unsigned int    pi_flags;
} rd_plt_info_t;

#define RD_FLG_PI_PLTBOUND     0x0001

The elements of the rd_plt_info_tstructure are:

pi_skip_method: Identifies how the procedure linkage table entry can be traversed. This method is set to one of the rd_skip_e values.
pi_nstep: Identifies how many instructions to step over when RD_RESOLVE_STEP or RD_RESOLVE_TARGET_STEP are returned.
pi_target: Specifies the address at which to set a breakpoint when RD_RESOLVE_TARGET_STEP or RD_RESOLVE_TARGET are returned.
pi_baddr: The procedure linkage table destination address, added with RD_VERSION3. When the RD_FLG_PI_PLTBOUND flag of the pi_flags field is set, this element identifies the resolved (bound) destination address.
pi_flags: A flags field, added with RD_VERSION3. The flag RD_FLG_PI_PLTBOUND identifies the procedure linkage entry as having been resolved (bound) to its destination address, which is available in the pi_baddr field.

The following scenarios are possible from the rd_plt_info_t return values.

The first call through this procedure linkage table must be resolved by the runtime linker. In this case, the rd_plt_info_t contains:
{RD_RESOLVE_TARGET_STEP, M, <BREAK>, 0, 0}
The controlling process sets a breakpoint at BREAK and continues the target process. When the breakpoint is reached, the procedure linkage table entry processing has finished. The controlling process can then step M instructions to the destination function. Notice that the bound address (pi_baddr) has not been set since this is the first call through a procedure linkage table entry.
On the Nth time through this procedure linkage table, rd_plt_info_t contains:
{RD_RESOLVE_STEP, M, 0, <BoundAddr>, RD_FLG_PI_PLTBOUND}
The procedure linkage table entry has already been resolved and the controlling process can step M instructions to the destination function. The address that the procedure linkage table entry is bound to is <BoundAddr> and the RD_FLG_PI_PLTBOUND bit has been set in the flags field.

Dynamic Object Padding

The default behavior of the runtime linker relies on the operating system to load dynamic objects where they can be most efficiently referenced. Some controlling processes benefit from the existence of padding around the objects loaded into memory of the target process. This interface enables a controlling process to request this padding.

rd_objpad_enable()

This function enables or disables the padding of any subsequently loaded objects with the target process. Padding occurs on both sides of the loaded object.

rd_err_e rd_objpad_enable(struct rd_agent * rdap, size_t padsize);

padsize specifies the size of the padding, in bytes, to be preserved both before and after any objects loaded into memory. This padding is reserved as a memory mapping using mmap(2) with PROT_NONE permissions and the MAP_NORESERVE flag. Effectively, an area of the virtual address space of the target process, adjacent to any loaded objects, is reserved. These areas can later be used by the controlling process.

A padsize of 0 disables any object padding for later objects.

Note –

Reservations obtained using mmap(2) from /dev/zero with MAP_NORESERVE can be reported using the proc(1) facilities and by referring to the link-map information provided in rd_loadobj_t.