ttrace(2)

This request must be issued by a child process if it is to be traced by its parent.

For this request, the pid, lwpid, addr, and addr2 arguments must be set to 0 (zero) and data must be set to TT_VERSION. Peculiar results occur if the parent does not expect to trace the child.

Note that it is critical for future backward compatibility that the TT_VERSION macro itself be used and not its value.

This request allows the calling process to trace the process identified by pid. The process pid does not have to be a child of the calling process, but the effective user ID of the calling process must match the real and saved uid of the process pid unless the effective user ID of the tracing process is super-user.

When this call returns, the target process (all its threads) is stopped.

The addr argument specifies the action to be taken if the debugger exits without having detached the target process. If the value is TT_KILL_ON_EXIT, the attached process(es) will be killed. If the value is TT_DETACH_ON_EXIT, the attached process(es) will be resumed and detached as if the debugger had performed a TT_PROC_DETACH request. The lwpid and addr2 arguments must be set to zero and data must be TT_VERSION (see TT_PROC_SETTRC above).

This request detaches the traced process and allows it to continue executing. It behaves identically to TT_PROC_CONTINUE except that the process is no longer being traced after the call returns.

For this request, the lwpid, addr, data and addr2 arguments must be set to zero.

These requests allow reading from the target process text (TT_PROC_RDTEXT) or data space (TT_PROC_RDDATA).

The addr argument specifies the offset to be read from. The data argument specifies the number of bytes to read and the addr2 argument specifies where to store that data in the tracing process.

The lwpid argument must be set to zero.

These requests allow writing into the target process text (TT_PROC_WRTEXT) and data spaces (TT_PROC_WRDATA).

The addr argument specifies the offset to be written to. The data argument specifies the number of bytes to write.a The addr2 argument specifies where to get the data in the tracing process.

The lwpid argument must be set to zero.

This request causes the traced process (all its threads) to stop. If a thread was already stopped by the debugger prior to this call, its state is not modified.

The lwpid, addr, data and addr2 arguments must be set to zero.

This request causes the entire traced process to resume execution. All threads that had been stopped directly (request) or indirectly (event) by the debugger are resumed with all their pending signals intact.

The data, addr and addr2 arguments must be set to zero.

This request is used by the calling process to access the path name of the executable file provided as a path or file argument to exec(). The request reads data bytes of data of the pathname string from the traced process' context into the data buffer in user space pointed to by addr.

In the typical case, data is equal to the value of the ttexec_data_t.tts_len member of the ttstate_t structure returned via the TT_LWP_GET_STATE or other ttrace requests returning a Lightweight Process (LWP or lwp) state. The length of the path does not include a terminating null character. The data is available during the entire life of the process.

The lwpid and addr2 arguments must be set to zero.

This request returns the process-wide event flags and signal mask values.

The data argument specifies the number of bytes to be read from the context of the traced process into the ttevent_t data structure in user space pointed to by addr.

The lwpid and addr2 arguments must be set to zero.

The ttevent_t data structure is as follows:

The options provided in tte_opts control the behavior of child processes produced by fork() and are as follows:

If TTEO_NOSTRCCHLD is set, the child process resulting from a fork() will not be traced. This makes it possible for a debugger to debug another debugger. The TTEO_PROC_INHERIT and TTEO_LWP_INHERIT options allow events to be inherited by child processes and/or threads. Refer to the EVENTS section below.

If TTEO_NORM_SIGTRAP is set, the SIGTRAP signal behaves normally. That is, it is getting delivered (the default behavior is to drop these signals).

This request allows the tracing process to establish events and signals the traced process will respond to. Refer to the EVENTS section for a description of these events.

The addr argument is a pointer to a ttevent_t structure to be copied into the target process. The data argument specifies the number of bytes to be transferred.

The lwpid and addr2 arguments must be set to zero.

This request returns the ttstate_t structure associated with the first thread on the stopped list. It resets the list pointer to the first entry in the list. The TT_PROC_GET_NEXT_LWP_STATE request (see below) provides the means to examine the state of other stopped threads.

The data argument specifies the number bytes to be read from the context of the traced process into the ttstate_t data structure in user space pointed to by addr. The lwpid and addr2 arguments must be zero.

The ttstate_t structure provides the debugger with the means to query the system for the state of a thread. It is established when a thread enters the debugger stopped state and, except for the TTS_WAITEDFOR bit, is invariant until the thread is resumed. Its layout is as follows:

tts_pid is the process ID.

tts_lwpid is the lwpid of the stopped thread.

tts_user_tid is the thread's user ID.

tts_event is the event that caused the stop (TTEVT_NONE if the thread stopped because of a ttrace command).

The tts_flags provide information about the state of the thread before it was stopped. The information specifies whether or not the thread has been waited for by ttrace_wait(), whether or not it is processing a system call, whether it is a 32-bit or a 64-bit process and whether the thread is in the exit() system call. The values are as follows:

The following three arguments provide information regarding the system call being executed when the thread was stopped. This information is valid only if the TTS_INSYSCALL bit is set in tts_flags.

tts_scno is the system call number.

tts_scnargs is the number of arguments of the system call.

tts_scarg is the argument list of the system call.

The data associated with a TTEVT_EXEC event is as follows:

tts_pathlen is the length of the pathname of the exec() system call.

The data associated with a TTEVT_FORK or TTEVT_VFORK event is as follows:

tts_fpid is the process ID of the other side of the fork.

tts_flwpid is the thread ID of the other side of the fork.

tts_isparent is zero for the child event and one for the parent.

The data associated with a TTEVT_SIGNAL event is as follows:

tts_signal is the signal number.

tts_sigflags is TTSF_USERSIGINFO if a siginfo was delivered with the signal, 0 otherwise.

tts_sigaction is the disposition of the signal.

tts_siginfo is the siginfo, if applicable.

The data associated with a TTEVT_LWP_CREATE, TTEVT_LWP_TERMINATE or TTEVT_LWP_ABORT_SYSCALL event is as follows:

tts_target_lwpid is the lwpid of the targeted lwp.

The data associated with a TTEVT_SYSCALL event is as follows:

The tts_rval fields are the return value(s) of the system call.

tts_errno is the error status if the system call failed.

The data associated with a TTEVT_LWP_EXIT event is as follows:

tts_exitcode is the exit code of the process.

The data associated with a TTEVT_BPT_SSTEP event is as follows:

tts_isbpt is set to zero if it is a single-step and to one if the event is a breakpoint (including single-stepping into a breakpoint).

This request is identical to TT_PROC_GET_FIRST_LWP_STATE except that it returns the state for the next thread on the stopped list. As events cause threads to stop, they are added to this list. This provides a way for the tracing process to examine the state of all the stopped threads in the target process. Both these requests return either a 1 (one) if valid data is returned or 0 (zero) otherwise. Valid data is returned if the status is that there was a stopped thread for which to return.

This request allows the debugger to obtain protection information for a page in the address space of the code being debugged. The addr argument specifies the address for which the protection is to be obtained. The addr2 argument specifies the address of an integer in which the protection data will be copied.

For this request, the lwpid and data arguments must be set to zero.

This requests allows the debugger to modify the protection of the address space of the code being debugged. The addr argument specifies the start address. The data argument specifies the extent (in bytes) of the space to be modified. The addr2 argument contains the new protection. Note that protection changes affect whole pages (see mprotect(2) for more information).

For this request, the lwpid argument must be set to zero.

This request allows the debugger to pass a bitmap to the kernel indicating which system calls should cause a debugger stop.

The addr argument must be set to TTSCBM_SELECT or TTSCBM_UNSELECT to indicate whether the bitmap represents a positive (meaning that the calls in the bitmap will result in a stop) or a negative (meaning that all calls except those in the bit map will result in a stop) list.

The data argument is the size of the bitmap, in bytes. A size of zero indicates that the current bitmap, if any, should be cleared.

The addr2 argument is the user address where the bitmap is located. If data is zero, this value must be zero too.

The lwpid argument must be zero.

This request causes the traced process to terminate. It has the same consequence as exit() being invoked by one of the process threads. The lwpid, addr, data and addr2 arguments must be zero.

This request causes the traced process to generate a core file in the target process's current working directory. The core file is named core.pid where pid is the process ID of the target process. The process's state is left unchanged. The lwpid, addr, data and addr2 arguments must be zero.

This request causes the thread identified by lwpid to stop executing. If the thread is already stopped by the debugger, or by an event, an error is returned.

The addr, data and addr2 arguments must be zero.

This request causes the thread identified by lwpid to resume execution or, rather, to return to the state it was in prior to being stopped by the debugger. If the thread had not previously been stopped by the debugger, an error is returned.

If addr is not TT_NOPC, that value is loaded in the program counter before execution is resumed. Unexpected behavior will result if this value is not within the same function since only the PC, not the context, is being modified.

If data is non-zero, it is expected to be a valid signal number and the thread will continue as if it had received this signal.

The addr2 argument must be zero.

This request causes the stopped thread identified by lwpid to resume execution for one machine instruction. It causes a flag to be set so that an interrupt occurs upon the completion of one machine instruction, and then executes the same steps as listed above for the TT_LWP_CONTINUE request.

This request is the same as TT_PROC_GET_EVENT_MASK except for the thread identified by lwpid.

This request is the same as TT_PROC_SET_EVENT_MASK except for the thread identified by lwpid.

This calls returns the state of the thread identified by lwpid. If the thread was not previously stopped by the debugger or waiting to be continued after an event, an error is returned.

This call returns the feature level of the operating system and has been introduced to help debugger developers make their tools more portable from one version to another. 11.0 systems can be identified by the fact that this call will return an error. Later releases will return the TT_FEATURE_LEVEL value the operating system was compiled with (see ttrace.h). The release levels for systems newer than 11.0 are:

This event flag indicates that the traced thread needs to examine signal mask bits when processing signals. This means that, by default, threads stop when receiving a signal. If the signal being processed has its mask bit set, signal processing continues as though the process were not traced: the traced thread is not stopped, and the tracing process is not notified of the signal. On the other hand, if the signal mask bit is not set for the signal being processed, the traced thread is stopped and the tracing process is notified via ttrace_wait().

Note that the SIGKILL signal can never be unmasked. It behaves as though its mask bit were always set. This means that a SIGKILL signal cannot be used to stop a traced thread. The SIGTRAP signal is also special in that it is used to stop traced threads when they respond to a trap, such as a breakpoint or a single step. Consequently, masking SIGTRAP, even though allowed, will result in unexpected behavior in these conditions.

This event flag indicates that the traced thread needs to take special action when it invokes fork(). When set, both the parent thread and the initial thread in the child process stop (after the child process is marked as a traced process and adopts its parent's debugger). Both threads log the fact that they stopped in response to a TTEVT_FORK event. The parent thread provides the pid of the child process in the appropriate portion of the ttstate_t structure. The initial thread of the child process provides the pid of the parent in the same location. See the ttstate_t structure description for further details.

This event flag indicates that the traced thread needs to take special action when it invokes vfork(). The behavior is identical to that of TTEVT_FORK but it is important to note that the caveats with respect to vfork(), continue to apply here. In particular, it needs to be remembered that when the child process stops, its parent is asleep, and that the child borrows the parent's address space until a call to exec() or an exit (either by a call to exit() or abnormally) takes place. Continuing the parent process before the above steps take place results in an error.

This event flag indicates that a traced thread needs to notify the debugger upon completion of loading the new executable file, in the exec() system call. The length of the pathname string (not including a null terminating character) is returned in the ttstate_t structure and the path may subsequently be obtained using the TT_PROC_GET_PATHNAME request.

This event flag indicates that the traced process will notify the debugger upon return of all system calls. The traced process will also provide the following information: the system call number, its number of arguments and all its arguments, its return value and its error return in the ttstate_t structure. If the system call is a fork(), vfork() or exec() and if, respectively, the TTEVT_FORK, TTEVT_VFORK or TTEVT_EXEC event is set, only the notification associated with these events is performed. See the TT_PROC_SET_SCBM request.

This event flag requests notification of system call entry points. By default, all system calls stop at this event if it is selected. The information provided is the same as for TTEVT_SYSCALL_RETURN events but the return value and error are always zero.

Identical to TTEVT_SYSCALL_ENTRY but for system call restarts.

This event flag indicates that the traced process needs to notify the debugger action when it invokes exit(). When set, the traced thread stops while still potentially multithreaded.

This event flag indicates that the debugger wants to be notified when the lwp_create() system call is invoked to create a thread. When set, the calling thread stops and provides the debugger with the lwpid of the newly created thread.

This event flag indicates that the debugger wants to be notified when a thread is exiting via the lwp_exit() system call. The thread stops upon entry to the system call.

This event flag indicates that the debugger wants to be notified when a caller thread invokes the lwp_terminate() call on a target thread. When set, the calling thread stops upon entering the system call and provides the lwpid of the thread to be terminated in the ttstate_t structure.

This event flag indicates that the debugger is to be notified when the lwp_abort_syscall() system call is invoked. The lwpid of the target thread is provided in the ttstate_t structure.

This event flag tells the kernel to perform event-based single-stepping and breakpoint notification. If this event is requested, SIGTRAP loses all special meaning. It is highly recommended that debuggers use this event instead of the old signal-based method as it will allow breakpoints and single-steps to take place regardless of the signals the thread is blocking. Unlike the signal-based method, it also guarantees that single-steps and breakpoints events are generated in the context of the thread even if other threads are active in the process.

Note that mixing signal-based and event-based breakpoint/single-stepping may result in unexpected SIGTRAPs being posted to the process being debugged.

With this request, the words at offset addr in the save_state structure are returned to the tracing process. The data argument is the size of the read. The addr2 argument points to the location in the debugger space where the data will be written. The addr argument must be word-aligned and addr+data must be less or equal to sizeof (save_state_t) (see <machine/save_state.h>).

NOTE: Only 4 and 8 bytes reads and writes are currently supported.

With this request, data bytes of data pointed to by addr2 are written at offset addr in the save_state structure. Only these locations can be written in this way: the general registers, most floating-point registers, a few control registers, and certain bits of the interruption processor status word.

NOTE: Only 4 and 8 bytes reads and writes are currently supported.

request is an illegal number.

A non-zero value has been passed in a parameter expecting a zero value or vice-versa.

The data argument of TT_PROC_SETTRC or TT_PROC_ATTACH is not TT_VERSION.

Size too large for data transfer.

Invalid signal number.

Misaligned request or not a word multiple (TT_PROC_RDTEXT, TT_PROC_WRTEXT).

Invalid signal (TT_LWP_CONTINUE, TT_LWP_SINGLE).

Invalid offset (TT_LWP_RUREGS, TT_LWP_WUREGS).

ptrace() and ttrace() requests are being mixed.

An offset in the save_state structure is not word-aligned.

An invalid register is targeted by TT_LWP_WUREGS.

The size argument to a TT_PROC_GET_PATHNAME is larger than MAXPATHLEN.

The pid argument to the TT_PROC_ATTACH is the pid of the invoker.

The process is already being traced.

Attempting to trace a process whose binary resides on a soft/interruptible NFS mount point.

The executable image of the process being attached resides across an interruptible NFS mount.

Invalid user address.

The specified thread cannot be attached for tracing.

pid and/or lwpid identify a process or a thread to be traced that does not exist or has not executed a ttrace() with the TT_PROC_SETTRC request.

Cannot suspend process or attach is interrupted (TT_PROC_ATTACH).

Attempting to stop a thread already stopped by the debugger.

Attempting to resume a thread not stopped by the debugger.

Attempting to read or write registers while the thread is not stopped.

Attempting to obtain the state of a thread which was not stopped by the debugger.

Invoked before an exec event took place (TT_PROC_GET_PATHNAME).

The process is exiting and the request is not allowed in this condition.

The debugger is attempting to modify wide registers after having modified narrow registers.

The debugger is attempting to first modify the text of a process in the middle of a vfork. Text modification is allowed during vfork as long as it was first modified before the vfork.

Data in this register is not readable or not writable at this time.

One thread of a multithreaded process (p1) has performed a vfork(), the child (p2) is stopped at the vfork event and the debugger is attempting to stop or resume a thread in the parent process (p1).

System is out of memory.

Unable to attach to a process. This error can only be encountered when attaching to a process in the middle of an exec(2) syscall.