DESCRIPTION

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:

• Populates its priority queue with raw events by calling into the backend populate function.
• Attempts to collect raw events that are deemed old enough from its priority queue, if successfull tries to aggregate such events.
• Converts the collected raw events into a proper quark_event. This involves consulting its internal cache and enriching said event. The storage for the returned quark_event is static and must not be modified.
• 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.

A quark_event is defined as:

struct quark_event {
	u64				 events;
	const struct quark_process	*process;
};

events

A bitmask representing the events that originated this quark_event:

QUARK_EV_FORK

New process, result of a fork.

QUARK_EV_EXEC

Process changed image, result of an exec.

QUARK_EV_EXIT

Process exited.

QUARK_EV_SETPROCTITLE

Process changed its name (COMM).

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.

process

A pointer to the process which originated the event. struct quark_process is defined as:

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];
};

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_PROC

proc_ members are valid.

QUARK_F_EXIT

exit_code is valid.

QUARK_F_COMM

comm is valid.

QUARK_F_FILENAME

filename is valid.

QUARK_F_CMDLINE

cmdline and cmdline_len are valid.

QUARK_F_CWD

cwd is valid.