1
2
3
4
5
6
7
8
9gd_entry_list(3) GETDATA gd_entry_list(3)
10
11
12
14 gd_entry_list, gd_field_list, gd_field_list_by_type gd_mfield_list,
15 gd_mfield_list_by_type, gd_mvector_list, gd_vector_list — list field
16 entries in a Dirfile
17
18
20 #include <getdata.h>
21
22 const char **gd_entry_list(DIRFILE *dirfile, const char *parent, int
23 type, unsigned int flags);
24
25 const char **gd_field_list(DIRFILE *dirfile);
26
27 const char **gd_field_list_by_type(DIRFILE *dirfile, gd_entype_t type);
28
29 const char **gd_mfield_list(DIRFILE *dirfile, const char *parent);
30
31 const char **gd_mfield_list_by_type(DIRFILE *dirfile, const char
32 *parent, gd_entype_t type);
33
34 const char **gd_mvector_list(DIRFILE *dirfile, const char *parent);
35
36 const char **gd_vector_list(DIRFILE *dirfile);
37
38
40 The gd_entry_list() function queries a dirfile(5) database specified by
41 dirfile and finds all the fields satisfying the provided criteria. If
42 parent is non-NULL, metafields under the field specified by parent are
43 considered; otherwise, top-level fields are considered, and metafields
44 ignored.
45
46 The type argument should be one of the following symbols indicating an
47 explicit entry type to list:
48
49 GD_BIT_ENTRY, GD_CARRAY_ENTRY, GD_CONST_ENTRY, GD_DIVIDE_ENTRY,
50 GD_INDEX_ENTRY, GD_INDIR_ENTRY, GD_LINCOM_ENTRY,
51 GD_LINTERP_ENTRY, GD_MPLEX_ENTRY, GD_MULTIPLY_ENTRY,
52 GD_PHASE_ENTRY, GD_POLYNOM_ENTRY, GD_RAW_ENTRY, GD_RECIP_ENTRY,
53 GD_SARRAY_ENTRY, GD_SBIT_ENTRY, GD_SINDIR_ENTRY,
54 GD_STRING_ENTRY, GD_WINDOW_ENTRY.
55
56 (GD_INDEX_ENTRY is a special field type for the implicit INDEX field)
57 or else one of the following special symbols:
58
59 GD_ALL_ENTRIES
60 (=0) List entries of all types.
61
62 GD_ALIAS_ENTRIES
63 List only aliases. This is the only way to get a list includ‐
64 ing aliases which do not point to valid field codes.
65
66 GD_SCALAR_ENTRIES
67 List only scalar field types (CONST, CARRAY, SARRAY, STRING).
68
69 GD_VECTOR_ENTRIES
70 List only numeric-valued vector field types (all field types
71 except SINDIR and the scalar field types listed above).
72
73 The flags argument should be zero or more of the following flags, bit‐
74 wise or'd together:
75
76 GD_ENTRIES_HIDDEN
77 Include hidden entries (see gd_hidden(3)) in the list: normally
78 hidden entries are skipped;
79
80 GD_ENTRIES_NOALIAS
81 Exclude aliases from the list: normally aliases are considered
82 the same as their target (that is: if a field satisfies the
83 criteria, both its canonical name and all its aliases will ap‐
84 pear in the list).
85
86 The array returned will be de-allocated by a call to gd_close(3) and
87 should not be de-allocated by the caller. The list returned should not
88 be assumed to be in any particular order. The array is terminated by a
89 NULL pointer. The number of elements in the array, excluding the ter‐
90 minating NULL, can be obtained from an equivalent call to
91 gd_nentries(3).
92
93 The caller may not modify any strings in the array, or the array it‐
94 self. Doing so may cause database corruption. The pointer returned is
95 guaranteed to be valid at least until gd_entry_list() is called again
96 on the same DIRFILE object, or until the array is de-allocated by a
97 call to gd_close(3). (Although the data may have become obsolete, if
98 metadata have been modified in the interrim.)
99
100 This function has a subset of the functionality of the
101 gd_match_entries(3) function (q.v.).
102
103
104 Special Cases
105 The call
106 gd_field_list(dirfile);
107
108 is equivalent to
109 gd_entry_list(dirfile, NULL, GD_ALL_ENTRIES, 0);
110
111 The call
112 gd_field_list_by_type(dirfile, type);
113
114 is equivalent to
115 gd_entry_list(dirfile, NULL, type, 0);
116
117 The call
118 gd_mfield_list(dirfile, parent);
119
120 is equivalent to
121 gd_entry_list(dirfile, parent, GD_ALL_ENTRIES, 0);
122
123 The call
124 gd_mfield_list_by_type(dirfile, parent, type);
125
126 is equivalent to
127 gd_entry_list(dirfile, parent, type, 0);
128
129 The call
130 gd_mvector_list(dirfile, parent);
131
132 is equivalent to
133 gd_entry_list(dirfile, parent, GD_VECTOR_ENTRIES, 0);
134
135 The call
136 gd_vector_list(dirfile);
137
138 is equivalent to
139 gd_entry_list(dirfile, NULL, GD_VECTOR_ENTRIES, 0);
140
141
143 Upon successful completion, these functions returns a pointer to an ar‐
144 ray of strings containing the names of all the entries in the database
145 satisfying the supplied criteria. On error, they return zero and store
146 a negative-valued error code in the DIRFILE object which may be re‐
147 trieved by a subsequent call to gd_error(3). Possible error codes are:
148
149 GD_E_BAD_CODE
150 The supplied parent field code was not found, or referred to a
151 metafield itself.
152
153 GD_E_BAD_DIRFILE
154 The supplied dirfile was invalid.
155
156 GD_E_BAD_ENTRY
157 The type parameter supplied was not one of the symbols listed
158 above.
159
160 A descriptive error string for the error may be obtained by calling
161 gd_error_string(3).
162
163
165 The get_field_list() function appeared in GetData-0.3.0.
166
167 The get_field_list_by_type(), get_mfield_list(),
168 get_mfield_list_by_type(), get_mvector_list(), and get_vector_list()
169 functions appeared in GetData-0.4.0.
170
171 In GetData-0.7.0, these functions were renamed to gd_field_list(),
172 gd_field_list_by_type(), gd_mfield_list(), gd_mfield_list_by_type(),
173 gd_mvector_list(), and gd_vector_list().
174
175 The gd_entry_list() function appeared in GetData-0.8.0.
176
177
179 gd_error(3), gd_error_string(3), gd_hidden(3), gd_match_entries(3),
180 gd_nentries(3), gd_open(3), dirfile(5)
181
182
183
184Version 0.10.0 25 December 2016 gd_entry_list(3)