Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Wednesday, July 27, 2022

proc_arg_psinfo (3PROC)


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


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


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:


Open the process but do not stop it


Retain existing /proc tracing flags


Open the process or file for inspection only


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:


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


Allow pid and /proc file arguments


Allow core file arguments



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.


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


Unanticipated error, errno is meaningful


No such process


No such core file


No such proc or core for proc_arg_grab


Cannot locate executable file


Zombie process


No permission


Another process has control


System process


Process is self


Interrupt received while grabbing


Process is _LP64, self is ILP32


File is not an ELF format core file


Libelf error, the elf_errno() function is meaningful


Required PT_NOTE Phdr not present in core


Wrong ELF machine type


Bad '/lwps' specification


No more file descriptors


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

Interface Stability

See Also

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