1
2
3
4
5
6
7
8
9gd_entry_list(3)                    GETDATA                   gd_entry_list(3)
10
11
12

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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
149       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
153       GD_E_BAD_CODE
154               The supplied parent field code was not found, or referred to  a
155               metafield itself.
156
157       GD_E_BAD_DIRFILE
158               The supplied dirfile was invalid.
159
160       GD_E_BAD_ENTRY
161               The  type  parameter supplied was not one of the symbols listed
162               above.
163
164       A descriptive error string for the error may  be  obtained  by  calling
165       gd_error_string(3).
166
167

HISTORY

169       The get_field_list() function appeared in GetData-0.3.0.
170
171       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
175       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
179       The gd_entry_list() function appeared in GetData-0.8.0.
180
181

SEE ALSO

183       gd_error(3),   gd_error_string(3),  gd_hidden(3),  gd_match_entries(3),
184       gd_nentries(3), gd_open(3), dirfile(5)
185
186
187
188Version 0.10.1                  4 October 2017                gd_entry_list(3)
Impressum