1.\" $NetBSD: librtld_db.3,v 1.2 2015/09/28 21:50:48 wiz Exp $ 2.\"- 3.\" Copyright (c) 2010 The FreeBSD Foundation 4.\" All rights reserved. 5.\" 6.\" This software was developed by Rui Paulo under sponsorship from 7.\" the FreeBSD Foundation. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD: head/lib/librtld_db/librtld_db.3 276294 2014-12-27 08:31:52Z joel $ 31.\" 32.Dd June 10, 2010 33.Dt LIBRTLD_DB 3 34.Os 35.Sh NAME 36.Nm librtld_db 37.Nd library for run-time linker debugging 38.Sh LIBRARY 39.Lb librtld_db 40.Sh SYNOPSIS 41.In rtld_db.h 42.Ft void 43.Fo rd_delete 44.Fa "rd_agent_t *rdap" 45.Fc 46.Ft char * 47.Fo rd_errstr 48.Fa "rd_err_e rderr" 49.Fc 50.Ft rd_err_e 51.Fo rd_event_addr 52.Fa "rd_agent_t *rdap, rd_event_e event, rd_notify_t *notify" 53.Fc 54.Ft rd_err_e 55.Fo rd_event_enable 56.Fa "rd_agent_t *rdap, int onoff" 57.Fc 58.Ft rd_err_e 59.Fo rd_event_getmsg 60.Fa "rd_agent_t *rdap, rd_event_msg_t *msg" 61.Fc 62.Ft rd_err_e 63.Fo rd_init 64.Fa "int version" 65.Fc 66.Ft typedef int 67.Fo rl_iter_f 68.Fa "const rd_loadobj_t *, void *" 69.Fc 70.Ft rd_err_e 71.Fo rd_loadobj_iter 72.Fa "rd_agent_t *rdap, rl_iter_f *cb, void *clnt_data" 73.Fc 74.Ft void 75.Fo rd_log 76.Fa "const int onoff" 77.Fc 78.Ft rd_agent_t * 79.Fo rd_new 80.Fa "struct proc_handle *php" 81.Fc 82.Ft rd_err_e 83.Fo rd_objpad_enable 84.Fa "rd_agent_t *rdap, size_t padsize" 85.Fc 86.Ft rd_err_e 87.Fo rd_plt_resolution 88.Fa "rd_agent_t *rdap, uintptr_t pc, struct proc *proc" 89.Fa "uintptr_t plt_base, rd_plt_info_t *rpi" 90.Fc 91.Ft rd_err_e 92.Fo rd_reset 93.Fa "rd_agent_t *rdap" 94.Fc 95.Sh DESCRIPTION 96The 97.Nm librtld_db 98library provides a debugging interface to the run-time linker (rtld). 99This library must be used along with 100.Xr libproc 3 . 101.Pp 102Most library functions take a 103.Ft rd_agent_t 104argument. 105This argument is an opaque structure containing information associated with 106the current status of the agent. 107.Pp 108Before you start using 109.Nm 110you should call 111.Fn rd_init 112with the 113.Ft RD_VERSION 114argument. 115This initializes the library to the correct version your program was compiled 116with and provides proper ABI stability. 117.Pp 118What follows is a description of what each function. 119.Pp 120.Fn rd_new 121creates a new 122.Nm 123agent. 124The 125.Ft php 126argument should be the 127.Ft proc_handle 128you received from 129.Xr libproc 3 . 130.Pp 131.Fn rd_reset 132resets your previously created agent. 133.Pp 134.Fn rd_delete 135deallocates the resources associated with the agent. 136.Pp 137.Fn rd_errstr 138returns an error string describing the error present in 139.Ft rderr . 140.Pp 141.Fn rd_event_enable 142enables reporting of events. 143This function always returns RD_OK. 144.Pp 145.Fn rd_event_addr 146returns the event address corresponding to the 147.Ft event 148parameter. 149At the moment we only report events of type RD_NOTIFY_BPT. 150.Pp 151.Fn rd_event_getmsg 152returns the message associated with the latest event. 153At the moment only RD_POSTINIT events are supported. 154.Pp 155.Fn rd_loadobj_iter 156allows you to iterate over the program's loaded objects. 157.Ft cb 158is a callback of type 159.Fn rl_iter_f . 160.Sh RETURN VALUES 161Most functions return an 162.Ft rd_err_e 163type error. 164The error codes are described in the header file for this library. 165You can get the error string using 166.Fn rd_errstr . 167.Sh SEE ALSO 168.Xr ld 1 , 169.Xr ld.elf_so 1 , 170.Xr ld.so 1 , 171.Xr rtld 1 , 172.Xr libproc 3 173.Sh HISTORY 174The 175.Nm librtld_db 176library first appeared in 177.Fx 9.0 178and was modeled after the same library present in the Solaris operating system. 179.Sh AUTHORS 180The 181.Nm librtld_db 182library and this manual page were written by 183.An Rui Paulo Aq Mt rpaulo@FreeBSD.org 184under sponsorship from the 185.Fx 186Foundation. 187.Sh CAVEATS 188The functions 189.Fn rd_event_enable , 190.Fn rd_log , 191.Fn rd_objpad_enable , 192and 193.Fn rd_plt_resolution 194are not yet implemented. 195