1gd_entry_list(3) GETDATA gd_entry_list(3)
10
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
20 #include <getdata.h>
21 const char **gd_entry_list(DIRFILE *dirfile, const char *parent, int
23 type, unsigned int flags);
24 const char **gd_field_list(DIRFILE *dirfile);
26 const char **gd_field_list_by_type(DIRFILE *dirfile, gd_entype_t type);
28 const char **gd_mfield_list(DIRFILE *dirfile, const char *parent);
30 const char **gd_mfield_list_by_type(DIRFILE *dirfile, const char
32 *parent, gd_entype_t type);
33 const char **gd_mvector_list(DIRFILE *dirfile, const char *parent);
35 const char **gd_vector_list(DIRFILE *dirfile);
37
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 The type argument should be one of the following symbols indicating an
47 explicit entry type to list:
48 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 (GD_INDEX_ENTRY is a special field type for the implicit INDEX field)
57 or else one of the following special symbols:
58 GD_ALL_ENTRIES
60 (=0) List entries of all types.
61 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 GD_SCALAR_ENTRIES
67 List only scalar field types (CONST, CARRAY, SARRAY, STRING).
68 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 The flags argument should be zero or more of the following flags, bit‐
74 wise or'd together:
75 GD_ENTRIES_HIDDEN
77 Include hidden entries (see gd_hidden(3)) in the list: normally
78 hidden entries are skipped;
79 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 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 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 This function has a subset of the functionality of the
101 gd_match_entries(3) function (q.v.).
102 Special Cases
105 The call
106 gd_field_list(dirfile);
107 is equivalent to
109 gd_entry_list(dirfile, NULL, GD_ALL_ENTRIES, 0);
110 The call
112 gd_field_list_by_type(dirfile, type);
113 is equivalent to
115 gd_entry_list(dirfile, NULL, type, 0);
116 The call
118 gd_mfield_list(dirfile, parent);
119 is equivalent to
121 gd_entry_list(dirfile, parent, GD_ALL_ENTRIES, 0);
122 The call
124 gd_mfield_list_by_type(dirfile, parent, type);
125 is equivalent to
127 gd_entry_list(dirfile, parent, type, 0);
128 The call
130 gd_mvector_list(dirfile, parent);
131 is equivalent to
133 gd_entry_list(dirfile, parent, GD_VECTOR_ENTRIES, 0);
134 The call
136 gd_vector_list(dirfile);
137 is equivalent to
139 gd_entry_list(dirfile, NULL, GD_VECTOR_ENTRIES, 0);
140
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. The array is terminated with a NULL
146 pointer. If there are no matching entries, an array containing only
147 the terminating NULL pointer is returned.
148 On error, these functions return NULL and store a negative-valued error
150 code in the DIRFILE object which may be retrieved by a subsequent call
151 to gd_error(3). Possible error codes are:
152 GD_E_BAD_CODE
154 The supplied parent field code was not found, or referred to a
155 metafield itself.
156 GD_E_BAD_DIRFILE
158 The supplied dirfile was invalid.
159 GD_E_BAD_ENTRY
161 The type parameter supplied was not one of the symbols listed
162 above.
163 A descriptive error string for the error may be obtained by calling
165 gd_error_string(3).
166
169 The get_field_list() function appeared in GetData-0.3.0.
170 The get_field_list_by_type(), get_mfield_list(),
172 get_mfield_list_by_type(), get_mvector_list(), and get_vector_list()
173 functions appeared in GetData-0.4.0.
174 In GetData-0.7.0, these functions were renamed to gd_field_list(),
176 gd_field_list_by_type(), gd_mfield_list(), gd_mfield_list_by_type(),
177 gd_mvector_list(), and gd_vector_list().
178 The gd_entry_list() function appeared in GetData-0.8.0.
180
183 gd_error(3), gd_error_string(3), gd_hidden(3), gd_match_entries(3),
184 gd_nentries(3), gd_open(3), dirfile(5)
185Version 0.10.1 4 October 2017 gd_entry_list(3)