README
1#
2# This file and its contents are supplied under the terms of the
3# Common Development and Distribution License ("CDDL"), version 1.0.
4# You may only use this file in accordance with the terms of version
5# 1.0 of the CDDL.
6#
7# A full copy of the text of the CDDL should have accompanied this
8# source. A copy of the CDDL is also available via the Internet at
9# http://www.illumos.org/license/CDDL.
10#
11
12#
13# Copyright 2014 Garrett D'Amore <garrett@damore.org>
14#
15
16The configuration files in this directory are structured as lines,
17where each line is made up of fields, separated by "|" characters,
18possibly surrounded by whitespace.
19
20New lines preceeded by backslashes are ignored, allowing for a continuation
21of lines, in the usual UNIX way.
22
23A line beginning with a hashmark is a comment, and is ignored, as are lines
24consisting solely of whitespace.
25
26The first field is always the "keyword", which determines the meaning and
27presence of any other fields.
28
29These files are parsed using the test_load_config() function. This
30function has the following prototype:
31
32 int test_load_config(test_t, const char *, ...);
33
34The variable arguments are the keywords and handling functions. These
35must be supplied in pairs and the list is terminated with a NULL, like this:
36
37 test_config_load(t, "myfile.cfg", "mykeyword", keywordcb, NULL);
38
39The test_config_load function will search for the named file (provided it
40is not an absolute path) in a few locations:
41
42 * relative to the current directory, exactly as specified
43 * relative to $STF_SUITE/cfg/ (if $STF_SUITE is defined)
44 * relative to ../../cfg/ (if $STF_SUITE is undefined)
45 * relative to cfg/
46
47The handling functions (keywordcb in the example above) have the following
48typedef:
49
50 typedef int (*test_cfg_func_t)(char **fields, int nfields, char **err);
51
52so for example, keywordcb should be declared thusly:
53
54 int keywordcb(char **fields, int nfields, char **err);
55
56These functions are called each time a paired keyword is seen in the file.
57"fields" is an array of fields, pre-split with surrounding whitespace removed,
58and contains "nfields" items. Internal whitespace is unaffected.
59
60The function should return 0 on successful handling, or -1 on failure. In
61the event of failure, it should record an error string in "err" using
62asprintf() or strdup(). ("err" should be unmodified otherwise.)
63
64This parser is rather simplistic, and it lacks support for embedding "|"
65fields in lines, and also doesn't support escaping, so you can't add "\"
66at the end of a line (if you need that, leave some trailing whitespace).
67
68There are also some internal limits on the length of lines (1K), and on the
69number of fields (20). As this is only used for these test suites, this
70should not be a significant limitation.
71
72Please see ../tests/symbols/symbols_test.c for an example of correct usage.
73
74Aside:
75
76 Astute readers may ask why invent a new configuration file, and why use
77 position based parsing instead of name value pairs. These files are
78 optimized for specific needs, and intended to support relatively dense
79 information in a format that is easy for humans to work with. JSON or XML
80 or even YAML could have served, but the overhead of a syntax was more than
81 we wanted to introduce. Test suites are free to use other formats if they
82 choose, but this simple format has the advantage of being built-in and
83 easy to use.
84