usr/src/man/man3proc/Pgrab_file.3proc

   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
  40 there be. If one intends to control a running process or create a
  41 process, see
  42 .Xr Pgrab 3PROC
  43 and
  44 .Xr Pcreate 3PROC
  45 respectively. 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. A human-readable form of the error can be obtained with
  55 .Xr Pgrab_error 3PROC .
  56 .Pp
  57 When finished with the returned handle,
  58 .Xr Prelease 3PROC
  59 must be called to clean up resources associated with it.
  60 .Sh RETURN VALUES
  61 Upon successful completion, the
  62 .Fn Pgrab_file
  63 function returns a control handle to the process. Otherwise,
  64 .Dv NULL
  65 is returned and
  66 .Fa perr
  67 is filled in with an error code.
  68 .Sh ERRORS
  69 .Bl -tag -width Er -offset indent
  70 .It Er G_ELF
  71 An unexpected
  72 .Xr libelf 3LIB
  73 failure occurred while processing the file named by
  74 .Fa fname .
  75 .It Er G_FORMAT
  76 The file named by
  77 .Fa fname
  78 is not a valid ELF file.
  79 .It Er G_NOEXEC
  80 The file named by
  81 .Fa fname
  82 does not exist.
  83 .It Er G_STRANGE
  84 An unanticipated system error occurred while trying to grab the
  85 file
  86 .Fa fname
  87 and create the handle.
  88 The value of
  89 .Sy errno
  90 indicates the system failure.
  91 .El
  92 .Sh INTERFACE STABILITY
  93 .Sy Uncommitted
  94 .Sh MT-LEVEL
  95 .Sy MT-Safe
  96 .Sh SEE ALSO
  97 .Xr errno 3C ,
  98 .Xr libelf 3LIB ,
  99 .Xr libproc 3LIB ,
 100 .Xr Pfree 3PROC ,
 101 .Xr Pgrab_core 3PROC ,
 102 .Xr Pgrab_error 3PROC ,
 103 .Xr Pgrab_file 3PROC ,
 104 .Xr Prelease 3PROC