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 eachfunction. Some functions are documented with a..., in which case theytake an arbitrary amount of arguments.

They can return scalar (string|int|real|bool), list (slist, ilist, rlist) and data values:

code

printf "one\ntwo\nthree\n" > /tmp/list.txtprintf "1\n2\n3\n"        >> /tmp/list.txtprintf "1.0\n2.0\n3.0"    >> /tmp/list.txt

code

bundleagentexample_function_return_types{classes:"this_file_exists"expression=>fileexists($(this.promise_filename));vars:"my_string"string=>concat("Promises you cannot keep"," are no better than lies");"my_list_of_strings"slist=>readstringlist("/tmp/list.txt",# File to read"",# Don't ignore any lines"\n",# Split on newlinesinf,# Extract as many entries as possibleinf);# Read in as much data as possible"my_list_of_integers"ilist=>readintlist("/tmp/list.txt",# File to read"^(\D+)|(\d+[^\n]+)",# Ignore any lines that are not integers"\n",# Split on newlinesinf,# Maximum number of entriesinf);# Maximum number of bytes to read"my_list_of_reals"rlist=>readreallist("/tmp/list.txt",# File to read"^(\D+)",# Ignore any lines that are not digits"\n",# Split on newlinesinf,# Maximum number of entriesinf);# Maximum number of bytes to read"my_integer"int=>string_length($(my_string));"my_real"real=>sum(my_list_of_integers);"my_data"data=>mergedata('{"Hello":"world!"}');reports:"my_string: '$(my_string)'";"my_list_of_strings includes '$(my_list_of_strings)'";"my_list_of_integers includes '$(my_list_of_integers)'";"my_list_of_reals includes '$(my_list_of_reals)'";"my_integer: '$(my_integer)'";"my_real: '$(my_real)'";"my_data: '$(with)'"with=>string_mustache("",my_data);this_file_exists::"This file exists.";}bundleagent__main__{methods:"example_function_return_types";}

code

R: my_string: 'Promises you cannot keep are no better than lies'R: my_list_of_strings includes 'one'R: my_list_of_strings includes 'two'R: my_list_of_strings includes 'three'R: my_list_of_strings includes '1'R: my_list_of_strings includes '2'R: my_list_of_strings includes '3'R: my_list_of_strings includes '1.0'R: my_list_of_strings includes '2.0'R: my_list_of_strings includes '3.0'R: my_list_of_integers includes '1'R: my_list_of_integers includes '2'R: my_list_of_integers includes '3'R: my_list_of_reals includes '1'R: my_list_of_reals includes '2'R: my_list_of_reals includes '3'R: my_list_of_reals includes '1.0'R: my_list_of_reals includes '2.0'R: my_list_of_reals includes '3.0'R: my_integer: '48'R: my_real: '6.000000'R: my_data: '{  "Hello": "world!"}'R: This file exists.

This policy can be found in/var/cfengine/share/doc/examples/function-return-types.cfand downloaded directly fromgithub.

Boolean return type

Functions which returnboolean, technically return a stringany or!any.This is for compatibility with other functions and promise attributes whichexpect class expressions.

Normally, you don't need to worry about this, you use the function call todefine classes, and use classes instead of boolean values:

code

bundleagentmain{vars:"five"int=>"5";classes:"is_var"if=>isvariable("five");reports:is_var::"Success!";}

There is no boolean data type forvars promises.If you want to store or print the class expression, you can useconcat():

code

bundleagentmain{vars:"five"int=>"5";"expression"string=>concat(isvariable("five"));classes:"is_var"if=>"$(expression)";# Will be expanded and evaluatedreports:is_var::"Success: expression expanded to '$(expression)' and evaluated to true!";}

Note: the truth of a class expression or the result of a function call maychange during evaluation, but typically, a class, once defined, will stay defined.

Promise attributes and function calls

Promise attributes which use a class expression (string) as input, likeifandunless, can take a function call which returns string or boolean as well.

A boolean function will be resolved toany, which is always true, or!anywhich is always false.
A string function will be resolved, and the returned string will beevaluated as a class expression.

code

bundleagentmain{vars:"five"int=>"5";"is_var_class_expression"string=>concat(isvariable("$(five)"));classes:"five_less_than_seven"expression=>islessthan("$(five)",7);"five_is_variable"if=>"$(is_var_class_expression)";reports:any::"five:$(five)";"is_var_class_expression:$(is_var_class_expression)";five_less_than_seven::"$(five) is smaller than 7";}

Function caching

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

Somesystem functions are particularly expensive:

execresult() andreturnszero() for shell execution
regldap(),ldapvalue(), andldaplist() for LDAP queries
findprocesses(), andprocessexists() for querying processes.
host2ip() andip2host() for DNS queries
readtcp() for TCP interactions
hubknowledge(), andremotescalar() for hub queries

When enabledcached functionsarenot executed on every pass of convergence. Instead, the function willonly be executed once during theagent evaluation stepand its result will be cached until the end of that agent execution.

Note: Cached functions are executed multiple times duringpolicy validation and pre-evaluation.Function caching isper-process, so results will not be cached betweenseparate components e.g.cf-agent,cf-serverd andcf-promises.Additionally functions are cached by hashing the function arguments. If you havethe exact same function call in two different promises (it does not matter ifthey are in the same bundle or not) only the first executed function will becached. That cached result will be re-used for other identical functionoccurrences.

Function caching can be globally disabled by settingcache_system_functions inbody common control tofalse or locally for a specific promise by usingifelapsed => "0" in theaction bodyof the promise.

Function skipping

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

Collecting Functions

Some function arguments are marked ascollecting which means theycan "collect" an argument from various sources. The data is normalizedinto the JSON format internally, so all of the following data typeshave consistent behavior.

If a key inside a data container is specified (mycontainer[key]),the value under that key is collected. The key can be a string forJSON objects or a number for JSON arrays.
If a single data container, CFEngine array, or slist is specified(mycontainer ormyarray ormyslist), the contents of it arecollected.
If a single data container, CFEngine array, or slist is specifiedwith@() around it (@(mycontainer) or@(myarray) or@(myslist)), the contents of it are collected.
If a function call that returns a data container or slist isspecified, that function call is evaluated and the results areinserted, so you can say for instancesort(data_expand(...), "lex")to expand a data container then sort it.
If a list (slist, ilist, or rlist) is named, its entries are collected.
If any CFEngine "classic" array (array[key]) is named, it's firstconverted to a JSON key-value map, then collected.
If a literal JSON string like[ 1,2,3 ] or{ "x": 500 } isprovided, it will be parsed and used.
If any of the above-mentioned ways to reference variables are usedinside a literal JSON string they will be expanded (or thefunction call will fail). This is similar to the behavior ofJavascript, for instance. For example,mergedata('[ thing, { "mykey": otherthing[123] } ]')will wrap thething in a JSON array; then the contents ofotherthing[123] will be wrapped in a JSON map which will also go inthe array.

Delayed Evaluation Functions

Since CFEngine 3.10, some functions are marked asdelayed evaluation whichmeans they can evaluate a function call across every element of a collection.This makes intuitive sense for the collection traversing functionsmaparray(),maplist(), andmapdata().

The practical use is for instancemaplist(format("%03d", $(this)), mylist)which will evaluate thatformat() call once for every element ofmylist.

Before 3.10, the same call would have resulted in running theformat()functionbefore the list is traversed, which is almost never what the userwants.

List of all functions

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

Functions by Category

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

Functions by Return Type

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