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

          --- old/usr/src/man/man3proc/Pmapping_iter.3proc
          +++ new/usr/src/man/man3proc/Pmapping_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 PMAPPING_ITER 3PROC
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm Pmapping_iter ,
  19   19  .Nm Pmapping_iter_resolved ,
  20   20  .Nm Pobject_iter ,
  21   21  .Nm Pobject_iter_resolved
  22   22  .Nd iterate over process mappings and objects
  23      -.Sh SYNOPSIS
       23 +.Sh LIBRARY
  24   24  .Lb libproc
       25 +.Sh SYNOPSIS
  25   26  .In libproc.h
  26   27  .Ft int
  27   28  .Fo Pmapping_iter
  28   29  .Fa "struct ps_prochandle *P"
  29   30  .Fa "proc_map_f *func"
  30   31  .Fa "void *data"
  31   32  .Fc
  32   33  .Ft int
  33   34  .Fo Pmapping_iter_resolved
  34   35  .Fa "struct ps_prochandle *P"

  35   36  .Fa "proc_map_f *func"
  36   37  .Fa "void *data"
  37   38  .Fc
  38   39  .Ft int
  39   40  .Fo Pobject_iter
  40   41  .Fa "struct ps_prochandle *P"
  41   42  .Fa "proc_map_f *func"
  42   43  .Fa "void *data"
  43   44  .Fc
  44   45  .Ft int
  45   46  .Fo Pobject_iter_resolved
  46   47  .Fa "struct ps_prochandle *P"
  47   48  .Fa "proc_map_f *func"
  48   49  .Fa "void *data"
  49   50  .Fc
  50   51  .Sh DESCRIPTION
  51   52  The
  52   53  .Fn Pmapping_iter
  53   54  and
  54   55  .Fn Pmapping_iter_resolved
  55   56  functions iterate over the memory mappings in the process represented by
  56   57  .Fa P.
  57   58  .Pp
  58   59  For each memory mapping, the callback function
  59   60  .Fa func
  60   61  will be invoked and it will be passed the
  61   62  .Fa data
  62   63  argument,
  63   64  the
  64   65  .Sy prmap_t
  65   66  structure defined from
  66   67  .Xr proc 4 ,
  67   68  and a name of the mapping.
  68   69  The way that the name is obtained varies based on whether one calls
  69   70  .Fn Pmapping_iter
  70   71  or
  71   72  .Fn Pmapping_iter_resolved .
  72   73  In both cases, the dynamic linker is consulted to determine the file
  73   74  name for the mapping, if it's known.
  74   75  If the name is unknown, for example an anonymous mapping, then the
  75   76  .Dv NULL
  76   77  pointer is passed in for the name.
  77   78  In the case of the
  78   79  .Fn Pmapping_iter_resolved
  79   80  function the system tries to resolve it to a complete file system path.
  80   81  If that fails, it falls back to the information from the dynamic linker,
  81   82  before returning
  82   83  .Dv NULL
  83   84  in the case of not being able to find any name.
  84   85  For more information on the
  85   86  signature of the
  86   87  .Ft proc_map_f ,
  87   88  see
  88   89  .Xr libproc 3LIB .
  89   90  .Pp
  90   91  The return value of
  91   92  .Fa func
  92   93  controls whether or not iteration continues.
  93   94  If
  94   95  .Fa func
  95   96  returns
  96   97  .Sy 0
  97   98  then iteration continues.
  98   99  If
  99  100  .Fa func
 100  101  returns non-zero then iteration will halt and the value will be
 101  102  returned to the caller.
 102  103  Because
 103  104  .Sy -1
 104  105  indicates internal failure, it is recommended that the callback function not
 105  106  return
 106  107  .Sy -1
 107  108  to indicate an error itself.
 108  109  This allows the caller to distinguish between failure of the callback function
 109  110  versus failure of the
 110  111  .Fn Pmapping_iter
 111  112  and
 112  113  .Fn Pmapping_iter_resolved
 113  114  functions.
 114  115  .Pp
 115  116  The
 116  117  .Fn Pobject_iter
 117  118  and
 118  119  .Fn Pobject_iter_resolved
 119  120  functions are similar to the
 120  121  .Fn Pmapping_iter
 121  122  and
 122  123  .Fn Pmapping_iter_resolved
 123  124  functions.
 124  125  Except, rather than iterating over every mapping, they iterate over the objects
 125  126  that the process has loaded by the dynamic linker.
 126  127  For example, an anonymous mapping will show up when iterating mappings, but will
 127  128  not show up when iterating objects.
 128  129  Further, while most dynamic shared objects have multiple mappings for the text
 129  130  and data sections, there will only be a single object that is iterated over.
 130  131  .Pp
 131  132  The distinction between the
 132  133  .Fn Pobject_iter
 133  134  and
 134  135  .Fn Pobject_iter_resolved
 135  136  functions is identical to the difference in name resolution between the
 136  137  .Fn Pmapping_iter
 137  138  and
 138  139  .Fn Pmapping_iter_resolved
 139  140  functions.
 140  141  .Sh RETURN VALUES
 141  142  Upon successful completion, the
 142  143  .Fn Pmapping_iter ,
 143  144  .Fn Pmapping_iter_resolved
 144  145  .Fn Pobject_iter ,
 145  146  and
 146  147  .Fn Pobject_iter_resolved
 147  148  functions return
 148  149  .Sy 0.
 149  150  Otherwise, if there was an internal error then
 150  151  .Sy -1
 151  152  is returned.
 152  153  Otherwise, if the callback function
 153  154  .Fa func
 154  155  returns non-zero, then its return value will be returned instead.
 155  156  .Sh INTERFACE STABILITY
 156  157  .Sy Uncommitted
 157  158  .Sh MT-LEVEL
 158  159  See
 159  160  .Sy LOCKING
 160  161  in
 161  162  .Xr libproc 3LIB .
 162  163  .Sh SEE ALSO
 163  164  .Xr libproc 3LIB ,
 164  165  .Xr proc 4

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX