1gd_add(3) GETDATA gd_add(3)
10
14 gd_add, gd_madd — add a field to a Dirfile
15
18 #include <getdata.h>
19 int gd_add(DIRFILE *dirfile, const gd_entry_t *entry);
21 int gd_madd(DIRFILE *dirfile, const gd_entry_t *entry, const char
23 *parent);
24
27 The gd_add() function adds the field described by entry to the dirfile
28 specified by dirfile. The gd_madd() function behaves similarly, but
29 adds the field as a metafield under the field indicated by the field
30 code parent.
31 The form of entry is described in detail on the gd_entry(3) man page.
33 All relevant members of entry for the field type specified must be
34 properly initialised. If entry specifies a CONST or CARRAY field, the
35 field's data will be set to zero. If entry specifies a STRING field,
36 the field data will be set to the empty string.
37 The only flags in the entry->flags member which are honoured are
39 GD_EN_HIDDEN, which should be set or cleared to set the hiddenness of
40 the entry (see gd_hidden(3)), and GD_EN_COMPSCAL, which indicates
41 whether scalar parameters are initialised from the complex valued or
42 purely real member, which both are present (LINCOM, POLYNOM, RECIP).
43 A metafield may be added either by calling gd_madd() with entry->field
45 containing only the metafield's name, or else by calling gd_add() with
46 the fully formed "<parent-field>/<meta-field>" field code in entry->
47 field. Regardless of which interface is used, when adding a metafield
48 the value of entry->fragment_index is ignored and GetData will add the
49 new metafield to the same format specification fragment in which the
50 parent field is defined. If the specified parent field name is an
51 alias, the canonical name of the field will be substituted.
52 Fields added with this interface may contain either literal parameters
54 or parameters based on scalar fields. If an element of the entry->
55 scalar array defined for the specified field type is non-NULL, this el‐
56 ement will be used as the scalar field code, and the corresponding nu‐
57 merical member will be ignored, and need not be initialised. Converse‐
58 ly, if numerical parameters are intended, the corresponding entry->
59 scalar elements should be set to NULL. If using an element of a CARRAY
60 field, entry->scalar_ind should also be set.
61
64 On success, gd_add() and gd_madd() return zero. On error, a negative-
65 valued error code is returned. Possible error codes are:
66 GD_E_ACCMODE
68 The specified dirfile was opened read-only.
69 GD_E_ALLOC
71 The library was unable to allocate memory.
72 GD_E_BAD_CODE
74 The field name provided in entry->field contained invalid char‐
75 acters; or it or an input field did not contain the affected
76 fragment's prefix or suffix. Alternately, the parent field code
77 was not found, or was already a metafield.
78 GD_E_BAD_DIRFILE
80 The supplied dirfile was invalid.
81 GD_E_BAD_ENTRY
83 There was an error in the specification of the field described
84 by entry, or the caller attempted to add a field of type RAW as
85 a metafield.
86 GD_E_BAD_INDEX
88 The entry->fragment_index parameter was out of range.
89 GD_E_BAD_TYPE
91 The entry->data_type parameter provided with a RAW entry, or
92 the entry->const_type parameter provided with a CONST or CARRAY
93 entry, was invalid.
94 GD_E_DUPLICATE
96 The field name provided in entry->field duplicated that of an
97 already existing field.
98 GD_E_INTERNAL_ERROR
100 An internal error occurred in the library while trying to per‐
101 form the task. This indicates a bug in the library. Please
102 report the incident to the GetData developers.
103 GD_E_IO An I/O error occurred while creating an empty binary file to be
105 associated with a newly added RAW field.
106 GD_E_PROTECTED
108 The metadata of the fragment was protected from change. Or,
109 the creation of a RAW field was attempted and the data of the
110 fragment was protected.
111 GD_E_UNKNOWN_ENCODING
113 The encoding scheme of the indicated format specification frag‐
114 ment is not known to the library. As a result, the library was
115 unable to create an empty binary file to be associated with a
116 newly added RAW field.
117 GD_E_UNSUPPORTED
119 The encoding scheme of the indicated format specification frag‐
120 ment does not support creating an empty binary file to be asso‐
121 ciated with a newly added RAW field.
122 The error code is also stored in the DIRFILE object and may be re‐
124 trieved after this function returns by calling gd_error(3). A descrip‐
125 tive error string for the error may be obtained by calling
126 gd_error_string(3).
127
130 The functions dirfile_add() and dirfile_madd() appeared in GetDa‐
131 ta-0.4.0.
132 In GetData-0.7.0, the functions were renamed to gd_add() and gd_madd().
134 In GetData-0.8.0, gd_add() first allowed adding metafields by providing
136 the full (slashed) field name. This was the first version supporting
137 fragment affixes, and in this version, gd_add() would apply the desti‐
138 nation fragment's affixes to the supplied entry->field name. In GetDa‐
139 ta-0.8.1, this changed: gd_add() now assumes entry->field contains the
140 full field name, including any necessary affixes.
141 In GetData-0.10.0, the error return from these functions changed from
143 -1 to a negative-valued error code.
144 See gd_entry(3) for the history of the gd_entry_t structure.
146
149 gd_add_bit(3), gd_add_carray(3), gd_add_const(3), gd_add_divide(3),
150 gd_add_lincom(3), gd_add_linterp(3), gd_add_multiply(3),
151 gd_add_phase(3), gd_add_polynom(3), gd_add_raw(3), gd_add_recip(3),
152 gd_add_sbit(3), gd_add_spec(3), gd_add_string(3), gd_entry(3),
153 gd_error(3), gd_error_string(3), gd_madd_bit(3), gd_madd_carray(3),
154 gd_madd_const(3), gd_madd_divide(3), gd_madd_lincom(3),
155 gd_madd_linterp(3), gd_madd_multiply(3), gd_madd_phase(3),
156 gd_madd_polynom(3), gd_madd_recip(3), gd_madd_sbit(3), gd_madd_spec(3),
157 gd_madd_string(3), gd_metaflush(3), gd_open(3), dirfile-format(5)
158Version 0.10.0 25 December 2016 gd_add(3)