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

          --- old/usr/src/man/man3proc/Pgrab_core.3proc.man.txt
          +++ new/usr/src/man/man3proc/Pgrab_core.3proc.man.txt
   1    1  PGRAB_CORE(3PROC)      Process Control Library Functions     PGRAB_CORE(3PROC)
   2    2  
   3    3  NAME
   4    4       Pgrab_core, Pfgrab_core - grab a core file
   5    5  
   6      -SYNOPSIS
        6 +LIBRARY
   7    7       Process Control Library (libproc, -lproc)
        8 +
        9 +SYNOPSIS
   8   10       #include <libproc.h>
   9   11  
  10   12       struct ps_prochandle *
  11   13       Pgrab_core(const char *core, const char *aout, int gflag, int *perr);
  12   14  
  13   15       struct ps_prochandle *
  14   16       Pfgrab_core(int core_fd, const char *aout, int *perr);
  15   17  
  16   18  DESCRIPTION
  17   19       The Pgrab_core() and Pfgrab_core() functions open a core file for

  18   20       introspection.  Unlike live processes, core files cannot have their state
  19   21       modified; however, all of the functions that iterate or query state will
  20   22       work.  These functions work on all illumos core files and the core files
  21   23       of some other operating systems.  See both core(4) and the Core Files
  22   24       section of libproc(3LIB) for more information.
  23   25  
  24   26       The Pgrab_core() function attempts to open the core file specified by
  25   27       core.  The system attempts to determine the path of the original
  26   28       executable.  The argument aout may either be the path to that file, a
  27   29       path to a directory to search, or the NULL pointer, if neither is known.
  28   30       The system will search for it and will supplement information in the core
  29   31       file with that.
  30   32  
  31   33       The gflag argument to the Pgrab_core() function controls how the file is
  32   34       opened.  If the PGRAB_RDONLY flag is specified, then the core file will
  33   35       be opened with the open(2) flag O_RDONLY.  Otherwise, it will be opened
  34   36       O_RDWR.
  35   37  
  36   38       The perr argument must be a non-NULL pointer which will store a more
  37   39       detailed error in the event that the Pgrab_core() function fails.  A
  38   40       human-readable form of the error can be obtained through the routine
  39   41       Pgrab_error(3PROC).
  40   42  
  41   43       The Pfgrab_core() is similar to the Pgrab_core() function.  Except,
  42   44       instead of operating on a path, it opens a handle to the core file
  43   45       referenced by core_fd.  The aout and perr arguments are identical to
  44   46       those in the Pgrab_core() function.
  45   47  
  46   48       The handle returned, from either function, is valid until it is closed
  47   49       with Prelease(3PROC) or Pfree(3PROC).
  48   50  
  49   51  RETURN VALUES
  50   52       Upon successful completion, the Pgrab_core() and Pfgrab_core() functions
  51   53       return a libproc handle to the core file.  Otherwise, NULL is returned
  52   54       and perr is filled in with a more detailed error message.
  53   55  
  54   56  ERRORS
  55   57       The Pgrab_core() function will fail if:
  56   58  
  57   59       G_NOCORE           The file core does not exist.
  58   60  
  59   61       G_STRANGE          An unexpected system error occurred while trying to
  60   62                          open core.  The value of errno indicates the system
  61   63                          failure.
  62   64  
  63   65       The Pgrab_core() and Pfgrab_core() functions will fail if:
  64   66  
  65   67       G_ELF              An unexpected libelf(3LIB) failure occurred.
  66   68  
  67   69       G_FORMAT           The core file referred to by either core or core_fd is
  68   70                          not a valid ELF core file.
  69   71  
  70   72       G_ISAINVAL         The architecture of the core file referred to by
  71   73                          either core or core_fd does not match the current
  72   74                          running system.
  73   75  
  74   76       G_LP64             The calling process is a 32-bit process and the core
  75   77                          file referenced by either core or core_fd refers to a
  76   78                          64-bit process.
  77   79  
  78   80       G_NOTE             The ELF notes present in the core file referred to by
  79   81                          either core or core_fd are corrupt or missing required
  80   82                          data.
  81   83  
  82   84       G_STRANGE          An unanticipated system error occurred while trying to
  83   85                          open the core file and create the handle.  The value
  84   86                          of errno indicates the system failure.
  85   87  
  86   88  INTERFACE STABILITY
  87   89       Uncommitted
  88   90  
  89   91  MT-LEVEL
  90   92       MT-Safe
  91   93  
  92   94  SEE ALSO
  93   95       gcore(1), open(2), errno(3C), libproc(3LIB), Pfree(3PROC),
  94   96       Pgrab_error(3PROC), Prelease(3PROC), core(4)
  95   97  
  96   98  illumos                          May 11, 2016                          illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX