Go to main content

man pages section 3: Extended Library Functions, Volume 3

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

Psyscall (3PROC)

Name

Psyscall - execute a system call trap in the victim process

Synopsis

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

Description

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:

AI_INPUT

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

AI_OUTPUT

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

AI_INOUT

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.

Notes

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.

Errors

On failure, these errno values may be set:

EAGAIN

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

EINTR

Signal received while waiting for stop

EINVAL

Invalid argument

ENOENT

The victim process has terminated

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Unsafe

See Also

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