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

          --- old/usr/src/man/man3proc/Paddr_to_map.3proc
          +++ new/usr/src/man/man3proc/Paddr_to_map.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 PADDR_TO_MAP 3PROC
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm Paddr_to_map ,
  19   19  .Nm Paddr_to_text_map ,
  20   20  .Nm Plmid_to_map ,
  21   21  .Nm Pname_to_map
  22   22  .Nd lookup memory map information
  23      -.Sh SYNOPSIS
       23 +.Sh LIBRARY
  24   24  .Lb libproc
       25 +.Sh SYNOPSIS
  25   26  .In libproc.h
  26   27  .Ft "const prmap_t *"
  27   28  .Fo Paddr_to_map
  28   29  .Fa "struct ps_prochandle *P"
  29   30  .Fa "uintptr_t addr"
  30   31  .Fc
  31   32  .Ft "const prmap_t *"
  32   33  .Fo Paddr_to_text_map
  33   34  .Fa "struct ps_prochandle *P"
  34   35  .Fa "uintptr_t addr"

  35   36  .Fc
  36   37  .Ft "const prmap_t *"
  37   38  .Fo Plmid_to_map
  38   39  .Fa "struct ps_prochandle *P"
  39   40  .Fa "Lmid_t lmid"
  40   41  .Fa "const char *name"
  41   42  .Fc
  42   43  .Ft "const prmap_t *"
  43   44  .Fo Pname_to_map
  44   45  .Fa "struct ps_prochandle *P"
  45   46  .Fa "const char *name"
  46   47  .Fc
  47   48  .Sh DESCRIPTION
  48   49  The
  49   50  .Fn Paddr_to_map ,
  50   51  .Fn Paddr_to_text_map ,
  51   52  .Fn Plmid_to_map ,
  52   53  and
  53   54  .Fn Pname_to_map
  54   55  functions lookup memory map information in the process handle
  55   56  .Fa P .
  56   57  The
  57   58  .Sy prmap_t
  58   59  structure provides information such as the size, offset, and object of
  59   60  the mapping and is defined in
  60   61  .Xr proc 4 .
  61   62  .Pp
  62   63  The pointer to the data returned by the library will only be valid for
  63   64  as long as the handle
  64   65  .Fa P
  65   66  is valid.
  66   67  Any calls to
  67   68  .Xr Prelease 3PROC
  68   69  will invalidate the data.
  69   70  .Pp
  70   71  The
  71   72  .Fn Paddr_to_map
  72   73  function attempts to find the mapping information corresponding to the
  73   74  address
  74   75  .Fa addr .
  75   76  .Pp
  76   77  The
  77   78  .Fn Paddr_to_text_map
  78   79  function is similar to the
  79   80  .Fn Paddr_to_map
  80   81  function; however, it only returns successfully if the specified address
  81   82  corresponds to a text mapping as identified by the run-time link-editor.
  82   83  One use of this is to ensure that a mapping is actually a text-mapping
  83   84  before inserting a breakpoint in it.
  84   85  .Pp
  85   86  The
  86   87  .Fn Pname_to_map
  87   88  function looks up the object named
  88   89  .Fa name
  89   90  and returns the corresponding mapping information.
  90   91  Two special values may be used for name.
  91   92  The macro
  92   93  .Dv PR_OBJ_EXEC
  93   94  refers to the executable object itself and the macro
  94   95  .Dv PR_OBJ_LDSO refers to the object ld.so.1 .
  95   96  .Pp
  96   97  The
  97   98  .Fn Plmid_to_map
  98   99  function is similar to
  99  100  .Fn Pname_to_map .
 100  101  It allows passing a link-map identifier,
 101  102  .Fa lmid ,
 102  103  which constricts the search of the object named with
 103  104  .Fa name
 104  105  to that link-map.
 105  106  The special value of
 106  107  .Dv PR_LMID_EVERY
 107  108  may be passed to indicate that every link-map should be searched, which
 108  109  is equivalent in behavior to the
 109  110  .Fn Pname_to_map
 110  111  function.
 111  112  .Sh RETURN VALUES
 112  113  Upon successful completion, the
 113  114  .Fn Paddr_to_map ,
 114  115  .Fn Paddr_to_text_map ,
 115  116  .Fn Plmid_to_map ,
 116  117  and
 117  118  .Fn Pname_to_map
 118  119  functions return a pointer to the corresponding mapping information.
 119  120  If none exists then
 120  121  .Dv NULL
 121  122  is returned.
 122  123  .Sh INTERFACE STABILITY
 123  124  .Sy Uncommitted
 124  125  .Sh MT-LEVEL
 125  126  See
 126  127  .Sy LOCKING
 127  128  in
 128  129  .Xr libproc 3LIB .
 129  130  .Sh SEE ALSO
 130  131  .Xr libproc 3LIB ,
 131  132  .Xr Prelease 3PROC ,
 132  133  .Xr proc 4

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX