1dirfile_alter_entry(3) GETDATA dirfile_alter_entry(3)
2
6 dirfile_alter_entry — modify the metadata of a dirfile field
7
9 #include <getdata.h>
10 int dirfile_alter_entry(DIRFILE *dirfile, const char *field_code, const
12 gd_entry_t *entry, int recode);
13
15 The dirfile_alter_entry() function modifies the field specified by
16 field_code in the dirfile specified by dirfile to correspond to the new
17 parameters specified by entry. In addition to specifying a regular
18 field, field_code may also refer to a metafield by specifying it using
19 its full (slashed) field code. However, field_code should never con‐
20 tain a represenation suffix.
21 The form of entry is described in detail in the get_entry(3) man page.
23 The entry->field and entry->fragment_index members are ignored by this
24 function and need not be initialised. All other members appropriate to
25 the field type of field_code should be initialised, except as noted be‐
26 low. To change the fragment index of a field, use dirfile_move(3). To
27 change the name of a field, use dirfile_rename(3).
28 If field_code specifies a RAW field and the recode argument is non-ze‐
30 ro, the binary file associated with the field will be converted for
31 changes in data type and samples-per-frame. If recode is zero, no bi‐
32 nary file conversion will take place.
33 If field_code specifies a LINTERP field and the recode argument is non-
35 zero, the look-up table file will be moved if entry->table specifies a
36 different path. If a file with the new pathname already exists, it
37 will be overwritten. If the field specified by field_code is of type
38 other than RAW or LINTERP, the recode argument is ignored.
39 If field_code specified a LINCOM or POLYNOM field, the value of en‐
41 try->comp_scal indicates whether the purely real scalar lists (en‐
42 try->a, or entry->b and entry->m) or the complex valued lists (en‐
43 try->ca, or entry->cb and entry->cm) will be used. The unused counter‐
44 parts need not be initialised.
45 The entry->field_type member must correspond to the field type of
47 field_code. This interface cannot be used to change the type of a giv‐
48 en field. To do so, delete the old field first with dirfile_delete(3),
49 and then create a new field of the desired type with dirfile_add(3).
50 Some field parameters have special values which indicate no change
52 should be made to the parameter. Specifically, if any of the string
53 parameters, or the parameters (entry->a, entry->b, entry->m, en‐
54 try->ca, entry->cb, or entry->cm) are NULL, the old values will be re‐
55 tained. Similarly, if entry->spf, entry->n_fields, or entry->numbits
56 is zero, or if entry->bitnum is -1, or if entry->data_type, or en‐
57 try->const_type are equal to GD_NULL, these parameters will not be mod‐
58 ified.
59 All entry->scalar elements relevant for the given field type must be
61 initialised to one of the following values:
62 · a pointer to a field code indicating a new CONST field to be used
64 for the corresponding field parameter. If the parameter was previ‐
65 ously a literal number, it will be replaced by the specified field
66 code. If the paramter was previously a field code, the new field
67 code will replace the old one.
68 · a pointer the empty string (""). In this case, no change is made
70 to the field code for the corresponding field parameter: if one al‐
71 ready existed, it is kept, otherise the correponding literal numer‐
72 ical parameter is used. If the value of the corresponding numeri‐
73 cal entry member is the special value listed above indicating no
74 change, no change is made to the field parameter at all.
75 · the NULL pointer. If the corresponding field parameter was previ‐
77 ously a field code, the field code will be deleted and a literal
78 number used instead. In the special case when a scalar element is
79 NULL and the corresponding numerical entry member contains a spe‐
80 cial value indicating no change listed above, GetData will de-ref‐
81 erence the previous field code value and convert it into a literal
82 number before removing the field code from the entry.
83
86 On success, dirfile_alter_entry() returns zero. On error, -1 is re‐
87 turned and the dirfile error is set to a non-zero error value. Possi‐
88 ble error values are:
89 GD_E_ACCMODE
91 The specified dirfile was opened read-only.
92 GD_E_ALLOC
94 The library was unable to allocate memory.
95 GD_E_BAD_CODE
97 The field specified by field_code was not found. This error
98 may also result from attempting to dereference a scalar field
99 code which indicates a non-existant field.
100 GD_E_BAD_DIRFILE
102 The supplied dirfile was invalid.
103 GD_E_BAD_ENTRY
105 One or more of the parameters specified in entry was invalid.
106 GD_E_BAD_FIELD_TYPE
108 The entry->field_type parameter did not correspond to the type
109 of the field specified by field_code, or an attempt was made to
110 modify the immutable INDEX field. This error may also result
111 from attempting to dereference a scalar field code which does
112 not indicate a CONST field.
113 GD_E_BAD_TYPE
115 The entry->data_type parameter provided with a RAW entry, or
116 the entry->const_type parameter provided with a CONST entry,
117 was invalid.
118 GD_E_PROTECTED
120 The metadata of the fragment was protected from change. Or, a
121 request to translate the binary file associated with a RAW
122 field was attempted, but the data of the fragment was protect‐
123 ed.
124 GD_E_RAW_IO
126 An I/O error occurred while translating the binary file associ‐
127 ated with a modified RAW field, or an I/O error occurred while
128 attempting to rename a LINTERP table file.
129 GD_E_UNKNOWN_ENCODING
131 The encoding scheme of the specified format file fragment is
132 not known to the library. As a result, the library was unable
133 to translate the binary file be associated with a modified RAW
134 field.
135 GD_E_UNSUPPORTED
137 The encoding scheme of the specified format file fragment does
138 not support translating the empty binary file associated with a
139 modified RAW field.
140 The dirfile error may be retrieved by calling get_error(3). A descrip‐
142 tive error string for the last error encountered can be obtained from a
143 call to get_error_string(3).
144
146 dirfile_alter_bit(3), dirfile_alter_clincom(3), dirfile_alter_const(3),
147 dirfile_alter_cpolynom(3), dirfile_alter_lincom(3), dirfile_alter_lin‐
148 terp(3), dirfile_alter_multiply(3), dirfile_alter_phase(3), dirfile_al‐
149 ter_polynom(3), dirfile_alter_raw(3), dirfile_alter_spec(3),
150 dirfile_delete(3), dirfile_malter_spec(3), dirfile_metaflush(3),
151 dirfile_move(3), dirfile_open(3), dirfile_rename(3), get_error(3),
152 get_error_string(3), dirfile-format(5)
153Version 0.6.0 19 October 2009 dirfile_alter_entry(3)