lib/librtld_db/librtld_db.3

   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
  93 The
  94 .Nm librtld_db
  95 library provides a debugging interface to the run-time linker (rtld).
  96 This library must be used along with
  97 .Xr libproc 3 .
  98 .Pp
  99 Most library functions take a
 100 .Ft rd_agent_t
 101 argument.
 102 This argument is an opaque structure containing information associated with
 103 the current status of the agent.
 104 .Pp
 105 Before you start using
 106 .Nm
 107 you should call
 108 .Fn rd_init
 109 with the
 110 .Ft RD_VERSION
 111 argument.
 112 This initializes the library to the correct version your program was compiled
 113 with and provides proper ABI stability.
 114 .Pp
 115 What follows is a description of what each function.
 116 .Pp
 117 .Fn rd_new
 118 creates a new
 119 .Nm
 120 agent.
 121 The
 122 .Ft php
 123 argument should be the
 124 .Ft proc_handle
 125 you received from
 126 .Xr libproc 3 .
 127 .Pp
 128 .Fn rd_reset
 129 resets your previously created agent.
 130 .Pp
 131 .Fn rd_delete
 132 deallocates the resources associated with the agent.
 133 .Pp
 134 .Fn rd_errstr
 135 returns an error string describing the error present in
 136 .Ft rderr .
 137 .Pp
 138 .Fn rd_event_enable
 139 enables reporting of events.
 140 This function always returns RD_OK.
 141 .Pp
 142 .Fn rd_event_addr
 143 returns the event address corresponding to the
 144 .Ft event
 145 parameter.
 146 At the moment we only report events of type RD_NOTIFY_BPT.
 147 .Pp
 148 .Fn rd_event_getmsg
 149 returns the message associated with the latest event.
 150 At the moment only RD_POSTINIT events are supported.
 151 .Pp
 152 .Fn rd_loadobj_iter
 153 allows you to iterate over the program's loaded objects.
 154 .Ft cb
 155 is a callback of type
 156 .Fn rl_iter_f .
 157 .Sh RETURN VALUES
 158 Most functions return an
 159 .Ft rd_err_e
 160 type error.
 161 The error codes are described in the header file for this library.
 162 You 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
 171 The
 172 .Nm librtld_db
 173 library first appeared in
 174 .Fx 9.0
 175 and was modeled after the same library present in the Solaris operating system.
 176 .Sh AUTHORS
 177 The
 178 .Nm librtld_db
 179 library and this manual page were written by
 180 .An Rui Paulo Aq Mt rpaulo@FreeBSD.org
 181 under sponsorship from the FreeBSD Foundation.
 182 .Sh CAVEATS
 183 The functions
 184 .Fn rd_event_enable ,
 185 .Fn rd_log ,
 186 .Fn rd_objpad_enable
 187 and
 188 .Fn rd_plt_resolution
 189 are not yet implemented.