.\" 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_spec.3. The gd_add_spec man page. .\" .\" Copyright (C) 2008, 2009, 2010, 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_spec 3 "25 December 2016" "Version 0.10.0" "GETDATA" .SH NAME gd_add_spec, gd_madd_spec \(em add a field to a Dirfile .SH SYNOPSIS .SC .B #include .HP .BI "int gd_add_spec(DIRFILE *" dirfile ", const char *" line , .BI "int " fragment_index ); .HP .BI "int gd_madd_spec(DIRFILE *" dirfile ", const char *" line , .BI "const char *" parent ); .EC .SH DESCRIPTION The .FN gd_add_spec function adds the field described by the field specification line in .ARG line to the dirfile specified by .ARG dirfile . The .FN gd_madd_spec function behaves similarly, but adds the field as a metafield under the field indicated by the field .ARG parent . Field specification lines are described in detail in dirfile-format(5). Since Standards Version 7 (see dirfile(5)) permits specifying metafield without the use of the .B /META directive, .FN 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 .FN gd_madd_spec , .ARG line should only contain a field specification, and not a .B /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 .ARG line contains a syntax error. .SH RETURN VALUE On success, .FN gd_add_spec and .FN gd_madd_spec 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 .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_INDEX The .ARG fragment_index argument was out of range. .DD GD_E_FORMAT A syntax error was encountered in .ARG line . .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_LINE_TOO_LONG The supplied .ARG line was longer than the parser was able to deal with. Line lengths are limited by the storage size of .BR size_t . .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_spec and .FN dirfile_madd_spec appeared in GetData-0.4.0. In GetData-0.7.0, these functions were renamed to .FN gd_add_spec and .FN gd_madd_spec . In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. .SH SEE ALSO .F3 gd_add , all the .BR gd_add_ functions (e.g., .F3 gd_add_bit ), .F3 gd_error , .F3 gd_error_string , .F3 gd_madd , all the .BR gd_madd_ functions (e.g., .F3 gd_madd_bit ), .F3 gd_metaflush , .F3 gd_open , dirfile-format(5)