Home | Back
New in version 0.8.2:

  Library Changes:
  * BUG FIX: A trailing symlink (i.e. situations where a symlink is the last
    element of a path) no longer confuses GetData when the target of the
    symlink: (1) is absolute, or (2) starts with "../".  Reported by S. J.

  * BUG FIX: Trying to read data from the first sample of an MPLEX no longer
    results in an internal error if the first sample of the index doesn't match
    the target value.


New in version 0.8.1:

  Library Changes:

  * BUG FIX: A segfault when negotiating symbolic links in file paths, typically
    manifesting in gd_open calls, has been fixed.

  * BUG FIX: gd_strtok now saves a copy of the string passed to it, as the
    documentation suggests it should.  Previously it cached the pointer itself.

  * BUG FIX: A number of minor memory leaks, mostly occurring when the library
    encounters an error, have been fixed.

  * BUG FIX: /HIDDEN directives weren't being written for aliases.

  * BUG FIX: The parser now fails properly on /INCLUDEs which specify paths
    which don't point to regular files.

  * BUG FIX: Fixed a bug which would result in the parser getting confused over
    the current Standards Version, potentially leading to rejected valid
    dirfiles.  Reported by Daniel Flanigan.

  * WIN32 BUG FIX: On Windows, the parser can now properly handle hexadecimal
    floating point.

  API Changes:

  * How the API deals with field code affixes has changed.  Input vector and
    scalar fields are reported by gd_entry(), &c. now include their prefix and
    suffix, if any, which should remove the need to do manual affix bookkeeping
    when reading metadata.  The other side to this change is that when modifying
    metdata (gd_add(), gd_alter_entry(), &c.), supplied field codes must also
    contain the appropriate suffixes.

  * gd_dirfilename() now returns a fully canonicalised version of the dirfile

  * A new function, gd_linterp_tablename() has been added which returns a fully
    canonicalised version of the look-up table pathname for a LINTERP.

  * BUG FIX: gd_alter_entry() and gd_madd_alias() weren't clearing the Dirfile
    error before operation, resulting in them failing erroneously in certain

  * BUG FIX: When including an existing fragment which itself has subfragments,
    gd_include() no longer returns the wrong fragment index.

  Bindings Changes:

  * F77 BUG FIX: A memory leak has been fixed in GDALLC.


New in version 0.8.0:

  Dirfile Changes:

  * Dirfile Standards Version 9 has been released.  It adds two new field
    types: MPLEX, which allows multiplexing multiple low-rate channels in
    one high-rate one, and WINDOW, which extracts a portion of a field
    based on the value of a second field.  More changes are listed below.

  * Alternate field names may be defined using the /ALIAS directive.
    Aliases can't be used as a parent when defining metafields, but are
    otherwise indistinguishable from a field's original ("canonical") name.

  * The /VERSION directive now has fragment scope, which should alleviate
    some of the problems associated with "version leakage" found in
    previous versions.  Previous versions are unchanged, but a "/VERSION 9"
    directive will not propagate back up into a parent fragment, nor will
    any /VERSION directive be propagated back up into a Version 9 fragment.

  * Fields may be "hidden" using the /HIDDEN directive.  The Standards
    don't say what a "hidden" field does, but GetData will, by default,
    exclude them from the count and list functions.

  * Literal integers in the format may now be specified in octal (using
    0####) or hexidecimal (using 0x##### or 0X#####) in addition to
    decimal.  C99-standard hexidecimal floating point literals (0x##.##p##,
    &c.) are also accepted.

  * The /INCLUDE directive can take two additional, optional parameters
    which specify a prefix and/or suffix used to modify the entry names of
    the fields defined in the included fragment.  (The intent of this is to
    permit the inclusion of multiple subdirfiles which define the same set
    of fields, by modifying their field names.)

  * Three new encoding schemes are available.  The first is the Sample-
    Index Encoding (SIE), similar to run-length encoding, useful for
    compressing data which changes very rarely varying data.  Like the
    ASCII encoding, GetData implements it internally, so it's always
    available.  The other two schemes (zzip and zzslim) are based around
    the ZZip library, an access library for PKWARE ZIP files.  These are
    unusual in that they store all raw data in the same ZIP archive.

  * The /ENCODING directive takes an optional second token.  The zzip and
    zzslim encoding schemes optionally use this token to specify the name
    of the combined ZIP archive.

  * The data type names FLOAT (an alias for FLOAT32) and DOUBLE (an alias
    for FLOAT64) have been deprecated.

  Library Changes:

  * On POSIX systems, GetData now caches the dirfile directory (and any
    other necessary subdirectories).  This guards against third-parties
    renaming the directory while GetData is interested in it.

  * GetData is, in general, more careful about pathname management.  At
    least on POSIX systems, it will now try to canonicalise all paths it
    comes across, including resolving symlinks.  As a result, GetData no
    longer becomes befuddled by a caller who opens a Dirfile with a
    relative pathname and then calls chdir(2).  Functions like
    gd_fragmentname() and gd_raw_filename() now return canonicalised paths.

  * The library no longer forces a sync of all raw data on close.  The sync
    causes a flush of filesystem buffers, which is usually unnecessary
    overhead, and degredatious to efficient disk I/O.  Use an explicit
    gd_sync() or gd_flush() before closing to recover the old behaviour, if

  * The error messages output by GetData with GD_VERBOSE turned on now has
    "libgetdata: " prefixed to it.  A further prefix may be specified by
    the caller.

  * When truncating a dirfile, the primary format file is no longer deleted
    and then recreated.  Instead, it is simply truncated in-place.  This
    change means that a Dirfile which is undergoing truncation always
    appears (to GetData, at least) to be a valid Dirfile, which can be
    useful if it is being concurrently read.

  * Write support for gzip-encoded data has been added.  Writes occur out
    of place, which means sufficient space on the filesystem is needed for
    a second copy of every field being written.  Writing to a gzip
    compressed field requires uncompressing the portion of the field before
    the write of the existing file, recompressing it to the temporary file,
    then writing the new data to the temporary file.  A subsequent write at
    a later position, will continue to write to the compressed file, but a
    subsequent write to an earlier position requires coping all remaining
    data from the old file to the temporary file, finalising it, moving it
    over top of the old file, and then starting afresh with a new temporary
    file.  As a result, it's not very fast, and likely should be avoided
    for non-sequential writes.

  * Raw data files are now only opened for writing if writing is going to
    occur.  In particular, this means that opening a dirfile with GD_RDWR
    will still work even if you don't have write access to it, so long as
    you don't try writing to it.

  * GetData now tracks a "current location" for all RAW files, and allows
    reads and writes to occur at the "current location" (via the special
    symbol GD_HERE).  For some derived fields the idea of a "current
    location" doesn't make sense, and this won't work.

  * BUG FIX: In previous versions, renaming a field with gd_rename()
    wouldn't update or invalidate the cache of fields which depended on the
    old name, leading to surprising results.  It will now either invalidate
    these fields' metadata caches or else change the name in those
    definitions as well.

  * BUG FIX: The invalid syntax "/META parent/child granchild ..." is now
    properly rejected by the parser.  Previously it half-worked, resulting
    in a segfault in gd_close().

  * BUG FIX: Several syntax errors encountered in PHASE and RECIP field
    specifications weren't being reported by the parser, leading to
    corrupted metadata on open.

  * BUG FIX: GetData no longer omits the input field to a RECIP when
    writing metadata to disk.  Nor does it forget to put newlines after
    RECIP or DIVIDE field specifications.

  * BUG FIX: GetData no longer assumes all LINCOM input fields have the
    same number of samples per frame.

  * BUG FIX: Writing an empty fragment with GD_PRETTY_PRINT turned on no
    longer results in a floating-point exception.

  * BUG FIX: Renaming a field now properly flags the fragment which
    contains it as dirty, which will ensure the rename is writen to disk
    when the metadata are next flushed.

  * BUG FIX: Whitespace within tokens is now properly escaped when metadata
    is flushed to disk.

  * BUG FIX: The parser no longer gets tripped up by two character escape
    sequences in a row, nor by an escape sequence at the start of a token.

  * BUG FIX: "/PROTECT data" directives are now being written when they
    should be.  Previously, they were dropped completely.  Reported by
    Alexandra Rahlin.

  * BUG FIX: CARRAY indices provided to gd_add() in the entry.scalar_ind
    member are no longer ignored.  Reported by S. J. Benton.

  * BUG FIX: When adding a metafield with gd_(m)add(), GetData no longer
    checks the protection of the fragment indexed by entry->fragment_index.
    Instead it ignores entry->fragment_index completely (as the
    documentation indicates it should) and checks the protection of the
    fragment containing the parent field.

  API Changes:

  * Functions which add fields (gd_add(), gd_add_<type>(), &c.) can now be
    used to add metafields by using their full "parent/name" field code.
    The old, explicit metafield adding routines (gd_madd(), &c.) are still

  * As with their corresponding names in the Standards, the gd_type_t
    symbols GD_FLOAT and GD_DOUBLE are now deprecated.  Use GD_FLOAT32 and
    GD_FLOAT64 as appropriate.

  * A new open flag, GD_TRUNCSUB, will cause GD_TRUNC to descend into
    subdirectories of a directory it is truncating.  If not specified along
    with GD_TRUNC, it does nothing.

  * New public functions gd_nentries() and gd_entry_list() provide a
    generic interface to the field counting and list functionality.  The
    other functions (gd_nfields(), gd_nfields_by_type(), &c. and
    gd_field_list(), gd_field_list_by_type(), &c.) are now simply special
    cases of these two functions.

  * The "hiddenness" of a field name may be queried with gd_hidden(), set
    with gd_hide() and cleared with gd_unhide().

  * /INCLUDE affixes may be queried with gd_fragment_affixes() and added,
    modified or deleted with gd_alter_affixes().  A new fragment can be
    added to the dirfile with affixes using gd_include_affix().

  * New aliases may be added with gd_add_alias() or gd_madd_alais.  The
    target of an alias is retrned by gd_alias_target(); a list of aliases
    of a field, or their number, is returned by gd_aliases() and

  * Because GetData considers aliases and canonical names to be
    indistinguishable, passing an alias name to most functions will result
    in the function operating on target field.  To manipulate aliases
    themselves, the API has the new interfaces gd_move_alias() and

  * In addition to the special symbol GD_HERE which may be passed to
    gd_getdata() and gd_putdata(), the "current location" of fields may be
    queried with gd_tell() and moved with gd_seek().

  * The typedefs gd_bit_t and gd_spf_t have been deprecated.  They are
    replaced with 'int' and 'unsigned int' respectively.  For backwards
    compatibility, the typedefs (with their new types) are still declared
    in getdata.h, but the API no longer makes use of them.

  * GetData's tokeniser has been exposed to the public API via the
    gd_strtok() function, which works similar to strtok(3), and returns
    successive tokens of a string given it.

  * A new function gd_error_count() returns the number of GetData errors
    encountered on a Dirfile since it was last called (or since the Dirfile
    was opened).  This is useful for programs that care whether *something*
    failed, but don't really care what it was.

  * Reading MPLEX fields can result in inefficiencies due to GetData having
    to look backwards for the first value of the part of the derived field
    requested.  A new function, gd_mplex_lookback(), can be used to alter
    how much lookback is done, if any.

  * The "move_data" flag in gd_rename() has been replaced with a generic
    "flags" parameter.  Two rename flags are defined: GD_REN_DATA, which
    recovers the old behaviour of move_data, and GD_REN_UBDB which will
    cause references to the renamed field to be renamed also in derived
    fields which refer to it.  Without GD_REN_UBDB, these definitions are
    left unchagned.

  * Flags which affect the long-term operation of GetData may be modified
    after open using gd_flags().  Currently these flags are just GD_VERBOSE

  * The gd_flush() function, which both syncs and closes RAW files, has
    been broken up into its two parts with two new functions: gd_sync(),
    which just syncs and gd_raw_close(), which just closes.  gd_flush()
    still does both.

  * Using the new gd_desync() function will cause GetData to determine
    whether the Dirfile metadata on disk has changed since the Dirfile was

  * A prefix to the automatic error messages printed by GetData when using
    the GD_VERBOSE flag may be specified with gd_verbose_prefix().

  * When requesting the exclusive creation of a new dirfile with (GD_CREAT
    | GD_EXCL) GetData will now return the new error GD_E_EXISTS if the
    dirfile already exists.  Previously it would return GD_E_CREAT in this

    GD_E_BAD_VERSION have been combined into a more generic error code:
    GD_E_ARGUMENT.  The old symbols are retained for backwards
    compatibility but have been marked deprecated.

  * CONST and CARRAY handling has been combined somewhat.  When passed to
    {get,put}_carray[_slice]() or gd_carray_len(), CONSTs behave like
    length-one CARRAYs.  Similarly, {get,put}_constant() will operate on
    the first element of a CARRAY, as if it were a CONST field.

  * C89 API: Passing NULL to gd_alter_crecip() for cdividend is now treated
    as if it were passed zero (ie. it indicates no change for cdividend).

  * BUG FIX: calling gd_putdata() with num_frames and num_samples both zero
    no longer confuses GetData: instead it simply does nothing.

  * BUG FIX: gd_spf() now returns GD_E_DIMENSION when passed a scalar field
    code, as the documentation says it should.  Previously it returned

  Legacy API Changes:

  * The never-used n_mplex/mplexEntries part of the FormatType now has a
    use: both MPLEX and WINDOW entries are reported there.

  Bindings Changes:

  * Bindings for Perl5 have been added.  Perl is not well suited to
    numerical analysis, and the bindings may be inefficient.

  * F77: Due to small namespace issues, the encoding parameters
    (corresponding to the GD_...ENCODED symbols in the C API) have all been
    renamed.  They are now of the form GDE_xx.

  * C++: The bindings now make use of the explicitly-64-bit offset type
    gd_off64_t defined in getdata.h.  Previously, the bindings tried to
    force off_t to be 64-bit through preprocessor shenanigans, which led,
    in certain cases, to linking problems down the road when used by third

  * Python: The return_type, num_fields, and num_samples parameters to
    dirfile.getdata() are now optional.  The return_type defautls to
    pygetdata.FLOAT, and if neither num_fields nor num_samples are given,
    all frames (ie. the value of dirfile.nframes) are returned.

  * IDL: A number of undocumented, unnecessary function aliases have been
    removed. They should be replaced with their canonical names, without
    change in use:

        Alias                   Replacement
        ----------------------  ----------------
        GD_ADD_CRECIP           GD_ADD_RECIP
        GD_MADD                 GD_ADD
        GD_MADD_BIT             GD_ADD_BIT
        GD_MADD_CRECIP          GD_ADD_RECIP
        GD_MADD_PHASE           GD_ADD_PHASE
        GD_MADD_RECIP           GD_ADD_RECIP
        GD_MADD_SBIT            GD_ADD_SBIT
        GD_MSTRINGS             GD_STRINGS
        GD_NMFIELDS             GD_NENTRIES
        GD_NMVECTORS            GD_NVECTORS

  * BUG FIX: All bindings now provide a named constant corresponding to the
    C API error GD_E_UNKNOWN_ENCODING, which was overlooked in previous

  * IDL BUG FIX: The missing /IGNORE_REFS and /PRETTY_PRINT are now
    available in gd_open.


New in version 0.7.3:

  Library Changes

  * BUG FIX: Passing a zero dividend to alter_crecip() and alter_recip() now
    results in the dividend not changing, per documentation.

  * BUG FIX: GetData wasn't properly computing the module directory, causing
    encodings using external modules to fail with GD_E_UNSUPPORTED.

  * BUG FIX: Metafield records are now properly stored in the format file for
    Standards Version 8.

  * BUG FIX: gd_raw_filename() wasn't clearing the Dirfile error before
    operation, resulting in it failing erroneously in certain situations.

  Utilities Changes:

  * BUG FIX: A potential segmentation fault has been patched in dirfile2ascii.


New in version 0.7.2:

  Library Changes

  * If built with modules, the plugin shared objects will now be installed in
    a separate directory (by default "${libdir}/getdata", but see the
    --with-module-dir option in ./configure).

  * BUG FIX: When using modules, a missing plugin no longer results in a lock up
    the second time an attempt is made to find it.

  * BUG FIX: GetData now properly processes /INCLUDE directives with absolute
    paths, as the documentation insists it should.

  * BUG FIX: gd_add()ing the first raw field in a dirfile to a subfragment no
    longer results in memory corruption when calling gd_close().

  API Changes

  * If called with GD_CREAT but no encoding specified, gd_include() now will
    duplicate the encoding of the parent fragment (if any).


  * The python module install dir can now be changed by passing
    --with-python-module-dir to configure.


New in version 0.7.1:

  Library Changes

  * BUG FIX: When the parser fails in a gd_include() call, the internal list of
    conformant Standards Versions for the loaded dirfile is no longer corrupted.

  * BUG FIX Performing two consecutive reads of the same field in an ASCII
    encoded datasources no longer confuses GetData.

  * BUG FIX: Numerous memory leaks have been patched (mostly pin-holes, although
    there are a few, rare but egregious ones).

  API Changes:

  * The value(s) of a CONST or CARRAY field added with gd_[m]add() is now
    guaranteed to be zero; previously, it was unspecified.

  * BUG FIX: Specifying both GD_VERBOSE and GD_IGNORE_DUPS no longer results in
    spurious "Field code already defined" messages when duplicate fields are

  * BUG FIX: Calling gd_delete on a metafield no longer results in a segfault.

  Bindings Changes:

  * F77 BUG FIX: A memory leak in GDASCA has been fixed.
  * Python BUG FIX: The first element of a python list (instead of a NumPy
    array) is no longer dropped when passed to pygetdata on 64-bit systems.

  Utilities Changes:

  * dirfile2ascii now pads reads past the end-of-field.  The value used to
    pad may be specified with '-z', and defaults to 0/NaN.  Previously, the
    value of uninitialized memory was output.

  * BUG FIX: dirfile2ascii now does what the user intends when presented with
    cart-before-horse arguments, ie. "dirfile2ascii -e field DIRFILE".
    Previously this resulted in confusion.

  * BUG FIX: dirfile2ascii now accepts field conversion '-u', which was
    documented but overlooked in the argument parser.


New in version 0.7.0:

  Dirfile Changes

  * Dirfile Standards Version 8 has been released.  It adds three new field
    types: DIVIDE, which computes X/Y for vectors X and Y, RECIP, which computes
    A/X for vector X and scalar A, and CARRAY, which is an array of CONST
    scalars.  A few other changes are listed below.

  * Like CONST fields, CARRAY elements can be used as parametersin the
    definition of other fields.  Syntax is 'field<n>', where 'field' is the
    field name and 'n' the element index in the CARRAY (and the angle brackets
    are literal angle brackets).  If the '<n>' is omitted, the first element
    (numbered 0) is assumed.

  * Slashes on reserved words are now mandatory, allowing fields with reserved
    words as names.

  * The long-deprecated single character data type codes have been removed from
    Standards Version 8.  (They are still accepted by GetData, which handles
    all previous Standards Versions as well.)

  * The /ENDIAN directive now takes an optional second parameter.  The only
    allowed value for this second token is "arm", which indicates that double
    precision floating point data (including double precision complex data) are
    stored in the ARM middle-endian format.  Without this, floating point data
    are assumed to have the same byte sex as integer data.

  Library Changes

  * GetData, including its bindings, is now supported under MacOS X, Cygwin, and
    Win32 using MinGW.  In the case of MinGW, this includes linking against the
    Microsoft C Runtime, which isn't POSIX compliant.  Users should excercise
    caution when writing to dirfiles in this case.

  * GetData can now be used on ARM processors.  As a side-effect, GetData can
    now read and write the middle-ended floating point format used by older ARM
    processors (on any processor, via endianness conversion).

  * Some changes have been made to the parser.  It now operates in one of two
    modes: pedantic mode, which adheres strictly to one particular Dirfile
    Standards Version, and permissive mode (the default) which is more
    lenient, as the old parser was.  Encountering a /VERSION directive will
    switch the parser from permissive to pedantic mode unless told not to (see
    GD_PERMISSIVE below), and will change the particular Standards Version to
    which pedantic mode is adhering.

  * As a result of the previous change, the Standards compliance of the parser
    in strict mode has been greatly increased.  This affects allowed characters
    in field names, and field name lengths.  The existance or lack thereof of
    the implicit FILEFRAM field (an alias for INDEX) is also affected.

  * Since Standards Versions 4 and earlier were never codified, we've made some
    assumptions as to their behaviour in certain undocumented situtations.  Most
    noticably, they still prohibit ASCII control codes (bytes < 0x20) and '/'
    in field names.  We also assume these dirfiles have native byte sex, even
    though some early GetData behaviour implied only little-ended data was

  * Every Dirfile object now records its current Standards Version, which
    affects functions such as gd_add_spec().  The Version will start out as the
    value of the last /VERSION directive encountered by the parser, or else the
    latest compliant Standards Version.  It can be changed (see below).

  * When writing metadata to disk, fragments will be written according to the
    current Standards Version of the dirfile object, rather than always using
    the latest version, as before.

  * The C library now sports an "ANSI C" mode, which allows compilation of
    GetData without a C99-compliant compiler.  Some functionality may be lost,
    most prominently, but unsurprisingly, the default (C99) API.

  * The artificial maximum line length of 4096 bytes for format metadata has
    been removed.  The maximum line length is now 2**31 bytes on 32-bit systems,
    and more on 64-bit systems.  This also has the side-effect of removing the
    same length limit which had been applied to field names.

  * LINTERP tables are no longer required to be sorted.  The library will
    sort them, if needed.  As a side-effect of this, tables are no longer read
    twice when loading, leading to potential speed-up.

  * BUG FIX: The library wasn't properly checking that the second and higher
    input fields in LINCOM and MULTIPLY fields were, in fact, vectors, leading
    to possible segfaults.

  * BUG FIX: A memory leak associated with modifying LINCOM metadata has been

  * BUG FIX: Using a complex valued vector as the second input field in a
    MULTIPLY wouldn't result in the field being internally flagged as complex,
    leading to loss of the imaginary part in certain situtaitons.

  * BUG FIX: Trying to write to a LINTERP via a table which isn't monotonic now
    results in error.  Previously, this was allowed, with arbitrary data stored
    to disk.

  * BUG FIX: On encountering a line longer than it was prepared to deal with,
    the parser used to get very confused, potentially resulting in bizarre
    behaviour.  On the off chance such a line is encountered, GetData will now
    raise GD_E_LINE_TOO_LONG in these cases. (And, since the maxmium line
    length has been increased to at least 2**31 characters, this should only
    occur in pathological situations.)

  * BUG FIX: Deleting a metafield was not being communicated to its parent,
    resulting in differing opinions within the library as to the deleted field's

  API Changes

  * Due to namespace conflicts with the MacOS X System Library (which contains
    the C Standard Library), a wholesale renaming of public symbols has been
    performed.  All public functions, and data types now begin with 'gd_'.  All
    public preprocessor macros now begin with 'GD_'.  Symbol renaming has
    occurred in the following manner:

    - functions which started with 'put' simply prefix 'gd_' to their name.  So
      put_constant() becomes gd_put_constant().
    - functions which started with 'get' replace 'get' with 'gd', except those
      functions with a corresponding 'put' function; these simply prefix 'gd_'.
      So, get_constants() becomes gd_constants(), but get_constant() becomes
    - functions which started with 'dirfile' replace 'dirfile' with 'gd',
      except for dirfilename(), which becomes gd_dirfilename().  So,
      dirfile_alter_encoding() becomes gd_alter_encoding().
    - macros which started with 'GETDATA_' now start with 'GD_'.  Those that
      started with 'NO_GETDATA_' now start with 'GD_NO_'.  So GETDATA_LEGACY_API

  * The above renaming rules result in one gd_ namespace clash.  As a result,
    get_reference() has been removed completely.  Calls will have to be
    changed to use gd_reference(), formerly dirfile_reference().

  * Furthermore, the function dirfile_protect() is now gd_alter_protection() to
    match the naming of other fragment metadata altering functions.

  * To ease transition to the new namespace, defining GD_FUNCTION_ALIASES before
    including getdata.h will create a bunch of preprocessor macros which map the
    old names to the new.

  * The meaning of the GD_PEDANTIC flag to gd_[cb]open() has changed.  It now
    forces the parser to start off in pedantic mode (see above), following the
    latest Standards Version, rather than the default permissive mode.  This is
    a subtle change, and in most cases the effects of GD_PEDANTIC will be the
    same as they were before.

  * A new dirfile flag, GD_PERMISSIVE, has been added.  Passing this to
    gd_[cb]open() will prohibit the parser from switching into pedantic mode
    when it encounters a /VERSION directive.  This flag is needed to read
    dirfiles which claim to adhere to the Standards via a /VERSION directive,
    but contain invalid syntax nonetheless.

  * The current Standards Version of an open dirfile can be set or queried by
    calling the new function gd_dirfile_standards().  NB: this only affects the
    open dirfile, not the metadata stored on disk.

  * A new function, gd_rewrite_fragment() will force GetData to write the
    specified fragment to disk, even if no metadata in the fragment has changed.

  * Two new functions, gd_bof() and gd_eof() can be used to find the sample
    number of the beginning- or end-of-field for a given field.  Notably, these
    can be used to calculate the amount of raw data on disk for a given field.

  * The new gd_invalid_dirfile() function will return a newly created, invalid
    dirfile.  Primarily useful to callers as a "null dirfile" placeholder.

  * GD_E_OPEN_INCLUDE has been renamed to GD_E_OPEN_FRAGMENT, but the former
    symbol remains as an alias.

  * Two new bitflags to gd_cbopen and gd_open: GD_ARM_ENDIAN and
    GD_NOT_ARM_ENDIAN allow specifying the default ordering of double precision
    data.  These flags may also be used with gd_alter_endianness() and will be
    returned by gd_endianness().  On all platforms except for middle-endian
    ARMs, GD_NOT_ARM_ENDIAN equals zero and may be omitted.

  * Where gd_flush() and gd_metaflush() in the past raised GD_E_OPEN_INCLUDE
    on I/O error, they now raise the new GD_FLUSH.

  * All functions now raise GD_E_DIMENSION when encountering a scalar field
    when expecting a vector.  In the past, the error value returned was
    different for different functions.

  * getdata.h now wraps itself in an extern "C" block if included by a C++

  * If passed a NULL pointer, gd_error_string() will return a newly malloc'd
    buffer long enough to hold the entire string.  It should be free'd by the

  * The parser data passed to the callback function now includes the length of
    the buffer.  The parser also permits the callback to assign a new pointer to
    the 'line' element of the parser data if the buffer passed in is too small.

  * gd_metaflush() now fails and raises GD_E_ACCMODE if called on a read-only
    dirfile.  (Previously it would successfully do nothing.)

  Legacy API Changes

  * In the legacy format struct, DIVIDE fields are listed as MULTIPLYs and RECIP
    fields are listed as LINCOMs, with the dividend stored in m[0].

  * BUG FIX: In previous versions, attempting to access an invalid dirfile
    (anything that would cause gd_open to fail) resulted in leaked memory.  This
    leak has been plugged.

  * BUG FIX: A segfault involving the reporting of POLYNOM fields has been fixed
    in GetFormat().


  * Bindings for the functionality introduced into 0.7.0 have been added.

  * F77: GDPROT has been renamed GDAPRT to mirror the renaming of

  * F77: GDGTCO and GDPTCO no longer return an indicator of success.

  * F77: The signatues of GDGSCA and GDASCA have changed to return/take the
    scalar index as well.

  * F95: For consistency sake, the Fortran 95 bindings have undergone the same
    renaming so they have the same name as their C counterparts.  All functions
    are now preceded by 'fgd_'.

  * F95: The fgd_get_constant_* and fgd_put_constant_* procedures are now
    subroutines, not functions.

  * C++: Const member functions are now flagged as such.

  * C++: The len parameter to Dirfile::ErrorString is now ignored.

  * C++: dirfiles are now opened read-only by default.

  * IDL: The IDL bindings have also followed suit in the great renaming.  The
    exception to this is GETDATA_CONSTANTS(), which is not renamed.

  * IDL: Various constants defined in getdata.h but not used by the IDL bindings
    have been removed from the structure returned by GETDATA_CONSTANTS().

  * Python: dirfile.getdata() now raises ValueError if neither num_frames nor
    num_samples are specified.  In the past, it would happily return nothing
    in this case.

  * Python: dirfiles are now opened read-only by default.

  * C++ BUG FIX: Entry::Scalar() no longer rejects valid values of index.

  * IDL BUG FIX: A memory impropriety involving keyword arguments.  This bug
    manifested by rejecting valid keyword arguments on 64-bit systems, but may
    have had other, subtle effects on 32-bit systems as well.

  * Python BUG FIX: A non-literal phase shift is now properly reported.

  * Python BUG FIX: Calling Dirfile.discard() or Dirfile.close() no longer
    results in a segfault.


  * The --disable-checkdirfile option has been removed from ./configure.  It
    is now always installed.

  * A utility, dirfile2ascii, is now installed alongside checkdirfile.  This
    utility converts all or part of a dirfile into ASCII text.  dirfile2ascii
    was written by Matthew Truch.

  * The thoroughness of the checks done by checkdirfile have increased.  It now
    reports format syntax errors, Dirfile Standards compliance, problems with
    field definitions (such as missing input fields), and the size of the


New in version 0.6.3:


  * A memory leak has been plugged in the Python bindings manifesting in calls
    to dirfile.getdata() returning a NumPy array.  In previous versions, the
    memory used by the returned array to hold the data was not reclaimed by GC.


New in version 0.6.2:

  Library Changes

  * Attempting to get the number of frames from an ASCII file no longer fails
    the second time.


New in version 0.6.1:

  API Changes

  * The getdata.h header no longer includes complex.h explicitly.

  Legacy API Changes

  * A potential segfault relating to error reporting in the legacy API has
    been fixed.


  * C++ BUG FIX: Several bugs preventing compilation of the C++ test-suite under
    Fedora 13 have been fixed.

  * IDL BUG FIX: Several segfaults in the IDL bindings have been eradicated.


  * Libtool has been upgraded to 2.2.6b, which provides proper support for
    Fortran-9x.  The outdated, internal libltdl has been removed.  Building
    modules now requires an installed libltdl.


New in version 0.6.0:


  * The GetData library and its bindings are now distributed under the GNU
    Lesser Public License, version 2.1 or later.

  Dirfile Changes

  * GetData now support Dirfile Standards Version 7.  Standards Version 7 adds
    complex data types, a signed bitfield (SBIT), a polynomial derived field
    (POLYNOM), and other features detailed below.

  * Metafields can now be specified using a normal format specification line and
    their full (slashed) field code.

  * Field codes can now contain a "representation suffix", which allows
    specifying a complex norm used to convert complex valued data into purely
    real data.

  * The n_fields parameter in a LINCOM specification is now optional.

  * A new encoding scheme which supports LZMA compressed data using the .xz
    container format has been added.

  * Look-up tables may contain a complex y-value.  This prohibits writing to
    the associated LINTERP field.

  Library Changes

  * The field parameters spf (RAW), bitnum and numbits (BIT and SBIT) are now
    restricted to 16-bit numbers, which should be more than enough.  The public
    API uses gd_spf_t and gd_bit_t for these quantities.

  * The shift field parameter is now a 64-bit integer type, called gd_shift_t.

  * The dirfile flags, including encoding and endianness symbols are now
    explicitly long ints.  Previously these quantities mixed long int with int
    arbitrarily.  This affects the public API.

  * The parser callback has received a new, API breaking signature, which should
    hopefully reduce the amount of API breakage in the future.  It is also now
    possible for the caller to pass data through GetData to the callback, if

  * Computation of derived fields can now handle complex valued inputs, and
    computation will occur in the complex plane when required.

  * The computation of LINCOM fields has been re-written and is now ~20% faster
    for LINCOMs with 2 or 3 input fields.  (No change for LINCOMs of 1 field.)

  * A new open flag, GD_PRETTY_PRINT, tells the library to attempt to write a
    nicer looking format file.  What this specifically means, isn't part of the
    public API and shouldn't be relied on in portable code.

  * BUG FIX: dirfile_madd_spec() and dirfile_add_spec() didn't properly flag
    the fragments they modified as dirty, leading to possible loss of metadata.

  * BUG FIX: calling get_nframes on a bzip2 encoded dirfile would report the
    wrong dirfile length.

  * BUG FIX: LINTERP tables are now closed after loading, resolving a file
    descriptor leak of great age (ie. pre-0.3.0).

  * BUG FIX: When re-writing a format file fragment containing fields with
    CONST scalar field parameters, GetData no longer replaces the CONST field
    codes in the field specification lines with the value of the CONST field.

  * BUG FIX: when moving a field with dirfile_move(), the fragment index in
    the entry objects of metafields defined for the field were not updated.
    (The metafields were placed in the correct fragment when the metadata was
    flushed to disk, despite this.)

  * BUG FIX: Calling getdata() or putdata() on 64-bit architectures in certain
    situations involving a non-zero frameoffset no longer results in bizarrity.

  * BUG FIX: A memory leak associated with RAW field metadata has been fixed.

  * BUG FIX: 64-bit integer literals in the format file are no longer truncated
    to double precision when read.

  API Changes

  * This release breaks ABI compatibility and, to a lesser extent, API
    compatibility.  The SOVERSION of the library has been incremented

  * A C-89 API will be declared by getdata.h if GETDATA_C89_API is defined
    before inclusion.  If this symbol is not defined, the C API defined will
    include C-99 conforming complex types, and getdata.h will include complex.h
    if `complex' has not been defined before inclusion.

  * Due to the new, simple way of specifying META fields in Standards Version 7,
    dirfile_add_spec() and dirfile_alter_spec() can be used to modify
    metafields. dirfile_madd_spec() and dirfile_malter_spec() remain as well.

  * An array containing the CONST scalar field codes used when non-literal
    parameters are used in the specification of various different fields has
    been added to the gd_entry_t object.  As a side-effect of this,
    dirfile_add(), dirfile_alter_entry(), and dirfile_madd() can be used to
    manipulate non-literal field parameters.

  * A function, get_native_type(), now exists which returns the underlying data
    type of a specified field code.

  * A function, get_framenum(), is now available to perform a "reverse look-up"
    on a field: given a data value, it reports the frame number where the field
    has that value.  The field must be monotonic.

  * A function, dirfile_validate(), now exists which can be used to check the
    validity of a field code before use.

  * Two new error codes have been added: GD_E_DOMAIN, potentially returned by
    get_framenum(), and GD_E_BAD_REPR, indicating an unrecognised representation
    suffix, or an attempt to write to a representation.

  * A new syntax error suberror code has been added: GD_E_FORMAT_LITERAL, which
    indicates a syntax error in a complex literal number.

  * BUG FIX: On success, dirfilename(), dirfile_reference(), and get_reference()
    didn't change the error code to GD_E_OK, resulting in spurious error codes
    from these functions.

  * BUG FIX: dirfile_madd_string() and dirfile_madd_const() now don't fail
    erroneously by reporting GD_E_BAD_CODE.

  * BUG FIX: error strings relating to GD_E_DELETE error codes now report the
    proper error information.

  * BUG FIX: the list returned by get_mstrings() is now properly NULL

  * BUG FIX: the entry->table member now reports the proper path to the LUT.
    (That is, the path stored in the format file.)  Previously it incorrectly
    reported a path relative to the base dirfile directory.

  Legacy API Changes

  * Because they would otherwise be unreported, in the structure returned by
    GetFormat(), POLYNOM entries are reported as LINCOM entries, by discarding
    higher order terms.  Similarly, SBIT entries are reported as BIT entries.


  * Bindings for Python and the Interactive Data Language (IDL) have been

  * Bindings for the functionality introduced into 0.6.0 have been added.

  * C++: The missing bindings for dirfilename(), get_nvectors(), and
    get_fragment_index() have been added.

  * C++: Empty entry class constructors have been added which allow delayed
    specification of field metadata.

  * C++: The dirfile.h header now includes all other C++ headers, and is now
    the only header required to be included in applications.  (The other headers
    can still be included, with no ill effects.)

  * All bindings have a much expanded test suite, which has resulted in the
    discovery of many bugs (subsequently fixed).

  * F77: The callback function is now dirfile-specific, as it is in the C API.

  * C++ BUG FIX: Entry class constructors now properly set the field name for

  * C++ BUG FIX: Fragment::SetEncoding() now actually does what it advertises,
    instead of doing nothing.

  * C++ BUG FIX: The recode argument to various functions is now optional and
    defaults to zero, as the documentation already indicated.

  * C++ BUG FIX: dirfile_close() was not being called by the Dirifle destructor.

  * F77 BUG FIX: a NULL C string returned from the C API now returns an empty
    string, rather than causing a segfault.

  * F77 BUG FIX: attempting to call another F77 function before calling GDCOPN
    or GDOPEN no longer results in a segfault.

  * F77 BUG FIX: passing an out-of-range dirfile unit no longer results in
    undefined behaviour.

  * F77 BUG FIX: the last character of a string returned by the bindings is no
    longer deleted.

  * F77 BUG FIX: string lengths now report the correct length.

  * F77 BUG FIX: passing dirfile unit 0 to GDCLOS or GDDSCD no longer corrupts
    the bindings.

  * F77 BUG FIX: GDFLDN no longer accepts indices less than one.

  * F77 BUG FIX: GDESTR now space pads its output string, rather than filling
    the remainder of the string with garbage.

  * F77 BUG FIX: The get_entry() bindings, GDGExx no longer segfault on dirfile

  * F77 BUG FIX: GDGTST and GDPTST now report the FORTRAN string length, which
    is one less than the C API would report, due to the lack of a terminating

  * F95 BUG FIX: Attempting to retrieve a PHASE entry with fget_entry() now

  * F95 BUG FIX: Several routines which were named fdrifile_<foo> are now
    properly spelled.


  * All bindings can now be disabled by passing --disable-bindings to


New in version 0.5.0:

  Dirfile Changes

  * Support for two new encoding schemes has been added which handle bzip2 and
    gzip compression.  Like the slim encoding, the bzip and gzip encoding
    schemes currently do not support writing, but do allow reading dirfile data
    compressed with the standard gzip and bzip2 utilities.  Reading compressed
    data is unsurprisingly slow.

  Library Changes

  * Encoding schemes relying on external libraries (slim, gzip, bzip2) may now
    be built into stand-alone library modules which will be loaded, as needed,
    at runtime.  GetData will fail gracefully if modules are missing.  See the
    README for full details.

  * BUG FIX: Writing metadata to disc now preserves the permissions of the
    format file fragments which are changed.

  * BUG FIX: Format files without a line feed character at the end of the file
    no longer cause the parser to segfault.

  * BUG FIX: putdata() now reports the correct number of samples written for
    ASCII encoded files.

  * BUG FIX: GetData no longer inserts unnecessary "/./" elements into the paths
    it reports.

  API Changes

  * The caller can now register a callback function with a DIRFILE by opening
    the dirfile with dirfile_cbopen instead of dirfile_open.  This callback
    function will be called by GetData whenever the format file parser
    encounters a syntax error.  The callback function can be used by the caller
    to either correct the syntax error, or else tell GetData whether to ignore
    the line or not.  The callback function may be later modified by calling

  * A fragment may be removed from a dirfile by calling dirfile_uninclude.

  * The pathname of the dirfile may be retrieved by calling dirfilename.

  * The reference field for the dirfile may be set or retrieved by calling

  * Fragment metadata may be queried or modified by calling:

      - get_encoding, dirfile_alter_encoding
      - get_endianness, dirfile_alter_endianness
      - get_frameoffset, dirfile_alter_frameoffset
      - get_protection, dirfile_protect
      - get_parent_fragment

  * Various functions now exist to modify field metadata:

      - dirfile_alter_entry, dirfile_alter_<field-type>, dirfile_alter_spec,

  * A field may be moved to a different format file fragment using dirfile_move.

  * A field may be renamed by using dirfile_rename.

  * A field may be removed from the dirfile by calling dirfile_delete.

  * The type or fragment index of a field may be retrieved by calling
    get_entry_type or get_fragment_index, respectively.

  * The pathname of a raw field may be obtained from a call to get_raw_filename.

  * A DIRFILE may be deallocated without saving modified metadata by calling

  * A new flag, GD_IGNORE_DUPS, may be passed to dirfile_open to tell the
    parser to ignore duplicate field specifications in the format files.  This
    is really only useful identically duplicate specifications, since there is
    no indication of which of the duplicates is honoured.  Explicit control can
    be obtained by handling this inside a caller supplied callback function.


  * All functions in the Fortran 77 bindings have been completely renamed from
    GDFxxx to GDxxxx to provide a larger namespace for our use.

  * Fortran 77, Fortran 95, and C++ bindings have been updated for the latest
    API changes.

  * BUG FIX: Fortran 77 functions which return character strings no longer
    corrupt memory as a side-effect of operation.  This also affected the
    Fortran 95 bindings.


  * BUG FIX: The dirifle_madd_bit(3) manual page has been corrected to show
    the correct order or parameters for all the dirfile_madd_<field_type>


New in version 0.4.2:

  Library Changes

  * BUG FIX: The default protection level of format file fragments is now
    properly set to "none".  Reported by Brendan Crill.

  * BUG FIX: getdata() now reports the correct number of samples read for slim
    and ASCII encoded files.  Reported by Adam Hincks.

  * BUG FIX: A segmentation fault only encountered when reading slim encoded
    data has been fixed in dirfile_flush().

  Legacy API Changes

  * Several fixes have been made to better re-create the legacy API:

      - the return value of GetFormat is no longer marked const (although
        it should be considered so).
      - a symbolic link getdata_struct.h -> getdata.h is created when the
        headers are installed, but only if the legacy API is present in the
      - when included with a C++ compiler, the legacy function prototypes
        are wrapped in an extern "C" block. (The new API functions are not.)


New in version 0.4.1:

  Library Changes

  * BUG FIX: Adding an ASCII encoded RAW field no longer creates an empty,
    unencoded binary file.

  * BUG FIX: A few minor memory leaks have been patched.  Most of these
    were the result of insufficient clean up in dirfile_close().

  * As an exception to the Standards, the full stop character '.' is once
    again permitted in field names.  This is required by BLAST.  Instead,
    field names are prohibited from ending with the known encoding extensions.
    The Standards still prohibit the full stop character in field names, and the
    GD_PEDANTIC flag will disable this exception.  Furthermore, fields may not
    be added via GetData which contain a full stop character.

  * Some minor speed improvements have been made to the format file parser
    resulting in a ~30% decrease in parsing time.


New in version 0.4.0:

  Dirfile Changes

  * GetData now supports Dirfile Standards Version 6.  Standards Version 6 adds
    numerical (CONST) and string (STRING) scalar fields to the dirfile, as well
    as other features outlined below.

  * CONST names can now appear as parameters in field specifications in certain
    places in lieu of a literal number.

  * The tokeniser has been re-written.  Any sequence of non-NUL bytes can now
    form a valid token.  Field codes may not have ASCII control characters
    or the "reserved characters" &, /, ;, <, >, |, . but may contain any other
    characters (including whitespace).

  * Subordinate fields may now be attached to fields.  These subfields are
    defined with the META directive, and referenced in most cases as

  * Binary files in dirfiles may now be "encoded".  In addition to raw
    (unencoded) files, two encodings are currently supported:

      - ASCII encoding (a simple proof-of-functionality encoding), and
      - Slimlib encoding (a compression library used by ACT).

    Encoding schemes are fragment-local, although they are inherited from parent

  * Endianness is now also fragment-local, meaning different endiannesses can
    co-exist in the same dirfile (so long as the fields are defined in different
    format file fragments), and GetData will do the Right Thing.

  * "FILEFRAM" is no-longer supported as an alias for "INDEX".  This affects
    GetData's implementation of all Standards Versions.  Code that made use of
    FILEFRAM will have to be updated to use INDEX instead.

  * The reference field, previously the first RAW field in the format file,
    may now be specified using the REFERENCE directive.  The reference field
    is the field that is looked at when get_nframes() is called.  This is
    important to programs like kst which support streaming dirfiles.

  * Portions (or all) of a dirfile's data and metadata can be protected from
    change by specifying the PROTECT directive.  This protection is "advisory",
    ie. while GetData will respect it in all cases, don't count on the PROTECT
    directive to ensure data integrity.

  Library Changes

  * INDEX is now a normal field.  It appears in the count/list functions.
    Attempts to write to INDEX will fail.

  * The GD_E_EMPTY error code has been removed: it is no longer an error to
    query a dirfile containing no RAW fields.

  * The presence of two fields in the dirfile with the same name is now
    detected, and will cause a syntax error when parsing the format file.
    Previously, such things were allowed, but only one of the synonym fields
    could ever be queried. (Which field was returned was arbitrary.)

  * Field code look-ups for input fields are now cached, which should result
    in slightly better performance from the library.

  API Changes

  * Fields may now be added to dirfiles in a number of different ways:

    - by passing an gd_entry_t to dirfile_add()
    - by passing a field specification line to dirfile_add_spec()
    - by passing field parameters to one of the dirfile_add_<foo>() functions.

  * Whole other format file fragments may also be added to the dirfile by
    calling dirfile_include().

  * A function is now present (dirfile_metaflush()) to flush metadata changes to
    disk (by re-writing format file fragments).  dirfile_flush() and
    dirfile_close() will also flush metadata, if needed.

  * STRING and CONST values can be retrieved/set by calling (get,put)_string()
    and (get,put)_constant().  (get,put)data() are only for vector type fields.

  * META fields can be queried/set like normal fields using the get/put
    functions and their full (slashed) field code.

  * In addition to get_nfields() and get_field_list(), there are now
    corresponding functions that provide lists/counts of vectors
    (get_vector_list()/get_nvectors()), particular field types
    (get_field_list_by_type()/get_nfields_by_type()), as well as functions
    that provide lists of string values (get_string_values()) and constant
    values (get_const_values()).

  * Analogous functions for the add, list, and counting functions exist for
    META fields, as well.

  * Extra flags have been added to dirfile_open() to permit indicating the
    encoding type, if not specified in the dirfile itself.

  * DIRFILE struct members and gd_entry_t private members are now completely
    hidden from the public interface.  Where previously callers could query
    dirfile->error to check for an error, they must now call get_error(dirfile).
    This change was made to reduce unintentional ABI breakage when modifying
    internal library properties.

  * GD_VERBOSE has been added to the list of available dirfile_open() flags.
    If this flag is specified, GetData will write errors to stderr as

  Legacy API Changes

  * Error codes which cannot be returned by the legacy API might not have a
    corresponding string in GD_ERROR_CODES[].  Instead, these entries will
    simply be the NULL pointer.

  * No facilities exist in the legacy API to set or query CONST or STRING
    fields.  However, META fields of vector type can be queried/set using
    GetData() and PutData(), as in the new API.


New in version 0.3.1:

  Legacy API Changes

  * BUG FIX: Dirfiles are now opened in read-only mode, unless instantiated via
    PutData(), allowing GetData() calls on read-only dirfiles.  If
    PutData() is called on a dirfile previously opened read-only, it will be
    re-opened in read-write mode.


  * The C++ bindings, formerly called libdirfile, are now called libgetdata++
    to be more explicit about what this library is.


  * The package now includes pkg-config support for libgetdata.


New in version 0.3.0:

  Dirfile Changes

  * GetData now supports Dirfile Standards Version 5 which includes support
    for signed 8-bit, and signed and unsigned 64-bit integer types.

  * As part of Standards Version 5, the restriction on field name length has
    been removed.  (The filesystem will impose an effective limit on RAW fields
    of a few hundred characters, and format file lines are limited to several
    thousand, limiting derived field names.)

  * The library can now convert between big and little endiannesses.  An
    optional directive, ENDIAN, added in Standards Version 5, is available to
    specify the byte-sex of a dirfile.

  API Changes

  * There is a new interface which fixes issues with thread safety and largefile
    support in the old interface.  The old interface (referred to as the "legacy
    API") is still supported, but doesn't fully implement Dirfile Standards
    Version 5.  See the README for full details.

  * putdata now respects FRAMEOFFSET.

  * putdata can now write to PHASE fields, and multi-bit BIT fields.

  * Some error codes have been renamed, and others removed or added, in order to
    regularise error codes between getdata and putdata in the sundry versions.
    Furthermore, the underlying values of some of these codes have changed
    (notably excluding GD_E_OK, which is guaranteed to be zero). Changes

      - GD_E_OPEN_FORMAT is now called GD_E_OPEN
      - GD_E_BAD_RETURN_TYPE is now called GD_E_BAD_TYPE
      - GD_E_NO_RAW_FIELDS is now called GD_E_EMPTY
      - PD_E_MULT_LINCOM is now called GD_E_BAD_PUT_FIELD
      - GD_E_OPEN_RAWFIELD and PD_E_OPEN RAWFIELD are now both represented by
      - PD_E_BAD_CODE is now handled by GD_E_BAD_CODE
        applicable and have been removed
        defined in the header but never used, have been removed
        are new

    This affects the legacy API.

  Legacy API Changes

  * The legacy API has been marked deprecated.

  * Error codes have changed per the description above.

  * Only the public members of FormatType are now initialised by GetFormat.


  * Added bindings for C++ (libdirfile), Fortran 77 (libfgetdata), and
    Fortran 95 (libf95getdata)


  * A rudimentary, but thorough, test-suite has been made.