ttrace_wait(2)                                               ttrace_wait(2)




 NAME    [Toc]    [Back]
      ttrace_wait - wait for ttrace event

 SYNOPSIS    [Toc]    [Back]
      #include <sys/ttrace.h>

      int ttrace_wait(pid_t pid, lwpid_t lwpid, ttwopt_t option,
           ttstate_t *tsp, size_t size);

 DESCRIPTION    [Toc]    [Back]
      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 nonzero
 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 11i Version 2: August 2003






 ttrace_wait(2)                                               ttrace_wait(2)




      the stopped thread.  The size argument specifies the size of the
      ttstate_t structure referenced by addr.

 RETURN VALUE    [Toc]    [Back]
      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    [Toc]    [Back]
      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    [Toc]    [Back]
      ttrace_wait() was developed by HP.

 SEE ALSO    [Toc]    [Back]
      ttrace(2), wait(2).


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003