cchecker reads its settings from the first of these that it finds, and the others are not read:

  1. The file of -c FILE (--config FILE). When it has a [tool.cchecker] table (an agentica.toml or another manifest), that table; else the whole file. A file that is not there or cannot be read is an error (exit 2).
  2. cchecker.toml in the working directory, the project folder.
  3. The [tool.cchecker] table of agentica.toml in the project folder. An agentica.toml without it is skipped.
  4. The defaults: every [library] flag on except short_lock_sections, no [roots], follow_cold = false, no [assume].

--json says which in config ("cchecker.toml", the path given to -c, or "defaults"), and a run without --json says it in one line on standard error. A key that is not one of those below, or a value of the wrong type, is an error (exit 2), so a typo cannot turn a check off.

# An example: every key is optional, and the defaults are in the sections below.
[library]
libuv_blocking = false
short_lock_sections = true

[roots]
short = ["io_poll", "on_timer"]
hot = ["dispatch"]

[effects]
follow_cold = true

[database]
fold_ignoring = ["BUILDING_UV_SHARED"]

[assume]
stop = ["trace_emit"]
stop_calls = ["on_exit>close_handles"]
acquires = ["my_lock(0)"]

Every value is a list of strings except the booleans. A name in a list of [roots] or [assume] is a function name (a static function of that name in any file) or name@path: the function whose file ends with path, by whole parts, with no .. and a leading ./ ignored (put@src/files.c, or put@files.c when no other files.c has a put). In [assume] the path may be the file of the definition or of any declaration (slow@slow.h); in [roots] it is the file of the definition. It works in every list that names functions, and on each side of a stop_calls pair; the lists of fields and locks (stop_fields, the classes of short_locks, owned_locks) name classes instead (below). acquires, releases, tries and the wrappers of short_locks add the place of the parameter: name@path(0).

A name or name@path that no function of the compile database declares is an error (exit 2) that names its key (trace (assume.stop)), so a rename cannot leave a setting that does nothing. Only a full run of a compile database can tell (a run of some files does not see the others), so only it checks the names; another run says on standard error that it did not.

[library] #

Each flag turns a family of library knowledge on or off; all are on by default except short_lock_sections. A finding of the rules has the flags that made it in source of --json (the family of the blocking call, libc_blocking; for an inferred root the inference before it, libuv_callbacks_short+libc_blocking), so a project knows which one to turn off. source is not part of the baseline key. The lists are the sets in src/known.agc (LIBC_BLOCKING, PTHREAD_BLOCKING, LIBUV_BLOCKING, LIBUV_SYSTEM, LOOP_CALLBACKS) and match libuv 1.50: a call that a later libuv adds is not known until they are updated.

FlagWhat it adds
libc_blockingthe calls of libc and POSIX that wait, to the blocking calls of CC_SHORT: files and streams (read, fopen, printf, fsync), sockets (accept, recv, getaddrinfo), waiting (poll, sleep, waitpid), processes (system, popen), dlopen, dlsym, POSIX semaphores and message queues, and the C11 threads (thrd_join, mtx_lock)
pthread_blockingpthread_join, the locks of pthread_mutex_, pthread_rwlock_ and pthread_spin_lock, the waits of pthread_cond_, pthread_barrier_wait and pthread_once
libuv_blockinguv_run, uv_sleep, uv_thread_join, the locks and waits of uv_mutex_, uv_rwlock_, uv_cond_, uv_sem_, uv_barrier_wait, uv_once, and the uv_fs_* calls whose libc call blocks (uv_fs_open, uv_fs_read, uv_fs_write, uv_fs_fsync, ...) when their callback, the last argument, is NULL or 0
libgc_blockingGC_gcollect of the Boehm collector, which stops the world
libuv_callbacks_shorta CC_SHORT root for each function passed as a callback that libuv runs on the loop thread (uv_timer_start, uv_read_start, uv_write, uv_close, the callback of a uv_fs_* request, the after_work_cb of uv_queue_work but never its work_cb, ...; LOOP_CALLBACKS has each call and the place of its callback), and a function stored in the exit_cb field of uv_process_options_t (by an assignment or an initializer; the root names uv_process_options_t.exit_cb). See Roots
libgc_allocthe allocators of the Boehm collector (GC_malloc, GC_malloc_atomic, GC_realloc, GC_strdup, their GC_debug_ forms) to the allocators of CC_GC_ALLOC (source libgc_alloc)
libc_nonblocking_flagsthe flags that make a blocking call return at once, so that it is not blocking for CC_SHORT: open and openat with O_NONBLOCK, recv, send, recvfrom and sendto with MSG_DONTWAIT, waitpid, wait3, wait4 and waitid with WNOHANG, and uv_run with UV_RUN_NOWAIT alone (not UV_RUN_ONCE, UV_RUN_DEFAULT or a mix of them; its value is the same on every target, so the target does not matter for it)
may_jump_callersthe inference of jumps through the calls (Jumps); a finding at such a call has this flag in source. Not library knowledge, but turned off the same way
short_lock_sectionsoff by default, experimental: a lock is short when none of its critical sections reaches a blocking call (see Short locks). Not library knowledge, and the one flag that is false unless the settings set it true

A blocking flag changes only the blocking calls of CC_SHORT: CC_HOT and CC_NO_SYSCALL_UNDER count every known blocking call as a system call whatever the flags.

libc_nonblocking_flags applies when the flag argument is a constant, or a local that gets only constants (no &, ++ or op=; a flag must be in all of them) and gets one before the call on every path: a statement before the call in a block that holds it, with no case of an outer switch between them and no goto in the function. Another variable leaves the call blocking. open with O_NONBLOCK is meant for FIFOs and devices: on a regular file it can still wait for the disk, and the rules do not tell the two apart. The values are those of the target clang builds for (Linux, but on MIPS, SPARC, Alpha and PA-RISC, and macOS); on another target only a flag that the C library defines as a constant of an enum (glibc's MSG_DONTWAIT) counts, and the run says on standard error that it does not know the values.

[effects] #

follow_cold = true makes the walk of the effect rules go into a function that never returns or is cold (see Rules); by default it does not.

[database] #

An entry of the compile database that repeats a file (the same folder and the same flags) is checked once, the first, and folded of --json counts the others. The flags that only change the code the compiler makes for a shared library do not count: -fPIC, -fpic, -fPIE, -fpie and CMake's -D<target>_EXPORTS. Any other define or include path can change the findings, so such entries are each checked.

fold_ignoring names more defines that do not count, when a build adds them to a second library (libuv's BUILDING_UV_SHARED): two entries of one file that differ only in those defines, with any value (-DNAME, -DNAME=1, -D NAME), are one. A name is C's own (NAME, not -DNAME, NAME=1 or A,B), and the list is taken as written (-UNAME -DNAME and -UNAME fold with ["NAME"]). A define in the list hides a different #ifdef from the entries left out, so list only those that do not change the C the rules read; one that adds test-only code or changes linkage (UNIT_TESTING) is a trade-off. Changing the list changes which entries run, so a finding that only an entry left out had counts as fixed for a baseline (--update-baseline drops it, --strict-baseline names it as stale), and one that was out comes back as new.

Roots #

A rule starts from its roots, which come from three places. A project leans on them in this order, and adds the next one only for what the one before does not cover:

  1. Inferred roots: a function passed as a callback to a libuv call that runs it on the loop thread is a CC_SHORT root (libuv_callbacks_short). --no-infer or the flag set to false turns it off.
  2. [roots]: short and hot name the functions that are CC_SHORT or CC_HOT without a mark in the C. A finding of such a root is the same as that of the mark. A name shared by static functions of several files marks all of them; name@path marks one.
  3. The marks of cchecker.h in the C (see Annotations).

A function that is a root in more than one way is one root. The callback of an inferred root is a function named in the call, or a pointer that the rules follow to the functions stored in it (see Rules). NULL or 0 is no callback. A callback that leads to no function (the return value of a call, a parameter that no caller passes a function to) is listed in unresolved_callbacks of --json, each with call, argument (its place, from 0; -1 for a function stored in exit_cb, where call is uv_process_options_t.exit_cb), file and line (absolute for a call outside the working directory), and a run without --json says how many in one line on standard error, so a root is never lost without a word.

A finding of an inferred root has its place in root of --json (callback of uv_read_start at src/net.c:41), and the printed line ends with it:

src/net.c:12:13 CC-EFFECT-SHORT-BLOCKS short function on_read reaches the blocking call write: on_read -> write (root: callback of uv_read_start at src/net.c:41)

The root is not part of the message, as the path is not: the baseline matches the message, and a root that named the line of its call would make a finding new each time the code above it moves. A finding of a marked or listed root has no root and does not name libuv_callbacks_short.

[assume] #

[assume] says what the project knows of its own functions and cchecker cannot see in the C, as the marks do on a declaration. An assumption says something about a function, once, for every root and every path that reaches it; a suppression (cchecker: ignore, CC_IGNORE) says one finding is wrong, at one place, and shows when the finding goes away (CC-UNUSED-IGNORE). Use an assumption when the same function makes many findings for the same reason.

KeyNamesLike the mark
shortfunctions that count as fine for CC_SHORT: that rule does not walk into them (a helper that runs a request inline only on the loop thread and queues it otherwise); the other rules still doCC_ASSUME_SHORT
stopfunctions that no rule walks into, and whose calls count for none (a trace call behind a runtime flag): the effect rules, the system calls under a CC_NO_SYSCALL_UNDER lock, the lock levels, the inference of jumpsCC_STOP
may_jumpfunctions that may jump out of their caller; a call of one is a way out for the lock and ownership rules (Jumps). Other rules do not changeCC_MAY_JUMP
jumpsfunctions that always jump out and never return: a way out as for may_jump, the path ends there, and the effect walk treats them as an error exitCC_JUMPS
catchesfunctions that catch the jumps of the functions they call: the inference of jumps stops there. A function that calls setjmp or sigsetjmp catches without a markCC_CATCHES
jump_releaseslock helpers that record their lock for the code that catches a jumpCC_JUMP_RELEASES
acquires, releases, trieslock wrappers in code that cannot be edited, as name(N) or name@path(N): see belowCC_ACQUIRES, CC_RELEASES, CC_TRIES
nonblockingfunctions whose descriptors are non-blocking: see belownone
short_locks, owned_lockslock classes and wrappers: see Short locksCC_NO_SYSCALL_UNDER (for short_locks classes)
stop_fields, stop_callsfunction-pointer fields and calls that no walk follows: see belownone

An assumption cuts the walk into the function, not the function itself: a root that is assumed short or stopped still has its own body checked, and what the function calls is not walked either, a callback passed to it as a function pointer included. short and stop hold for every root, inferred roots included, and for every path of --all-paths; the ownership rules and the rule on values of the collector, which read one function at a time, do not change. A function that is CC_BLOCKING cannot be assumed short: its mark wins. CC_STOP wins over every other mark. A function that is both stop and may_jump is both: no walk goes into it, and a call of it is still a way out of its caller. A function that calls one that may jump out may jump out too, unless it catches the jump (may_jump_callers), where a call cut by stop_calls is no call. A function in jump_releases that takes or releases no lock for its caller is accepted and changes nothing.

Lock wrappers: acquires, releases, tries #

An entry is name(N) or name@path(N), N the place of the parameter (from 0) that holds the lock. my_lock(0) takes the lock it is given and returns with it held, my_unlock(0) releases it, my_trylock(0) takes it only where it returns 0 (for int my_trylock(pthread_mutex_t *m) { return pthread_mutex_trylock(m); }). The body of the wrapper is then no CC-PATH-LOCK-NOT-RELEASED or CC-PATH-LOCK-NOT-HELD, and a call of it is a lock for its callers, as the mark's. A known lock call (pthread_mutex_lock, uv_mutex_unlock, ...) already takes or releases its lock, so naming one is an error. The function has one such lock whatever its declarations call the parameter, and it keeps the one a CC_ACQUIRES already gives it. N has to be a named parameter of a declaration (not past the end or in the ...), and a function is in only one of the three lists. A wrapper that no declaration matches, or whose N no declaration reaches, is an error (exit 2) (my_lock(0) (assume.acquires)).

The path tells static functions of one name apart (grab@a.c(0), by the file of the definition); a function with external linkage is one in the whole project, so its path is only checked against a declaration of it (slow@slow.h) and does not tell two such functions apart: lock@a.c(0) in acquires and lock@b.c(0) in releases name one external lock both ways, and grab@a.c(0) for a static grab of a.c also marks an external grab of another file.

nonblocking #

Names the functions whose descriptors are non-blocking (libuv sets O_NONBLOCK on every descriptor it polls): their own calls of read, write, readv, writev, recv, send, recvfrom, sendto, recvmsg, sendmsg, recvmmsg, sendmmsg, accept, accept4 and connect are not blocking for CC_SHORT. It asserts that every descriptor these calls use there is a socket, a pipe or a terminal: a read or write of a regular file in a listed function is hidden too. It holds with libc_nonblocking_flags = false, and the inference of short locks counts these calls as not blocking. The calls of the functions they call are still blocking, and so are their other blocking calls (sleep, pread); CC_HOT still counts them as system calls.

Short locks #

A short lock is one held for a few instructions: a lock whose field or global is marked CC_NO_SYSCALL_UNDER(), or whose class short_locks names: queue.mu for the field mu of struct queue, the name of a global, and for a static global its name (every static global of that name) or name@path (big_lock@src/queue.c). Taking it (pthread_mutex_lock(&q->mu)) is not blocking for CC_SHORT; the rule on what runs under it still checks that no system call does, and CC_HOT still counts the call. A lock the rules cannot tell is not short: one named through a parameter, or through a local that points to it. A lock wrapper is assumed short with CC_ASSUME_SHORT or [assume] short. A class of short_locks that no lock of the compile database has is an error.

A lock that reaches a wrapper as a parameter has no class to name. An entry name(N) of short_locks (uv_mutex_lock(0), my_lock(0)) says that every lock taken through that wrapper is short: a call of a known take such as uv_mutex_lock, and the takes inside a function of the project of that name, are not blocking for CC_SHORT, whatever the lock, so listing a library take makes every call of it in the project short. N only has to be a number (the parameter is not checked). A wrapper that no function of the compile database declares is an error, except a known take such as uv_mutex_lock.

Experimental inference, off by default: with [library] short_lock_sections = true, a lock is short without a mark or a setting when no critical section of its class reaches a blocking call (as the short rule sees it: a take of a lock that is not short blocks, a call that returns at once does not; a lock helper's body counts after its take; a class whose sections take another lock becomes short once that lock is). It may call a lock short wrongly in cases it does not handle yet.

  • Only a full run of a compile database infers (no FILE, no --exclude, no error, no file left unchecked); another run says on standard error that it did not. inferred_short_locks of --json lists the classes (only with the inference on), and the text report says how many on standard error.
  • It trusts no class whose sections it cannot all see: a lock that a function returns or jumps out with, or releases without holding it (for a helper, a lock its marks do not name), as its caller holds it across code no walk reads; a function with more paths than the lock walk follows; a lock taken through a parameter or reached through a pointer field, global or array of pointers (c->lk of pthread_mutex_t *lk), which may be any class: when one of its sections blocks, or is not all seen, no class is inferred; a take that names no object (&locks[hash(k)]) is not seen at all. A call through a pointer that the run stores no function in, counts as blocking in a section, and so does a call through a stop_fields field made in a section (in a function that the section reaches it reaches nothing, as for the short rule). A lock taken by a CC_JUMP_RELEASES helper gives no finding at a jump.
  • owned_locks names the pointer fields and globals that point to a mutex of their own, which no other field or global points to (lock.mutex of struct lock { void *mutex; }): a lock reached through one has the class of the pointer. It matters only with short_lock_sections on. cchecker does not check the stores into the pointer: one that shares its mutex with another class may let the inference call that mutex short while a section of it blocks, which hides a CC-EFFECT-SHORT-BLOCKS. Names are classes, as in short_locks; a name in both lists is short by the setting, and its sections do not stop the inference of the others. A name that no lock through a pointer has is an error (exit 2).
  • An inferred class is matched as it is (inferring the global lock does not make a static lock of another file short) and is short for CC_SHORT only, not for CC_NO_SYSCALL_UNDER.
  • It changes findings both ways: a root that only took short locks before its blocking call reports that call, not the take (another baseline key), and a run that does not infer reports the takes of the inferred locks as new against a baseline of a run that did. The inference does not stop --update-baseline or --strict-baseline when it is off.

stop_fields and stop_calls #

stop_fields names the function-pointer fields that no walk follows, by struct and field (request.call; for an anonymous struct the name of its typedef, or of the record it is declared in; also when the code names the struct by a typedef such as request_t): a call through the field reaches none of the functions stored in it, for every rule and every root, --all-paths included. Use it for a field that holds many kinds of work (one call slot of every request). Only a call through the field itself is cut: one through a local that got its value (fn f = r->call; f(x)) is still followed, and a store into the field still counts when cchecker infers the roots. A field that the compile database neither stores a function in nor calls through is an error (exit 2).

stop_calls cuts the calls between two functions: each entry is caller>callee, and no walk follows a direct call of callee in caller (all its call sites there), while the other callers of callee still reach it (stop removes the function for all of them). Either side may be a name@path (on_exit@proc.c>close_handles). Use it for an edge that cannot happen at run time. The cut holds for every rule that walks the call graph: the effect rules, the lock rules, and the inference of may_jump_callers (the ownership rules read one body at a time, so it changes them only through that inference). A call that a lock or ownership rule reads in the body it checks (the call made under the lock, a call that may jump) is not cut itself: cut the edge below it. If callee is still reachable from caller through another function, that path is followed. A pair that matches no call of the compile database is an error (exit 2), and so is a value that is not caller>callee (a->b, a>b>c, a > b).