lib/libexecinfo/backtrace.3

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