.\" header.tmac. GetData manual macros. .\" .\" Copyright (C) 2016 D. V. Wiebe .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .\" .\" This file is part of the GetData project. .\" .\" Permission is granted to copy, distribute and/or modify this document .\" under the terms of the GNU Free Documentation License, Version 1.2 or .\" any later version published by the Free Software Foundation; with no .\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover .\" Texts. A copy of the license is included in the `COPYING.DOC' file .\" as part of this distribution. .\" Format a function name with optional trailer: func_name()trailer .de FN \" func_name [trailer] .nh .BR \\$1 ()\\$2 .hy .. .\" Format a reference to section 3 of the manual: name(3)trailer .de F3 \" func_name [trailer] .nh .BR \\$1 (3)\\$2 .hy .. .\" Format the header of a list of definitons .de DD \" name alt... .ie "\\$2"" \{ \ .TP 8 .PD .B \\$1 \} .el \{ \ .PP .B \\$1 .PD 0 .DD \\$2 \\$3 \} .. .\" Start a code block: Note: groff defines an undocumented .SC for .\" Bell Labs man legacy reasons. .de SC .fam C .na .nh .. .\" End a code block .de EC .hy .ad .fam .. .\" Format a structure pointer member: struct->member\fRtrailer .de SPM \" struct member trailer .nh .ie "\\$3"" .IB \\$1 ->\: \\$2 .el .IB \\$1 ->\: \\$2\fR\\$3 .hy .. .\" Format a function argument .de ARG \" name trailer .nh .ie "\\$2"" .I \\$1 .el .IR \\$1 \\$2 .hy .. .\" Hyphenation exceptions .hw sarray carray lincom linterp .\" gd_add.3in. The gd_add man page. .\" .\" Copyright (C) 2008, 2009, 2010, 2012, 2013, 2014, 2016 D. V. Wiebe .\" .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .\" .\" This file is part of the GetData project. .\" .\" Permission is granted to copy, distribute and/or modify this document .\" under the terms of the GNU Free Documentation License, Version 1.2 or .\" any later version published by the Free Software Foundation; with no .\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover .\" Texts. A copy of the license is included in the `COPYING.DOC' file .\" as part of this distribution. .\" .TH gd_add 3 "25 December 2016" "Version 0.10.0" "GETDATA" .SH NAME gd_add, gd_madd \(em add a field to a Dirfile .SH SYNOPSIS .SC .B #include .HP .BI "int gd_add(DIRFILE *" dirfile ", const gd_entry_t *" entry ); .HP .BI "int gd_madd(DIRFILE *" dirfile ", const gd_entry_t *" entry , .BI "const char *" parent ); .EC .SH DESCRIPTION The .FN gd_add function adds the field described by .ARG entry to the dirfile specified by .ARG dirfile . The .FN gd_madd function behaves similarly, but adds the field as a metafield under the field indicated by the field code .ARG parent . The form of .ARG entry is described in detail on the .F3 gd_entry man page. All relevant members of .ARG entry for the field type specified must be properly initialised. If .ARG entry specifies a .B CONST or .B CARRAY field, the field's data will be set to zero. If .ARG entry specifies a .B STRING field, the field data will be set to the empty string. The only flags in the .SPM entry flags member which are honoured are .BR GD_EN_HIDDEN , which should be set or cleared to set the hiddenness of the entry (see .F3 gd_hidden ), and .BR GD_EN_COMPSCAL , which indicates whether scalar parameters are initialised from the complex valued or purely real member, which both are present .RB ( LINCOM , .BR POLYNOM , .BR RECIP ). A metafield may be added either by calling .FN gd_madd with .SPM entry field containing only the metafield's name, or else by calling .FN gd_add with the fully formed .RI """" / """" field code in .SPM entry field . Regardless of which interface is used, when adding a metafield the value of .SPM entry fragment_index is ignored and GetData will add the new metafield to the same format specification fragment in which the parent field is defined. If the specified parent field name is an alias, the canonical name of the field will be substituted. Fields added with this interface may contain either literal parameters or parameters based on scalar fields. If an element of the .SPM entry scalar array defined for the specified field type is non-NULL, this element will be used as the scalar field code, and the corresponding numerical member will be ignored, and need not be initialised. Conversely, if numerical parameters are intended, the corresponding .SPM entry scalar elements should be set to NULL. If using an element of a .B CARRAY field, .SPM entry scalar_ind should also be set. .SH RETURN VALUE On success, .FN gd_add and .FN gd_madd return zero. On error, a negative-valued error code is returned. Possible error codes are: .DD GD_E_ACCMODE The specified dirfile was opened read-only. .DD GD_E_ALLOC The library was unable to allocate memory. .DD GD_E_BAD_CODE The field name provided in .SPM entry field contained invalid characters; or it or an input field did not contain the affected fragment's prefix or suffix. Alternately, the .ARG parent field code was not found, or was already a metafield. .DD GD_E_BAD_DIRFILE The supplied dirfile was invalid. .DD GD_E_BAD_ENTRY There was an error in the specification of the field described by .ARG entry , or the caller attempted to add a field of type .B RAW as a metafield. .DD GD_E_BAD_INDEX The .SPM entry fragment_index parameter was out of range. .DD GD_E_BAD_TYPE The .SPM entry data_type parameter provided with a .BR RAW entry, or the .SPM entry const_type parameter provided with a .B CONST or .B CARRAY entry, was invalid. .DD GD_E_DUPLICATE The field name provided in .SPM entry field duplicated that of an already existing field. .DD 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. .DD GD_E_IO An I/O error occurred while creating an empty binary file to be associated with a newly added .B RAW field. .DD GD_E_PROTECTED The metadata of the fragment was protected from change. Or, the creation of a .B RAW field was attempted and the data of the fragment was protected. .DD 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 unable to create an empty binary file to be associated with a newly added .B RAW field. .DD 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 .B RAW field. .PP The error code is also stored in the .B DIRFILE object and may be retrieved after this function returns by calling .F3 gd_error . A descriptive error string for the error may be obtained by calling .F3 gd_error_string . .SH HISTORY The functions .FN dirfile_add and .FN dirfile_madd appeared in GetData-0.4.0. In GetData-0.7.0, the functions were renamed to .FN gd_add and .FN gd_madd . In GetData-0.8.0, .FN gd_add first allowed adding metafields by providing the full (slashed) field name. This was the first version supporting fragment affixes, and in this version, .FN gd_add would apply the destination fragment's affixes to the supplied .SC .SPM entry field .EC name. In GetData-0.8.1, this changed: .FN gd_add now assumes .SC .SPM entry field .EC contains the full field name, including any necessary affixes. In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. See .F3 gd_entry for the history of the .B gd_entry_t structure. .SH SEE ALSO .F3 gd_add_bit , .F3 gd_add_carray , .F3 gd_add_const , .F3 gd_add_divide , .F3 gd_add_lincom , .F3 gd_add_linterp , .F3 gd_add_multiply , .F3 gd_add_phase , .F3 gd_add_polynom , .F3 gd_add_raw , .F3 gd_add_recip , .F3 gd_add_sbit , .F3 gd_add_spec , .F3 gd_add_string , .F3 gd_entry , .F3 gd_error , .F3 gd_error_string , .F3 gd_madd_bit , .F3 gd_madd_carray , .F3 gd_madd_const , .F3 gd_madd_divide , .F3 gd_madd_lincom , .F3 gd_madd_linterp , .F3 gd_madd_multiply , .F3 gd_madd_phase , .F3 gd_madd_polynom , .F3 gd_madd_recip , .F3 gd_madd_sbit , .F3 gd_madd_spec , .F3 gd_madd_string , .F3 gd_metaflush , .F3 gd_open , dirfile-format(5)