HP-UX Reference (11i v1 00/12) - 2 System Calls (vol 5)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man2/!!!intro.2
________________________________________________________________
___ ___
t
ttrace_wait(2) ttrace_wait(2)
NAME
ttrace_wait - wait for ttrace event
SYNOPSIS
#include <sys/ttrace.h>
int ttrace_wait(pid_t pid, lwpid_t lwpid, ttwopt_t option,
ttstate_t *tsp, size_t size);
DESCRIPTION
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 running.
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 availablein 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 esta-
blished 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 the stopped thread. The size argument specifies the size of the ttstate_t
structure referenced by addr.
RETURN VALUE
If the call succeeds,
ttrace_wait() will return 1 (one) if the event was never waited for, 0 (zero) other-
wise. If the call fails, -1 is returned and errno is set to the appropriate value.
ERRORS
The ttrace_wait() system call fails if one or more of the following is true:
[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 (LWP).
[EACCES] The pid does not identify a process debugged by the invoking process.
[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 data into.
HP-UX Release 11i: December 2000 − 1 − Section 2−−427
___
___