The functions in the "iv_ini.c" file, which requires "iv_list.c" to work,
are:


  -----------------------------------------------------------------------------

  ini_initialise

    This sets up the internal data structures. Call it BEFORE CALLING ANY OTHER
    INI_* FUNCTIONS. It takes no parameters and doesn't return anything.

  -----------------------------------------------------------------------------

  ini_closedown

    The reverse of ini_initialise. Call it to close any open files and free up
    any memory being used by these routines. Again, no parameters, nothing.

  -----------------------------------------------------------------------------

  ini_key_value (file, section, key, duff)

    This is the magic function. All parameters are "char *", i.e. strings, and
    the return value is also "char *".

    file     - the filename of your INI file.
    section  - the section in that file (see terminology below for a definition
               of "section").
    key      - the key you're looking for - again, see the terminology below.
    duff     - what to return if the key can't be found under that section.

    The return value will be either the value for the key in the specified
    section, or the string "duff" which you supplied (which can be null).

  NOTE: The returned string is in a statically allocated buffer and will be
        overwritten next time an ini_* function is called. Copy it elsewhere if
        you want to keep it.

  EXAMPLE:

    printf ("Key 'foo' in section [Bar] in file 'baz.ini' has value: %s\n",
            ini_key_value ("baz.ini", "Bar", "foo", "<none found>");

    - displays the value of the "foo" key, or "<none found>" if it's not there.

-------------------------------------------------------------------------------

You can get away with just those functions, but the following are also
available:

-------------------------------------------------------------------------------

  ini_list_sections (arrayptr, file)

    At first sight the prototype for this one looks pretty awful, since
    arrayptr is a pointer to an array of char *, and hence is char ***. Fret
    not, all will be revealed.

    "file" is just your average char *, being the filename of the INI file
    that you want to list the sections of.

    Calling this function creates an array of strings, the address of which
    is placed in "arrayptr". The number of elements in the array, i.e. the
    number of sections in the file, is returned as an integer.

    On error, a number lower than zero is returned (and the contents of
    "arrayptr" are undefined).

  EXAMPLE:

    char ** array;
    int num_sections;
    num_sections = ini_list_sections (&array, "WHELK.INI");
    if (num_sections <= 0) exit (EXIT_FAILURE);
    printf ("Last section in WHELK.INI: %s\n", array[num_sections-1]);

  NOTE: You may want to free up the array afterwards with ini_free_array().
        Also: BE SURE TO PUT THAT & NEXT TO "ARRAY" IN INI_LIST_SECTIONS.
        Otherwise... ooh, problems.

  -----------------------------------------------------------------------------

  ini_list_keys (arrayptr, file, section)

    This works identically to the above function call, except that you also
    specify the section, and the keys within that section are listed.

  -----------------------------------------------------------------------------

  ini_free_array (array, num)

    Call this after ini_list_* to free up the array - all elements from
    array[0] to array[num-1] are freed, and then "array" itself is freed too.

  EXAMPLE:

    (code as above)...
    printf ("Last section in WHELK.INI: %s\n", array[num_sections-1]);
    ini_free_array (array, num_sections);
    array = NULL;	/* just to make the point... */

  NOTE: There's no & before "array" for this function, since - well, if you
        can't work it out, an explanation would only confuse you.

-------------------------------------------------------------------------------

That's all that is in the "iv_ini.c" file. The following linked list functions
are available in "iv_list.c" and are prototyped in "iv_list.h".

Before they're listed, you might need to know something about how the linked
lists should work.

Your list record structure should be of the form

  struct whatever {
    void * next;
    int foo;
    char bar[256];
    ...
  };

It is *vital* that the first field in there is a pointer to the next record.
If it's not, the linked list routines will die horribly.

To keep track of your list you just need a base pointer. Call this "base",
it'll be of the form "struct whatever * base".

When your program starts up, do "base = 0" to set the list to be initially
empty.

Now, read on to find out how to add and remove things to this list.

-------------------------------------------------------------------------------

  ll_add (baseptr, size)

    Adds an entry to the list, where "baseptr" is a pointer to the base pointer
    and "size" is the sizeof() the record structure.

    A pointer (void *) to the added element will be returned, or 0 on failure.
    The new element is added to the end of the list.

  EXAMPLE:

    struct whatever * base;
    struct whatever * new_record;
    base = 0;
    new_record = ll_add (&base, sizeof (*base));

  -----------------------------------------------------------------------------

  ll_insert (baseptr, size)

    Adds an entry, as above, but it is added to the *start* of the list instead
    of the end.

  -----------------------------------------------------------------------------

  ll_delete (baseptr, record, destructor)

    Removes the entry pointed to by "record" from the list, calling the
    function void destructor(void * record) before freeing "record". If
    "destructor" is 0, no extra function is called.

  EXAMPLE:

    (code as above)
    ...
    ll_delete (&base, new_record, 0);

    For an example of the use of the destructor function, look in "iv_ini.c".

  -----------------------------------------------------------------------------

  ll_destroy (baseptr, destructor)

    Calls ll_delete() above for every record in the list. Call this function to
    to make sure that you've freed up all the memory used.

  EXAMPLE:

    ll_destroy (&base, 0);

  -----------------------------------------------------------------------------

  ll_next (ptr)

    Returns a (void *) pointer to the record after "ptr", i.e. ptr->next.
    Fairly pointless unless the calling function doesn't have access to the
    innards of the record structure.

-------------------------------------------------------------------------------

That's about it.

Error codes returned by the functions in iv_ini.c are enumerated in iv_ini.h:

  INI_ENOMEM    - memory allocation failed
  INI_ENOENT    - failed to open file for reading
  INI_EFILE     - file error while reading
  INI_EFAULT    - an illegal null pointer was passed

Remember that these are negative.

/* EOF */
