Integers are represented internally as a C/C++ long int. Maximum and minimum values are platform dependent. Integers are written in the C-style syntax; for example, -1958, 0377 (octal), and 0xABC (hexadecimal, upper or lower case).

Reals are represented internally as a C/C++ double. Maximum and minimum values are platform dependent. A real constant is an optional sequence of decimal digits (possibly signed) followed by a period and 1) at least one digit or 2) an 'e' or 'E' followed by at least one digit.

A string is a sequence of characters enclosed between matching single or double quotes (e.g., 'Hello world'). Interpolation of variables occurs within double quotes but not single quotes. C-style character escape codes and octal and hex numeric escape codes are understood (e.g., "\t", "\010", "\xfa") and either quote character (e.g., 'It\'s here') and the backslash character (e.g., "\\") can be quoted. An unrecognized quoted character is mapped to that character (e.g., "\x" is "x"). Character strings are limited in length by available memory and are represented internally as a null-terminated vector.

Variable references may occur within a (double-quoted) string; the value of the variable reference is interpolated at that point. If ${Foo::bar} is "hello", then the value of "${Foo::bar}, world" is "hello, world".

foo"baz"
foo."baz"

A binary string is a sequence of bytes, limited in length by available memory. Most language operators cannot be applied to data of this type without converting it to another type (e.g., two bstring values cannot be added using the + operator). A binary string is not necessarily portable across systems.

> "\0\1\2"
"000102"

This type is a "literal word" much like Perl's barewords. A bareword consists of an initial alphabetic character, followed by any number of alphanumerics and underscores. The resulting lexical token must have no other interpretation in the language and is treated as if it were a quoted string. This syntactic convenience makes these two function calls equivalent:

file(test, "-e", foo)
file("test", "-e", "foo")

These two expressions are equivalent and yield "foobaz":

foo."baz"
foo.baz

The boolean values True and False are either the result of evaluating certain expressions or are implicit argument values. This is really a pseudo-type because it is represented internally as an integer. In the former case, the integer 1 is the canonical "true" value and 0 is considered "false". In the latter case, there are several possibilities. If the argument is an integer or real, any non-zero value is considered True and 0 is considered False. For the string data type, both the empty string (i.e., "") and the string "0" are considered False and anything else is considered True. A binary string is equivalent to False if and only if its length is zero. An empty list of either variety ("[]" or "{}") is False, while any non-empty list or alist is True.

This is the C/C++ comma operator. A pair of expressions separated by a comma is evaluated left to right, and the type and value of the result are the type and value of the right operand.

Assignment is done using a simple or compound assignment operator, each of which has right to left associativity. In the case of a compound assignment operator, the left hand side is evaluated only once. The type and value of an assignment is that of its right hand side. A variable reference is expected on the left side of the operator. Modifier flags are not permitted. The variable, which is created if it does not exist. The syntax of the variable reference includes the initial "${" and terminating "}" character (so it's similar to Perl's syntax).

> ${foo::bar} = "hello"
"hello"
> ${foo::bar} .= ", world"
"hello, world"
> ${a} = [1, 2]
[1,2]
> ${a} .= [3, 4]
[1,2,3,4]

This is equivalent to the C/C++ conditional expression, which has right to left associativity. If the first expression is True, the result is the value of the second expression (the third is not evaluated). If the first expression is False, the result is the value of the third expression (the second is not evaluated).

This is the C/C++ logical OR operator, which yields 1 (True) if either operand is True, otherwise it yields 0 (False). Evaluation is from left to right and and stops as soon as the truth or falsehood of the result is known. The two tokens are synonymous.

This is the C/C++ logical AND operator, which yields 1 (True) if both operands are True, otherwise it yields 0 (False). Evaluation is from left to right and and stops as soon as the truth or falsehood of the result is known. The two tokens are synonymous.

This is the C/C++ bitwise inclusive OR operator. Both operands must be integers.

This is the C/C++ bitwise exclusive OR operator. Both operands must be integers.

This is the C/C++ bitwise AND operator. Both operands must be integers.

These operators compare their arguments and return 1 if the relation is true, 0 otherwise. If both arguments are lists, corresponding elements of both lists are compared, recursively. If both arguments are alists, the number of pairs in both lists is compared and, if necessary, pairs in the first list are looked up in the second list for matching values (note that the case-insensitive variant applies only to the value component of a pair, not the key component). For other valid arguments an attempt is first made to coerce both arguments to numbers and do a numeric comparison. If that fails, a lexicographic comparison is performed. Operators having a :i modifier are like their counterparts without the modifier except they do case-insensitive string comparisons.

If either argument is of type bstring, however, the comparison is done differently than explained above. Two bstring arguments are equal if and only if they are byte-wise identical. If one argument is a bstring and the other is a string, the latter is treated as a bstring of length(string) bytes. The case flag is ignored if at least one argument is a bstring.

These operators compare their arguments and return 1 if the relation is true, 0 otherwise. An attempt is first made to coerce both arguments to numbers and do a numeric comparison. If that fails, a lexicographic comparison is performed. Operators having a :i modifier are like their counterparts without the modifier except they do a case-insensitive comparison.

The symbolic and alphabetic versions of the relational operators are semantically identical. So >= and ge mean exactly the same thing. The latter form may sometimes be more convenient.

If either argument is of type bstring the comparison is done differently than explained above. If two bstring arguments are compared, the shorter bstring is "less than" the other argument and they are equal if and only if they are byte-wise identical. If one argument is a bstring and the other is a string, the latter is treated as a bstring of length(string) bytes. The case flag is ignored if at least one argument is a bstring.

The "dot" operator (not in ISO C) concatenates its right operand to its left operand. If both arguments are of type bstring, the result is also of type bstring. If the left operand is a list and the right operand is a basic data type, the right operand is appended to the list. If the left operand is a list and the right operand is also a list, the elements of the right operand are appended to the left operand. A list may not appear as the right operand if the left operand is not a list. In all other cases, both arguments are coerced to string (an error occurs if this cannot be done) before the left operand is appended to the right.

> "hello" . ", world"
"hello, world"
> "hello" . (16 + 1)
"hello17"
> 17 . (16 + 1)
"1717"
> [1, 2, 3] . 4
[1,2,3,4]
> [1, 2, 3] . [4, 5, 6]
[1,2,3,4,5,6]
> [1, 2, 3] . [[4]]
[1,2,3,[4]]

4.5

"4".5

These are the C/C++ bitwise left shift and right shift operators, respectively. The first operand may be an integer or a list, the second operand must be an integer. When shifting an integer, these operators are implemented using the corresponding C/C++ operators. In the case of right shifting, the behaviour with respect to arithmetic vs. logical shifts will be platform dependent.

These are the (binary) addition and subtraction operators, respectively. Both arguments are coerced to numbers. An error occurs if this cannot be done. Also, unary + and - operators may precede an arithmetic-valued expression.

These are the multiplication, division, and remainder operators, respectively. Both arguments are coerced to numbers. An error occurs if this cannot be done, such as attempting to divide by zero. For the remainder operator, both operands must be integers.

This is the exponentiation operator (not in ISO C). Both arguments are coerced to numbers (either both integers or both reals). An error occurs if this cannot be done, such as attempting to raise to a negative power.

> 2**10
1024

The + and - operators are the (unary) arithmetic plus and minus operators, respectively. These may precede an arithmetic-valued expression. Both arguments are coerced to numbers. An error occurs if this cannot be done.

The logical NOT operator (not, or equivalently, !) yields a result of zero when applied to a non-zero numeric value and non-zero when applied to an operand of zero. The result of applying this operator to a non-empty string is zero and it is non-zero when applied to an empty string string. These two tokens are synonymous.

The ~ operator is the one's complement (bitwise not) unary operator.

The ++VAR and --VAR operators are the prefix increment and decrement operators, respectively. These operators are followed by a variable reference. The variable must have an integer value.

> ${foo} = 17, ++${foo}
18

An explicit type conversion can be forced by using a cast. The syntax for this type coercion is:

(type) expression

The type must be a recognized data type name: integer or int (for an integer), real or double (for a real), bool (for a boolean value as a long integer), string (for a character string), bstring or binary (for a binary string), list, alist, or void.

A list can be cast to an alist, provided it has no elements or an even number of elements and if no key would appear more than once in the alist. A namespace can be cast to an alist; the operand specifies the namespace, either as a literal or a string. An alist can be cast to an list; the ordering of the pairs in the resulting list is unspecified. A void type can only be cast to void, which is a no-op. Here are some examples:

> (int) 3.4
3
> (int) "3.6"
3
> (bool) 17
1
> (bool) ""
0
> (string) (4 * 3)
"12"
> ${x} = "17"; (int) ((real) ${x} + (bool) 1965)
18
> (bstring) "abc"
"abc"
> (bstring) 4.4 
"4.400000"
> (bstring) "\0\1\2"
""
> bstring("\0\1\2",3) . bstring("\3\4", 3)
"0001020304"
> (void) ($b=$x)
>
> (alist) [a, 1, "b", 2, 3, 3]
{"a", 1, "b", 2, "3", 3}
> (list) { red, first, blue, second, white, third }
["blue", "second", "white", "third", "red", "first"]
> $env = (alist) Env; $env["HOME"]
"/home/bobo"
> $env{HOME}
{"HOME","/home/bobo"}

The VAR++ and VAR-- operators are the postfix increment and decrement operators, respectively. These operators are preceded by a variable reference. The variable must have an integer value.

A primary is a basic data type (i.e., an integer or real number, string, bareword, or binary string), or a variable reference.

This function, which is associated with notice acknowledgement processing, indicates that the current service request has one or more notices associated with it (identified by a sequence of notice-uri arguments), each one represented by a URI that will return the text of a notice that must be acknowledged by the user. Following the last URI is an optional mode argument. The EXACT_MATCH mode is the default mode and requires a single acknowledgement to address all of the specified notices. The ALL_MATCH argument specifies a less stringent matching mode that requires any set of acknowledgements to collectively address all of the specified notices. See dacs_notices(8).

This function is equivalent to the alist construction operator. There must be an even number of arguments, or no arguments. If the first argument of each pair (the key) is not a string or literal, it will be converted to a string, if possible.

alist(cars, 2, bikes, 5)

is equivalent to the expression:

{"cars", 2, "bikes", 5}

And the call:

alist(2, xx, [0, 1], yy)

yields:

{"2", xx, "[0,1]", yy}

This function creates a new list that is equivalent to that of the special "brace syntax" subscript used to dereference an alist. This is currently useful only in conjunction with listref().

listref({"a", 1, "b", 2, "c", 3}, alistref(["b"]))

is equivalent to the expression:

{"a", 1, "b", 2, "c", 3}{"b"}

the value of which is:

{"b", 2}

Compute the Argon2 memory-hard password hash function (a key derivation function), which uses BLAKE2b as its underlying hash function, on password, salt, secret, and ad (all binary strings, or converted as required), to produce a digest of outlen bytes, modified by parameters t_cost (the number of iterations), m_cost (the memory requirement, in KB), lanes (the amount of requested parallelism), and threads (the actual parallelism). By default, the argon2i variant is used. As an optional final argument, any of the strings "argon2i", "argon2d", or "argon2id" may appear to select the variant. The secret and ad ("associated data") arguments can be zero length strings.

Argon2 was selected as the winner of the Password Hashing Competition in 2015. For details, refer to draft-irtf-cfrg-argon2-03 and phc-winner-argon2.

> argon2(
bstring("\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1\1", 0),
bstring("\2\2\2\2\2\2\2\2\2\2\2\2\2\2\2\2", 0),
bstring("\3\3\3\3\3\3\3\3",0),
bstring("\4\4\4\4\4\4\4\4\4\4\4\4",0), 32, 3, 32, 4, 4)
"c814d9d1dc7f37aa13f0d77f2494bda1c8de6b016dd388d29952a4c4672b6ce8"

This function converts the first length characters of string (which may also be a bstring and which is converted to a string if necessary) into the binary type. The length argument may be less than the actual length of string. If length is zero or omitted, the actual length is computed. If length is greater than the actual length, the actual length is used. The implicit null character on the end of string is not considered part of it.

> bstring("\0\1\2", 4)
"000102"
> bstring("\0\1\2", 2)
"0001"

This function returns a count of the number of elements of test-set that appear in target-set at least once. Duplicate elements may appear in test-set and are considered to be distinct. The format indicates how to parse the set arguments. It can be the space, tab, or newline character, or any punctuation character. For both sets, it is currently interpreted as the character that separates elements. If the optional nocase literal argument is given, then set elements are compared case-insensitively. The greatest possible return value is the number of distinct elements in the third parameter.

contains_any(",", ${Args::LAYERS:i}, "Nests,Secret_roads,Heritage")
contains_any(",", "a,a,b,z", "a,a,a,b,b,b,a,z,z")

The first expression returns 3 if every element in the third parameter appears at least once (case insensitive) in the second parameter, otherwise the value of the expression is 0. The second expression returns 4.

This function is used to manage persistent integer counters, which can be useful for a variety of purposes, such as counting the number of logins for a particular identity, limiting the number of logins, or restricting the number of times a resource can be accessed. Internally, counter values are integers.

The first argument specifies an operation and is case-insensitive. The second argument identifies a filestore (typically a file or database). It must be an indexed filestore scheme, such as dacs-kwv-fs or dacs-db (see VFS). The third argument is the name of the counter, which acts as a key. The meaning of the fourth argument depends on the operation, but if present it must be an integer.

Operations that set or change the counter value return the new value.

For filestores that support locking, read-only operations obtain a shared lock while the other operations obtain an exclusive lock.

It is an error to reference a counter that does not exist unless the operation is set or exists.

A counter would typically be created by running dacsexpr(1):

% dacsexpr -e 'counter(set, "dacs-kwv-fs:/usr/local/dacs/counters/logins", "EXAMPLE::EX:bob", 1)'

The counter's value might then be tested in the revocation list or by an access control rule, for instance:

counter(exists, "dacs-kwv-fs:/usr/local/dacs/counters/logins", ${DACS::IDENTITY})

The counter might be conditionally updated using the on_success() function, or the AUTH_SUCCESS or ACS_SUCCESS directives, using an expression like:

counter(decdel, "dacs-kwv-fs:/usr/local/dacs/counters/logins", ${DACS::IDENTITY})

EXPERIMENTAL. Return a list of fields in input, where each field is separated from the next by any character in ifs or terminated by a newline or the end of string. A backslash can be used to quote any character. A field may also include embedded ifs characters by quoting the entire field. Any character in the string startq that appears at the beginning of a field indicates the start of a quoted field; the character at the same index into endq indicates the end of the quoted field (they can be the same character). A quote character embedded within a field has no special meaning if it has not been used as the starting quote character in that field; it is an error if has been used as the starting quote character, it must be escaped. Following RFC 4180, if double quotes are used as both the opening and closing quote characters, an embedded double quote can also be quoted by doubling it. An empty field or missing field is parsed as an empty string. Spaces preceding a field are ignored. When used as a separator character, unlike other separators, multiple consecutive spaces are always equivalent to a single space.

This predicate returns True if the user making a service request has any credentials that match any specified by the ADMIN_IDENTITY configuration directive.

This function is used to create an approval stamp or inspect or validate one.

The following operations are available:

This function returns information associated with the current federation, current jurisdiction, or other jurisdictions in the current federation. See dacs_list_jurisdictions(8) for additional information.

The following operations are available:

This function provides an interface to dacsauth(1). In the first usage, the single string argument is parsed into space or tab separated flags. Single or double quotes are allowed. In the second usage, each flag is a separate string or literal argument and is not parsed.

An alist is returned that has the following three elements:

Examples:

> dacsauth("-m unix suff -user bobo -p apassword")
{"result",0,"identity","","roles",""}
> dacsauth("-m", "unix", "suff", "-user", "bobo", "-p", "bpassword")
{"result",1,"identity","EXAMPLE::FEDROOT:bobo","roles",""}
> dacsauth("-r unix -DVFS='[federation_keys]dacs-fs:/usr/local/dacs/federations/federation_keys' -u bobo")
{"result",0,"identity","","roles","bobo,wheel,www,users"}

This function provides an interface to dacscheck(1), returning 1 if access is granted, 0 if access is denied, and -1 if an error occurs. In the first usage, the single string argument is parsed into space or tab separated flags. Single or double quotes are allowed. In the second usage, each flag is a separate string or literal argument and is not parsed.

This function enables, disables, or adjusts the amount of debugging output produced by the interpreter. Output type type is set to value, which may be "on", "off", or a non-negative integer level (the meaning of which depends on type.

The following type names are recognized: TBD

This function performs the inverse of encode() for the same encoding-type. The result is a bstring. The function will fail if its argument is not properly encoded.

For the hex encoding type, alphabetic characters may be upper case or lower case.

This function computes a cryptographic hash of msg (a string or bstring). The msg-len is the length of msg in bytes; if it is 0, its length is implicitly the entire length of msg.

The following digest algorithms (digest-name) are available:

SHA1 is used by default.

The available digest functions are described by the "dacs --digests" command (see dacs(1)) and listed by dacsversion(1) and dacs_version(8). The available key derivation functions, such as pbkdf2() and scrypt(), are also shown.

The digest-name is matched against the names of available hash functions case-insensitively. Non-consecutive hyphens, underscores, and slashes may be used as equivalent separators in digest-name. A separator may be omitted if doing so would not join two digits. An initial or trailing separator is disallowed. For example, "Sha224" matches "SHA-224", "md-5" matches "md5", "sha/512" matches "SHA-512", "sha-512t" matches "SHA512/t", and "SHA_512_224" matches "SHA512/224", but "sha3224" is invalid for "sha3-224", as are "sha3--224" and "sha3-224_".

The function value is a bstring and is always printed as a hex string.

If cryptographic strength is not required, see hash().

> digest("foo", 0, "md5")
"acbd18db4cc2f85cedef654fccc4a4d8"
> digest("Hello, world", 0, "SHA256")
"4ae7c3b6ac0beff671efa8cf57386151c06e58ca53a78d83f36107316cec125f"
> digest("abc", 0, "sha512/t", 72)
"644d768d5298864595"
> digest("abc", 0, "blake2s")
"508c5e8c327c14e2e1a72ba34eeb452f37458b209ed63a294d999b4c86675982"
> digest("\x0c", 0, "SHA3-384",7)
"b5a8cb0bf073b6b68d95cd33f5b09289670120bb931fc838b830d2592268b9e145a09088172b96eafb0093ef9a85df08"
> substr(encode(hex, digest("one two three", 0, blake2b, 64, "my secret", 0)), 1, 64)
"fc182724dc024b95f62e606859ac806e4edca09a927f6bc8bccd07dade3e4f26"

Like print() except always write to stderr.

Like printf() except always write to stderr.

This function converts arg, a string or bstring, into a printable text representation that depends on encoding-type. Applying decode() with the same encoding-type to the output of this function will produce a value equivalent to the original arg. The result is a string.

Note that encoding is only a representational or formatting change. If secrecy, authentication, or verification of integrity are required, use a cryptographic method.

The following encoding types are recognized:

This function evaluates its string argument and returns the result.

The call:

> eval("length(\"abc\")")
3

The exec function executes prog, waits (indefinitely) for it to terminate, and returns the program's standard output. A trailing newline in the output is deleted. Optionally, command line arguments to prog may be given; they are automatically converted to strings. By default, no environment variables are passed to the program; if the namespace ExecEnv exists, however, its contents are used as the executed program's environment variables. The exit status of prog is made available as the value of ${DACS::status}. The program is executed using the execv(3) function, not a command shell.

On POSIX systems, this call returns the string "1\n" on Thursdays, "0\n" on any other day:

> exec("/bin/sh", "-c", "date | grep -c ^Thu")
"0"

> ${ExecEnv::PATH} = "/usr/bin";
"/usr/bin"
> exec("/bin/sh", "-c", "printenv");
"PATH=/usr/bin"

Equivalent to return, this function causes evaluation of the expression, block, or program being evaluated to terminate and returns result as the value of the expression or the program's exit status.

The argument, a string, is returned with variable references expanded. An undefined variable expands to the empty string.

> ${a} = 17
17
> "${a}"
"17"
> '${a}'
"${a}"
> expand('${a}')
"17"
> ${b} = 1999, ${c} = expand('${a}, \${b}')
"17, ${b}"
> expand(${c})
"17, 1999"

This function performs various operations on files and filenames according to op, which is one of the following operation names, followed by command-specific arguments. All arguments must either be strings or literal words.

Test if path (defaults to ${DACS::FILENAME}, which is equivalent to Apache's SCRIPT_FILENAME or REQUEST_FILENAME variables) has a group ownership with which the user making the request is associated. This is effectively the same as:

file(test, "-e", ${DACS::FILENAME})
and
user("%" . ${Conf::JURISDICTION_NAME} . ":" \
  . file(stat, "%G", ${DACS::FILENAME}))

This predicate provides a simple way of limiting access to a file to its group membership with respect to file system permissions:

<allow>
  file_group()
</allow>

For example, if the user requesting access has been assigned the following roles by the current jurisdiction (e.g., through local_unix_roles):

wheel,www,users

and the resource being requested is the file:

-rw-r--r--  1 bobo     www  75 Apr 11 12:41 htdocs/foo.html

then this predicate would return True because the file has group ownership www and the user is associated with that role.

There is an implicit assumption that the file in question is associated with the current jurisdiction; this might be problematic if more than one jurisdiction can claim this association.

Test if path (defaults to ${DACS::FILENAME}, which is equivalent to Apache's SCRIPT_FILENAME or REQUEST_FILENAME variables) is owned by the user making the request. This is effectively the same as:

file(test, "-e", ${DACS::FILENAME})
and
user(${Conf::JURISDICTION_NAME} . ":" . file(stat, "%U", ${DACS::FILENAME}))

This predicate provides a simple way of limiting access to a file to its owner with respect to file system permissions:

<allow>
  file_owner()
</allow>

There is an implicit assumption that the file in question is associated with the current jurisdiction; this might be problematic if more than one jurisdiction can claim this association.

This predicate is used to test where a request comes from, based on the values of REMOTE_ADDR and REMOTE_HOST. These environment variables are passed to DACS from Apache. The supported argument types are similar to those recognized by the Apache mod_authz_host module's allow and deny directives. If either REMOTE_HOST or REMOTE_ADDR are needed to evaluate the argument but are not available, the result will be False.

The string argument may be:

An alternative method is to perform a regular expression match against ${DACS::REMOTE_ADDR} using regmatch().

The file or item specified by vfs-ref, which may be followed by a key if it is an indexed filestore, is read and returned. The vfs-ref may be an absolute pathname, an item type, or a vfs_uri, except if called from a standalone application without a key argument, in which case vfs-ref may also be a relative pathname.

This function computes a fast hash of msg, a string or bstring. The msg-len is the length of msg in bytes; if it is 0, its length is computed. The hash-name can be the 32-bit hash "hash32" (the default) or the 64-bit hash "hash64". The result is a string. Although the algorithms have been used extensively with very good results, they should not be used for cryptographic purposes; see digest().

> hash("Hello, world", 0)
"3696529580"
> hash("Hello, world", 0, hash64)
"462009511995194717"

This function computes an HMAC-based key derivation function (HKDF) that takes initial keying material and derives from it a cryptographically strong secret key. For details, refer to RFC 5869 and Cryptographic Extraction and Key Derivation: The HKDF Scheme (Hugo Krawczyk, Proceedings of CRYPTO 2010).

The input, salt, and info arguments are of type string or bstring (converted as required). Only input must not be zero length. A bstring of length bytes is returned. Any HMAC compatible cryptographic hash function can be given as digest-name.

> hkdf(decode(hex, "0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"), \
    decode(hex, "000102030405060708090a0b0c"), \
    decode(hex, "f0f1f2f3f4f5f6f7f8f9"), 42, "sha-256")
"3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865"
> hkdf("\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b\x0b", \
   "","",42,"sha-1")
"0ac1af7002b3d761d1e55298da9d0506b9ae52057220a306e07b6b87e8df21d0ea00033de03984d34918"

This function computes a cryptographic message authentication code - specifically, the Keyed-Hash Message Authentication Code (HMAC) - of msg (a string or bstring), using key (a string or bstring). The msg-len is the length of msg in bytes; if it is 0, its length is computed. Similarly, key-len is the length of key in bytes and if it is 0, its length is computed. The available digests are those listed by the "dacs --digests" command (see dacs(1)) having the HMAC attribute. This includes the Secure Hash Standard functions, such as SHA-512. The digest-name is case insensitive; if absent, SHA-1 is used. The function value is a bstring.

Note that the function is not commutative. The key is the third argument, not the first. If you are not getting the expected value from this function, try exchanging the msg and key arguments.

Although the MD5 hash function is deprecated for some purposes, it is still considered adequate in some applications and is required by many older protocols that are still in widespread use.

> hmac("Sample #2", 0,
  decode(hex, "303132333435363738393a3b3c3d3e3f40414243"), 0)
"0922d3405faa3d194f82a45830737d5cc6c75d24"
> hmac(decode(hex, "4869205468657265"), 0, \
    decode(hex, "0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"), 0, "sha3-224")
"3b16546bbc7be2706a031dcafd56373d9884367641d8c59af3c860f7"
> hmac("abc", 3, "", 0, "blake2s")
"4a79a31b10a8c34b7c89735b8088e6b810b4bad4f36d671b65ca2ea0914952bf"

This function sends an HTTP request to url, using a given method (GET, POST, HEAD, PUT, DELETE, or OPTIONS, case insensitively), and optionally passing parameters. If no method is given (and no arguments), GET is assumed. The value of the function is the message returned by the request. The url is in the usual syntax and must use either the http or https scheme (case insensitive). The argument list, if present, consists of some number of pairs, the first being the name of the parameter and the second the value of the parameter.

The first statement sends an HTTP request to example.com and sets the variable to the message body (if any) that is returned. The second statement makes a GET request to port 8443 of example.com over SSL/TLS, passing it two parameters, FOO=17 and FOO=2:

> ${x} = http("http://example.com")
> http("https://example.com:8443/cgi-bin/dacs_prenv.cgi", "GET", "FOO", 17,
      "BAZ", 1+1)

If the first argument is a string, this function returns the first position in string (counting from 1) where the first character in character-class was found, or 0. Case-sensitive character comparison is used unless the optional nocase literal argument is present.

If the first argument is a list, the position of element search_operand (counting from 1) in list is returned, or 0 if it is not found. During comparison, types are automatically converted as necessary. Case-sensitive character comparison is used unless the optional nocase literal argument is present.

Examples:

> index("abcdef", "abc")
1
> index("abcdef", "e")
5
> index("zzz", "abc")
0
> index([a, b, c, d, e], d)
4
> index(["hello", world, 2009, qUAKe], "quake", nocase)
4
> index([1.0, 2.2, 3.3, 4.4, 5.0, 6.6], "1")
1
> index(["apple", ["orange", "banana"], ["peach", "mango"]], "orange")
0
> index(["apple", ["orange", "banana"], ["peach", "mango"]], ["orange", "banana"])
2

Return a string containing information about variables and namespaces. The first form returns a comma-separated list of known namespaces. The second form returns a list containing all variables in the given namespace and their values, one per line. This can be useful for debugging.

Examples:

info(namespaces)
info(namespace, "Conf")

If its argument is a single pair, the pair's key is returned. If there is more than one pair in the argument, a list of keys is returned. To get the value component of a pair or set of pairs, use valuesof().

Examples:

> keysof({red, 17})
"red"
> keysof({red, 17, blue, 100})
["red", "blue"]

The ldap function is used to extract components of LDAP names. Its first argument, a literal, determines the operation mode to be used and the semantics of the following arguments. Distinguished Name (DN) and Relative Distinguished Name (RDN) strings are as defined in RFC 2253.

The dn_length mode returns the number of RDN components in its DN argument; -1 is returned if the argument is not a valid DN. The dn_index mode returns the nth RDN component of the DN, where nth is an integer greater than zero. If nth is greater than the number of components, the last component is returned.

The rdn_length mode returns the number of AttributeTypeAndValue elements in its RDN argument; -1 is returned if the argument is not a valid RDN. The rdn_index mode returns the nth AttributeTypeAndValue component of the RDN, where nth is an integer greater than zero. If nth is greater than the number of components, the last component is returned.

The rdn_attrtype mode returns the AttributeType of the nth AttributeTypeAndValue component of the RDN, where nth is an integer greater than zero. If nth is missing, it is taken to be 1. If nth is greater than the number of components, the last component is selected. The rdn_attrvalue mode is similar except that it returns the AttributeValue.

The first and second expressions below return 2, the third expression returns Administrator:

ldap(dn_length, "dc=example,dc=com")
ldap(rdn_length, "foo=bar+bar=baz")
ldap(rdn_attrvalue, ldap(dn_index, \
    "CN=Administrator,CN=Users,DC=example,DC=com", 1))

This function returns the length, in characters, of string, the number of bytes in binary string bstring, the number of elements in list, or the number of pairs in alist.

This function is equivalent to the list construction operator.

list(1, 2, [hello, world], 5)

is equivalent to the expression:

[1, 2, [hello, world], 5]

This function provides an alternate syntax to the language's list/array notation. For example, the function call:

listref([1, 2, [3, 4], 5], 2, 1)

is equivalent to the expression:

[1, 2, [3, 4], 5][2][1]

Note that a list reference may follow a list-valued expression (e.g., a list constructor, a list-valued variable, a function that returns a list) this syntax is valid:

($a . $b)[0]

The parentheses are necessary here because the subscript binds more tightly than the concatenation operator. This expression can also be written as:

listref($a . $b, 0)

The list-name argument must be either acs or auth (case insensitive) to select the post-authorization list or the post-authentication list, respectively. For the former case, if authorization is successful, the expr argument (a string) will be evaluated by dacs_acs immediately after any ACS_SUCCESS directive, and just prior to program termination. These expressions are not evaluated if authorization is denied, an authorization processing error occurs, or a DACS_ACS argument prevents execution of the request. For the latter case, if authentication is successful, the expr argument (a string) will be evaluated by dacs_authenticate(8) immediately after any AUTH_SUCCESS directive, and just prior to program termination. These expressions are not evaluated if authentication fails or an authentication processing error occurs.

Once added to either list, an entry cannot be removed. The expressions are evaluated in the order in which on_success() was called. The values returned by the expressions are discarded and errors are ignored.

If no expr is given, the current list of expressions is returned, one per line, in order of evaluation. With an expression argument, it returns the number of expressions in the list after any addition.

This function performs a variety of read-only operations on DACS accounts and their passwords. See dacspasswd(1) and directives PASSWORD_DIGEST and PASSWORD_SALT_PREFIX for additional information.

The following operations are available (the operation is specified by the first argument to the function):

Examples:

> password(hash, "bobo")
"2|XYZZYxBhU/7VgJAt2lc.G|HL4RQ2vo0uNoXlXnv.GcY3Vlf9."
> password(check, "bobo", "2|XYZZYxBhU/7VgJAt2lc.G|HL4RQ2vo0uNoXlXnv.GcY3Vlf9.")
1

Perform string interpolation on path based on the other arguments. For details, please see dacs.conf(5) (where hostname is SERVER_NAME).

Apply a pseudo-random function (by default, HMAC-SHA-1) to password and salt (both binary strings, or converted as required), modified by count iterations, returning a binary string of length dklen bytes (greater than zero). Optionally, digest-name can be provided (see digest()). For details, please see RFC 2898 and RFC 3962.

> pbkdf2("password", "ATHENA.MIT.EDUraeburn", 1200, 32)
"5c08eb61fdf71e4e4ec3cf6ba1f5512ba7e52ddbc5e5142f708a31e2e62b1e13"
> pbkdf2("password", decode(hex,"1234567878563412"), 5, 16)
"d1daa78615f287e6a1c8b120d7062a49"
> pbkdf2("password", "salt", 4096, 20, "SHA256")
"c5e478d59288c841aa530db6845c4c8d962893a0"
> pbkdf2("1", "2", 1024, 32, "SHA512")
"a180451f4618df9515ab0be2c56ac3420287cb8fc015f78494c9394a62ef6e66"

Each argument is converted to a string, the strings are concatenated, a newline is appended, and the result is printed. The return type is void. If called from dacsexpr(1), the string is printed to the standard output; otherwise, it is printed to the DACS log file (or stderr), which can be useful for debugging purposes. These log messages are associated with the user class (see the LOG_FILTER directive).

This is a slightly scaled-down version of the printf(3) library function. If called from dacsexpr(1), the string is printed to the standard output; otherwise, it is printed to the DACS log file (or stderr), which can be useful for debugging purposes. These log messages are associated with the user class (see the LOG_FILTER directive). This can be useful for debugging purposes. If necessary and possible, arguments are converted to the type requested by a formatting specification. The return type is void.

The various forms of this function, distinguished by the first argument, return cryptographically strong pseudo-random values in various formats. The starting point (seed value) for the pseudo-random sequence cannot be set, meaning that the sequence cannot be (intentionally) reproduced.

The bytes operation requests nbytes bytes of random material. The result is a bstring of that length.

The uint operation requests an unsigned random integer between lo and hi (both unsigned integers), inclusive. It is an error if lo is not greater than hi. The result is an (unsigned) integer.

The string operation requests nbytes of random material, returned as a hex-encoded string. If a spec argument is present, it uses the character specification syntax of strtr() to indicate the characters that can be used to encode the result. Only printable characters, excluding the space, are allowed in the result, regardless of the spec argument. Example:

> random(string,12,"a-zA-Z0-9")
"LgROshy6SMMH"
> random(string,12,"a-z")
"kehhvwydhhbk"

The functionality of the stringc operation is identical to that of the three-argument instance of the string operation except that the sense of the spec argument is complemented to indicate those characters that may not be used in the encoding of the result.

Read one line from /dev/stdin, strip any trailing newline character, and return the string. This function is experimental.

Permitted only within the context of an access control rule's deny clause, this function causes expression evaluation and rule processing to stop immediately, access to be denied, and the client to be redirected to target, a URL that may contain a query component. If the error-code is present, it must be an ACS error name or number (see the ACS_ERROR_HANDLER directive), otherwise "BY_REDIRECT" is used.

The target string is expected to have one of the syntaxes of the document component of Apache's ErrorDocument directive. In essence, this function causes an ACS_ERROR_HANDLER directive to be created and triggered. The function returns the target string, although because of the function's run time behaviour the value cannot be used.

<acl_rule status="enabled">
 <services>
  <service url_pattern="/id/*"/>
 </services>

 <rule order="allow,deny">
  <deny>
    setvar(split, "X", ${Env::REQUEST_URI}, "/");
    ${x} = var(get, X, ${X::#} - 1);
    redirect(BY_SIMPLE_REDIRECT, "https://example.com/docs/${x}.html");
  </deny>
 </rule>
</acl_rule>

https://example.com/id/17795821

https://example.com/docs/17795821.html

This is a pattern matching function. The first two arguments are coerced to strings, with the second one taken to be the regular expression, with a "^" (the start-of-string anchor) implicitly prepended. The string argument is then matched against the regular expression, which may contain subexpressions enclosed between '(' and ')' (or '\(' and '\)'). If the match fails, the result is 0. If the match succeeds there are several possibilities:

If the optional nocase literal argument is given, then matching is done case-insensitively. Only one parenthesized pair can be used. IEEE Std 1003.2 ("POSIX.2") "extended" regular expressions are supported (regex(3), re_format(7)).

Examples:

> ${X} = "abfoo"
"abfoo"
> regmatch(${X}, ".*foo", nocase)
5
> regmatch("abcdefgzz", "(.*)g")
"abcdefg"
> regmatch("foo", "(bar)|(baz)|(foo)")
"foo"
> regmatch("abcdefgzz", "ab(.*)efg(.*)", "x")
9
> ${x::0}
"abcdefgzz"
> ${x::1}
"cd"
> ${x::2}
"zz"
> $addr = "192.168.7.3"
"192.168.7.3"
> regmatch($addr, "192\\.168\\.(.*)\\..*", "X")
11
> ${X::1}
"7"

This function matches regex against string, like regmatch() does, and returns the string that results when the substitution specified by replacement is applied to the matched text. This is similar to the ed/vi/sed command "s/regex/replacement/" applied to string. If no match is found, the empty string is returned.

The optional repeat literal argument causes the replacement to be applied to all matches; i.e., like the ed/vi/sed command "s/regex/replacement/g".

Examples:

> regsub("hello world", "world", "auggie")
"hello auggie"
> regsub("hello world", "auggie", "world")
""
> regsub("hello", ".*", "& &")
"hello hello"
> regsub("one two three", "(.*) (.*) (.*)", "\${3} \${2} \${1}")
"three two one"
> regsub("one two three", "(.*) (.*) (.*)", '${3} ${2} ${1}')
"three two one"
> strtr(regsub("https://BOB.Example.com",
    "\([^:]*\)://\([^.]*\)\\.\(.*\)", '${1}-${2}@${3}'),
      "A-Z", "a-z")
"https-bob@example.com"
> regsub("one, bone, cone, hone", "one", "two", repeat)
"two, btwo, ctwo, htwo"

This function is used to inspect the current request. The argument is either a valid URI (RFC 2396) or a path component that begins with a slash. In the latter case, the scheme and authority components of the current request are effectively prepended to the given path. Case-insensitive string matching is used to compare host elements (usually a hostname or IP address) of authority components; no DNS-based equivalencies are considered. The path component is like the url_pattern attribute used in access control rules in that it can either specify an exact match or, by ending in "/*", a wildcard match. A query component is allowed but ignored. The function returns 0 if uri-string does not match the current request, otherwise it returns the number of path components of uri-string that match the current request. If the scheme and authority components are given in uri-string, they count as one naming component.

Assuming that the current request is http://example.com:18123/a/b/c, we get:

> request_match("http://example.com:18123/a/b/c")
4
> request_match("https://example.com:18123/a/b/c")
0
> request_match("http://example.com:18123/a/b/c/d")
0
> request_match("http://example.com:18123/a/b")
0
> request_match("http://example.com:18123/a/b/*")
4
> request_match("http://example.com:18123/*")
2
> request_match("http://example.com:18123")
0
> request_match("http://example.com")
0
> request_match("http://example.com/*")
2
> request_match("/*")
1
> request_match("/a/b/c")
3
> request_match("/a/b/*")
3
> request_match("/")
0

Experimental.

Equivalent to exit, this function causes evaluation of the expression to terminate and returns result as the value of the expression.

The rule predicate is an interface to the DACS rule processing engine. It is used to test if the rule set ruleset_vfs authorizes object, much as dacscheck(1) does. The object argument is the name to match against the services specified in access control rules and can either be a URI or an absolute pathname (one that begins with a slash character). It can have an optional query string component attached. An absolute pathname path is mapped internally to a URI as file://path; e.g., /myapp is interpreted as file:///myapp (see RFC 1738).

One application of this predicate is for a rule associated with a program to check that the user requesting access is entitled to use a data file needed by the program.

The ruleset_vfs is a URI in the syntax of the VFS configuration directive.

The various components of the URI that names the object are available as DACS variables and environment variables (see below). If a query string is given, it is parsed and the individual arguments are made available to rules through the Args namespace, just as for DACS-wrapped web services.

Many variables normally set by a web server are instantiated based on the object name and the execution environment. These variables are available in the DACS namespace. For example, if the object name is https://example.com:8443/myapp/edit-menu?entry=item1, the following variables will be set as indicated:

${DACS::HTTPS}=on
${DACS::SERVER_NAME}=example.com
${DACS::SERVER_ADDR}=142.179.101.118
${DACS::HTTP_HOST}=example.com:8443
${DACS::SERVER_PORT}=8443
${DACS::REQUEST_URI}=/myapp/edit-menu
${DACS::DOCUMENT_ROOT}=/
${DACS::REQUEST_METHOD}=GET
${DACS::SERVER_SOFTWARE}=dacsexpr-1.4.14
${DACS::QUERY_STRING}=entry=item1
${DACS::ARG_COUNT}=1
${DACS::CURRENT_URI}=/myapp/edit-menu?entry=item1
${DACS::CURRENT_URI_NO_QUERY}=/myapp/edit-menu

The value of ${Args::entry} will be item1. The request method is always GET. The variable ${DACS::REMOTE_USER} will be set if credentials are available in the execution environment.

For example, assuming that the file /usr/local/exams/acls/acl-exams.17 contains:

<acl_rule status="enabled">
  <services>
    <service url_pattern="/exam1.html"/>
  </services>

  <rule order="allow,deny">
    <precondition><predicate>
      ${Args::user} eq "teacher"
    </predicate></precondition>

    <allow>
      time(hour) eq 17
    </allow>
  </rule>
</acl_rule>

The following call would only return True (1) any day between 5:00pm and 5:59pm:

rule("/exam1.html?user=teacher", "dacs-fs:/usr/local/exams/acls");

Compute the scrypt memory-hard password-based key derivation function, which applies a pseudo-random function (HMAC-SHA-256) to password and salt (both binary strings, or converted as required), modified by CPU/memory cost N, block size r, and parallelization parameter p, returning a binary string of length dklen. The last four arguments are integers greater than zero. For details, refer to The scrypt key derivation function and draft-josefsson-scrypt-kdf-05.

> scrypt("password", "NaCl", 1024, 8, 16, 32)
"fdbabe1c9d3472007856e7190d01e9fe7c6ad7cbc8237830e77376634b373162"

This function, which performs various operations on namespaces, has several different syntaxes. The first argument always specifies the operation (case insensitively) and determines the meaning of the arguments that follow it. The second argument always specifies a namespace that is created or modified. If successful, the function returns the number of variables created (or replaced) in dst-namespace.

The dst-namespace cannot be a read-only namespace. Unless otherwise specified, if dst-namespace exists, variables are added to it, with any existing variable assigned its new value.

The following operations are recognized:

This function returns the amount of memory in bytes, as an integer, used by typename, the name of a basic data type. For the string and binary types, the returned value is the number of bytes used by each element of that type (1, typically). To find the number of elements in string or binary data, use length().

> sizeof(real)
8

The process is suspended for approximately seconds seconds, or until a signal is received and caught or the process terminated. It returns the "unslept" number of seconds, which will be zero if the process slept for the requested interval. This is an interface to sleep(3). It can be useful for inserting delays in conjunction with error handlers, for instance.

The expressions in the file or item specified by vfs-ref, which may be followed by a key if it is an indexed filestore, are read and evaluated as a block. The vfs-ref can be an absolute pathname, an item type, or a VFS URI. The value returned is that of the evaluated block. The following two expressions are essentially equivalent:

source("/usr/local/dacs/scripts/script17")
eval(get("/usr/local/dacs/scripts/script17"))

This function is handy when a lengthy expression is needed but one does not want to clutter a configuration file or a rule.

This is a slightly scaled-down version of the sprintf(3) library function. If necessary and possible, arguments are converted to the type requested by a formatting specification. The formatted string is returned.

${a} = sprintf("Hello") . ", world."
"Hello, world."
length(sprintf("Hello") . ", world.")
13

This function returns a new string by selecting characters from str according to a sequence of one or more range specifications (each one a range-spec). A range-spec is a string argument that determines the indexes of characters to select within str. Indexes start at zero. The result of each successive range specification is appended to the previous result.

A range-spec is an unordered set of one or more comma-separated elements, each of which is either an index or a range. An index may either be a non-negative integer or "#", which means "all indexes". A range represents a sequence of indexes and has the syntax:

range-start ".." range-end

A range-start may be a non-negative integer, the character "#" (which means "from the beginning"), or may be elided (also meaning "from the beginning"). A range-end may be a non-negative integer (not less than range-start, if it is also a non-negative integer), the character "#" (which means "to the end"), or may be omitted (also meaning "to the end").

> $a = "abcdef"
"abcdef"
> strchars($a, 2)
"c"
> strchars($a, "1..4", "0")
"bcdea"
> strchars($a . $a, "5..#")
"fabcdef"
> strchars($a, "#")
"abcdef"
> strchars($a, "#..#")
"abcdef"
> strchars($a, "#..3")
"abcd"
> strchars($a, "..3")
"abcd"
> strchars($a, "..3", "#")
"abcdabcdef"

This function deletes from the end of str a continuous run of any characters in del-spec.

> strchop("foo4.859", ".56789")
"foo4"
> strchop("foo7.859", ".5679")
"foo7.8"
> strchop("hello    ", " ")
"hello"
> strchop("dogs rule\n\n", "\n")
"dogs rule"

This function returns the concatenation of count copies of str. The result has the same type as str, which may be a string or bstring. The count must not be less than 1. A limit is imposed on the length of the result. This function is sometimes useful when forming an argument to a hash or encryption function, which often consists of a repeated substring.

> strclone("abc", 1)
"abc"
> strclone("abc", 3)
"abcabcabc"
> strclone("\x0b",22)
"0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"
> strclone(decode(hex, "01"), 7)
"01010101010101"

This function is an interface to the strftime(3) function. It is applied to the current date and time.

This function is an interface to the strptime(3) function. The date-str argument is a string representation of a date and/or time, with date-format describing its syntax. If the parse of date-str succeeds, the following elements of namespace are set from the corresponding fields of struct tm: tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday, tm_yday, tm_isdst, tm_zone, and tm_gmtoff. Additionally, a variable named clock is set to the Unix time that corresponds to the parsed date and time. Any existing elements of namespace are not modified. If date-str does not fully describe a date and time, it is taken to be relative to the current date and time (e.g., if only a time is given, "today's date" is used).

In the single-argument usage, the current date and time are parsed and namespace is assigned values as previously described.

The return value is the "Unix time" equivalent of the resulting time and date.

> strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", tm)
1007670825
> "${tm::tm_mon} ${tm::tm_mday} ${tm::tm_hour} ${tm::tm_min}"
"11 6 12 33"
> ${tm::clock}
1007670825

Return the start of the last occurrence of substring within string. The empty string is returned if string is empty or if no occurrence of substring is found. If substring is empty, string is returned. The optional nocase literal argument requests case-insensitive comparison.

> strrstr("afoofoofooz", "foo")
"fooz"
> strrstr("afOOfoofooz", "FooF", nocase)
"foofooz"
> strrstr("afOOfoofooz", "ofoo",nocase)
"ofooz"

Return the start of the first occurrence of substring within string. The empty string is returned if string is empty or if no occurrence of substring is found. If substring is empty, string is returned. The optional nocase literal argument requests case-insensitive comparison.

> strstr("foobazbar", "baz")
"bazbar"
> strstr("foobazbar", "")
"foobazbar"
> strstr("foobazbar", "zzz")
""
> strstr("", "zzz")
""
> strstr("afoofoofooz", "foo")
"foofoofooz"
> strstr("fooZbar", "Ozb", nocase)
"oZbar"

A new string is returned where each uppercase character in string is mapped to lowercase and all other characters are mapped to themselves. These two expressions are equivalent and have the value "hello, world 2008":

strtolower("Hello, World 2008")
strtr("Hello, World 2008", "A-Z", "a-z")

A new string is returned where each lowercase character in string is mapped to uppercase and all other characters are mapped to themselves. These two expressions are equivalent and have the value "HELLO, WORLD 2008":

strtoupper("Hello, World 2008")
strtr("Hello, World 2008", "a-z", "A-Z")

This function performs string transliteration, like the tr(1) command and Perl's tr and y operators. The result is the transliterated string. The first argument is the input string to be transliterated (stdin in the tr command). The second argument is the search list ("string1" in the tr command). The third argument is the (possibly empty) replacement list ("string2" in the tr command); it may be omitted if no flag string argument follows.

The fourth, optional argument is a literal flag string made of the characters 'c', 'd', and 's' (in any order), which correspond to the flags of the same name in the tr command:

> strtr("AbCdEf", "A-Z", "a-z")
"abcdef"
> strtr("/a//b///c", "/", "", "s")
"/a/b/c"

This function returns True if every element of the purported-subset appears in superset. The format indicates how to parse the set arguments. It can be the space, tab, or newline character, or any punctuation character. It is currently interpreted as the character that separates elements. If the optional nocase literal argument is given, then set elements are compared case-insensitively.

Example:

subset(",", ${Args::LAYERS:i}, "RELIEF:Foundation,GTOPO30:Foundation")

This call returns True if every element of the LAYERS parameter (case insensitive) appears in the given list, otherwise the expression is False.

This function returns the substring of string beginning at start-position with length at most length characters. The first character is in position one. If start-position is negative, the position is relative to the end of string (-1 specifies the last character in string). If the effective starting position is outside of string, an empty string is returned. If length is negative, it means "the remainder of the string". It is an error if either numeric argument is zero. It is not an error if length exceeds the actual number of characters returned.

> substr("foozle", 3, 4)
"ozle"
> substr("foobar", -3, 2)
"ba"
> substr("foobar", -5, -1)
"oobar"
> substr("foobar", 10, -1)
""
> substr("foobar", -10, 3)
""

This function performs a syntax test, specified by type, on name. It returns 0 if the test fails, 1 or a type-dependent, non-zero value if the test is successful. It can be useful for testing, catching errors, recognizing when a string must be mapped, and for learning about DACS. Note that these are purely syntactical checks. They do not test whether an object called name exists or is configured.

The following tests are recognized:

> syntax(federation, "FOO")
1
> syntax(dacsname, "FOO::BAZ:bar")
1
> syntax(dacsname, "FOO::")
4
> syntax(charset, "bobo17+", "a-z0-9")
0
> syntax(expr, '1 + 1 + 1')
1
> syntax(variable, '${1$}')
0
> syntax(variable, '${Foo::baz:z}')
0
> syntax(varname, 'Foo::baz')
1
> syntax(varname, "17")
1
> syntax(username, "/bobo/")
0
> syntax(group, "blop")
1
> syntax(group, "%blop")
0
> syntax(dacsname, "%blop:flop")
1
> syntax(uri,"https://foo.example.com:8443/cgi-bin/prog?a=17")
1

This function returns time and date information, as specified by the first argument. The second argument, if present, either specifies the "Unix time" from which to obtain the time and date or a namespace that was returned by strptime(). If the second argument is absent, the result is the same as if a second argument were given as time("now"). The localtime(3) library function is used internally to perform the date calculations.

The format argument, which is treated case-insensitively, can be any of the following:

This function provides a simplified API for dacstransform(1) - refer to its description for additional details. The first form of the function uses compile-time defaults, unless they are overridden by configuration variables (e.g., ${Conf::transform_prefix}). The second form passes a configuration object returned by transform_config(). The input argument is the text to be passed through the function. The name argument is equivalent to the value of the dacstransform -name flag, rules is equivalent to the value of the -r flag, docs is equivalent to the value of the -docs flag, and the optional idents argument is a whitespace-separated list of identities in the concise user syntax. The function returns the transformed input.

This function returns a configuration object that is passed to subsequent calls to transform() so that defaults can be overridden. The single string argument is parsed into whitespace-separated words. If a flag is repeated, the right-most occurrence is used.

The following flags are recognized:

Delete each character in delete-set that appears at the end of string, up to limit characters. The delete-set is a search list specification as used by strtr(). If limit is missing or zero, all of the characters in string can potentially be deleted (leaving the empty string). The new string is returned.

> trim("abceffff", "f")
"abce"
> trim("abceffff", abf)
"abce"
> trim("a\n\n\n", "\n")
"a"
> trim("a", "a-z")
""

If there are two arguments and the first is a recognized data type name, the return value is 1 (True) if expression has that type and 0 (False) otherwise. If there is one argument, the function yields a string that is the data type name of the evaluated expression.

> typeof(4.5)
"real"
> typeof(integer, 4.5)
0

This function returns a special value that represents the "undefined value". It is normally an error to use this value, just as it would be to reference an undefined variable. It can be used to undefine a configuration directive. The undefined value prints as the string "<UNDEFINED>". See dacs.conf(5).

This function compares its argument against each set of current credentials and returns the number of credentials that match. The argument is a user filter expression that must evaluate to True for a set of credentials for those credentials to match. See dacs(1) for information about naming.

The string argument (EXP) has the following syntax:

EXP -> E1
E1  -> E2 | E2 OR E2
E2  -> E3 | E3 AND E2
E3  -> E4 | NOT E3
E4  -> primary | "(" E1 ")"

OR  -> "or"  | "||"
AND -> "and" | "&&"
NOT -> "not" | "!"

Whitespace (spaces and tabs) is permitted before and after lexical elements. Keywords are case sensitive except when otherwise stated.

A primary, which evaluates to True or False, is one of the following:

By default, an exact string comparison (case sensitive) is used to match name components other than the special names; this default behaviour can be overridden using the NAME_COMPARE configuration directive (dacs.conf(5)). The method used to compare federation names, jurisdiction names, and usernames can also be specified by following the primary with a mode. If the value of mode (which is itself case insensitive) is case, then case-sensitive comparisons are used, if its value is nocase, then case-insensitive comparisons are used, and if its value is default, then the value of the NAME_COMPARE directive will be used if present, otherwise the application default is used (either case or the value selected by the application).

user("not METALOGIC:rmorriso")

user("not METALOGIC:rmorriso and auth")

user("auth")
user("DSS:auth")

This function generates a string called a stamp that is globally unique and sequenced, with high probability. It has the following syntax:

h=hostid, s=seqno

A hostid consists of one or more characters from the same set used for a DACS username. A seqno consists of two elements, separated by a colon, each of which is an unsigned decimal value.

The first component of a stamp, the hostid, is intended to be uniquely associated with the host that generates the stamp. By default, it is a 128-bit, cryptographically strong pseudo-random value. This value is stored in vfs-ref, which may be an absolute pathname, an item type, or a VFS URI. If vfs-ref does not exist, it is created and a new value is stored in it.

Note that by default, hostid identifies a host, not a jurisdiction. If required, it is possible to configure unique stamps for each jurisdiction on a host.

The second component (seqno) is a sequence number string relative to hostid. Sequence numbers should never repeat with respect to a host and always increase in value so that any two sequence numbers created by the same host must be different. Successive sequence numbers need not increase by uniform steps. If stamp1 compares less than stamp2, then stamp1 was created before stamp2. Comparison of sequence numbers is performed on matching elements numerically, left to right. Two hostid components are compared case insensitively. No ordering is necessarily implied by stamps created by different hosts.

Sequence number state information is stored in a file that must be specified using the configuration variable ${Conf::ustamp_seqno}; e.g.,

EVAL ${Conf::ustamp_seqno} = "${Conf::DACS_HOME}/seqno"

The variable must be set to the absolute pathname of a file that is readable and writable by any process that needs to generate a stamp. If this file is deleted, the sequence will be reinitialized. Note that updates to the state information are unlikely to be atomic, which means that in the event of a system crash the state information should be deleted so that a new stream of sequence numbers is generated.

One application of these stamps is to provide an efficient way to detect replayed messages. A recipient may only need to keep track of the stamp sent with the last message received from a jurisdiction to detect an invalid stamp in any subsequent message. Cryptographic techniques can be employed to prevent a stamp from being altered or forged.

The following operations are recognized:

Examples:

> ustamp(clock, "${Conf::DACS_HOME}/hostid")
"h=2fbae312ddc1d2ae388cea1b57a47c66, s=1185565675:9"

If its argument is a single pair, the pair's value is returned. If there is more than one pair in the argument, a list of values is returned. To get the key component of a pair or set of pairs, use keysof().

Examples:

> valuesof({red, 17})
17
> valuesof({red, 17, blue, 100})
[17, 100]

This function performs various operations on a variable, some of which are awkward or impossible to do using the more concise variable reference syntax. For example, the namespace or variable name argument to var() can be specified by an expression.

The following operations are available:

Examples:

> ${Y::foo} = 17
17
> var(get, Y, foo)
"17"
> $y = "Y", $x="foo"
"foo"
> var(get, $y, $x)
"17"
> setvar(split, X, "/a/b/c/Y", "/")
5
> var(get, X, 4)
"Y"
> var(get, X, ${X::#} - 1)
"Y"
> var(get, var(get, X, "4"), "foo")
"17"
> var(set, Y, "f" . "o" . "o", 2007)
2007
> ${Temp::x}
"foo"

This function is an interface to the DACS virtual filestore subsystem, described in dacs.vfs(5). Please refer to dacs.conf(5) and dacsvfs(1) for details and examples.

The first argument specifies the operation to be performed. The second argument identifies a filestore (typically a file or database); it can be an absolute pathname, an item_type that has been configured through a VFS directive, or a VFS URI. Zero or more arguments may follow, depending on op. For most operations, the third argument will be the key that identifies the object of interest. The underlying filestore is implicitly opened and closed.

An operation that fails abnormally triggers a fatal error.

The following operations (op) are available:

This statement sets a variable to the contents of the file /tmp/somefile:

${somefile} = vfs(get, "file:///tmp/somefile")

As do this equivalent statements:

${somefile} = vfs(get, "/tmp/somefile")
${somefile} = get("/tmp/somefile")

This expression lists the files in the /tmp directory:

vfs(list,"dacs-fs:/tmp")

These expressions 1) add a key/value pair to a Berkeley DB database (/tmp/mydb.db), creating the database file if necessary, 2) retrieve the value, 3) rename the key, and 4) list the keys in the database:

vfs(put, "dacs-db:/tmp/mydb.db", "foo", "baz");
vfs(get, "dacs-db:/tmp/mydb.db", "foo");
vfs(rename, "dacs-db:/tmp/mydb.db", "foo", "bar");
vfs(list, "dacs-db:/tmp/mydb.db");

This rule fragment denies access if the user has already been granted access five times:

<deny>
  if (user("auth")) {
    if (vfs(exists, counter_db, ${DACS::IDENTITY})) {
      ${count} = vfs(get, counter_db, ${DACS::IDENTITY});
    }
    else {
      ${count} = 0;
    }
    if (${count} gt 5) {
      return(1);
    }
    vfs(put, counter_db, ${DACS::IDENTITY}, ++${count});
    return(0);
  }
</deny>

The item type counter_db would be configured in dacs.conf; e.g.,

VFS "[counter_db]dacs-db:/usr/local/dacs/federations/counters.db"