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