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.Dd June 10, 2010 30.Dt LIBRTLD_DB 3 31.Os 32.Sh NAME 33.Nm librtld_db 34.Nd library for run-time linker debugging 35.Sh LIBRARY 36.Lb librtld_db 37.Sh SYNOPSIS 38.In rtld_db.h 39.Ft void 40.Fo rd_delete 41.Fa "rd_agent_t *rdap" 42.Fc 43.Ft char * 44.Fo rd_errstr 45.Fa "rd_err_e rderr" 46.Fc 47.Ft rd_err_e 48.Fo rd_event_addr 49.Fa "rd_agent_t *rdap, rd_event_e event, rd_notify_t *notify" 50.Fc 51.Ft rd_err_e 52.Fo rd_event_enable 53.Fa "rd_agent_t *rdap, int onoff" 54.Fc 55.Ft rd_err_e 56.Fo rd_event_getmsg 57.Fa "rd_agent_t *rdap, rd_event_msg_t *msg" 58.Fc 59.Ft rd_err_e 60.Fo rd_init 61.Fa "int version" 62.Fc 63.Ft typedef int 64.Fo rl_iter_f 65.Fa "const rd_loadobj_t *, void *" 66.Fc 67.Ft rd_err_e 68.Fo rd_loadobj_iter 69.Fa "rd_agent_t *rdap, rl_iter_f *cb, void *clnt_data" 70.Fc 71.Ft void 72.Fo rd_log 73.Fa "const int onoff" 74.Fc 75.Ft rd_agent_t * 76.Fo rd_new 77.Fa "struct proc_handle *php" 78.Fc 79.Ft rd_err_e 80.Fo rd_objpad_enable 81.Fa "rd_agent_t *rdap, size_t padsize" 82.Fc 83.Ft rd_err_e 84.Fo rd_plt_resolution 85.Fa "rd_agent_t *rdap, uintptr_t pc, struct proc *proc" 86.Fa "uintptr_t plt_base, rd_plt_info_t *rpi" 87.Fc 88.Ft rd_err_e 89.Fo rd_reset 90.Fa "rd_agent_t *rdap" 91.Fc 92.Sh DESCRIPTION 93The 94.Nm librtld_db 95library provides a debugging interface to the run-time linker (rtld). 96This library must be used along with 97.Xr libproc 3 . 98.Pp 99Most library functions take a 100.Ft rd_agent_t 101argument. 102This argument is an opaque structure containing information associated with 103the current status of the agent. 104.Pp 105Before you start using 106.Nm 107you should call 108.Fn rd_init 109with the 110.Ft RD_VERSION 111argument. 112This initializes the library to the correct version your program was compiled 113with and provides proper ABI stability. 114.Pp 115What follows is a description of what each function. 116.Pp 117.Fn rd_new 118creates a new 119.Nm 120agent. 121The 122.Ft php 123argument should be the 124.Ft proc_handle 125you received from 126.Xr libproc 3 . 127.Pp 128.Fn rd_reset 129resets your previously created agent. 130.Pp 131.Fn rd_delete 132deallocates the resources associated with the agent. 133.Pp 134.Fn rd_errstr 135returns an error string describing the error present in 136.Ft rderr . 137.Pp 138.Fn rd_event_enable 139enables reporting of events. 140This function always returns RD_OK. 141.Pp 142.Fn rd_event_addr 143returns the event address corresponding to the 144.Ft event 145parameter. 146At the moment we only report events of type RD_NOTIFY_BPT. 147.Pp 148.Fn rd_event_getmsg 149returns the message associated with the latest event. 150At the moment only RD_POSTINIT events are supported. 151.Pp 152.Fn rd_loadobj_iter 153allows you to iterate over the program's loaded objects. 154.Ft cb 155is a callback of type 156.Fn rl_iter_f . 157.Sh RETURN VALUES 158Most functions return an 159.Ft rd_err_e 160type error. 161The error codes are described in the header file for this library. 162You can get the error string using 163.Fn rd_errstr . 164.Sh SEE ALSO 165.Xr ld 1 , 166.Xr ld-elf.so.1 1 , 167.Xr ld.so 1 , 168.Xr rtld 1 , 169.Xr libproc 3 170.Sh HISTORY 171The 172.Nm librtld_db 173library first appeared in 174.Fx 9.0 175and was modeled after the same library present in the Solaris operating system. 176.Sh AUTHORS 177The 178.Nm librtld_db 179library and this manual page were written by 180.An Rui Paulo Aq Mt rpaulo@FreeBSD.org 181under sponsorship from the FreeBSD Foundation. 182.Sh CAVEATS 183The functions 184.Fn rd_event_enable , 185.Fn rd_log , 186.Fn rd_objpad_enable 187and 188.Fn rd_plt_resolution 189are not yet implemented. 190