Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Friday, August 13, 2021

Psyscall (3PROC)


Psyscall - execute a system call trap in the victim process


#include <sys/syscall.h>
#include <libproc.h>
 int Psyscall(ps_prochandle_t *Pr, sysret_t *rval,
         int systrap, uint_t nargs, argdes_t *argp);


The Psyscall() function forces a victim process to execute a system call trap on behalf of the controlling process.

The Pr argument identifies a live 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 systrap argument identifies the system call trap number to be executed by the victim process. It must be one of the SYS_* values defined in the <sys/syscall.h> header file.

The nargs argument is the count of system call trap arguments to be passed to the victim process. The argp argument is an array of nargs argdes_t structures, each describing the system call argument to be passed to the victim process:

typedef struct {
    long     arg_value;   /* value of argument given to system call */
    void     *arg_object; /* pointer to object in controlling process */
    char     arg_type;    /* AT_BYVAL, AT_BYREF */
    char     arg_inout;   /* AI_INPUT, AI_OUTPUT, AI_INOUT */
    ushort_t arg_size;    /* if AT_BYREF, size of object in bytes */
} argdes_t;

If arg_type is AT_BYVAL, the argument value must be contained in arg_value and no other members have any meaning.

If arg_type is AT_BYREF, then arg_value has no meaning but arg_object must point to an object of size arg_size in the controlling process and arg_inout has the following meanings:


The object will be copied to the victim process before execution of the system call trap.


The object will be copied back to the controlling process after the system call trap is executed.


Both of the above actions will occur.

The maximum number of arguments or MAXARGS is 8. The maximum size of a BYREF object or MAXARGL is 8 Kilobytes.

On successful completion, the Psyscall() function returns the errno value produced by the system call trap in the victim process. If this value is zero, then one or two return values from the successful system call trap in the victim process are returned in the rval argument, whose type is defined in <sys/syscall.h>:

typedef struct {
    long    sys_rval1;  /* primary return value from system call */
    long    sys_rval2;  /* second return value from system call */
} sysret_t;

Return Values

On failure to cause execution of the system call trap in the victim process, the Psyscall() function returns -1 and sets the errno of the controlling process to indicate the error.


The Psyscall() function uses the /proc agent lwp in the victim process to perform the actual system call trap, creating it if necessary. This means that all of the lwps in the victim process are stopped and restarted for each call to the Psyscall() function, unless the calls are bracketed by calls to the Pcreate_agent() and Pdestroy_agent() functions, in which case the stopping and restarting happens just once, not on every embedded call to the Psyscall() function. For more information, see the Pcreate_agent(3PROC) man page.

To make things complicated, the system call trap table is not a public interface. Details of the trap table interfaces can change on any update of the operating system, even in a system patch, not just on system release boundaries. The libproc library includes many pre-defined victim process system call interfaces which will be updated as needed on any release that requires it. See what you can find in pr_access(3PROC) before creating another one.


On failure, these errno values may be set:


Process has been lost to control, needs the Preopen() function


Signal received while waiting for stop


Invalid argument


The victim process has terminated


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

Interface Stability

See Also

gelf(3ELF), libproc.h(3HEAD), libproc(3LIB), Pcreate(3PROC), Pgrab(3PROC), Pcreate_agent(3PROC), proc(5)