NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | ATTRIBUTES | SEE ALSO
#include <chorus.h> #include <reg.h> #include <atrace.h>int atrace(int request, const KnCap *cactorcap, char *addr, int data, char *addr2);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
The atrace() call allows a process to control the execution of another process. This system call is similar to the ptrace() system call in UNIX. Its primary use is for the implementation of breakpoint debugging. The traced process behaves normally until it encounters an exception, at which point it enters a stopped state and the debugger is notified using awaits(2K).
The system maintains the concept of a target thread, which is the identifier of the thread that encountered the exception. Some atrace() requests apply to the thread identified by the value of the target thread. (ATRACE_SINGLESTEP, ATRACE_SETREGS and ATRACE_GETREGS.) The target thread is set or reset by the system as soon as a thread causes the process to stop. It can also be reset by the debugger using a specific atrace() request.
When the process is stopped, the debugger can examine and modify its core image using atrace(). The debugger can also make the process terminate or continue. By using the ATRACE_THREADSUSPEND and ATRACE_THREADRESUME requests before making the process continue execution using ATRACE_CONT, the debugger can restart a subset of the threads within the process.
The request argument determines the precise action to be taken by atrace(). For each request, cactorcap must designate a debugged process. If the semantics of the addr, data and/or addr2 arguments are not specified for a request, those arguments are ignored. The debugged process must be stopped before the requests can be made.
These requests return the word at the location addr in the address space of the process to the debugger. These two requests will fail if addr is not the start address of a word or is outside the process's address space; in this case, a value of -1 is returned to the debugger and errno is set to EIO.
These requests put the value given by the data argument into the address space of the process at the location addr. Upon successful completion, the value written into the address space of the process is returned to the debugger. These two requests will fail if addr is not the start address of a word or is outside the process's address space; in this case, a value of -1 is returned to the debugger and errno is set to EFAULT.
This request causes the process to resume execution. The target thread resumes execution at the address addr. All other threads will also resume execution, unless suspended by ATRACE_THREADSUSPEND. For this request, the data argument must be equal to 0. Upon successful completion, 0 is returned to the debugger; otherwise -1 is returned and errno is set to EFAULT.
This request causes the process to terminate with the same consequences as _exit(2K).
This request sets the trace bit in the Processor Status Word of the target thread, it then executes the same steps listed above for the ATRACE_CONT request, with the exception that only the target thread will be restarted. All other threads remain in a stopped state. The trace bit causes an exception upon completion of one machine instruction, which allows single-stepping of the target thread.
Start tracing a running process, designated by cactorcap.
Stop tracing the process designated by cactorcap. The process continues its execution from the address addr. If addr is defined as (char *) 1 the execution continues from where it stopped. The data argument must be 0.
ATRACE_GETREGS
returns the registers of the target thread in the process designated by cactorcap to a table pointed to by addr.
The registers table type is regs
as described in <reg.h>. ATRACE_SETREGS writes the registers
of the target thread in the process designated by cactorcap
from a table pointed to by addr. The registers table
type is regs
as described in <reg.h>.
ATRACE_GETTHREADREGS returns the registers of the thread identified by data in the process designated by cactorcap
to a structure pointed to by addr. The registers table
type is regs
as described in <reg.h>. ATRACE_SETTHREADREGS writes the registers
of the thread identified by data in the process designated
by cactorcap from a structure pointed to by addr.The registers table type is regs
as described
in <reg.h>.
The identifier of the current target thread is returned.
Set the target thread to the thread identified by the data argument.
Suspend the thread identified by data (see threadSuspend(2K)). If that thread is the thread which caused the process to stop, the thread will only be suspended at the time the debugger restarts the process using ATRACE_CONT or ATRACE_DETACH.
Resume the thread identified by data (see threadResume(2K)).
Return the number of threads in the process designated by cactorcap. For each thread within the process, return the KnThreadStat
structure in an array pointed to by addr.
The number of bytes copied to addr is limited to the
amount specified in data.
Get or set the symbolic name of the thread identified by data.
Note: -1 can be a legitimate return value of atrace() in the case of a PEEK request. Therefore, the only way to check whether atrace() has failed is to set errno to 0 before calling atrace() and then check the value of the errno variable.
If atrace() fails, it will set errno to one of the following values:
request is an illegal number.
One or more of the arguments provided is outside the caller's memory space.
The thread designated by data does not correspond to a valid thread identifier within the process designated by cactorcap.
cactorcap designated a process that does not exist or is not debugged by the calling process.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Deprecated : Replaced by ptrace(2K) |
NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | ATTRIBUTES | SEE ALSO