8158 Want named threads API
9857 proc manpages should have LIBRARY section

          --- old/usr/src/man/man3proc/Pstack_iter.3proc
          +++ new/usr/src/man/man3proc/Pstack_iter.3proc

   1    1  .\"
   2    2  .\" This file and its contents are supplied under the terms of the
   3    3  .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4    4  .\" You may only use this file in accordance with the terms of version
   5    5  .\" 1.0 of the CDDL.
   6    6  .\"
   7    7  .\" A full copy of the text of the CDDL should have accompanied this
   8    8  .\" source.  A copy of the CDDL is also available via the Internet at
   9    9  .\" http://www.illumos.org/license/CDDL.

  10   10  .\"
  11   11  .\"
  12   12  .\" Copyright 2015 Joyent, Inc.
  13   13  .\"
  14   14  .Dd May 11, 2016
  15   15  .Dt PSTACK_ITER 3PROC
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm Pstack_iter
  19   19  .Nd iterate process stack frames
  20      -.Sh SYNOPSIS
       20 +.Sh LIBRARY
  21   21  .Lb libproc
       22 +.Sh SYNOPSIS
  22   23  .In libproc.h
  23   24  .Ft int
  24   25  .Fo Pstack_iter
  25   26  .Fa "struct ps_prochandle *P"
  26   27  .Fa "const prgregset_t regs"
  27   28  .Fa "proc_stack_f *func"
  28   29  .Fa "void *data"
  29   30  .Fc
  30   31  .Sh DESCRIPTION
  31   32  The

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

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX