LIBRTLD_DB(3)

💅 LIBRTLD_DB(3) — hey bestie, it's the librtld_db page 💅

Okay so this is the LIBRTLD_DB(3) page from the Library Functions Manual, and we're talking about librtld_db, the library for run-time linker debugging. Buckle up, it's giving debugger-core 🫶

---

🌸 NAME 🌸

librtld_db — library for run-time linker debugging

📚 LIBRARY 📚

library “librtld_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 gives you a debugging interface to the run-time linker, aka rtld. It literally must be used along with libproc(3), no solo missions bestie.

Most library functions take an rd_agent_t argument. That argument is an opaque structure containing information associated with the current status of the agent. Very mystery, very iconique 🎀

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. Slay, ABI stability matters.

Okay, function-by-function breakdown time 🧚

• 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(). iykyk, check the header.

👀 SEE ALSO 👀

ld(1), ld-elf.so.1(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. History lesson served, bestie.

👑 AUTHORS 👑

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

💀 CAVEATS 💀

Heads up: the functions rd_event_enable(), rd_log(), rd_objpad_enable() and rd_plt_resolution() are not yet implemented. Not me pretending they're ready — they are literally not yet implemented.

---

🍓 source/version: Debian · date: June 10, 2010 · page: LIBRTLD_DB(3) — okay bye bestie, mwah 💋