usr/src/man/man3proc/Pgrab_core.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_CORE 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pgrab_core ,
  19 .Nm Pfgrab_core
  20 .Nd grab a core file
  21 .Sh SYNOPSIS
  22 .Lb libproc
  23 .In libproc.h
  24 .Ft "struct ps_prochandle *"
  25 .Fo Pgrab_core
  26 .Fa "const char *core"
  27 .Fa "const char *aout"
  28 .Fa "int gflag"
  29 .Fa "int *perr"
  30 .Fc
  31 .Ft "struct ps_prochandle *"
  32 .Fo Pfgrab_core
  33 .Fa "int core_fd"
  34 .Fa "const char *aout"
  35 .Fa "int *perr"
  36 .Fc
  37 .Sh DESCRIPTION
  38 The
  39 .Fn Pgrab_core
  40 and
  41 .Fn Pfgrab_core
  42 functions open a core file for introspection.
  43 Unlike live processes, core files cannot have their state modified;
  44 however, all of the functions that iterate or query state will work.
  45 These functions work on all illumos core files and the core files of some other
  46 operating systems.
  47 See both
  48 .Xr core 4
  49 and the
  50 .Em Core Files
  51 section of
  52 .Xr libproc 3LIB
  53 for more information.
  54 .Pp
  55 The
  56 .Fn Pgrab_core
  57 function attempts to open the core file specified by
  58 .Fa core .
  59 The system attempts to determine the path of the original executable.
  60 The argument
  61 .Fa aout
  62 may either be the path to that file, a path to a directory to search, or the
  63 .Dv NULL
  64 pointer, if neither is known.
  65 The system will search for it and will supplement information in the core file
  66 with that.
  67 .Pp
  68 The
  69 .Fa gflag
  70 argument to the
  71 .Fn Pgrab_core
  72 function controls how the file is opened.
  73 If the
  74 .Dv PGRAB_RDONLY
  75 flag is specified, then the core file will be opened with the
  76 .Xr open 2
  77 flag
  78 .Dv O_RDONLY .
  79 Otherwise, it will be opened
  80 .Dv O_RDWR .
  81 .Pp
  82 The
  83 .Fa perr
  84 argument must be a
  85 .Pf non- Dv NULL
  86 pointer which will store a more detailed error in the event that the
  87 .Fn Pgrab_core
  88 function fails.
  89 A human-readable form of the error can be obtained through the routine
  90 .Xr Pgrab_error 3PROC .
  91 .Pp
  92 The
  93 .Fn Pfgrab_core
  94 is similar to the
  95 .Fn Pgrab_core
  96 function.
  97 Except, instead of operating on a path, it opens a handle to the core file
  98 referenced by
  99 .Fa core_fd .
 100 The
 101 .Fa aout
 102 and
 103 .Fa perr
 104 arguments are identical to those in the
 105 .Fn Pgrab_core
 106 function.
 107 .Pp
 108 The handle returned, from either function, is valid until it is closed
 109 with
 110 .Xr Prelease 3PROC
 111 or
 112 .Xr Pfree 3PROC .
 113 .Sh RETURN VALUES
 114 Upon successful completion, the
 115 .Fn Pgrab_core
 116 and
 117 .Fn Pfgrab_core
 118 functions return a
 119 .Sy libproc
 120 handle to the core file.
 121 Otherwise,
 122 .Dv NULL
 123 is returned and
 124 .Fa perr
 125 is filled in with a more detailed error message.
 126 .Sh ERRORS
 127 The
 128 .Fn Pgrab_core
 129 function will fail if:
 130 .Bl -tag -width Er
 131 .It Er G_NOCORE
 132 The file
 133 .Fa core
 134 does not exist.
 135 .It Er G_STRANGE
 136 An unexpected system error occurred while trying to open
 137 .Fa core .
 138 The value of
 139 .Sy errno
 140 indicates the system failure.
 141 .El
 142 .Pp
 143 The
 144 .Fn Pgrab_core
 145 and
 146 .Fn Pfgrab_core
 147 functions will fail if:
 148 .Bl -tag -width Er
 149 .It Dv G_ELF
 150 An unexpected
 151 .Xr libelf 3LIB
 152 failure occurred.
 153 .It Dv G_FORMAT
 154 The core file referred to by either
 155 .Fa core
 156 or
 157 .Fa core_fd
 158 is not a valid ELF core file.
 159 .It Dv G_ISAINVAL
 160 The architecture of the core file referred to by either
 161 .Fa core
 162 or
 163 .Fa core_fd
 164 does not match the current running system.
 165 .It Dv G_LP64
 166 The calling process is a 32-bit process and the core file referenced by
 167 either
 168 .Fa core
 169 or
 170 .Fa core_fd
 171 refers to a 64-bit process.
 172 .It Dv G_NOTE
 173 The ELF notes present in the core file referred to by either
 174 .Fa core
 175 or
 176 .Fa core_fd
 177 are corrupt or missing required data.
 178 .It Dv G_STRANGE
 179 An unanticipated system error occurred while trying to open the core
 180 file and create the handle.
 181 The value of
 182 .Sy errno
 183 indicates the system failure.
 184 .El
 185 .Sh INTERFACE STABILITY
 186 .Sy Uncommitted
 187 .Sh MT-LEVEL
 188 .Sy MT-Safe
 189 .Sh SEE ALSO
 190 .Xr gcore 1 ,
 191 .Xr open 2 ,
 192 .Xr errno 3C ,
 193 .Xr libproc 3LIB ,
 194 .Xr Pfree 3PROC ,
 195 .Xr Pgrab_error 3PROC ,
 196 .Xr Prelease 3PROC ,
 197 .Xr core 4