| QUARK_QUEUE_GET_EVENT(3) | Library Functions Manual | QUARK_QUEUE_GET_EVENT(3) |
quark_queue_get_event —
main quark driver
#include
<quark.h>
const struct quark_event *
quark_queue_get_event(struct
quark_queue *qq);
quark_queue_get_event returns a pointer to the next
quark_event, or NULL if there isn't any.
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 quark(7). A summary of what this function does:
A quark_event is defined as:
struct quark_event {
u64 events;
const struct quark_process *process;
};
QUARK_EV_FORKQUARK_EV_EXECQUARK_EV_EXITQUARK_EV_SETPROCTITLEQUARK_EV_MPROTECTsecurity_file_mprotect()
check. The
mprotect
member contains the VMA bounds, normalized previous protection,
userspace-requested and kernel-adjusted protection, and backing-file
identity. For file-backed mappings,
path
is the mount-namespace relative path of the backing file; it is
NULL for anonymous mappings. Anonymous
attempts are reported once per protection transition per program
image. File-backed attempts are reported once per protection
transition, file and program image when the device and inode number
can be read. On ext2, ext3, ext4, XFS and tmpfs, the file identity
also includes a usable, nonzero inode generation. A file with a reused
inode number and a new generation is reported again. Without a usable
generation, the cache uses only the device and inode number. Repeated
transitions are still suppressed, but a new file with a reused inode
number can have its first event suppressed. If the device or inode
number cannot be read, attempts can report repeats. A successful
execve(2) starts a new program
image and resets this tracking, so the same process can report a
transition again. The event describes an attempt and does not assert
that the protection change was committed.QUARK_EV_BPFBPF_PROG_LOAD attempt, reported with its
actual operation result in
bpf.ret
(a nonnegative fd, including zero, or negative errno).
cmd is
the command with the BPF_COMMON_ATTRS bit
removed. The process identifies the actor when available in the
process cache.
bpf.tgid,
bpf.tid
and
bpf.start_time_ns
retain its host process ID, invoking thread ID and process start time
even when the process cache has no entry. The start time uses
CLOCK_BOOTTIME, like
proc_time_boot.
valid
indicates which metadata was captured.
QUARK_BPF_VALID_ATTR means that
type,
insn_cnt,
attach_type,
flags and
name
were copied from the kernel's zero-filled attributes at
security_bpf().
These describe the requested program type, instruction count,
expected attach type, program flags and name. The instruction count
precedes verifier rewriting. An attempt that fails before the
security check has no valid attributes; zero values alone do not
indicate availability.
QUARK_BPF_VALID_OBJECT
means that a referenced program was observed after ID allocation and
the operation subsequently succeeded.
kind is then
QUARK_BPF_PROG,
id is
its kernel ID and type is its observed program
type. Identity is captured before fd installation, without looking
up the returned fd through the process's fd table. A failed
operation has no valid object identity, including failure to install
the fd after verification. A successful event without valid identity
indicates capture loss; consult
quark_queue_get_stats(3).
It's important to note that events is what triggered the event, not what is known about the process.
It might also be more than one value as
events get aggregated. For example, a short lived process will have the
following mask: QUARK_EV_FORK |
QUARK_EV_EXEC
|
QUARK_EV_EXIT.
struct quark_process {
/* Always present */
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;
/* QUARK_F_CMDLINE */
size_t cmdline_len;
char *cmdline;
/* QUARK_F_CWD */
char *cwd;
/* QUARK_F_CGROUP */
char *cgroup;
};
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.
QUARK_F_PROCQUARK_F_EXITQUARK_F_COMMQUARK_F_FILENAMEQUARK_F_CMDLINEQUARK_F_CWDQUARK_F_CGROUPThe returned quark_event pointer as well as
the process member point to internal data, they
MUST NOT
be modified and/or stored. In the case of multithreading, the pointers
should not be accessed concurrently with another running
quark_queue_get_event.
In other words, read the stuff you want, copy it out, and forget about it.
A pointer to quark_event. If there aren't events, NULL is returned and the user should consider calling quark_queue_block(3).
quark_event_dump(3), quark_process_lookup(3), quark_queue_block(3), quark_queue_close(3), quark_queue_default_attr(3), quark_queue_get_epollfd(3), quark_queue_get_stats(3), quark_queue_open(3), quark(7), quark-btf(8), quark-mon(8), quark-test(8)
| November 17, 2026 | Linux |