.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PGRAB_CORE 3PROC
.Os
.Sh NAME
.Nm Pgrab_core ,
.Nm Pfgrab_core
.Nd grab a core file
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft "struct ps_prochandle *"
.Fo Pgrab_core
.Fa "const char *core"
.Fa "const char *aout"
.Fa "int gflag"
.Fa "int *perr"
.Fc
.Ft "struct ps_prochandle *"
.Fo Pfgrab_core
.Fa "int core_fd"
.Fa "const char *aout"
.Fa "int *perr"
.Fc
.Sh DESCRIPTION
The
.Fn Pgrab_core
and
.Fn 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
.Xr core 5
and the
.Em Core Files
section of
.Xr libproc 3LIB
for more information.
.Pp
The
.Fn Pgrab_core
function attempts to open the core file specified by
.Fa core .
The system attempts to determine the path of the original executable.
The argument
.Fa aout
may either be the path to that file, a path to a directory to search, or the
.Dv NULL
pointer, if neither is known.
The system will search for it and will supplement information in the core file
with that.
.Pp
The
.Fa gflag
argument to the
.Fn Pgrab_core
function controls how the file is opened.
If the
.Dv PGRAB_RDONLY
flag is specified, then the core file will be opened with the
.Xr open 2
flag
.Dv O_RDONLY .
Otherwise, it will be opened
.Dv O_RDWR .
.Pp
The
.Fa perr
argument must be a
.Pf non- Dv NULL
pointer which will store a more detailed error in the event that the
.Fn Pgrab_core
function fails.
A human-readable form of the error can be obtained through the routine
.Xr Pgrab_error 3PROC .
.Pp
The
.Fn Pfgrab_core
is similar to the
.Fn Pgrab_core
function.
Except, instead of operating on a path, it opens a handle to the core file
referenced by
.Fa core_fd .
The
.Fa aout
and
.Fa perr
arguments are identical to those in the
.Fn Pgrab_core
function.
.Pp
The handle returned, from either function, is valid until it is closed
with
.Xr Prelease 3PROC
or
.Xr Pfree 3PROC .
.Sh RETURN VALUES
Upon successful completion, the
.Fn Pgrab_core
and
.Fn Pfgrab_core
functions return a
.Sy libproc
handle to the core file.
Otherwise,
.Dv NULL
is returned and
.Fa perr
is filled in with a more detailed error message.
.Sh ERRORS
The
.Fn Pgrab_core
function will fail if:
.Bl -tag -width Er
.It Er G_NOCORE
The file
.Fa core
does not exist.
.It Er G_STRANGE
An unexpected system error occurred while trying to open
.Fa core .
The value of
.Sy errno
indicates the system failure.
.El
.Pp
The
.Fn Pgrab_core
and
.Fn Pfgrab_core
functions will fail if:
.Bl -tag -width Er
.It Dv G_ELF
An unexpected
.Xr libelf 3LIB
failure occurred.
.It Dv G_FORMAT
The core file referred to by either
.Fa core
or
.Fa core_fd
is not a valid ELF core file.
.It Dv G_ISAINVAL
The architecture of the core file referred to by either
.Fa core
or
.Fa core_fd
does not match the current running system.
.It Dv G_LP64
The calling process is a 32-bit process and the core file referenced by
either
.Fa core
or
.Fa core_fd
refers to a 64-bit process.
.It Dv G_NOTE
The ELF notes present in the core file referred to by either
.Fa core
or
.Fa core_fd
are corrupt or missing required data.
.It Dv G_STRANGE
An unanticipated system error occurred while trying to open the core
file and create the handle.
The value of
.Sy errno
indicates the system failure.
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
.Sy MT-Safe
.Sh SEE ALSO
.Xr gcore 1 ,
.Xr open 2 ,
.Xr errno 3C ,
.Xr libproc 3LIB ,
.Xr Pfree 3PROC ,
.Xr Pgrab_error 3PROC ,
.Xr Prelease 3PROC ,
.Xr core 5