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

NAME

14       gd_add_spec, gd_madd_spec — add a field to a Dirfile
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_add_spec(DIRFILE *dirfile, const char *line, int
21              fragment_index);
22
23       int gd_madd_spec(DIRFILE *dirfile, const char *line, const char
24              *parent);
25
26

DESCRIPTION

28       The gd_add_spec() function adds the field described by the field speci‐
29       fication line in  line  to  the  dirfile  specified  by  dirfile.   The
30       gd_madd_spec()  function  behaves  similarly,  but  adds the field as a
31       metafield under the field indicated by the field parent.  Field  speci‐
32       fication  lines  are  described  in detail in dirfile-format(5).  Since
33       Standards Version 7 (see dirfile(5)) permits specifying metafield with‐
34       out  the  use of the /META directive, gd_add_spec() may also be used to
35       add metafields, by specifying the metafield's  full  field  code.   See
36       dirfile-format(5) for full details.
37
38       When  using gd_madd_spec(), line should only contain a field specifica‐
39       tion, and not a /META directive.
40
41       Passing these functions a directive line instead of a field  specifica‐
42       tion  line  will  result in a syntax error.  These functions never call
43       the registered parser callback function, even if line contains a syntax
44       error.
45
46

RETURN VALUE

48       On success, gd_add_spec() and gd_madd_spec() return zero.   On error, a
49       negative-valued error code is returned.  Possible error codes are:
50
51       GD_E_ACCMODE
52               The specified dirfile was opened read-only.
53
54       GD_E_ALLOC
55               The library was unable to allocate memory.
56
57       GD_E_BAD_CODE
58               The  parent  field  code  was  not  found,  or  was  already  a
59               metafield.
60
61       GD_E_BAD_DIRFILE
62               The supplied dirfile was invalid.
63
64       GD_E_BAD_INDEX
65               The fragment_index argument was out of range.
66
67       GD_E_FORMAT
68               A syntax error was encountered in line.
69
70       GD_E_IO An I/O error occurred while creating an empty binary file to be
71               associated with a newly added RAW field.
72
73       GD_E_LINE_TOO_LONG
74               The supplied line was longer than the parser was able  to  deal
75               with.  Line lengths are limited by the storage size of size_t.
76
77       GD_E_PROTECTED
78               The  metadata  of  the fragment was protected from change.  Or,
79               the creation of a RAW field was attempted and the data  of  the
80               fragment was protected.
81
82       GD_E_UNKNOWN_ENCODING
83               The encoding scheme of the indicated format specification frag‐
84               ment is not known to the library.  As a result, the library was
85               unable  to  create an empty binary file to be associated with a
86               newly added RAW field.
87
88       GD_E_UNSUPPORTED
89               The encoding scheme of the indicated format specification frag‐
90               ment does not support creating an empty binary file to be asso‐
91               ciated with a newly added RAW field.
92
93       The error code is also stored in the DIRFILE  object  and  may  be  re‐
94       trieved after this function returns by calling gd_error(3).  A descrip‐
95       tive  error  string  for  the  error  may  be   obtained   by   calling
96       gd_error_string(3).
97
98

HISTORY

100       The  functions  dirfile_add_spec()  and dirfile_madd_spec() appeared in
101       GetData-0.4.0.
102
103       In GetData-0.7.0, these functions were  renamed  to  gd_add_spec()  and
104       gd_madd_spec().
105
106       In  GetData-0.10.0,  the error return from these functions changed from
107       -1 to a negative-valued error code.
108
109

SEE ALSO

111       gd_add(3), all the gd_add_<entry-type> functions (e.g., gd_add_bit(3)),
112       gd_error(3),  gd_error_string(3),  gd_madd(3),  all the gd_madd_<entry-
113       type> functions (e.g.,  gd_madd_bit(3)),  gd_metaflush(3),  gd_open(3),
114       dirfile-format(5)
115
116
117
118Version 0.10.0                 25 December 2016                 gd_add_spec(3)
Impressum