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