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