Document how memory management is done in the GSF decoder.

[schwehr]

It looks like the caller doesn't have to worry about memory allocated in gsf decoding from the C library. The file table has space for records so that it is safe to have multiple threads access different files, but it will implode if a separate thread reads or (possibly) get the wrong record info if a record pointer is used later.

The memory management strategy needs to be doc'ed in gsf.h and GSF_lib.md.

e.g. memory management from gsf_dec.c:

    /* Make sure we have memory for the attitude measurements. */
    if (ft->rec.attitude.heading == (double *) NULL)
    {
        ft->rec.attitude.heading = (double *) calloc(attitude->num_measurements, sizeof(double));

        if (ft->rec.attitude.heading == (double *) NULL)
        {
            gsfError = GSF_MEMORY_ALLOCATION_FAILED;
            return (-1);
        }
    }
    /* Re-allocate the dynamic memory if the number of measurements in the record
     * is greater this time than it was last time.
     */
    else if (ft->rec.attitude.num_measurements < attitude->num_measurements)
    {
        ft->rec.attitude.heading = (double *) realloc(ft->rec.attitude.heading, attitude->num_measurements * sizeof(double));

        if (ft->rec.attitude.heading == (double *) NULL)
        {
            gsfError = GSF_MEMORY_ALLOCATION_FAILED;
            return (-1);
        }
        memset(ft->rec.attitude.heading, 0, attitude->num_measurements * sizeof(double));
    }
    /* Set the caller's pointer to this dynamic memory. */
    attitude->heading = ft->rec.attitude.heading;