Table of Contents

Functions

Table of Contents

Functions take zero or more values as arguments and return a value. Argument values need to be of the type and range as documented for each function. Some functions are documented with a ..., in which case they take an arbitrary amount of arguments.

They can return scalar and list values:

    vars:
      "random" int => randomint("0", "100");
      "list" slist => readstringlist("/tmp/listofstring", "#.*", "\s", 10, 400);

In addition, functions with return type boolean evaluate to true or false. The class on the left-hand side is set if the function evaluates to true. If the function evaluates to false, then the class remains unchanged.

    bundle agent test
    {
    vars:
      "five" int => "5";
      "seven" " int => "7";
    classes:
      "ok" expression => islessthan("$(five)","$(seven)");

    reports:

      ok::
        "$(five) is smaller than $(seven)";

     !ok::
        "$(seven) is smaller than $(five)";

    }

Underneath, CFEngine functions that return boolean will actually return a context expression like any or !any which will then be deemed true or false by the CFEngine evaluator. Note the truth of a context expression or the result of a function call may change during evaluation, but a class, once defined, will stay defined.

Functions that return a boolean can thus sometimes be used in places where a string is accepted as well, but this behavior is not clearly defined or supported. Use at your own discretion.

Function caching

During convergence, CFEngine's evaluation model will evaluate functions multiple times, which can be a performance concern.

Some system functions are particularly expensive:

execresult() and returnszero() for shell execution
regldap(), ldapvalue(), ldaparray(), and ldaplist() for LDAP queries
host2ip() and ip2host() for DNS queries
readtcp() for TCP interactions
hubknowledge(), selectservers(), remoteclassesmatching(), and remotescalar() for hub queries

As of 3.6.0, the new cache_system_functions body common argument is set to true by default and CFEngine's evaluator will use it. Although you can override it to false, in practice you should almost never need to do so. The effect of having it true (the default) is that the expensive system functions will be run just once and then their result will be cached.

Note that caching is per-process so results will not be cached between runs of e.g. cf-agent and cf-promises.

Function Skipping

If a variable passed to a function is unable to be resolved the function will be skipped. The function will be evaluated during a later pass when all variables passed as arguments are able to be resolved. The function will never be evaluated if any argument contains a variable that never resolves.

List of all functions

There are a large number of functions built into CFEngine. The following tables might make it easier for you to find the function you need.

Functions by Category

`files`	`communication`	`utils`	`system`	`io`	`data`
`accessedbefore()`	`host2ip()`	`bundlestate()`	`getenv()`	`countlinesmatching()`	`accumulated()`
`changedbefore()`	`hostrange()`	`classesmatching()`	`getuid()`	`data_readstringarray()`	`ago()`
`dirname()`	`hostsseen()`	`classmatch()`	`getusers()`	`data_readstringarrayidx()`	`and()`
`diskfree()`	`hostswithclass()`	`countclassesmatching()`	`groupexists()`	`parseintarray()`	`bundlesmatching()`
`file_hash()`	`hubknowledge()`	`datastate()`	`hostinnetgroup()`	`parsejson()`	`canonify()`
`fileexists()`	`ip2host()`	`execresult()`	`now()`	`parserealarray()`	`canonifyuniquely()`
`filesexist()`	`iprange()`	`getclassmetatags()`	`packagesmatching()`	`parsestringarray()`	`classify()`
`filesize()`	`ldaparray()`	`getvariablemetatags()`	`packageupdatesmatching()`	`parsestringarrayidx()`	`concat()`
`filestat()`	`ldaplist()`	`isvariable()`	`registryvalue()`	`parseyaml()`	`data_expand()`
`findfiles()`	`ldapvalue()`	`returnszero()`	`userexists()`	`readcsv()`	`data_regextract()`
`isdir()`	`peerleader()`	`splayclass()`		`readdata()`	`difference()`
`isexecutable()`	`peerleaders()`	`usemodule()`		`readfile()`	`escape()`
`islink()`	`peers()`	`variablesmatching()`		`readintarray()`	`eval()`
`isnewerthan()`	`readtcp()`			`readintlist()`	`every()`
`isplain()`	`regldap()`			`readjson()`	`expandrange()`
`laterthan()`	`remoteclassesmatching()`			`readrealarray()`	`filter()`
`lsdir()`	`remotescalar()`			`readreallist()`	`format()`
`translatepath()`	`selectservers()`			`readstringarray()`	`getfields()`
	`url_get()`			`readstringarrayidx()`	`getgid()`
				`readstringlist()`	`getindices()`
				`readyaml()`	`getvalues()`
				`regline()`	`grep()`
					`hash()`
					`hashmatch()`
					`ifelse()`
					`intersection()`
					`irange()`
					`isgreaterthan()`
					`islessthan()`
					`join()`
					`lastnode()`
					`length()`
					`makerule()`
					`maparray()`
					`mapdata()`
					`maplist()`
					`max()`
					`mean()`
					`mergedata()`
					`min()`
					`none()`
					`not()`
					`nth()`
					`on()`
					`or()`
					`product()`
					`randomint()`
					`regarray()`
					`regcmp()`
					`regextract()`
					`reglist()`
					`reverse()`
					`rrange()`
					`shuffle()`
					`some()`
					`sort()`
					`splitstring()`
					`storejson()`
					`strcmp()`
					`strftime()`
					`string_downcase()`
					`string_head()`
					`string_length()`
					`string_mustache()`
					`string_reverse()`
					`string_split()`
					`string_tail()`
					`string_upcase()`
					`sublist()`
					`sum()`
					`unique()`
					`variance()`

Functions by Return Type

`real`	`(i,r)range`	`string`	`int`	`(i,r,s)list`	`data`	`class`
`mean()`	`irange()`	`and()`	`accumulated()`	`bundlesmatching()`	`bundlestate()`	`accessedbefore()`
`product()`	`rrange()`	`canonify()`	`ago()`	`classesmatching()`	`data_expand()`	`changedbefore()`
`sum()`		`canonifyuniquely()`	`countclassesmatching()`	`difference()`	`data_readstringarray()`	`classify()`
`variance()`		`concat()`	`countlinesmatching()`	`expandrange()`	`data_readstringarrayidx()`	`classmatch()`
		`dirname()`	`diskfree()`	`filter()`	`data_regextract()`	`every()`
		`escape()`	`filesize()`	`findfiles()`	`datastate()`	`fileexists()`
		`eval()`	`getfields()`	`getclassmetatags()`	`mapdata()`	`filesexist()`
		`execresult()`	`getgid()`	`getindices()`	`mergedata()`	`groupexists()`
		`file_hash()`	`getuid()`	`getusers()`	`packagesmatching()`	`hashmatch()`
		`filestat()`	`length()`	`getvalues()`	`packageupdatesmatching()`	`hostinnetgroup()`
		`format()`	`now()`	`getvariablemetatags()`	`parsejson()`	`hostrange()`
		`getenv()`	`on()`	`grep()`	`parseyaml()`	`iprange()`
		`hash()`	`parseintarray()`	`hostsseen()`	`readcsv()`	`isdir()`
		`host2ip()`	`parserealarray()`	`hostswithclass()`	`readdata()`	`isexecutable()`
		`hubknowledge()`	`parsestringarray()`	`intersection()`	`readjson()`	`isgreaterthan()`
		`ifelse()`	`parsestringarrayidx()`	`ldaplist()`	`readyaml()`	`islessthan()`
		`ip2host()`	`randomint()`	`lsdir()`	`url_get()`	`islink()`
		`join()`	`readintarray()`	`maparray()`		`isnewerthan()`
		`lastnode()`	`readrealarray()`	`maplist()`		`isplain()`
		`ldapvalue()`	`readstringarray()`	`peerleaders()`		`isvariable()`
		`makerule()`	`readstringarrayidx()`	`peers()`		`laterthan()`
		`max()`	`selectservers()`	`readintlist()`		`ldaparray()`
		`min()`	`string_length()`	`readreallist()`		`none()`
		`not()`		`readstringlist()`		`regarray()`
		`nth()`		`reverse()`		`regcmp()`
		`or()`		`shuffle()`		`regextract()`
		`peerleader()`		`sort()`		`regldap()`
		`readfile()`		`splitstring()`		`regline()`
		`readtcp()`		`string_split()`		`reglist()`
		`registryvalue()`		`sublist()`		`remoteclassesmatching()`
		`remotescalar()`		`unique()`		`returnszero()`
		`storejson()`		`variablesmatching()`		`some()`
		`strftime()`				`splayclass()`
		`string_downcase()`				`strcmp()`
		`string_head()`				`usemodule()`
		`string_mustache()`				`userexists()`
		`string_reverse()`
		`string_tail()`
		`string_upcase()`
		`translatepath()`