Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Thursday, June 13, 2019
 
 

proc_arg_grab (3PROC)

Name

Pgrab, Pgrab_core, Pfgrab_core, Pgrab_file, Pgrab_error, proc_arg_grab, proc_arg_psinfo, proc_lwp_in_set, proc_lwp_range_valid - grab a process or core file

Synopsis

#include <libproc.h>
ps_prochandle_t *Pgrab(pid_t pid, int gflags, int *perr);
ps_prochandle_t *Pgrab_core(const char *core, const char *aout_path,
         int *perr);
ps_prochandle_t *Pfgrab_core(int corefd, const char *aout_path,
         int *perr);
ps_prochandle_t *Pgrab_file(const char *fname, int *perr);
ps_prochandle_t *proc_arg_grab(const char *arg, int oflag,
         int gflags, int *perr, const char **lwps);
pid_t proc_arg_psinfo(const char *arg, int oflag,
         psinfo_t *psp, size_t size, int *perr, const char **lwps);
const char *Pgrab_error(int error);
int proc_lwp_in_set(const char *lwps, lwpid_t lwpid);
int proc_lwp_range_valid(const char *lwps);

Description

The Pgrab(), Pgrab_core(), Pfgrab_core(), and Pgrab_file() functions are used to attach a controlling process to a victim process, core file, or object file. The Pgrab_error() function is a convenience function for returning error strings for the possible errors from the grab interfaces.

The gflags argument is constructed by a bitwise-inclusive-OR of zero or more flags from the following list:

PGRAB_NOSTOP

Open the process but do not stop it

PGRAB_RETAIN

Retain existing /proc tracing flags

PGRAB_RDONLY

Open the process or file for inspection only

PGRAB_FORCE

Forcefully open the process

By default, Pgrab() attaches to the victim process identified by pid, causes it to stop, and clears any existing /proc tracing flags such as stop-on-syscall-entry, stop-on-syscall-exit, stop-on-signal, and stop-on-fault. For more information, see the proc(5) man page.

If PGRAB_NOSTOP is set in gflags, the Pgrab() function will not cause the victim process to stop immediately. If PGRAB_RETAIN is set in gflags, any existing /proc tracing flags are retained. If PGRAB_RDONLY is set in gflags, the Pgrab() function will not open the process for control, but only for inspection. PGRAB_RDONLY implies both PGRAB_NOSTOP and PGRAB_RETAIN.

Unless PGRAB_FORCE is set in gflags, the Pgrab() function will fail if there is another controlling process already attached to the victim process. Use this flag cautiously as multiple controlling processes can result in chaos.

The Pgrab_core() function attaches the controlling process to a core file named by the core path name argument for inspection only since a dead process cannot be controlled. The optional aout_path argument, which may be NULL, either names the executable file by which the dead process was executed or names a directory that the Pgrab_core() function will search for the executable file. If the aout_path argument is NULL, then the Pgrab_core() function uses information from the core file to attempt to locate the executable file. The core file is opened as read-only.

The Pfgrab_core() function behaves the same as the Pgrab_core() function except that the core file is designated by the corefd file descriptor argument rather than a path name. The controlling process must open the core file, but the corefd file descriptor will ultimately be closed by the library after being passed to the Pfgrab_core() function. If the Pfgrab_core() fails, it is closed by the Prelease(3PROC) function.

The Pgrab_file() function attaches the controlling process to an ELF executable file or an ELF dynamic library for inspection using the symbol table interfaces of the libproc library. The file is opened as read-only.

The proc_arg_grab() and proc_arg_psinfo() functions are useful when interpreting arguments passed to a main() function in a controlling process. The proc_arg_grab() and proc_arg_psinfo() functions accept an arg argument string that may be one of:

  • A decimal string, interpretable as a process-ID

  • A path name naming an entry in /proc (/proc/nnn)

  • A path name naming a core file

  • Any of the above, appended with a slash character ("/") followed by an lwp range specification, with numeric ranges separated by commas. A range is specified as:

    -n      lwpid <= n
    n-m     n <= lwpid <= m
    n-      lwpid >= n
    n       lwpid == n

For example, for a pid equal to 1234 and lwpids equal to 1, 3, 4, 5, and 8 or greater:

/proc/1234/1,3-5,8-

The oflag argument to the proc_arg_grab() and proc_arg_psinfo() functions determines how the arg argument is interpreted:

PR_ARG_PIDS

Allow pid and /proc file arguments

PR_ARG_CORES

Allow core file arguments

PR_ARG_ANY

Try PR_ARG_PIDS, then PR_ARG_CORES

The gflags argument to the proc_arg_grab() function is meaningful only if the proc_arg_grab() function grabs a live victim process. For more information, see the proc(5) man page.

If the lwps argument to the proc_arg_grab() or proc_arg_psinfo() functions is not NULL, and an lwp range specification is present in the arg argument, then *lwps will be set to the lwp range specification portion of the arg argument. On successful return from the proc_arg_grab() or proc_arg_psinfo() functions, the lwp range specification will be verified to be syntactically valid.

The Pgrab_error() function maps the error from a grabbing failure to an error message string and returns a pointer to that string.

The proc_lwp_range_valid() function returns non-zero if the lwp range specification is syntactically valid, else, it returns 0. This does not imply that any of the lwps specified in the range are actually present in the victim process.

The proc_lwp_in_set() function returns non-zero if the lwpid value is within the ranges of the lwp range specification. This does not imply that the lwp specified by the lwpid argument actually exists in the victim process.

Return Values

On successful completion, the Pgrab(), Pgrab_core(), Pfgrab_core(), Pgrab_file(), and proc_arg_grab() functions return a pointer to an opaque ps_prochandle_t structure, allocated by the library, which must be used by almost all of the remaining functions in the libproc library to effect inspection and control of the victim process. On failure, these functions return a NULL pointer and set the integer pointed to by the perr argument to an error code. For more information, see the libproc.h(3HEAD) man page.

Errors

These are the possible values returned in the integer pointed to by the perr argument if a grab failure occurs:

G_STRANGE

Unanticipated error, errno is meaningful

G_NOPROC

No such process

G_NOCORE

No such core file

G_NOPROCORCORE

No such proc or core for proc_arg_grab

G_NOEXEC

Cannot locate executable file

G_ZOMB

Zombie process

G_PERM

No permission

G_BUSY

Another process has control

G_SYS

System process

G_SELF

Process is self

G_INTR

Interrupt received while grabbing

G_LP

Process is _LP64, self is ILP32

G_FORMAT

File is not an ELF format core file

G_ELF

Libelf error, the elf_errno() function is meaningful

G_NOTE

Required PT_NOTE Phdr not present in core

G_ISAINVAL

Wrong ELF machine type

G_BADLWPS

Bad '/lwps' specification

G_NOFD

No more file descriptors

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Unsafe

See Also

libproc.h(3HEAD), libproc(3LIB), Pcreate(3PROC), Prelease(3PROC)