Prelease, Pfree - release a victim process or core file
#include <libproc.h>
void Prelease(ps_prochandle_t *Pr, int flags);
void Pfree(ps_prochandle_t *Pr);
Almost all inspection and control interfaces provided by libproc are effected using an opaque ps_prochandle_t structure, allocated by the library when the grab or create interfaces are called. A pointer to this structure, returned by the grab or create interfaces, must be passed to the Prelease() or Pfree() functions when the controlling process is finished manipulating the victim process. For more information, see the Pcreate(3PROC) and Pgrab(3PROC) man pages.
The Prelease() function releases the victim process identified by the Pr argument, subject to the actions specified by the flags argument. The flags argument is constructed by a bitwise-inclusive-OR of flags from the following list:
Terminate the process with SIGKILL signal
Clear all of the /proc tracing flags
Retain the final /proc tracing flags
Leave the process stopped and abandoned
None of these flags apply to a grabbed core file, ELF file, or to a process grabbed with the PGRAB_RDONLY flag. All that the Prelease() function can do with such victims is to call the Pfree() function to close all of the /proc files that it has opened since the grab took place and to free all of the memory allocated for the instance of ps_prochandle_t pointed to by the Pr argument.
If PRELEASE_KILL is set in the flags argument, then the victim process is terminated with the SIGKILL signal.
If PRELEASE_CLEAR is set in the flags argument, then all of the /proc tracing flags are cleared in the victim process.
If PRELEASE_RETAIN is set in the flags argument, then all of the /proc tracing flags set by the controlling process, during its control of the victim process, are retained after it is released.
If both PRELEASE_CLEAR and PRELEASE_RETAIN are set, then PRELEASE_CLEAR takes precedence.
If neither PRELEASE_CLEAR nor PRELEASE_RETAIN are set, then any /proc tracing flags that were in effect when the victim process was first grabbed, remain in effect.
If PRELEASE_HANG is set, then the victim process is left stopped and abandoned. It can be reattached or re-grabbed to the controlling process or to some other controlling process later.
If PRELEASE_HANG is not set, and then if PRELEASE_CLEAR is set, or if the victim process was created with the Pcreate() function, or if the victim process was not already stopped when it was first grabbed, then the victim process is set running.
After performing these actions, Prelease() calls Pfree() function to close all of the /proc file descriptors and free all of the memory allocated for the instance of ps_prochandle_t identified by the Pr argument.
The Pfree() function closes all of the /proc file descriptors, and frees all of the memory allocated for the instance of ps_prochandle_t pointed to by the Pr argument, but does not perform any other Prelease() logic.
Any use of the Pr argument after the Prelease() or Pfree() function is called, yields undefined results.
There are no return values from these functions.
There are no errors returned by these functions.
See attributes(7) for descriptions of the following attributes:
|
libproc.h(3HEAD), libproc(3LIB), Pcreate(3PROC), Pgrab(3PROC)