unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 ttrace_wait(2)						      ttrace_wait(2)




 NAME
      ttrace_wait - wait for ttrace event

 SYNOPSIS
      #include <&lt&lt&lt;sys/ttrace.h>&gt&gt&gt;

      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



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 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
      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.

 SEE ALSO
      ttrace(2), wait(2).


















 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000