ttrace_wait.2 (2010 09)

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 pro-
cess 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 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) oth-
erwise. 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.
AUTHOR
ttrace_wait() was developed by HP.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1