PGRAB_FILE(3PROC) Process Control Library Functions PGRAB_FILE(3PROC)
Pgrab_file - grab and inspect an ELF object
Process Control Library (libproc, -lproc)
#include <libproc.h>
struct ps_prochandle
Pgrab_file(const char *fname, int *perr);
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.
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.
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.
Uncommitted
MT-LEVEL
MT-Safe
errno(3C), libelf(3LIB), libproc(3LIB), Pfree(3PROC),
Pgrab_core(3PROC), Pgrab_error(3PROC), Prelease(3PROC)
illumos May 11, 2016 illumos
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
SEE ALSO
errno(3C), libelf(3LIB), libproc(3LIB), Pfree(3PROC),
Pgrab_core(3PROC), Pgrab_error(3PROC), Prelease(3PROC)
illumos May 11, 2016 illumos