ttrace_wait - wait for ttrace event
int ttrace_wait(pid_t pid, lwpid_t lwpid, ttwopt_t option,
ttstate_t *tsp, size_t size);
The ttrace_wait() system call provides a means to wait for a ttrace()
event to occur. A tracing process (debugger) will normally invoke
ttrace_wait() after a process or any of its threads has been set
ttrace_wait() synchronizes tracing requests directed at threads within
the traced process. This mechanism differs from the process-oriented
synchronization provided by wait() or waitpid() (see wait(2)).
The pid argument identifies the process-id of a traced process which
the debugger expects to stop. If pid is a positive value, and lwpid
is zero, then ttrace_wait() will wait for any thread in the traced
process identified by pid to stop in response to an outstanding ttrace
event. The information concerning the thread that hit the event point
is available in the ttstate_t structure (see ttrace(2)).
The lwpid argument identifies the Lightweight Process (LWP) id of a
thread in the traced process pid for which the debugger must wait to
validate ttrace() request completion. If both pid and lwpid are non-
zero values, ttrace_wait() suspends the calling process until the
specified LWP in the traced process stops.
When multiple child processes are simultaneously traced, ttrace_wait()
can be used to identify the process-id and LWP id of a thread which
stopped in response to any outstanding ttrace() request established
for the group of traced child processes. This is achieved by invoking
ttrace_wait() with both pid and lwpid set to 0 (zero).
A zero pid and non-zero lwpid will return an error.
The option argument must specify either TTRACE_WAITOK or
TTRACE_NOWAIT. These values control the synchronizing effect of
ttrace_wait() on the calling process. The TTRACE_NOWAIT value causes
ttrace_wait() to behave in non-blocking mode and return to the calling
process immediately whether or not a pre-existing ttrace request
completed on behalf of the tracing process. With TTRACE_WAITOK,
ttrace_wait() suspends the calling process until the requested pid
and/or LWP stop.
As mentioned above, the tsp argument references a ttstate_t structure
(see ttrace(2)) which provides all the needed information regarding
Hewlett-Packard Company - 1 - HP-UX Release 11i: November 2000
the stopped thread. The size argument specifies the size of the
ttstate_t structure referenced by addr.
If the call succeeds, ttrace_wait() will return 1 (one) if the event
was never waited for, 0 (zero) otherwise. If the call fails, -1 is
returned and errno is set to the appropriate value.
The ttrace_wait() system call fails if one or more of the following is
[EINVAL] pid is zero and lwpid is non-zero.
[EINVAL] The option is invalid.
[EINVAL] The lwpid is not controlled by process pid.
[ESRCH] The pid or lwpid do not identify an existing process
[EACCES] The pid does not identify a process debugged by the
[ECHILD] The process (LWP) died while it was waited for.
[EINTR] ttrace_wait() was interrupted by a signal.
[EFAULT] An invalid address was given for the kernel to write
ttrace_wait() was developed by HP.
Hewlett-Packard Company - 2 - HP-UX Release 11i: November 2000