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