LIBRTLD_DB(3)

LIBRTLD_DB(3) | Library Functions Manual | LIBRTLD_DB(3)

# NAME

`librtld_db` —
library for run-time linker debugging

# LIBRARY

Debugging interface to the runtime linker Library (librtld_db, -lrtld_db)

# SYNOPSIS

`#include <rtld_db.h>`

void
`rd_delete`(rd_agent_t *rdap);

char *
`rd_errstr`(rd_err_e rderr);

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

rd_err_e
`rd_event_enable`(rd_agent_t *rdap, int onoff);

rd_err_e
`rd_event_getmsg`(rd_agent_t *rdap, rd_event_msg_t *msg);

rd_err_e
`rd_init`(int version);

typedef int
`rl_iter_f`(const rd_loadobj_t *, void *);

rd_err_e
`rd_loadobj_iter`(rd_agent_t *rdap, rl_iter_f *cb, void *clnt_data);

void
`rd_log`(const int onoff);

rd_agent_t *
`rd_new`(struct proc_handle *php);

rd_err_e
`rd_objpad_enable`(rd_agent_t *rdap, size_t padsize);

rd_err_e
`rd_plt_resolution`(rd_agent_t *rdap, uintptr_t pc, struct proc *proc, uintptr_t plt_base, rd_plt_info_t *rpi);

rd_err_e
`rd_reset`(rd_agent_t *rdap);

# DESCRIPTION

The `librtld_db` library provides a debugging interface to the run-time linker (rtld). This library must be used along with libproc(3).

Most library functions take a rd_agent_t argument. This argument is an opaque structure containing information associated with the current status of the agent.

Before you start using `librtld_db` you should call `rd_init`() with the RD_VERSION argument. This initializes the library to the correct version your program was compiled with and provides proper ABI stability.

What follows is a description of what each function.

`rd_new`() creates a new `librtld_db` agent. The php argument should be the proc_handle you received from libproc(3).

`rd_reset`() resets your previously created agent.

`rd_delete`() deallocates the resources associated with the agent.

`rd_errstr`() returns an error string describing the error present in rderr.

`rd_event_enable`() enables reporting of events. This function always returns RD_OK.

`rd_event_addr`() returns the event address corresponding to the event parameter. At the moment we only report events of type RD_NOTIFY_BPT.

`rd_event_getmsg`() returns the message associated with the latest event. At the moment only RD_POSTINIT events are supported.

`rd_loadobj_iter`() allows you to iterate over the program's loaded objects. cb is a callback of type `rl_iter_f`().

# RETURN VALUES

Most functions return an rd_err_e type error. The error codes are described in the header file for this library. You can get the error string using `rd_errstr`().

# SEE ALSO

ld(1), ld.elf_so(1), ld.so(1), rtld(1), libproc(3)

# HISTORY

The `librtld_db` library first appeared in FreeBSD 9.0 and was modeled after the same library present in the Solaris operating system.

# AUTHORS

The `librtld_db` library and this manual page were written by Rui Paulo <rpaulo@FreeBSD.org> under sponsorship from the FreeBSD Foundation.

# CAVEATS

The functions `rd_event_enable`(), `rd_log`(), `rd_objpad_enable`(), and `rd_plt_resolution`() are not yet implemented.

June 10, 2010 | NetBSD 9.0