utrace_prepare_examine(9) [suse man page]

UTRACE_PREPARE_EXAMI(9) 					  utrace core API					   UTRACE_PREPARE_EXAMI(9)

NAME

       utrace_prepare_examine - prepare to examine thread state

SYNOPSIS

       int utrace_prepare_examine(struct task_struct * target, struct utrace_engine * engine, struct utrace_examiner * exam);

ARGUMENTS

       target
	   thread of interest, a struct task_struct pointer

       engine
	   engine pointer returned by utrace_attach_task

       exam
	   temporary state, a struct utrace_examiner pointer

DESCRIPTION

       This call prepares to safely examine the thread target using struct user_regset calls, or direct access to thread-synchronous fields.

       When target is current, this call is superfluous. When target is another thread, it must held stopped via UTRACE_STOP by engine.

       This call may block the caller until target stays stopped, so it must be called only after the caller is sure target is about to
       unschedule. This means a zero return from a utrace_control call on engine giving UTRACE_STOP, or a report_quiesce or report_signal callback
       to engine that used UTRACE_STOP in its return value.

       Returns -ESRCH if target is dead or -EINVAL if UTRACE_STOP was not used. If target has started running again despite UTRACE_STOP (for
       SIGKILL or a spurious wakeup), this call returns -EAGAIN.

       When this call returns zero, it's safe to use struct user_regset calls and task_user_regset_view on target and to examine some of its
       fields directly. When the examination is complete, a utrace_finish_examine call must follow to check whether it was completed safely.

Kernel Hackers Manual 2.6.					     July 2010						   UTRACE_PREPARE_EXAMI(9)

UTRACE_SET_EVENTS(9)						  utrace core API					      UTRACE_SET_EVENTS(9)

NAME

       utrace_set_events - choose which event reports a tracing engine gets

SYNOPSIS

       int utrace_set_events(struct task_struct * target, struct utrace_engine * engine, unsigned long events);

ARGUMENTS

       target
	   thread to affect

       engine
	   attached engine to affect

       events
	   new event mask

DESCRIPTION

       This changes the set of events for which engine wants callbacks made.

       This fails with -EALREADY and does nothing if you try to clear UTRACE_EVENT(DEATH) when the report_death callback may already have begun,
       if you try to clear UTRACE_EVENT(REAP) when the report_reap callback may already have begun, or if you try to newly set UTRACE_EVENT(DEATH)
       or UTRACE_EVENT(QUIESCE) when target is already dead or dying.

       This can fail with -ESRCH when target has already been detached, including forcible detach on reaping.

       If target was stopped before the call, then after a successful call, no event callbacks not requested in events will be made; if
       UTRACE_EVENT(QUIESCE) is included in events, then a report_quiesce callback will be made when target resumes.

       If target was not stopped and events excludes some bits that were set before, this can return -EINPROGRESS to indicate that target may have
       been making some callback to engine. When this returns zero, you can be sure that no event callbacks you've disabled in events can be made.
       If events only sets new bits that were not set before on engine, then -EINPROGRESS will never be returned.

       To synchronize after an -EINPROGRESS return, see utrace_barrier.

       When target is current, -EINPROGRESS is not returned. But note that a newly-created engine will not receive any callbacks related to an
       event notification already in progress. This call enables events callbacks to be made as soon as engine becomes eligible for any callbacks,
       see utrace_attach_task.

       These rules provide for coherent synchronization based on UTRACE_STOP, even when SIGKILL is breaking its normal simple rules.

Kernel Hackers Manual 2.6.					     July 2010						      UTRACE_SET_EVENTS(9)