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