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

NAME

6       utrace_prepare_examine - prepare to examine thread state
7

SYNOPSIS

9       int utrace_prepare_examine(struct task_struct * target,
10                                  struct utrace_engine * engine,
11                                  struct utrace_examiner * exam);
12

ARGUMENTS

14       target
15           thread of interest, a struct task_struct pointer
16
17       engine
18           engine pointer returned by utrace_attach_task
19
20       exam
21           temporary state, a struct utrace_examiner pointer
22

DESCRIPTION

24       This call prepares to safely examine the thread target using struct
25       user_regset calls, or direct access to thread-synchronous fields.
26
27       When target is current, this call is superfluous. When target is
28       another thread, it must be held stopped via UTRACE_STOP by engine.
29
30       This call may block the caller until target stays stopped, so it must
31       be called only after the caller is sure target is about to unschedule.
32       This means a zero return from a utrace_control call on engine giving
33       UTRACE_STOP, or a report_quiesce or report_signal callback to engine
34       that used UTRACE_STOP in its return value.
35
36       Returns -ESRCH if target is dead or -EINVAL if UTRACE_STOP was not
37       used. If target has started running again despite UTRACE_STOP (for
38       SIGKILL or a spurious wakeup), this call returns -EAGAIN.
39
40       When this call returns zero, it´s safe to use struct user_regset calls
41       and task_user_regset_view on target and to examine some of its fields
42       directly. When the examination is complete, a utrace_finish_examine
43       call must follow to check whether it was completed safely.
44
45
46
47Kernel Hackers Manual 2.6.         June 2019           UTRACE_PREPARE_EXAMI(9)