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

          --- old/usr/src/man/man3proc/Pgetareg.3proc
          +++ new/usr/src/man/man3proc/Pgetareg.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 PGETAREG 3PROC
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm Pgetareg ,
  19   19  .Nm Pputareg ,
  20   20  .Nm Lgetareg ,
  21   21  .Nm Lputareg
  22   22  .Nd set and get a register from a stopped process or thread
  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 Pgetareg
  28   29  .Fa "struct ps_prochandle *P"
  29   30  .Fa "int regno"
  30   31  .Fa "prgreg_t *preg"
  31   32  .Fc
  32   33  .Ft int
  33   34  .Fo Pputareg
  34   35  .Fa "struct ps_prochandle *P"

  35   36  .Fa "int regno"
  36   37  .Fa "prgreg_t preg"
  37   38  .Fc
  38   39  .Ft int
  39   40  .Fo Lgetareg
  40   41  .Fa "struct ps_lwphandle *L"
  41   42  .Fa "int regno"
  42   43  .Fa "prgreg_t *preg"
  43   44  .Fc
  44   45  .Ft int
  45   46  .Fo Lputareg
  46   47  .Fa "struct ps_lwphandle *L"
  47   48  .Fa "int regno"
  48   49  .Fa "prgreg_t preg"
  49   50  .Fc
  50   51  .Sh DESCRIPTION
  51   52  The
  52   53  .Fn Pgetareg
  53   54  and
  54   55  .Fn Pputareg
  55   56  functions read and update the registers of the process handle referred
  56   57  to by
  57   58  .Fa P .
  58   59  The getting and setting of registers of the process operates on the
  59   60  representative thread (LWP).
  60   61  For more information on how the representative is chosen, see
  61   62  .Xr proc 4 .
  62   63  .Pp
  63   64  To change the registers of a specific thread, use the
  64   65  .Fn Lgetareg
  65   66  and
  66   67  .Fn Lputareg
  67   68  functions.
  68   69  .Pp
  69   70  The getting and setting of registers only applies to stopped processes.
  70   71  In addition, one may obtain registers from core files, but not set them.
  71   72  To stop a process, see the
  72   73  .Xr Pstop 3PROC
  73   74  function.
  74   75  .Pp
  75   76  The register to get or set is indicated by the
  76   77  .Fa regno
  77   78  argument.
  78   79  For a list of registers, see
  79   80  .In sys/regset.h .
  80   81  The set of registers is specific to each architecture of the system.
  81   82  The
  82   83  .Fn Pgetareg
  83   84  function will fill in the value of
  84   85  .Fa preg
  85   86  with the value of the register
  86   87  .Fa regno ,
  87   88  while the
  88   89  .Fn Pputareg
  89   90  function will update the value of the register
  90   91  .Fa regno
  91   92  with the value in
  92   93  .Fa preg .
  93   94  Updated registers will be set when the process resumes execution.
  94   95  .Pp
  95   96  The
  96   97  .Fn Lgetareg
  97   98  and
  98   99  .Fn Lputareg
  99  100  functions are equivalent to the
 100  101  .Fn Pgetareg
 101  102  and
 102  103  .Fn Psetareg
 103  104  functions, except rather than operating on the process and its
 104  105  representative thread, they instead operate on the thread handle
 105  106  .Fa L .
 106  107  .Sh RETURN VALUES
 107  108  Upon successful completion, the
 108  109  .Fn Pgetareg
 109  110  and
 110  111  .Fn Pputareg
 111  112  function return
 112  113  .Sy 0 .
 113  114  Otherwise,
 114  115  .Sy -1
 115  116  is returned,
 116  117  .Sy errno
 117  118  is set, and no registers will have been gotten or updated.
 118  119  .Sh ERRORS
 119  120  The
 120  121  .Fn Pgetareg
 121  122  and
 122  123  .Fn Lgetareg
 123  124  functions will fail if:
 124  125  .Bl -tag -width Er
 125  126  .It Er EINVAL
 126  127  The value of
 127  128  .Fa regno
 128  129  is invalid.
 129  130  This means it is less than
 130  131  .Sy 0
 131  132  and greater than
 132  133  .Sy NPRGREG .
 133  134  Note,
 134  135  .Sy NPRGREG Ns 's
 135  136  value varies based on process architecture.
 136  137  .It Er EBUSY
 137  138  The handle
 138  139  .Fa P
 139  140  is neither stopped nor a core file.
 140  141  .It Er ENODATA
 141  142  The handle
 142  143  .Fa P
 143  144  refers to a file obtained through
 144  145  .Xr Pgrab_file 3PROC .
 145  146  .El
 146  147  .Pp
 147  148  The
 148  149  .Fn Pputareg
 149  150  and
 150  151  .Fn Lputareg
 151  152  functions will fail if:
 152  153  .Bl -tag -width Er
 153  154  .It Er EINVAL
 154  155  The value of
 155  156  .Fa regno
 156  157  is invalid.
 157  158  This means it is less than
 158  159  .Sy 0
 159  160  and greater than
 160  161  .Sy NPRGREG .
 161  162  Note,
 162  163  .Sy NPRGREG Ns 's
 163  164  value varies based on process architecture.
 164  165  .It Er EBUSY
 165  166  The handle
 166  167  .Fa P
 167  168  is not stopped or refers to a non-active process.
 168  169  .El
 169  170  .Sh INTERFACE STABILITY
 170  171  .Sy Uncommitted
 171  172  .Sh MT-LEVEL
 172  173  See
 173  174  .Sy LOCKING
 174  175  in
 175  176  .Xr libproc 3LIB .
 176  177  .Sh SEE ALSO
 177  178  .Xr errno 3C ,
 178  179  .Xr libproc 3LIB ,
 179  180  .Xr Lgrab 3PROC ,
 180  181  .Xr Pgrab_file 3PROC ,
 181  182  .Xr Pstop 3PROC ,
 182  183  .Xr proc 4

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX