paccess(S)

paccess -- used in conjunction with ptrace for tracing a child process

Syntax

cc . . . -lc

#include <sys/paccess.h>

int paccess (pid, cmd, offset, count, ptr)
int pid, cmd, offset, count;
char *ptr;

Description

paccess(S) provides an extended interface for accessing the address space, register save areas and local descriptor table of a child process that is being traced using ptrace(S). paccess also provides information about the u-area layout so that applications can determine this at runtime. This allows the developer to avoid hard coding kernel dependencies into the application.

The primary use of paccess is in the implementation of debuggers such as adb(CP) and sdb(CP).

Parameters

Except for P_RUOFFS, all paccess commands transfer information between the calling process and a child process designated by pid. The parent and child processes must coordinate tracing using the facilities described by ptrace. Each command selects a particular class of data such as data address space or floating point register save area, and is used by the parent process to read or write the child process's context.

offset is a byte granularity logical offset from the base of the particular data area (determined by paccess relative to cmd).

count is the size in bytes of the requested transfer. count may be sized down by paccess if offset plus count would exceed the size of the particular data area. count may not exceed MAXIPCDATA.

ptr designates a buffer in the caller's address space.

Note

paccess will transfer a maximum of count bytes between a buffer designated by ptr and a point offset bytes into a region of the child process's context designated by cmd. P_RUOFFS is an exception as indicated below.

Commands

The first four commands are used to read or write data in the data, text or stack regions of a process:

P_RDUSER

Reads a child process's D address space. offset is a 32 byte virtual address in the child's address space.

P_RIUSER

Reads a child process's I address space. offset is a 32 byte virtual address in the child's address space.

P_WDUSER

Writes to a child process's D address space. offset is a 32 byte virtual address in the child's address space.

P_WIUSER

Writes to a child process's I address space. offset is a 32 byte virtual address in the child's address space.

P_RUREGS

Reads the child process's register save area in the uarea. offset is a logical offset from the base of the register save area in the uarea. This may be used to read a particular register or a subset of the entire save area. Note that the ordering of registers in the save area is highly machine dependent. The offsets of the registers are defined in <sys/reg.h>.

P_WUREGS

Writes to the child process's register save area in the uarea. offset is a logical offset from the base of the register save area in the uarea. This may be used to read a particular register or a subset of the entire save area. Note that the ordering of registers in the save area is highly machine dependent. The offsets of the registers are defined in <sys/reg.h>.

The kernel stack pointer [KESP] will remain unchanged after any instance of P_WUREGS. Certain flags in the flags register [EFL] will remain unchanged after any instance of P_WUREGS. The flags are:

PS_T
PS_IE
PS_IOPL
PS_NT
PS_RF
PS_VM

See the file <sys/tss.h> for a definition of these flags.

P_RUFREGS

Reads the child process floating point register save area in the uarea. offset is a logical offset from the base of the register save area in the uarea. This may be used to read a particular register or a subset of the entire save area.

P_WUFREGS

Writes to the child process floating point register save area in the uarea. offset is a logical offset from the base of the register save area in the uarea. This may be used to read a particular register or a subset of the entire save area.

For the above two commands paccess selects the appropriate save area relative to whether the process is using an Intel 87 series or Weitek co-processor chip and whether or not the hardware is present or is being emulated in software. Note that data is not currently transformed in any way and is highly chip and/or emulator dependent.

The ordering of registers in the save area is highly machine dependent. The offsets of the registers are defined in <sys/reg.h>.

P_RULDT: Read the child processor's local descriptor table. This command has no write capability. offset is a logical byte offset from the base of the local descriptor table. paccess may have to be invoked several times to read the entire local descriptor table.

The following commands provide read and write access to the 80386 debug register save area.

P_RUDREGS: Reads the 386 debug register save area. offset is a logical offset from the base of the register save area in the uarea. This command may be used to read a particular register or a subset of the entire save area.
P_WUDREGS: Writes to the 386 debug register save area. offset is a logical offset from the base of the register save area in the uarea. This command may be used to read a particular register or a subset of the entire save area.

The 80386 debug register set may be used to implement text and data breakpoints. The layout and format of the debug register save area is highly chip dependent. The offsets of the registers are defined in <sys/reg.h>.

Certain fields, such as global bits, in the status register remains unaffected by any instance of P_WUDREGS. See /usr/include/sys/debugreg.h for the definition of any flags.

The file /usr/include/sys/paccess.h includes a structure template for reading and writing the debug register save area:

   struct debugregs

This may be used in conjuction with /usr/include/sys/debugreg.h for convenient handling of bitwise operations.

P_RUOFFS: This command is used to obtain a list of kernel dependent uarea offsets typically used by debuggers such as adb and sdb. This allows an application developer to avoid using hard coded values and thereby gain greater independence from specific kernel versions.
pid and offset are ignored by this command.

The command returns the first count bytes of the offsets structure defined in paccess.h. That structure is defined as follows:

   typedef long uoff;
   
   /* 3.2 uarea offsets  */
   

   struct uoffsets {
           uoff u_info;            /* version */
           uoff u_uaddr;           /* kernel virtual address of uarea  */
           uoff u_ar0;             /* user register save area pointer */
           uoff u_fps;             /* floating point save area  */
           uoff u_fpemul;          /* separate emulator save area  */
           uoff u_fpvalid;         /* if floating point save is valid */
           uoff u_weitek;          /* per proc weitek flag */
           uoff u_weitek_reg;      /* weitek save area  */
           uoff u_debugreg;        /* debug register save area  */
           uoff u_ldt;             /* offset of ldt  */
           uoff u_ldtlimit;        /* size of ldt  */
           uoff u_tss;             /* 3.2 adb  */
           uoff u_sztss;           /* 3.2 adb  */
           uoff u_sigreturn;       /* user signal return */
           uoff u_signal;
           uoff u_sdata;           /* u_exdata.ux_datorg */
           uoff u_dsize;           /* data size */
           uoff u_ssize;           /* stack size */
           uoff u_tsize;           /* text size  */
           uoff u_sub;             /* stack upper  bound */
           uoff uvstack;           /* virtual address of stack top */
           uoff uvtext;            /* virtual address of text */
   };

Errors

paccess fails if one or more of the following is true:

[EFAULT]: ptr points outside the allocated address space.
[EINVAL]: 1. cmd is invalid.
2. offset is less than 0 or beyond the size of the relevant structure.
[EIO]: An error was encountered when attempting to access data in the child's address space.
[ESRCH]: pid identifies a child that does not exist or has not executed a ptrace with request 0.

Return value

Upon successful completion, paccess returns the number of bytes successfully transferred to or from the child process. Otherwise, a value of -1 is returned and errno is set to indicate the error.

Files

/usr/include/sys/paccess.h

Standards conformance

paccess is an extension of AT&T System V provided by the Santa Cruz Operation.