gd_madd_spec(3) [debian man page]
gd_add_spec(3) GETDATA gd_add_spec(3) NAME
gd_add_spec, gd_madd_spec -- add a field to a dirfile SYNOPSIS
#include <getdata.h> int gd_add_spec(DIRFILE *dirfile, const char *line, int fragment_index); int gd_madd_spec(DIRFILE *dirfile, const char *line, const char *parent); DESCRIPTION
The gd_add_spec() function adds the field described by the field specification line in line to the dirfile specified by dirfile. The gd_madd_spec() function behaves similarly, but adds the field as a metafield under the field indicated by the field parent. Field specifi- cation lines are described in detail in dirfile-format(5). Since Standards Version 7 (see dirfile(5)) permits specifying metafield without the use of the /META directive, gd_add_spec() may also be used to add metafields, by specifying the metafield's full field code. See dirfile-format(5) for full details. When using gd_madd_spec(), line should only contain a field specification, and not a /META directive. Passing these functions a directive line instead of a field specification line will result in a syntax error. These functions never call the registered parser callback function, even if line contains a syntax error. RETURN VALUE
On success, gd_add_spec() and gd_madd_spec() return zero. On error, -1 is returned and the dirfile error is set to a non-zero error val- ue. Possible error values are: GD_E_ACCMODE The specified dirfile was opened read-only. GD_E_ALLOC The library was unable to allocate memory. GD_E_BAD_CODE The parent field code was not found, or was already a metafield. GD_E_BAD_DIRFILE The supplied dirfile was invalid. GD_E_BAD_INDEX The fragment_index argument was out of range. GD_E_FORMAT A syntax error was encountered in line. GD_E_LINE_TOO_LONG The supplied line was longer than the parser was able to deal with. Lines are limited by the storage size of ssize_t. On 32-bit systems, this limits line to 2**31 bytes. The limit is larger on 64-bit systems. GD_E_PROTECTED The metadata of the fragment was protected from change. Or, the creation of a RAW field was attempted and the data of the fragment was protected. GD_E_RAW_IO An I/O error occurred while creating an empty binary file to be associated with a newly added RAW field. GD_E_UNKNOWN_ENCODING The encoding scheme of the indicated format specification fragment is not known to the library. As a result, the library was un- able to create an empty binary file to be associated with a newly added RAW field. GD_E_UNSUPPORTED The encoding scheme of the indicated format specification fragment does not support creating an empty binary file to be associated with a newly added RAW field. The dirfile error may be retrieved by calling gd_error(3). A descriptive error string for the last error encountered can be obtained from a call to gd_error_string(3). SEE ALSO
gd_add(3), gd_add_bit(3), gd_add_carray(3), gd_add_const(3), gd_add_divide(3), gd_add_lincom(3), gd_add_linterp(3), gd_add_multiply(3), gd_add_phase(3), gd_add_recip(3), gd_add_raw(3), gd_error(3), gd_error_string(3), gd_madd(3), gd_madd_bit(3), gd_madd_carray(3), gd_madd_const(3), gd_madd_divide(3), gd_madd_lincom(3), gd_madd_linterp(3), gd_madd_multiply(3), gd_madd_phase(3), gd_madd_polynom(3), gd_madd_recip(3), gd_madd_string(3), gd_metaflush(3), gd_open(3), dirfile-format(5) Version 0.7.0 4 November 2010 gd_add_spec(3)
Check Out this Related Man Page
gd_add(3) GETDATA gd_add(3) NAME
gd_add, gd_madd -- add a field to a dirfile SYNOPSIS
#include <getdata.h> int gd_add(DIRFILE *dirfile, const gd_entry_t *entry); int gd_madd(DIRFILE *dirfile, const gd_entry_t *entry, const char *parent); DESCRIPTION
The gd_add() function adds the field described by entry to the dirfile specified by dirfile. The gd_madd() function behaves similarly, but adds the field as a metafield under the field indicated by the field code parent. The form of entry is described in detail on the gd_entry(3) man page. All relevant members of entry for the field type specified must be properly initialised. If entry specifies a CONST or CARRAY field, the field's data will be set to zero. If entry specifies a STRING field, the field data will be set to the empty string. When adding a metafield, the entry->field member should contain just the metafield's name, not the fully formed <parent-field>/<meta-field> field code. Also, gd_madd() ignores the value of entry->fragment_index, and instead adds the new meta field to the same format specifica- tion fragment in which the parent field is defined. Fields added with this interface may contain either literal parameters or parameters based on scalar fields. If an element of the en- try->scalar array defined for the specified field type is non-NULL, this element will be used as the scalar field code, and the correspond- ing numerical member will be ignored, and need not be initialised. Conversely, if numerical parameters are intended, the corresponding en- try->scalar elements should be set to NULL. If using an element of a CARRAY field, entry->scalar_ind should also be set. RETURN VALUE
On success, gd_add() and gd_madd() return zero. On error, -1 is returned and the dirfile error is set to a non-zero error value. Possi- ble error values are: GD_E_ACCMODE The specified dirfile was opened read-only. GD_E_ALLOC The library was unable to allocate memory. GD_E_BAD_CODE The field name provided in entry->field contained invalid characters. Alternately, the parent field code was not found, or was al- ready a metafield. GD_E_BAD_DIRFILE The supplied dirfile was invalid. GD_E_BAD_ENTRY There was an error in the specification of the field described by entry, or the caller attempted to add a field of type RAW as a metafield. GD_E_BAD_INDEX The entry->fragment_index parameter was out of range. GD_E_BAD_TYPE The entry->data_type parameter provided with a RAW entry, or the entry->const_type parameter provided with a CONST or CARRAY entry, was invalid. GD_E_BOUNDS The entry->array_len parameter provided with a CARRAY entry was greater than GD_MAX_CARRAY_LENGTH. GD_E_DUPLICATE The field name provided in entry->field duplicated that of an already existing field. GD_E_INTERNAL_ERROR An internal error occurred in the library while trying to perform the task. This indicates a bug in the library. Please report the incident to the GetData developers. GD_E_PROTECTED The metadata of the fragment was protected from change. Or, the creation of a RAW field was attempted and the data of the fragment was protected. GD_E_RAW_IO An I/O error occurred while creating an empty binary file to be associated with a newly added RAW field. GD_E_UNKNOWN_ENCODING The encoding scheme of the indicated format specification fragment is not known to the library. As a result, the library was un- able to create an empty binary file to be associated with a newly added RAW field. GD_E_UNSUPPORTED The encoding scheme of the indicated format specification fragment does not support creating an empty binary file to be associated with a newly added RAW field. The dirfile error may be retrieved by calling gd_error(3). A descriptive error string for the last error encountered can be obtained from a call to gd_error_string(3). NOTES
GetData artifically limits the number of elements in a CARRAY to the value of the symbol GD_MAX_CARRAY_LENGTH defined in getdata.h. This is done to be certain that the CARRAY won't overrun the line when flushed to disk. On a 32-bit system, this number is 2**24. It is larger on a 64-bit system. SEE ALSO
gd_add_bit(3), gd_add_carray(3), gd_add_const(3), gd_add_divide(3), gd_add_lincom(3), gd_add_linterp(3), gd_add_multiply(3), gd_add_phase(3), gd_add_polynom(3), gd_add_raw(3), gd_add_recip(3), gd_add_sbit(3), gd_add_spec(3), gd_add_string(3), gd_entry(3), gd_er- ror(3), gd_error_string(3), gd_madd_bit(3), gd_madd_carray(3), gd_madd_const(3), gd_madd_divide(3), gd_madd_lincom(3), gd_madd_linterp(3), gd_madd_multiply(3), gd_madd_phase(3), gd_madd_polynom(3), gd_madd_recip(3), gd_madd_sbit(3), gd_madd_spec(3), gd_madd_string(3), gd_metaflush(3), gd_open(3), dirfile-format(5) Version 0.7.1 30 November 2010 gd_add(3)