Selecting Subsets

libgreat will only intercept the things you tell it to. This page explains how you tell it what you'd like.

Organisation

Subsets may be selected by way of regular expressions. These are given via the environment variable $GREAT_SUBSETS, which may either contain a single regex, or a list delimited by non-special punctuation characters.

If not set, $GREAT_SUBSETS defaults to ., thereby matching all functions.

API names are categorised into headers, groups and function names. These are colon-separated - for example, malloc() is stdlib:memory:malloc. This is the form matched against the given regular expressions.

This mechanism has no concept of to which standard a function belongs, as that is implicit from the library being linked.

Granularity

The system cannot operate with per-function granularity in all cases. For example, overriding rand() also requires srand() to be overridden, else their behaviours would become inconsistent. Hence for these co-dependant functions, enabling one also has the effect of enabling the other, and vice-versa. In other words, it is meaningless to ask for one without the other.

The idea behind this co-dependence is that the user needn't be concerned with exactly which of these co-dependant functions is being intercepted; since the intercepted functions conform to standard behaviour by definition, this should never be visible to the application. There should not be a situation where the user asks for one function, that brings in another, and that produces unexpected results (if it were really so unrelated, they would not be codependent).

In another example, we can override (for example) realloc without depending on malloc. However, our free() depends on both. The exact behaviour here is specific to how such functions are implemented.

Group names

The group names are essentially arbitrary, but are intended to correspond to sections within standards.

Examples

This examples are given in sh's syntax for setting environment variables.

$GREAT_SUBSETS='^stdlib:prng:'

Match all random-number related things (such as rand(), srand() and so on). Note that this is anchored by ^ just incase stdlib appears anywhere else, and : serves to eliminate any groups which happen to be named prngsomethingelse.

$GREAT_SUBSETS='/stdlib:prng/stdlib:memory/'

An example of a list, delimited by /.

$GREAT_SUBSETS=':rand$'

Matching just a function name. Note the $.

$GREAT_SUBSETS='/^stdlib://^stdio:/^stdbool:'

Lists needn't end with a delimiter, nor need every entry contain a regexp.

$GREAT_SUBSETS='.'

Match everything. This is the default.

$GREAT_SUBSETS=

This disables all overrides, producing the system default.