paccess(S) 6 January 1993 paccess(S) Name 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(CP). paccess also provides information about the u-area layout so that applications can determine this at run- time. 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 PRUOFFS, 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 particu- lar 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 partic- ular 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 desig- nated by ptr and a point offset bytes into a region of the child pro- cess's context designated by cmd. PRUOFFS 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: PRDUSER Reads a child process's D address space. offset is a 32 byte virtual address in the child's address space. PRIUSER Reads a child process's I address space. offset is a 32 byte virtual address in the child's address space. PWDUSER Writes to a child process's D address space. offset is a 32 byte virtual address in the child's address space. PWIUSER Writes to a child process's I address space. offset is a 32 byte virtual address in the child's address space. PRUREGS 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 particu- lar 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>. PWUREGS 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 PWUREGS. Certain flags in the flags regis- ter [EFL] will remain unchanged after any instance of PWUREGS. The flags are: + PS_T + PSIE + PSIOPL + PSNT + PSRF + PSVM See the file <sys/tss.h> for a definition of these flags. PRUFREGS 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. PWUFREGS 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>. PRULDT 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. PRUDREGS 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. PWUDREGS Writes to the 386 debug register save area. offset is a log- ical offset from the base of the register save area in the uarea. This command may be used to read a particular regis- ter 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 unaf- fected by any instance of PWUDREGS. 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 con- venient handling of bitwise operations. PRUOFFS 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 exe- cuted a ptrace with request 0. Return value Upon successful completion, paccess returns the number of bytes success- fully 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 See also access(S), ptrace(S) Standards conformance paccess is an extension of AT&T System V provided by the Santa Cruz Operation.