usr/src/man/man3proc/Pstack_iter.3proc

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd May 11, 2016
  15 .Dt PSTACK_ITER 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pstack_iter
  19 .Nd iterate process stack frames
  20 .Sh LIBRARY
  21 .Lb libproc
  22 .Sh SYNOPSIS
  23 .In libproc.h
  24 .Ft int
  25 .Fo Pstack_iter
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "const prgregset_t regs"
  28 .Fa "proc_stack_f *func"
  29 .Fa "void *data"
  30 .Fc
  31 .Sh DESCRIPTION
  32 The
  33 .Fn Pstack_iter
  34 function iterates over the stack frames in the process
  35 .Fa P
  36 starting at the point defined by
  37 .Fa regs .
  38 .Pp
  39 For each valid stack frame encountered, the callback function
  40 .Fa func
  41 is invoked with
  42 .Fa data
  43 passed as argument.
  44 The full signature of
  45 .Ft proc_stack_f
  46 is defined in
  47 .Xr libproc 3LIB .
  48 With each callback, a register set, argument set, and argument count
  49 will be provided.
  50 In that register set, only a subset of the registers will be valid, which
  51 include the frame pointer, program counter, and on SPARC systems, the next
  52 program counter.
  53 These registers can be accessed with the constants
  54 .Sy R_FP ,
  55 .Sy R_PC ,
  56 and
  57 .Sy R_nPC
  58 respectively.
  59 These correspond to the registers
  60 .Em %ebp
  61 and
  62 .Em %eip
  63 on i386,
  64 .Em %rbp
  65 and
  66 .Em %rip
  67 on amd64,
  68 .Em %fp ,
  69 .Em %pc ,
  70 and
  71 .Em %npc
  72 on both SPARC and SPARCv9.
  73 .Pp
  74 Callers will receive a callback for the first stack frame indicated by
  75 .Fa regs
  76 and then will receive a subsequent callback for each caller of that
  77 frame until no such frame can be found.
  78 Stack frames that logically come after the frame indicated by
  79 .Fa regs
  80 will not receive callbacks.
  81 .Pp
  82 The compiler can either facilitate or stymie the iteration of the stack.
  83 Programs that have been compiled in such a way as to omit the frame pointer will
  84 result in truncated stacks.
  85 Similarly, if the initial set of registers passed in via
  86 .Fa regs
  87 is invalid, then the ability to iterate the stack will be limited.
  88 The return value of
  89 .Fa func
  90 controls whether or not iteration continues.
  91 If
  92 .Fa func
  93 returns
  94 .Sy 0
  95 then iteration continues.
  96 However, if
  97 .Fa func
  98 returns non-zero, then iteration will halt and that value will be used
  99 as the return value of the
 100 .Fn Pstack_iter
 101 function.
 102 Because
 103 .Fn Pstack_iter
 104 returns
 105 .Sy -1
 106 on internal failure it is recommended the callback function not return
 107 .Sy -1
 108 to indicate an error.
 109 Thus the caller may distinguish between the failure of the callback function and
 110 the failure of the
 111 .Fn Pstack_iter
 112 function.
 113 .Sh RETURN VALUES
 114 Upon successful completion, the
 115 .Fn Pstack_iter
 116 function returns
 117 .Sy 0.
 118 If there was an internal error then
 119 .Sy -1
 120 is returned.
 121 Otherwise, if the callback function
 122 .Fa func
 123 returns non-zero, then its return value will be returned instead.
 124 .Sh INTERFACE STABILITY
 125 .Sy Uncommitted
 126 .Sh MT-LEVEL
 127 See
 128 .Sy LOCKING
 129 in
 130 .Xr libproc 3LIB .
 131 .Sh SEE ALSO
 132 .Xr libproc 3LIB ,
 133 .Xr proc 4