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

          --- old/usr/src/man/man3proc/Plwp_iter.3proc
          +++ new/usr/src/man/man3proc/Plwp_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 PLWP_ITER 3PROC
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm Plwp_iter ,
  19   19  .Nm Plwp_iter_all
  20   20  .Nd iterate over threads
  21      -.Sh SYNOPSIS
       21 +.Sh LIBRARY
  22   22  .Lb libproc
       23 +.Sh SYNOPSIS
  23   24  .In libproc.h
  24   25  .Ft int
  25   26  .Fo Plwp_iter
  26   27  .Fa "struct ps_prochandle *P"
  27   28  .Fa "proc_lwp_f *func",
  28   29  .Fa "void *data"
  29   30  .Fc
  30   31  .Ft int
  31   32  .Fo Plwp_iter_all
  32   33  .Fa "struct ps_prochandle *P"

  33   34  .Fa "proc_lwp_all_f *func"
  34   35  .Fa "void *data"
  35   36  .Fc
  36   37  .Sh DESCRIPTION
  37   38  The
  38   39  .Fn Plwp_iter
  39   40  and
  40   41  .Fn Plwp_iter_all
  41   42  functions iterates over threads in the given process handle
  42   43  .Fa P .
  43   44  The
  44   45  .Fn Plwp_iter
  45   46  function iterates over all active threads, where as the
  46   47  .Fn Plwp_iter_all
  47   48  function iterates over both active threads and zombie threads -- threads
  48   49  waiting to be reaped.
  49   50  .Pp
  50   51  For each thread, the callback function
  51   52  .Fa func
  52   53  is called with the pointer to the private data argument,
  53   54  .Fa data ,
  54   55  and the thread's
  55   56  .Sy lwpstatus_t
  56   57  structure.
  57   58  In the case of the
  58   59  .Fn Plwp_iter_all
  59   60  function, the thread's
  60   61  .Sy lwpsinfo_t
  61   62  is also included.
  62   63  .Pp
  63   64  The return value of
  64   65  .Fa func
  65   66  controls whether or not iteration continues.
  66   67  If
  67   68  .Fa func
  68   69  returns
  69   70  .Sy 0 ,
  70   71  then both functions will continue iteration.
  71   72  However, if
  72   73  .Fa func
  73   74  returns non-zero, then iteration will halt and that value will be used
  74   75  as the return value of the
  75   76  .Fn Plwp_iter
  76   77  and
  77   78  .Fn Plwp_iter_all
  78   79  functions.
  79   80  Because both functions return
  80   81  .Sy -1
  81   82  on internal failure, it is recommended that the callback function does
  82   83  not return
  83   84  .Sy -1
  84   85  to indicate an error so that the caller may distinguish between the
  85   86  failure of the callback function and the failure of the
  86   87  .Fn Plwp_iter
  87   88  and
  88   89  .Fn Plwp_iter_all
  89   90  functions.
  90   91  .Sh RETURN VALUES
  91   92  Upon successful completion, the
  92   93  .Fn Plwp_iter
  93   94  and
  94   95  .Fn Plwp_iter_all
  95   96  functions return
  96   97  .Sy 0 .
  97   98  Otherwise, if there was an internal error or there is no thread data, then
  98   99  .Sy -1
  99  100  is returned.
 100  101  Otherwise, if the callback function
 101  102  .Fa func
 102  103  returns non-zero, then its return value will be returned instead.
 103  104  .Sh INTERFACE STABILITY
 104  105  .Sy Uncommitted
 105  106  .Sh MT-LEVEL
 106  107  See
 107  108  .Sy LOCKING
 108  109  in
 109  110  .Xr libproc 3LIB .
 110  111  .Sh SEE ALSO
 111  112  .Xr libproc 3LIB

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX