Pcreate_agent, Pdestroy_agent - create and destroy the /proc agent lwp in the victim process
int Pcreate_agent(struct ps_prochandle *Pr);
void Pdestroy_agent(struct ps_prochandle *Pr);
The Pcreate_agent() function creates the /proc agent lwp if it does not exist. If the /proc agent lwp already exists, the Pcreate_agent() function increments a reference count on it. For more information, see the proc(5) man page.
The Pdestroy_agent() function decrements the reference count on the /proc agent lwp, if it exists. If the reference count reaches zero, the agent lwp is destroyed.
As a side-effect, the Pcreate_agent() function causes the victim process to be stopped. The Pdestroy_agent() function releases the victim process back to its original state when the reference count reaches zero and the agent lwp is destroyed.
The various pr_*() functions enable a controlling process to force a victim process to execute system calls on behalf of the controlling process. This is accomplished using the /proc agent lwp, which is created and destroyed on each call to one of the pr_*() functions. For more information, see the pr_access(3PROC) man page.
If a controlling process wants to execute more than one system call in the victim process, then as an efficiency matter, it should create the /proc agent lwp just once, after grabbing and stopping the victim process and before it calls the several pr_*() functions it is interested in. It must call the Pdestroy_agent() function before releasing the victim process.
On successful completion, the Pcreate_agent() function returns 0. On error, it returns -1 and sets the errno value to indicate the error. There is no return value from the Pdestroy_agent() function.
The Pcreate_agent() function will fail if:
The Pr argument does not refer to a live process. It may be a zombie process or a core file.
See attributes(7) for descriptions of the following attributes: