1
2
3
4
5
6
7
8
9gd_add(3)                           GETDATA                          gd_add(3)
10
11
12

NAME

14       gd_add, gd_madd — add a field to a Dirfile
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_add(DIRFILE *dirfile, const gd_entry_t *entry);
21
22       int gd_madd(DIRFILE *dirfile, const gd_entry_t *entry, const char
23              *parent);
24
25

DESCRIPTION

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
32       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
38       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
44       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
53       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
62

RETURN VALUE

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
67       GD_E_ACCMODE
68               The specified dirfile was opened read-only.
69
70       GD_E_ALLOC
71               The library was unable to allocate memory.
72
73       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
79       GD_E_BAD_DIRFILE
80               The supplied dirfile was invalid.
81
82       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
87       GD_E_BAD_INDEX
88               The entry->fragment_index parameter was out of range.
89
90       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
95       GD_E_DUPLICATE
96               The  field  name provided in entry->field duplicated that of an
97               already existing field.
98
99       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
104       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
107       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
112       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
118       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
123       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
128

HISTORY

130       The  functions  dirfile_add()  and  dirfile_madd()  appeared  in GetDa‐
131       ta-0.4.0.
132
133       In GetData-0.7.0, the functions were renamed to gd_add() and gd_madd().
134
135       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
142       In  GetData-0.10.0,  the error return from these functions changed from
143       -1 to a negative-valued error code.
144
145       See gd_entry(3) for the history of the gd_entry_t structure.
146
147

SEE ALSO

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)
158
159
160
161Version 0.10.0                 25 December 2016                      gd_add(3)
Impressum