1gd_move(3) GETDATA gd_move(3)
10
14 gd_move — move a Dirfile entry between format specification fragments
15
18 #include <getdata.h>
19 int gd_move(DIRFILE *dirfile, const char *field_code, int new_fragment,
21 unsigned int flags);
22
25 The gd_move() function transfers the field or alias specified by
26 field_code, which should not have a representation suffix, defined in
27 the dirfile specified by dirfile from it's current format specification
28 fragment to the fragment indexed by new_fragment. If the field is al‐
29 ready defined in the fragment index by new_fragment, this function does
30 nothing and returns no error.
31 If the new fragment has different affixes, the field will be renamed as
33 part of the move. See gd_rename(3) for details on field renaming. The
34 field is closed before moving, resulting in it's I/O pointer being re‐
35 set to the beginning-of-field.
36 The flags parameter should be zero or more of the following flags, bit‐
38 wise or'd together:
39 GD_REN_DANGLE
41 By default, if the move results in a change of name for the
42 field due to differing fragment affixes, ALIAS entries pointing
43 to this field will be updated with the field's new name. Spec‐
44 ifying this flag prohibits this behaviour, turning these alias‐
45 es into dangling aliases. If moving the field doesn't rename
46 it, this flag is ignored.
47 GD_REN_DATA
49 If field_code specifies a RAW field, the binary file associated
50 with the field will be translated to account for the possibly
51 different encoding, endianness, and frame offset of the new
52 format specification fragment. It will also be moved to a new
53 directory, if necessary.
54 If this flag is not specified, no changes will be made to the
56 binary file. If field_code specifies a field of type other
57 than RAW, this flag is ignored.
58 If the binary file is translated, and the frame offset of the
60 destination fragment is larger than that of the source frag‐
61 ment, this will result in permanent deletion of data from the
62 database. If the new frame offset is smaller than the old
63 frame offset, the binary file will be padded at the front with
64 zeroes.
65 GD_REN_FORCE
67 Skip updating entries which would be invalid (see gd_rename(3)
68 for details). By default, an invalid field causes the move to
69 fail. If moving the field doesn't rename it, this flag is ig‐
70 nored.
71 GD_REN_UPDB
73 If moving the field renames it, update entries which use this
74 field as an input to account for the new name (see
75 gd_rename(3)). If moving the field doesn't rename it, this
76 flag is ignored.
77
80 On success, gd_move() returns zero. On error, a negative-valued error
81 code is returned. Possible error codes are:
82 GD_E_ACCMODE
84 The specified dirfile was opened read-only.
85 GD_E_ALLOC
87 The library was unable to allocate memory.
88 GD_E_BAD_CODE
90 The field specified by field_code was not found, or else the
91 move resulted in the field being renamed and the resultant
92 metadata update tried to change a field code into something
93 prohibited by a fragment's affixes.
94 GD_E_BAD_DIRFILE
96 The supplied dirfile was invalid.
97 GD_E_BAD_FIELD_TYPE
99 An attempt was made to move the immutable INDEX field.
100 GD_E_BAD_INDEX
102 The new_fragment argument did not index a valid format specifi‐
103 cation fragment.
104 GD_E_IO An I/O error occurred while attempting to translate a binary
106 file.
107 GD_E_PROTECTED
109 The metadata of the source or destination format specification
110 fragments was protected from change, or the binary data of the
111 source or destination fragments was protected from change and
112 binary file translation was requested.
113 GD_E_UNKNOWN_ENCODING
115 The encoding scheme of the source or destination fragment is
116 unknown.
117 GD_E_UNSUPPORTED
119 The encoding scheme of the source or destination fragment does
120 not support binary file translation.
121 The error code is also stored in the DIRFILE object and may be re‐
123 trieved after this function returns by calling gd_error(3). A descrip‐
124 tive error string for the error may be obtained by calling
125 gd_error_string(3).
126
129 A binary file translation occurs out-of-place. As a result, sufficient
130 space must be present on the filesystem for both the binary file before
131 translation and the binary file after translation.
132
135 The dirfile_move() function appeared in GetData-0.5.0. It had no flags
136 parameter. In place of flags was int move_data. Passing a non-zero
137 value for this parameter had the same effect as the GD_REN_DATA flag
138 does now.
139 In GetData-0.7.0, this function was renamed to gd_move().
141 In all GetData-0.8.x releases, passing an alias name to this function
143 would move the target of the alias. To move an alias itself, a sepa‐
144 rate function, gd_move_alias() was available.
145 In GetData-0.9.0, gd_move_alias() was removed. Also in this release,
147 the move_data parameter was repaced with the flags parameter.
148 In GetData-0.10.0, the error return from this function changed from -1
150 to a negative-valued error code.
151
154 gd_metaflush(3), gd_open(3), gd_error(3), gd_error_string(3),
155 dirfile(5), dirfile-format(5)
156Version 0.10.0 25 December 2016 gd_move(3)