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 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 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) otherwise.
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.
Printable version
