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