NAME

       gd_move — move a Dirfile entry between format specification fragments

SYNOPSIS

       #include <getdata.h>

       int gd_move(DIRFILE *dirfile, const char *field_code, int new_fragment, unsigned int flags);

DESCRIPTION

       The gd_move() function transfers the field or alias specified by field_code, which should not have a rep‐
       resentation  suffix,  defined  in the dirfile specified by dirfile from it's current format specification
       fragment to the fragment indexed by new_fragment.  If the field is already defined in the fragment  index
       by new_fragment, this function does nothing and returns no error.

       If  the  new  fragment  has  different  affixes,  the  field  will  be  renamed as part of the move.  See
       gd_rename(3) for details on field renaming.  The field is closed before moving,  resulting  in  it's  I/O
       pointer being reset to the beginning-of-field.

       The flags parameter should be zero or more of the following flags, bitwise or'd together:

       GD_REN_DANGLE
               By  default,  if the move results in a change of name for the field due to differing fragment af‐
               fixes, ALIAS entries pointing to this field will be updated with the field's new name.   Specify‐
               ing  this  flag prohibits this behaviour, turning these aliases into dangling aliases.  If moving
               the field doesn't rename it, this flag is ignored.

       GD_REN_DATA
               If field_code specifies a RAW field, the binary file associated with the field will be translated
               to account for the possibly different encoding, endianness, and frame offset of  the  new  format
               specification fragment.  It will also be moved to a new directory, if necessary.

               If  this flag is not specified, no changes will be made to the binary file.  If field_code speci‐
               fies a field of type other than RAW, this flag is ignored.

               If the binary file is translated, and the frame offset of the destination fragment is larger than
               that of the source fragment, this will result in permanent deletion of data  from  the  database.
               If  the  new frame offset is smaller than the old frame offset, the binary file will be padded at
               the front with zeroes.

       GD_REN_FORCE
               Skip updating entries which would be invalid (see gd_rename(3) for details).  By default, an  in‐
               valid  field  causes  the  move to fail.  If moving the field doesn't rename it, this flag is ig‐
               nored.

       GD_REN_UPDB
               If moving the field renames it, update entries which use this field as an input  to  account  for
               the new name (see gd_rename(3)).  If moving the field doesn't rename it, this flag is ignored.

RETURN VALUE

       On success, gd_move() returns zero.   On error, a negative-valued error code is returned.  Possible error
       codes are:

       GD_E_ACCMODE
               The specified dirfile was opened read-only.

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The field specified by field_code was not found, or else the move resulted in the field being re‐
               named and the resultant metadata update tried to change a field code into something prohibited by
               a fragment's affixes.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_FIELD_TYPE
               An attempt was made to move the immutable INDEX field.

       GD_E_BAD_INDEX
               The new_fragment argument did not index a valid format specification fragment.

       GD_E_IO An I/O error occurred while attempting to translate a binary file.

       GD_E_PROTECTED
               The  metadata  of  the  source  or  destination format specification fragments was protected from
               change, or the binary data of the source or destination fragments was protected from  change  and
               binary file translation was requested.

       GD_E_UNKNOWN_ENCODING
               The encoding scheme of the source or destination fragment is unknown.

       GD_E_UNSUPPORTED
               The  encoding  scheme of the source or destination fragment does not support binary file transla‐
               tion.

       The error code is also stored in the DIRFILE object and may be retrieved after this function  returns  by
       calling   gd_error(3).    A   descriptive  error  string  for  the  error  may  be  obtained  by  calling
       gd_error_string(3).

NOTES

       A binary file translation occurs out-of-place.  As a result, sufficient space  must  be  present  on  the
       filesystem for both the binary file before translation and the binary file after translation.

HISTORY

       The dirfile_move() function appeared in GetData-0.5.0.  It had no flags parameter.  In place of flags was
       int  move_data.   Passing a non-zero value for this parameter had the same effect as the GD_REN_DATA flag
       does now.

       In GetData-0.7.0, this function was renamed to gd_move().

       In all GetData-0.8.x releases, passing an alias name to this function would move the target of the alias.
       To move an alias itself, a separate function, gd_move_alias() was available.

       In GetData-0.9.0, gd_move_alias() was removed.  Also in this release, the move_data parameter was repaced
       with the flags parameter.

       In GetData-0.10.0, the error return from this function changed from -1 to a negative-valued error code.

SEE ALSO

       gd_metaflush(3), gd_open(3), gd_error(3), gd_error_string(3), dirfile(5), dirfile-format(5)

Version 0.10.0                                  25 December 2016                                      gd_move(3)