1UTRACE_SET_EVENTS(9)            utrace core API           UTRACE_SET_EVENTS(9)
2
3
4

NAME

6       utrace_set_events - choose which event reports a tracing engine gets
7

SYNOPSIS

9       int utrace_set_events(struct task_struct * target,
10                             struct utrace_engine * engine,
11                             unsigned long events);
12

ARGUMENTS

14       target
15           thread to affect
16
17       engine
18           attached engine to affect
19
20       events
21           new event mask
22

DESCRIPTION

24       This changes the set of events for which engine wants callbacks made.
25
26       This fails with -EALREADY and does nothing if you try to clear
27       UTRACE_EVENT(DEATH) when the report_death callback may already have
28       begun, if you try to clear UTRACE_EVENT(REAP) when the report_reap
29       callback may already have begun, or if you try to newly set
30       UTRACE_EVENT(DEATH) or UTRACE_EVENT(QUIESCE) when target is already
31       dead or dying.
32
33       This can fail with -ESRCH when target has already been detached,
34       including forcible detach on reaping.
35
36       If target was stopped before the call, then after a successful call, no
37       event callbacks not requested in events will be made; if
38       UTRACE_EVENT(QUIESCE) is included in events, then a report_quiesce
39       callback will be made when target resumes.
40
41       If target was not stopped and events excludes some bits that were set
42       before, this can return -EINPROGRESS to indicate that target may have
43       been making some callback to engine. When this returns zero, you can be
44       sure that no event callbacks you've disabled in events can be made. If
45       events only sets new bits that were not set before on engine, then
46       -EINPROGRESS will never be returned.
47
48       To synchronize after an -EINPROGRESS return, see utrace_barrier.
49
50       When target is current, -EINPROGRESS is not returned. But note that a
51       newly-created engine will not receive any callbacks related to an event
52       notification already in progress. This call enables events callbacks to
53       be made as soon as engine becomes eligible for any callbacks, see
54       utrace_attach_task.
55
56       These rules provide for coherent synchronization based on UTRACE_STOP,
57       even when SIGKILL is breaking its normal simple rules.
58
59
60
61Kernel Hackers Manual 2.6.       November 2011            UTRACE_SET_EVENTS(9)