Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Wednesday, July 27, 2022

Pcreate_agent (3PROC)


Pcreate_agent, Pdestroy_agent - create and destroy the /proc agent lwp in the victim process


#include <libproc.h>
int Pcreate_agent(struct ps_prochandle *Pr);
void Pdestroy_agent(struct ps_prochandle *Pr);


The Pr argument identifies a victim process attached to the controlling process by the create and grab interfaces. For more information, see the Pcreate(3PROC) and Pgrab(3PROC)) man pages.

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.

Return Values

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:

Interface Stability

See Also

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