Incorporate rmustacc's review feedback.

          --- old/usr/src/test/libc-tests/cfg/README
          +++ new/usr/src/test/libc-tests/cfg/README

   1    1  #
   2    2  # This file and its contents are supplied under the terms of the
   3    3  # Common Development and Distribution License ("CDDL"), version 1.0.
   4    4  # You may only use this file in accordance with the terms of version
   5    5  # 1.0 of the CDDL.
   6    6  #
   7    7  # A full copy of the text of the CDDL should have accompanied this
   8    8  # source.  A copy of the CDDL is also available via the Internet at
   9    9  # http://www.illumos.org/license/CDDL.
  10   10  #
  11   11  
  12   12  #

  13   13  # Copyright 2014 Garrett D'Amore <garrett@damore.org>
  14   14  #
  15   15  
  16   16  The configuration files in this directory are structured as lines,
  17   17  where each line is made up of fields, separated by "|" characters,
  18   18  possibly surrounded by whitespace.
  19   19  
  20   20  New lines preceeded by backslashes are ignored, allowing for a continuation
  21   21  of lines, in the usual UNIX way.
  22   22  
  23      -A line beginning with a hashmark is comment, and is ignore, as are lines
       23 +A line beginning with a hashmark is a comment, and is ignored, as are lines
  24   24  consisting solely of whitespace.
  25   25  
  26   26  The first field is always the "keyword", which determines the meaning and
  27   27  presence of any other fields.
  28   28  
  29   29  These files are parsed using the test_load_config() function.  This
  30   30  function has the following prototype:
  31   31  
  32   32          int test_load_config(test_t, const char *, ...);
  33   33  

  34   34  The variable arguments are the keywords and handling functions.  These
  35   35  must be supplied in pairs and the list is terminated with a NULL, like this:
  36   36  
  37   37          test_config_load(t, "myfile.cfg", "mykeyword", keywordcb, NULL);
  38   38  
  39   39  The test_config_load function will search for the named file (provided it
  40   40  is not an absolute path) in a few locations:
  41   41  
  42   42          * relative to the current directory, exactly as specified
  43   43          * relative to $STF_SUITE/cfg/   (if $STF_SUITE is defined)
  44   44          * relative to ../../cfg/        (if $STF_SUITE is undefined)
  45   45          * relative to cfg/
  46   46  
  47   47  The handling functions (keywordcb in the example above) have the following
  48   48  typedef:
  49   49  
  50   50          typedef int (*test_cfg_func_t)(char **fields, int nfields, char **err);
  51   51  
  52   52  so for example, keywordcb should be declared thusly:
  53   53  
  54   54          int keywordcb(char **fields, int nfields, char **err);
  55   55  
  56   56  These functions are called each time a paired keyword is seen in the file.
  57   57  "fields" is an array of fields, pre-split with surrounding whitespace removed,
  58   58  and contains "nfields" items.  Internal whitespace is unaffected.
  59   59  
  60   60  The function should return 0 on successful handling, or -1 on failure.  In
  61   61  the event of failure, it should record an error string in "err" using
  62   62  asprintf() or strdup(). ("err" should be unmodified otherwise.)
  63   63  
  64   64  This parser is rather simplistic, and it lacks support for embedding "|"
  65   65  fields in lines, and also doesn't support escaping, so you can't add "\"
  66   66  at the end of a line (if you need that, leave some trailing whitespace).
  67   67  
  68   68  There are also some internal limits on the length of lines (1K), and on the
  69   69  number of fields (20).  As this is only used for these test suites, this
  70   70  should not be a significant limitation.
  71   71  
  72   72  Please see ../tests/symbols/symbols_test.c for an example of correct usage.
  73   73  
  74   74  Aside:
  75   75  
  76   76    Astute readers may ask why invent a new configuration file, and why use
  77   77    position based parsing instead of name value pairs.  These files are
  78   78    optimized for specific needs, and intended to support relatively dense
  79   79    information in a format that is easy for humans to work with.  JSON or XML
  80   80    or even YAML could have served, but the overhead of a syntax was more than
  81   81    we wanted to introduce.  Test suites are free to use other formats if they
  82   82    choose, but this simple format has the advantage of being built-in and
  83   83    easy to use.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX