PGRAB_CORE(3PROC) Process Control Library Functions PGRAB_CORE(3PROC)

Pgrab_core, Pfgrab_core — grab a core file

Process Control Library (libproc, -lproc)

#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);

The () 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 section of libproc(3LIB) for more information.

The () 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 () 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 () function fails. A human-readable form of the error can be obtained through the routine Pgrab_error(3PROC).

The () 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).

Upon successful completion, the Pgrab_core() and Pfgrab_core() functions return a handle to the core file. Otherwise, NULL is returned and perr is filled in with a more detailed error message.

The Pgrab_core() function will fail if:

The file core does not exist.
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:

An unexpected libelf(3LIB) failure occurred.
The core file referred to by either core or core_fd is not a valid ELF core file.
The architecture of the core file referred to by either core or core_fd does not match the current running system.
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.
The ELF notes present in the core file referred to by either core or core_fd are corrupt or missing required data.
An unanticipated system error occurred while trying to open the core file and create the handle. The value of errno indicates the system failure.

gcore(1), open(2), errno(3C), libproc(3LIB), Pfree(3PROC), Pgrab_error(3PROC), Prelease(3PROC), core(5)

May 11, 2016 OmniOS