1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
.\" 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_reference.3. The gd_reference man page.
.\"
.\" Copyright (C) 2008, 2010, 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_reference 3 "25 December 2016" "Version 0.10.0" "GETDATA"
.SH NAME
gd_reference \(em retrieve or set the reference field for a Dirfile
.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "const char *gd_reference(DIRFILE *" dirfile ", const char"
.BI * field_code );
.EC
.SH DESCRIPTION
The
.FN gd_reference
function sets or retrieves the reference field (see
dirfile(5))
associated with the dirfile specified by
.IR dirfile .
If the
.I field_code
argument is non-NULL, the reference field for the dirfile will be set to the
field specified. If
.I field_code
is NULL, the reference field is not modified. The field code should refer to
a RAW field, and may not contain a representation suffix.
.SH RETURN VALUE
On success,
.FN gd_reference
returns the field code of the dirfile's reference field, which will be
.IR field_code ,
if
.I field_code
is non-NULL. If no
.B RAW
fields are defined in the dirfile, this function will return NULL, without
raising an error. On error, NULL is returned and the dirfile error is set to a
non-zero error value. Possible error values 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 by
.I field_code
was not found.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_FIELD_TYPE
The field specified by
.I field_code
was not a
.B RAW
field.
.DD GD_E_PROTECTED
The metadata of the primary format specification fragment (the file named
.I format
in the root dirfile directory) was protected from change.
.PP
The dirfile error may be retrieved by calling
.F3 gd_error .
A descriptive error string for the last error encountered can be obtained from
a call to
.F3 gd_error_string .
.SH HISTORY
The
.FN get_reference
function appeared in GetData-0.4.2. It took only one parameter (the
.BR DIRFILE ),
and returned the current reference field.
The
.FN dirfile_reference
function appeared in GetData-0.5.0.
In GetData-0.7.0, the
.FN dirfile_reference
function was renamed to
.FN gd_reference
and the
.FN get_reference
function was removed.
.SH SEE ALSO
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_metaflush ,
.F3 gd_open ,
dirfile(5),
dirfile-format(5)
|
