PGRAB_CORE(3PROC) Process Control Library Functions PGRAB_CORE(3PROC)
NAME
Pgrab_core,
Pfgrab_core - grab a core file
LIBRARY
Process Control Library (libproc, -lproc)
SYNOPSIS
#include <libproc.h> struct ps_prochandle * Pgrab_core(
const char *core,
const char *aout,
int gflag,
int *perr);
struct ps_prochandle * Pfgrab_core(
int core_fd,
const char *aout,
int *perr);
DESCRIPTION
The
Pgrab_core() and
Pfgrab_core() functions open a core file for
introspection. Unlike live processes, core files cannot have their
state modified; however, all of the functions that iterate or query
state will work. These functions work on all illumos core files and
the core files of some other operating systems. See both
core(5) and
the
Core Files section of
libproc(3LIB) for more information.
The
Pgrab_core() function attempts to open the core file specified by
core. The system attempts to determine the path of the original
executable. The argument
aout may either be the path to that file, a
path to a directory to search, or the NULL pointer, if neither is
known. The system will search for it and will supplement information
in the core file with that.
The
gflag argument to the
Pgrab_core() function controls how the file
is opened. If the PGRAB_RDONLY flag is specified, then the core file
will be opened with the
open(2) flag O_RDONLY. Otherwise, it will be
opened O_RDWR.
The
perr argument must be a non-NULL pointer which will store a more
detailed error in the event that the
Pgrab_core() function fails. A
human-readable form of the error can be obtained through the routine
Pgrab_error(3PROC).
The
Pfgrab_core() is similar to the
Pgrab_core() function. Except,
instead of operating on a path, it opens a handle to the core file
referenced by
core_fd. The
aout and
perr arguments are identical to
those in the
Pgrab_core() function.
The handle returned, from either function, is valid until it is closed
with
Prelease(3PROC) or
Pfree(3PROC).
RETURN VALUES
Upon successful completion, the
Pgrab_core() and
Pfgrab_core()
functions return a
libproc handle to the core file. Otherwise, NULL is
returned and
perr is filled in with a more detailed error message.
ERRORS
The
Pgrab_core() function will fail if:
G_NOCORE The file
core does not exist.
G_STRANGE An unexpected system error occurred while trying to
open
core. The value of
errno indicates the system
failure.
The
Pgrab_core() and
Pfgrab_core() functions will fail if:
G_ELF An unexpected
libelf(3LIB) failure occurred.
G_FORMAT The core file referred to by either
core or
core_fd is not a valid ELF core file.
G_ISAINVAL The architecture of the core file referred to by
either
core or
core_fd does not match the current
running system.
G_LP64 The calling process is a 32-bit process and the core
file referenced by either
core or
core_fd refers to
a 64-bit process.
G_NOTE The ELF notes present in the core file referred to
by either
core or
core_fd are corrupt or missing
required data.
G_STRANGE An unanticipated system error occurred while trying
to open the core file and create the handle. The
value of
errno indicates the system failure.
INTERFACE STABILITY
UncommittedMT-LEVEL MT-SafeSEE ALSO
gcore(1),
open(2),
errno(3C),
libproc(3LIB),
Pfree(3PROC),
Pgrab_error(3PROC),
Prelease(3PROC),
core(5)illumos May 11, 2016 illumos
