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

          --- old/usr/src/man/man3proc/Pgrab_file.3proc
          +++ new/usr/src/man/man3proc/Pgrab_file.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 PGRAB_FILE 3PROC
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm Pgrab_file
  19   19  .Nd grab and inspect an ELF object
  20      -.Sh SYNOPSIS
       20 +.Sh LIBRARY
  21   21  .Lb libproc
       22 +.Sh SYNOPSIS
  22   23  .In libproc.h
  23   24  .Ft struct ps_prochandle
  24   25  .Fo Pgrab_file
  25   26  .Fa "const char *fname"
  26   27  .Fa "int *perr"
  27   28  .Fc
  28   29  .Sh DESCRIPTION
  29   30  The
  30   31  .Fn Pgrab_file
  31   32  function creates a handle to the ELF object contained in file

  32   33  .Fa fname .
  33   34  This handle is considered an
  34   35  .Em idle
  35   36  handle, it allows one to inspect aspects of the ELF contents present in
  36   37  the handle, for example obtaining CTF information and looking up
  37   38  symbols.
  38   39  .Pp
  39   40  There is no running state associated with this handle nor can there be.
  40   41  If one intends to control a running process or create a process, see
  41   42  .Xr Pgrab 3PROC
  42   43  and
  43   44  .Xr Pcreate 3PROC
  44   45  respectively.
  45   46  To inspect a core file use
  46   47  .Xr Pgrab_core 3PROC .
  47   48  .Pp
  48   49  The
  49   50  .Fa perr
  50   51  argument must be a
  51   52  .Pf non- Dv NULL
  52   53  pointer which will store a more detailed error in the event that
  53   54  .Fn Pgrab_file
  54   55  fails.
  55   56  A human-readable form of the error can be obtained with
  56   57  .Xr Pgrab_error 3PROC .
  57   58  .Pp
  58   59  When finished with the returned handle,
  59   60  .Xr Prelease 3PROC
  60   61  must be called to clean up resources associated with it.
  61   62  .Sh RETURN VALUES
  62   63  Upon successful completion, the
  63   64  .Fn Pgrab_file
  64   65  function returns a control handle to the process.
  65   66  Otherwise,
  66   67  .Dv NULL
  67   68  is returned and
  68   69  .Fa perr
  69   70  is filled in with an error code.
  70   71  .Sh ERRORS
  71   72  .Bl -tag -width Er -offset indent
  72   73  .It Er G_ELF
  73   74  An unexpected
  74   75  .Xr libelf 3LIB
  75   76  failure occurred while processing the file named by
  76   77  .Fa fname .
  77   78  .It Er G_FORMAT
  78   79  The file named by
  79   80  .Fa fname
  80   81  is not a valid ELF file.
  81   82  .It Er G_NOEXEC
  82   83  The file named by
  83   84  .Fa fname
  84   85  does not exist.
  85   86  .It Er G_STRANGE
  86   87  An unanticipated system error occurred while trying to grab the
  87   88  file
  88   89  .Fa fname
  89   90  and create the handle.
  90   91  The value of
  91   92  .Sy errno
  92   93  indicates the system failure.
  93   94  .El
  94   95  .Sh INTERFACE STABILITY
  95   96  .Sy Uncommitted
  96   97  .Sh MT-LEVEL
  97   98  .Sy MT-Safe
  98   99  .Sh SEE ALSO
  99  100  .Xr errno 3C ,
 100  101  .Xr libelf 3LIB ,
 101  102  .Xr libproc 3LIB ,
 102  103  .Xr Pfree 3PROC ,
 103  104  .Xr Pgrab_core 3PROC ,
 104  105  .Xr Pgrab_error 3PROC ,
 105  106  .Xr Prelease 3PROC

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX