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;
};
A bitmask representing the events that originated this quark_event:
New process, result of a fork.
Process changed image, result of an exec.
Process exited.
Process changed its name (COMM).
An executable protection attempt reached the kernel's () check. The member contains the VMA bounds, normalized previous protection, userspace-requested and kernel-adjusted protection, and backing-file identity. For file-backed mappings, 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.
A BPF_PROG_LOAD attempt, reported with its actual operation result in (a nonnegative fd, including zero, or negative errno). is the command with the BPF_COMMON_ATTRS bit removed. The process identifies the actor when available in the process cache. , and 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 .

indicates which metadata was captured. QUARK_BPF_VALID_ATTR means that type, , , flags and were copied from the kernel's zero-filled attributes at (). 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. is then QUARK_BPF_PROG, 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 | | .

A pointer to the process which originated the event. struct quark_process is defined as:
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.

members are valid.
is valid.
is valid.
is valid.
and are valid.
is valid.
is valid.

The returned quark_event pointer as well as the process member point to internal data, they 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