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