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