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 
  16 The configuration files in this directory are structured as lines,
  17 where each line is made up of fields, separated by "|" characters,
  18 possibly surrounded by whitespace.
  19 
  20 New lines preceeded by backslashes are ignored, allowing for a continuation
  21 of lines, in the usual UNIX way.
  22 
  23 A line beginning with a hashmark is comment, and is ignore, as are lines
  24 consisting solely of whitespace.
  25 
  26 The first field is always the "keyword", which determines the meaning and
  27 presence of any other fields.
  28 
  29 These files are parsed using the test_load_config() function.  This
  30 function has the following prototype:
  31 
  32         int test_load_config(test_t, const char *, ...);
  33 
  34 The variable arguments are the keywords and handling functions.  These
  35 must 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 
  39 The test_config_load function will search for the named file (provided it
  40 is 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 
  47 The handling functions (keywordcb in the example above) have the following
  48 typedef:
  49 
  50         typedef int (*test_cfg_func_t)(char **fields, int nfields, char **err);
  51 
  52 so for example, keywordcb should be declared thusly:
  53 
  54         int keywordcb(char **fields, int nfields, char **err);
  55 
  56 These 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,
  58 and contains "nfields" items.  Internal whitespace is unaffected.
  59 
  60 The function should return 0 on successful handling, or -1 on failure.  In
  61 the event of failure, it should record an error string in "err" using
  62 asprintf() or strdup(). ("err" should be unmodified otherwise.)
  63 
  64 This parser is rather simplistic, and it lacks support for embedding "|"
  65 fields in lines, and also doesn't support escaping, so you can't add "\"
  66 at the end of a line (if you need that, leave some trailing whitespace).
  67 
  68 There are also some internal limits on the length of lines (1K), and on the
  69 number of fields (20).  As this is only used for these test suites, this
  70 should not be a significant limitation.
  71 
  72 Please see ../tests/symbols/symbols_test.c for an example of correct usage.
  73 
  74 Aside:
  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.