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

NAME

14       gd_alter_spec, gd_malter_spec — modify a field in a Dirfile
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_alter_spec(DIRFILE *dirfile, const char *line, int recode);
21
22       int gd_malter_spec(DIRFILE *dirfile, const char *line, const char
23              *parent, int recode);
24
25

DESCRIPTION

27       The gd_alter_spec() function modifies the field described by the  field
28       specification  line  in  line to the dirfile specified by dirfile.  The
29       gd_malter_spec() function behaves similarly, but modifies the metafield
30       under  the  field indicated by the field code parent.  Field specifica‐
31       tion lines are described in detail in dirfile-format(5).
32
33       The name of the field to be modified, which must already exist, will be
34       obtained  from  the field specification line.  When adding a metafield,
35       line should only contain a field specification, and not a /META  direc‐
36       tive.
37
38       If the modified field is of type RAW and the recode argument is non-ze‐
39       ro, the binary file associated with the field  will  be  converted  for
40       changes  in data type and samples-per-frame.  In this case, the field's
41       I/O pointer will be reset to the beginning-of-frame.  If recode is  ze‐
42       ro, no binary file conversion will take place.
43
44       If  the  modified  field  is of type LINTERP and the recode argument is
45       non-zero, the look-up table file will be moved if line specifies a dif‐
46       ferent  path,  overwriting  an  existing file with the new pathname, if
47       present.  If the field specified by field_code is of  type  other  than
48       RAW or LINTERP, the recode argument is ignored.
49
50       Passing  these functions a directive line instead of a field specifica‐
51       tion line will result in a syntax error.  These  functions  never  call
52       the registered parser callback function, even if line contains a syntax
53       error.
54
55

RETURN VALUE

57       On success, gd_alter_spec() and gd_malter_spec() return zero.   On  er‐
58       ror,  it  returns  a  negative-valued error code.  Possible error codes
59       are:
60
61       GD_E_ACCMODE
62               The specified dirfile was opened read-only.
63
64       GD_E_ALLOC
65               The library was unable to allocate memory.
66
67       GD_E_BAD_CODE
68               The field specified in line was not found, or the parent  field
69               code was not found.
70
71       GD_E_BAD_DIRFILE
72               The supplied dirfile was invalid.
73
74       GD_E_FORMAT
75               A syntax error was encountered in line.
76
77       GD_E_IO An I/O error occurred while translating the binary file associ‐
78               ated with a modified RAW field, or an I/O error occurred  while
79               attempting to rename a LINTERP table file.
80
81       GD_E_LINE_TOO_LONG
82               The  supplied  line was longer than the parser was able to deal
83               with.  Line lengths are limited by the storage size of size_t.
84
85       GD_E_PROTECTED
86               The metadata of the fragment was protected from change.  Or,  a
87               request  to  translate  the  binary  file associated with a RAW
88               field was attempted, but the data of the fragment was  protect‐
89               ed.
90
91       GD_E_UNKNOWN_ENCODING
92               The encoding scheme of the indicated format specification frag‐
93               ment is not known to the library.  As a result, the library was
94               unable  to translate the binary file be associated with a modi‐
95               fied RAW field.
96
97       GD_E_UNSUPPORTED
98               The encoding scheme of the indicated format specification frag‐
99               ment does not support translating the empty binary file associ‐
100               ated with a modified RAW field.
101
102       The error code is also stored in the DIRFILE  object  and  may  be  re‐
103       trieved after this function returns by calling gd_error(3).  A descrip‐
104       tive  error  string  for  the  error  may  be   obtained   by   calling
105       gd_error_string(3).
106
107

HISTORY

109       The  functions  dirfile_alter_spec() and dirfile_malter_spec() appeared
110       in GetData-0.5.0.
111
112       In GetData-0.7.0, these functions were renamed to  gd_alter_spec()  and
113       gd_malter_spec.()
114
115       In  GetData-0.10.0,  the error return from these functions changed from
116       -1 to a negative-valued error code.
117
118

SEE ALSO

120       Any of the  gd_alter_<entry-type>  functions  (e.g.,  gd_alter_bit(3)),
121       gd_alter_spec(3),   gd_error(3),  gd_error_string(3),  gd_metaflush(3),
122       gd_open(3), dirfile-format(5)
123
124
125
126Version 0.10.0                 25 December 2016               gd_alter_spec(3)
Impressum