diff options
Diffstat (limited to 'lib/librtld_db/librtld_db.3')
-rw-r--r-- | lib/librtld_db/librtld_db.3 | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/lib/librtld_db/librtld_db.3 b/lib/librtld_db/librtld_db.3 new file mode 100644 index 0000000..0c9a762 --- /dev/null +++ b/lib/librtld_db/librtld_db.3 @@ -0,0 +1,191 @@ +.\"- +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This software was developed by Rui Paulo under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 10, 2010 +.Dt LIBRTLD_DB 3 +.Os +.Sh NAME +.Nm librtld_db +.Nd library for run-time linker debugging +.Sh LIBRARY +.Lb librtld_db +.Sh SYNOPSIS +.In rtld_db.h +.Ft void +.Fo rd_delete +.Fa "rd_agent_t *rdap" +.Fc +.Ft char * +.Fo rd_errstr +.Fa "rd_err_e rderr" +.Fc +.Ft rd_err_e +.Fo rd_event_addr +.Fa "rd_agent_t *rdap, rd_notify_t *notify" +.Fc +.Ft rd_err_e +.Fo rd_event_enable +.Fa "rd_agent_t *rdap, int onoff" +.Fc +.Ft rd_err_e +.Fo rd_event_getmsg +.Fa "rd_agent_t *rdap, rd_event_msg_t *msg" +.Fc +.Ft rd_err_e +.Fo rd_init +.Fa "int version" +.Fc +.Ft typedef int +.Fo rl_iter_f +.Fa "const rd_loadobj_t *, void *" +.Fc +.Ft rd_err_e +.Fo rd_loadobj_iter +.Fa "rd_agent_t *rdap, rl_iter_f *cb, void *clnt_data" +.Fc +.Ft void +.Fo rd_log +.Fa "const int onoff" +.Fc +.Ft rd_agent_t * +.Fo rd_new +.Fa "struct proc_handle *php" +.Fc +.Ft rd_err_e +.Fo rd_objpad_enable +.Fa "rd_agent_t *rdap, size_t padsize" +.Fc +.Ft rd_err_e +.Fo rd_plt_resolution +.Fa "rd_agent_t *rdap, uintptr_t pc, struct proc *proc" +.Fa "uintptr_t plt_base, rd_plt_info_t *rpi" +.Fc +.Ft rd_err_e +.Fo rd_reset +.Fa "rd_agent_t *rdap" +.Fc +.Sh DESCRIPTION +The +.Nm librtld_db +library provides a debugging interface to the run-time linker (rtld). +This library must be used along with +.Xr libproc 3 . +.Pp +Most library functions take a +.Ft rd_agent_t +argument. +This argument is an opaque structure containing information associated with +the current status of the agent. +.Pp +Before you start using +.Nm +you should call +.Fn rd_init +with the +.Ft RD_VERSION +argument. +This initializes the library to the correct version your program was compiled +with and provides proper ABI stability. +.Pp +What follows is a description of what each function. +.Pp +.Fn rd_new +creates a new +.Nm +agent. +The +.Ft php +argument should be the +.Ft proc_handle +you received from +.Xr libproc 3 . +.Pp +.Fn rd_reset +resets your previously created agent. +.Pp +.Fn rd_delete +deallocates the resources associated with the agent. +.Pp +.Fn rd_errstr +returns an error string describing the error present in +.Ft rderr . +.Pp +.Fn rd_event_enable +enables reporting of events. +This function always returns RD_OK. +.Pp +.Fn rd_event_addr +returns the event address in the +.Ft event +parameter. +At the moment we only report RD_NOTIFY_BPT events. +.Pp +.Fn rd_event_getmsg +returns the message associated with the latest event. +At the moment only RD_POSTINIT events are supported. +.Pp +.Fn rd_loadobj_iter +allows you to iterate over the program's loaded objects. +.Ft cb +is a callback of type +.Fn rl_iter_f . +.Sh RETURN VALUES +Most functions return an +.Ft rd_err_e +type error. +The error codes are described in the header file for this library. +You can get the error string using +.Fn rd_errstr . +.Sh SEE ALSO +.Xr ld 1 , +.Xr ld-elf.so.1 1 , +.Xr ld.so 1 , +.Xr libproc 3 , +.Xr rtld 1 +.Sh HISTORY +The +.Nm librtld_db +library first appeared in +.Fx 9.0 +and was modeled after the same library present in the Solaris operating system. +.Sh AUTHORS +The +.Nm librtld_db +library and this manual page were written by +.An Rui Paulo Aq rpaulo@FreeBSD.org +under sponsorship from the FreeBSD Foundation. +.Sh CAVEATS +The functions +.Fn rd_event_enable , +.Fn rd_log , +.Fn rd_objpad_enable +and +.Fn rd_plt_resolution +are not yet implemented. |