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. 84