lib/libexecinfo/backtrace.3

   1 .\"     $NetBSD: backtrace.3,v 1.5 2013/08/22 17:08:43 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2012 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd May 26, 2012
  31 .Dt BACKTRACE 3
  32 .Os
  33 .Sh NAME
  34 .Nm backtrace
  35 .Nd fill in the backtrace of the currently executing thread
  36 .Sh LIBRARY
  37 .Lb libexecinfo
  38 .Sh SYNOPSIS
  39 .In execinfo.h
  40 .Ft size_t
  41 .Fn backtrace "void **addrlist" "size_t len"
  42 .Ft "char **"
  43 .Fn backtrace_symbols "void * const *addrlist" "size_t len"
  44 .Ft int
  45 .Fn backtrace_symbols_fd "void * const *addrlist" "size_t len" "int fd"
  46 .Ft "char **"
  47 .Fn backtrace_symbols_fmt "void * const *addrlist" "size_t len" "const char *fmt"
  48 .Ft int
  49 .Fn backtrace_symbols_fmt_fd "void * const *addrlist" "size_t len" "const char *fmt" "int fd"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn backtrace
  53 function places into the array pointed by
  54 .Fa addrlist
  55 the array of the values of the program counter for each frame called up to
  56 .Fa len
  57 frames.
  58 The number of frames found (which can be fewer than
  59 .Fa len )
  60 is returned.
  61 .Pp
  62 The
  63 .Fn backtrace_symbols_fmt
  64 function takes an array of previously filled addresses from
  65 .Fn backtrace
  66 in
  67 .Fa addrlist
  68 of
  69 .Fa len
  70 elements, and uses
  71 .Fa fmt
  72 to format them.
  73 The formatting characters available are:
  74 .Bl -tag -width a -offset indent
  75 .It Dv a
  76 The numeric address of each element as would be printed using %p.
  77 .It Dv n
  78 The name of the nearest function symbol (smaller than the address element)
  79 as determined by
  80 .Xr dladdr 3
  81 if the symbol was dynamic, or looked up in the executable if static and
  82 the /proc filesystem is available to determine the executable path.
  83 .It Dv d
  84 The difference of the symbol address and the address element printed
  85 using 0x%tx.
  86 .It Dv D
  87 The difference of the symbol addresss and the address element printed using
  88 +0x%tx if non-zero, or nothing if zero.
  89 .It Dv f
  90 The filename of the symbol as determined by
  91 .Xr dladdr 3 .
  92 .El
  93 .Pp
  94 The array of formatted strings is returned as a contiguous memory address which
  95 can be freed by a single
  96 .Xr free 3 .
  97 .Pp
  98 The
  99 .Fn backtrace_symbols
 100 function is equivalent of calling
 101 .Fn backtrace_symbols_fmt
 102 with a format argument of
 103 .Dv "%a <%n%D> at %f"
 104 .Pp
 105 The
 106 .Fn backtrace_symbols_fd
 107 and
 108 .Fn backtrace_symbols_fmt_fd
 109 are similar to the non _fd named functions, only instead of returning
 110 an array or strings, they print a new-line separated array of strings in
 111 fd, and return
 112 .Dv 0
 113 on success and
 114 .Dv \-1
 115 on failure.
 116 .Sh RETURN VALUES
 117 The
 118 .Fn backtrace
 119 function returns the number of elements that were filled in the backtrace.
 120 The
 121 .Fn backtrace_symbols
 122 and
 123 .Fn backtrace_symbols_fmt
 124 return a string array on success, and
 125 .Dv NULL
 126 on failure, setting
 127 .Va errno .
 128 Diagnostic output may also be produced by the ELF symbol lookup functions.
 129 .Sh SEE ALSO
 130 .Xr dladdr 3 ,
 131 .Xr elf 3
 132 .Sh HISTORY
 133 The
 134 .Fn backtrace
 135 library of functions first appeared in
 136 .Nx 7.0 .
 137 .Sh BUGS
 138 .Bl -enum
 139 .It
 140 Errors should not be printed but communicated to the caller differently.
 141 .It
 142 Because these functions use
 143 .Xr elf 3
 144 this is a separate library instead of being part of libc/libutil
 145 so that no library dependencies are introduced.
 146 .It
 147 The Linux versions of the functions (there are no _fmt variants) use
 148 .Ft int
 149 instead of
 150 .Ft size_t
 151 arguments.
 152 .It
 153 Since
 154 .Xr dladdr 3
 155 only deals with dynamic symbols, we need to find the symbols from the main
 156 portion of the program.
 157 For that we need to locate the executable, and we use procfs for
 158 finding it, which is not portable.
 159 .El