1 PGRAB_FILE(3PROC)      Process Control Library Functions     PGRAB_FILE(3PROC)
   2 
   3 NAME
   4      Pgrab_file - grab and inspect an ELF object
   5 
   6 LIBRARY
   7      Process Control Library (libproc, -lproc)
   8 
   9 SYNOPSIS
  10      #include <libproc.h>
  11 
  12      struct ps_prochandle
  13      Pgrab_file(const char *fname, int *perr);
  14 
  15 DESCRIPTION
  16      The Pgrab_file() function creates a handle to the ELF object contained in
  17      file fname.  This handle is considered an idle handle, it allows one to
  18      inspect aspects of the ELF contents present in the handle, for example
  19      obtaining CTF information and looking up symbols.
  20 
  21      There is no running state associated with this handle nor can there be.
  22      If one intends to control a running process or create a process, see
  23      Pgrab(3PROC) and Pcreate(3PROC) respectively.  To inspect a core file use
  24      Pgrab_core(3PROC).
  25 
  26      The perr argument must be a non-NULL pointer which will store a more
  27      detailed error in the event that Pgrab_file() fails.  A human-readable
  28      form of the error can be obtained with Pgrab_error(3PROC).
  29 
  30      When finished with the returned handle, Prelease(3PROC) must be called to
  31      clean up resources associated with it.
  32 
  33 RETURN VALUES
  34      Upon successful completion, the Pgrab_file() function returns a control
  35      handle to the process.  Otherwise, NULL is returned and perr is filled in
  36      with an error code.
  37 
  38 ERRORS
  39            G_ELF              An unexpected libelf(3LIB) failure occurred
  40                               while processing the file named by fname.
  41 
  42            G_FORMAT           The file named by fname is not a valid ELF file.
  43 
  44            G_NOEXEC           The file named by fname does not exist.
  45 
  46            G_STRANGE          An unanticipated system error occurred while
  47                               trying to grab the file fname and create the
  48                               handle.  The value of errno indicates the system
  49                               failure.
  50 
  51 INTERFACE STABILITY
  52      Uncommitted
  53 
  54 MT-LEVEL
  55      MT-Safe
  56 
  57 SEE ALSO
  58      errno(3C), libelf(3LIB), libproc(3LIB), Pfree(3PROC), Pgrab_core(3PROC),
  59      Pgrab_error(3PROC), Prelease(3PROC)
  60 
  61 illumos                          May 11, 2016                          illumos