-
Notifications
You must be signed in to change notification settings - Fork 2
/
quark_queue_get_event.3
181 lines (181 loc) · 4.29 KB
/
quark_queue_get_event.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
.Dd $Mdocdate$
.Dt QUARK_QUEUE_GET_EVENT 3
.Os
.Sh NAME
.Nm quark_queue_get_event
.Nd main quark driver
.Sh SYNOPSIS
.In quark.h
.Ft const struct quark_event *
.Fn quark_queue_get_event "struct quark_queue *qq"
.Sh DESCRIPTION
.Nm
returns a pointer to the next
.Vt quark_event ,
or NULL if there isn't any.
.Pp
This function is the main driver of quark.
Quark doesn't create threads or introduces hidden control flows, all its state
is mutated through this function call.
For a better explanation of quark's design, refer to
.Xr quark 7 .
A summary of what this function does:
.Bl -bullet
.It
Populates its priority queue with raw events by calling into the backend
populate function.
.It
Attempts to collect raw events that are deemed old enough from its priority
queue, if successfull tries to aggregate such events.
.It
Converts the collected raw events into a proper
.Vt quark_event .
This involves consulting its internal cache and enriching said event.
The storage for the returned
.Vt quark_event
is static and must not be modified.
.It
Garbage collects cached events that are marked for deletion and are old enough.
When a process exits, its event cache is marked for deletion, but a grace time
is given before purging it so that the user might still query it for some time.
.El
.Pp
A
.Vt quark_event
is defined as:
.Bd -literal
struct quark_event {
u64 events;
const struct quark_process *process;
};
.Ed
.Bl -tag -width "events"
.It Em events
A bitmask representing the events that originated this
.Vt quark_event :
.Bl -tag -width "QUARK_EV_SETPROCTITLE" -compact
.It Dv QUARK_EV_FORK
New process, result of a fork.
.It Dv QUARK_EV_EXEC
Process changed image, result of an exec.
.It Dv QUARK_EV_EXIT
Process exited.
.It Dv QUARK_EV_SETPROCTITLE
Process changed its name (COMM).
.El
.Pp
It's important to note that
.Em events
is what triggered the event, not what is known about the process.
.Pp
It might also be more than one value as events get
aggregated.
For example, a short lived process will have the following mask:
.Dv QUARK_EV_FORK | QUARK_EV_EXEC | QUARK_EV_EXIT .
.It Em process
A pointer to the process which originated the event.
.Vt struct quark_process
is defined as:
.Bd -literal
struct quark_process {
u32 pid;
u64 flags;
/* QUARK_F_PROC */
u64 proc_cap_inheritable;
u64 proc_cap_permitted;
u64 proc_cap_effective;
u64 proc_cap_bset;
u64 proc_cap_ambient;
u64 proc_time_boot;
u32 proc_ppid;
u32 proc_uid;
u32 proc_gid;
u32 proc_suid;
u32 proc_sgid;
u32 proc_euid;
u32 proc_egid;
u32 proc_pgid;
u32 proc_sid;
u32 proc_tty_major;
u32 proc_tty_minor;
u32 proc_entry_leader_type;
u32 proc_entry_leader;
u32 proc_uts_inonum;
u32 proc_ipc_inonum;
u32 proc_mnt_inonum;
u32 proc_net_inonum;
/* QUARK_F_EXIT */
s32 exit_code;
u64 exit_time_event;
/* QUARK_F_COMM */
char comm[16];
/* QUARK_F_FILENAME */
char filename[1024];
/* QUARK_F_CMDLINE */
size_t cmdline_len;
char cmdline[1024];
/* QUARK_F_CWD */
char cwd[1024];
};
.Ed
.Pp
.Em flags
represent the fields which are known about the process, these can be
cached and originate from previous events.
Each bit in the set represents one or more members of the structure, if the bit
is unset, the respective members are invalid/unknown.
.Pp
.Bl -tag -width "QUARK_F_FILENAME" -compact
.It Dv QUARK_F_PROC
.Em proc_
members are valid.
.It Dv QUARK_F_EXIT
.Em exit_code
is valid.
.It Dv QUARK_F_COMM
.Em comm
is valid.
.It Dv QUARK_F_FILENAME
.Em filename
is valid.
.It Dv QUARK_F_CMDLINE
.Em cmdline
and
.Em cmdline_len
are valid.
.It Dv QUARK_F_CWD
.Em cwd
is valid.
.El
.El
.Sh MEMORY PROTOCOL
The returned
.Vt quark_event
pointer as well as the
.Em process
member point to internal data, they
.Em MUST NOT
be modified and/or stored.
In the case of multithreading, the pointers should not be accessed concurrently
with another running
.Nm .
.Pp
In other words, read the stuff you want, copy it out, and forget about it.
.Sh RETURN VALUES
A pointer to
.Vt quark_event .
If there aren't events, NULL is returned and the user should consider calling
.Xr quark_queue_block 3 .
.Sh SEE ALSO
.Xr quark_event_dump 3 ,
.Xr quark_process_lookup 3 ,
.Xr quark_queue_block 3 ,
.Xr quark_queue_close 3 ,
.Xr quark_queue_default_attr 3 ,
.Xr quark_queue_get_epollfd 3 ,
.Xr quark_queue_get_stats 3 ,
.Xr quark_queue_open 3 ,
.Xr quark 7 ,
.Xr quark-btf 8 ,
.Xr quark-mon 8 ,
.Xr quark-test 8