illumos: manual page: Pgrab

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

NAME

Pgrab_file - grab and inspect an ELF object

LIBRARY

Process Control Library (libproc, -lproc)

SYNOPSIS

#include <libproc.h>

struct ps_prochandle
Pgrab_file(const char *fname, int *perr);

DESCRIPTION

The Pgrab_file() function creates a handle to the ELF object contained in
file fname. This handle is considered an idle handle, it allows one to
inspect aspects of the ELF contents present in the handle, for example
obtaining CTF information and looking up symbols.

There is no running state associated with this handle nor can there be. If
one intends to control a running process or create a process, see
Pgrab(3PROC) and Pcreate(3PROC) respectively. To inspect a core file use
Pgrab_core(3PROC).

The perr argument must be a non-NULL pointer which will store a more
detailed error in the event that Pgrab_file() fails. A human-readable form
of the error can be obtained with Pgrab_error(3PROC).

When finished with the returned handle, Prelease(3PROC) must be called to
clean up resources associated with it.

RETURN VALUES

Upon successful completion, the Pgrab_file() function returns a control
handle to the process. Otherwise, NULL is returned and perr is filled in
with an error code.

ERRORS

G_ELF An unexpected libelf(3LIB) failure occurred while
processing the file named by fname.

G_FORMAT The file named by fname is not a valid ELF file.

G_NOEXEC The file named by fname does not exist.

G_STRANGE An unanticipated system error occurred while
trying to grab the file fname and create the
handle. The value of errno indicates the system
failure.

INTERFACE STABILITY

Uncommitted

MT-LEVEL
MT-Safe