1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd May 11, 2016
  15 .Dt PGRAB_FILE 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pgrab_file
  19 .Nd grab and inspect an ELF object
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft struct ps_prochandle
  24 .Fo Pgrab_file
  25 .Fa "const char *fname"
  26 .Fa "int *perr"
  27 .Fc
  28 .Sh DESCRIPTION
  29 The
  30 .Fn Pgrab_file
  31 function creates a handle to the ELF object contained in file
  32 .Fa fname .
  33 This handle is considered an
  34 .Em idle
  35 handle, it allows one to inspect aspects of the ELF contents present in
  36 the handle, for example obtaining CTF information and looking up
  37 symbols.
  38 .Pp
  39 There is no running state associated with this handle nor can there be.
  40 If one intends to control a running process or create a process, see
  41 .Xr Pgrab 3PROC
  42 and
  43 .Xr Pcreate 3PROC
  44 respectively.
  45 To inspect a core file use
  46 .Xr Pgrab_core 3PROC .
  47 .Pp
  48 The
  49 .Fa perr
  50 argument must be a
  51 .Pf non- Dv NULL
  52 pointer which will store a more detailed error in the event that
  53 .Fn Pgrab_file
  54 fails.
  55 A human-readable form of the error can be obtained with
  56 .Xr Pgrab_error 3PROC .
  57 .Pp
  58 When finished with the returned handle,
  59 .Xr Prelease 3PROC
  60 must be called to clean up resources associated with it.
  61 .Sh RETURN VALUES
  62 Upon successful completion, the
  63 .Fn Pgrab_file
  64 function returns a control handle to the process.
  65 Otherwise,
  66 .Dv NULL
  67 is returned and
  68 .Fa perr
  69 is filled in with an error code.
  70 .Sh ERRORS
  71 .Bl -tag -width Er -offset indent
  72 .It Er G_ELF
  73 An unexpected
  74 .Xr libelf 3LIB
  75 failure occurred while processing the file named by
  76 .Fa fname .
  77 .It Er G_FORMAT
  78 The file named by
  79 .Fa fname
  80 is not a valid ELF file.
  81 .It Er G_NOEXEC
  82 The file named by
  83 .Fa fname
  84 does not exist.
  85 .It Er G_STRANGE
  86 An unanticipated system error occurred while trying to grab the
  87 file
  88 .Fa fname
  89 and create the handle.
  90 The value of
  91 .Sy errno
  92 indicates the system failure.
  93 .El
  94 .Sh INTERFACE STABILITY
  95 .Sy Uncommitted
  96 .Sh MT-LEVEL
  97 .Sy MT-Safe
  98 .Sh SEE ALSO
  99 .Xr errno 3C ,
 100 .Xr libelf 3LIB ,
 101 .Xr libproc 3LIB ,
 102 .Xr Pfree 3PROC ,
 103 .Xr Pgrab_core 3PROC ,
 104 .Xr Pgrab_error 3PROC ,
 105 .Xr Prelease 3PROC