.\" 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_alter_spec.3. The gd_alter_spec man page. .\" .\" Copyright (C) 2008, 2010, 2011, 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_alter_spec 3 "25 December 2016" "Version 0.10.0" "GETDATA" .SH NAME gd_alter_spec, gd_malter_spec \(em modify a field in a Dirfile .SH SYNOPSIS .SC .B #include .HP .BI "int gd_alter_spec(DIRFILE *" dirfile ", const char *" line , .BI "int " recode ); .HP .BI "int gd_malter_spec(DIRFILE *" dirfile ", const char *" line , .BI "const char *" parent ", int " recode ); .EC .SH DESCRIPTION The .FN gd_alter_spec function modifies the field described by the field specification line in .ARG line to the dirfile specified by .ARG dirfile . The .FN gd_malter_spec function behaves similarly, but modifies the metafield under the field indicated by the field code .ARG parent . Field specification lines are described in detail in dirfile-format(5). The name of the field to be modified, which must already exist, will be obtained from the field specification line. When adding a metafield, .ARG line should only contain a field specification, and not a .B /META directive. If the modified field is of type .B RAW and the .ARG recode argument is non-zero, the binary file associated with the field will be converted for changes in data type and samples-per-frame. In this case, the field's I/O pointer will be reset to the beginning-of-frame. If .ARG recode is zero, no binary file conversion will take place. If the modified field is of type .B LINTERP and the .ARG recode argument is non-zero, the look-up table file will be moved if .ARG line specifies a different path, overwriting an existing file with the new pathname, if present. If the field specified by .ARG field_code is of type other than .B RAW or .BR LINTERP , the .ARG recode argument is ignored. 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_alter_spec and .FN gd_malter_spec return zero. On error, it returns a negative-valued error code. 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 specified in .ARG line was not found, or the .ARG parent field code was not found. .DD GD_E_BAD_DIRFILE The supplied dirfile was invalid. .DD GD_E_FORMAT A syntax error was encountered in .ARG line . .DD GD_E_IO An I/O error occurred while translating the binary file associated with a modified .B RAW field, or an I/O error occurred while attempting to rename a .B LINTERP table file. .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, a request to translate the binary file associated with a .B RAW field was attempted, but 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 translate the binary file be associated with a modified .B RAW field. .DD GD_E_UNSUPPORTED The encoding scheme of the indicated format specification fragment does not support translating the empty binary file associated with a modified .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_alter_spec and .FN dirfile_malter_spec appeared in GetData-0.5.0. In GetData-0.7.0, these functions were renamed to .FN gd_alter_spec and .FN gd_malter_spec. In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code. .SH SEE ALSO Any of the .BR gd_alter_ functions (e.g., .F3 gd_alter_bit ), .F3 gd_alter_spec , .F3 gd_error , .F3 gd_error_string , .F3 gd_metaflush , .F3 gd_open , dirfile-format(5)