usr/src/man/man3c/walkcontext.3c

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH WALKCONTEXT 3C "Apr 10, 2007"
   7 .SH NAME
   8 walkcontext, addrtosymstr, printstack, backtrace, backtrace_symbols,
   9 backtrace_symbols_fd \- walk stack pointed to by ucontext
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <ucontext.h>
  14
  15 \fBint\fR \fBwalkcontext\fR(\fBconst ucontext_t *\fR\fIuptr\fR,
  16      \fBint (*\fR\fIoperate_func\fR)(uintptr_t, int, void *), \fBvoid *\fR\fIusrarg\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBaddrtosymstr\fR(\fBuintptr_t\fR \fIaddr\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIlen\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBprintstack\fR(\fBint\fR \fIfd\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 #include <execinfo.h>
  32
  33 \fBint\fR \fBbacktrace\fR(\fBvoid **\fR\fIbuffer\fR, \fBint\fR \fIsize\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBchar **\fR\fBbacktrace_symbols\fR(\fBvoid *const *\fR\fIbuffer\fR, \fBint\fR \fIsize\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBvoid\fR \fBbacktrace_symbols_fd\fR(\fBvoid *const *\fR\fIbuffer\fR, \fBint\fR \fIsize\fR, \fBint\fR \fIfd\fR);
  44 .fi
  45
  46 .SH DESCRIPTION
  47 .sp
  48 .LP
  49 The \fBwalkcontext()\fR function walks the call stack pointed to by \fIuptr\fR,
  50 which can be obtained by a call to \fBgetcontext\fR(2) or from a signal handler
  51 installed with the \fBSA_SIGINFO\fR flag.  The \fBwalkcontext()\fR function
  52 calls the user-supplied function \fIoperate_func\fR for each routine found on
  53 the call stack and each signal handler invoked. The user function is passed
  54 three arguments: the PC at which the call or signal occurred, the signal number
  55 that occurred at this PC (0 if no signal occurred), and the third argument
  56 passed to \fBwalkcontext()\fR. If the user function returns a non-zero value,
  57 \fBwalkcontext()\fR returns without completing the callstack walk.
  58 .sp
  59 .LP
  60 The \fBaddrtosymstr()\fR function attempts to convert a PC into a symbolic
  61 representation of the form
  62 .sp
  63 .in +2
  64 .nf
  65 \fIobjname\fR'\fIfuncname\fR+0x\fIoffset\fR[0xPC]
  66 .fi
  67 .in -2
  68
  69 .sp
  70 .LP
  71 where \fIobjname\fR is the module in which the PC is located, \fIfuncname\fR is
  72 the name of the function, and \fIoffset\fR is the offset from the beginning of
  73 the function. The \fIobjname\fR, \fIfuncname\fR, and \fIoffset\fR values are
  74 obtained from \fBdladdr\fR(3C) and might not always be present. The resulting
  75 string is written to the user-supplied buffer. Should the length of the string
  76 be larger than the user-supplied buffer, only the portion of the string that
  77 will fit is written and null-terminated.
  78 .sp
  79 .LP
  80 The \fBprintstack()\fR function uses \fBwalkcontext()\fR to print a symbolic
  81 stack trace to the specified file descriptor. This is useful for reporting
  82 errors from signal handlers. The \fBprintstack()\fR function uses
  83 \fBdladdr1()\fR (see \fBdladdr\fR(3C)) to obtain symbolic symbol names. As a
  84 result, only global symbols are reported as symbol names by \fBprintstack()\fR.
  85 .sp
  86 .LP
  87 The \fBbacktrace()\fR function uses \fBwalkcontext()\fR to generate a stack's
  88 program counter values for the calling thread and place these values into the
  89 array specified by the buffer argument. The \fIsize\fR argument specifies the
  90 maximum number of program counters that will be recorded.  This function is
  91 provided for compatibility with the GNU \fBlibc\fR used on Linux systems,
  92 \fBglibc\fR.
  93 .sp
  94 .LP
  95 The \fBbacktrace_symbols()\fR function translates the numerical program counter
  96 values previously recorded by a call to \fBbacktrace()\fR in the \fIbuffer\fR
  97 argument, and converts, where possible, each PC to a string indicating the
  98 module, function and offset of each call site. The number of symbols present in
  99 the array must be passed in with the \fIsize\fR argument.
 100 .sp
 101 .LP
 102 The set of strings is returned in an array obtained from a call to
 103 \fBmalloc\fR(3C). It is the responsibility of the caller to pass the returned
 104 pointer to \fBfree()\fR.  The individual strings must not be freed.  Since
 105 \fBmalloc()\fR is used to obtain the needed space, this function is MT-Safe
 106 rather than Async-Signal-Safe and cannot be used reliably from a signal
 107 handler.  This function is provided for \fBglibc\fR compatibility.
 108 .sp
 109 .LP
 110 The \fBbacktrace_symbols_fd()\fR function translates the numerical program
 111 counter values previously recorded by a call to \fBbacktrace()\fR in the buffer
 112 argument, and converts, where possible, each PC to a string indicating the
 113 module, function, and offset of each call site. These strings are written to
 114 the file descriptor specified in the \fIfd\fR argument. This function is
 115 provided for \fBglibc\fR compatibility.
 116 .SH RETURN VALUES
 117 .sp
 118 .LP
 119 Upon successful completion, \fBwalkcontext()\fR and \fBprintstack()\fR return
 120 0.  If \fBwalkcontext()\fR cannot read the stack or the stack trace appears
 121 corrupted, both functions return -1.
 122 .sp
 123 .LP
 124 The \fBaddrtosymstr()\fR function returns the number of characters necessary to
 125 hold the entire string representation of the passed in address, irrespective of
 126 the size of the user-supplied buffer.
 127 .sp
 128 .LP
 129 The \fBbacktrace()\fR function returns the number of stack frames captured.
 130 .sp
 131 .LP
 132 The \fBbacktrace_symbols()\fR function returns a pointer to an array containing
 133 string representations of the calling sequence.
 134 .SH ERRORS
 135 .sp
 136 .LP
 137 No error values are defined.
 138 .SH USAGE
 139 .sp
 140 .LP
 141 The \fBwalkcontext()\fR function is typically used to obtain information about
 142 the call stack for error reporting, performance analysis, or diagnostic
 143 purposes. Many library functions are not Async-Signal-Safe and should not be
 144 used from a signal handler. If \fBwalkcontext()\fR is to be called from a
 145 signal handler, careful programming is required.  In particular,
 146 \fBstdio\fR(3C) and \fBmalloc\fR(3C) cannot be used.
 147 .sp
 148 .LP
 149 The \fBwalkstack()\fR, \fBaddrtosymstr()\fR, \fBprintstack()\fR,
 150 \fBbacktrace()\fR, and \fBbacktrace_symbols_fd()\fR functions are
 151 Async-Signal-Safe and can be called  from  a  signal  handler.  The string
 152 representation generated by \fBaddrtosymstr()\fR and displayed by
 153 \fBprintstack()\fR, \fBbacktrace_symbols()\fR and \fBbacktrace_symbols_fd()\fR
 154 is unstable and will change depending on the information available in the
 155 modules that comprise the stack trace.
 156 .sp
 157 .LP
 158 Tail-call optimizations on SPARC eliminate stack frames that would otherwise be
 159 present.  For example, if the code is of the form
 160 .sp
 161 .in +2
 162 .nf
 163 #include <stdio.h>
 164
 165 main()
 166 {
 167         bar();
 168         exit(0);
 169 }
 170
 171 bar()
 172 {
 173         int a;
 174         a = foo(fileno(stdout));
 175         return (a);
 176 }
 177
 178 foo(int file)
 179 {
 180         printstack(file);
 181 }
 182 .fi
 183 .in -2
 184
 185 .sp
 186 .LP
 187 compiling without optimization will yield a stack trace of the form
 188 .sp
 189 .in +2
 190 .nf
 191 /tmp/q:foo+0x8
 192 /tmp/q:bar+0x14
 193 /tmp/q:main+0x4
 194 /tmp/q:_start+0xb8
 195 .fi
 196 .in -2
 197
 198 .sp
 199 .LP
 200 whereas with higher levels of optimization the output is
 201 .sp
 202 .in +2
 203 .nf
 204 /tmp/q:main+0x10
 205 /tmp/q:_start+0xb8
 206 .fi
 207 .in -2
 208
 209 .sp
 210 .LP
 211 since both the call to \fBfoo()\fR in main and the call to \fBbar()\fR in
 212 \fBfoo()\fR are handled as tail calls that perform a return or restore in the
 213 delay slot. For further information, see \fIThe SPARC Architecture Manual\fR.
 214 .SH ATTRIBUTES
 215 .sp
 216 .LP
 217 See \fBattributes\fR(5) for descriptions of the following attributes:
 218 .sp
 219
 220 .sp
 221 .TS
 222 box;
 223 c | c
 224 l | l .
 225 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 226 _
 227 Interface Stability     Stable
 228 _
 229 MT-Level        See below.
 230 .TE
 231
 232 .sp
 233 .LP
 234 The \fBbacktrace_symbols()\fR function is MT-Safe. The remaining functions are
 235 Async-Signal-Safe.
 236 .SH SEE ALSO
 237 .sp
 238 .LP
 239 \fBIntro\fR(2), \fBgetcontext\fR(2), \fBsigaction\fR(2), \fBdladdr\fR(3C),
 240 \fBsiginfo.h\fR(3HEAD), \fBattributes\fR(5)
 241 .sp
 242 .LP
 243 Weaver, David L. and Tom Germond, eds. \fIThe SPARC Architecture Manual\fR,
 244 Version 9. Santa Clara: Prentice Hall, 2000.