1gd_match_entries(3) GETDATA gd_match_entries(3)
10
14 gd_match_entries — search the entry list of a Dirfile
15
18 #include <getdata.h>
19 unsigned int gd_match_entries(DIRFILE *dirfile, const char *regex, int
21 fragment, int type, unsigned int flags, const char ***entries);
22
25 The gd_match_entries() function queries a dirfile(5) database specified
26 by dirfile and all the fields satisfying the provided criteria. If en‐
27 tries is not NULL, a list of matched entries will be returned in *en‐
28 tries.
29 The match criteria are:
31 • If regex is non-NULL, it is a regular expression to match
34 against the entry names. Various regular expression grammars
35 (or none) may be supported by the library. See the REGULAR EX‐
36 PRESSIONS section below for details.
37 • If the fragment argument is GD_ALL_FRAGMENTS, entries defined in
39 all fragments are matched. Otherwise only entries specified in
40 the fragment indexed by fragment are matched.
41 • The type argument should be one of the following symbols indi‐
43 cating an explicit entry type to match:
44 GD_BIT_ENTRY, GD_CARRAY_ENTRY, GD_CONST_ENTRY,
46 GD_DIVIDE_ENTRY, GD_INDEX_ENTRY, GD_INDIR_ENTRY,
47 GD_LINCOM_ENTRY, GD_LINTERP_ENTRY, GD_MPLEX_ENTRY,
48 GD_MULTIPLY_ENTRY, GD_PHASE_ENTRY, GD_POLYNOM_ENTRY,
49 GD_RAW_ENTRY, GD_RECIP_ENTRY, GD_SARRAY_ENTRY,
50 GD_SBIT_ENTRY, GD_SINDIR_ENTRY, GD_STRING_ENTRY,
51 GD_WINDOW_ENTRY.
52 (GD_INDEX_ENTRY is a special field type for the implicit INDEX
54 field) or else one of the following special symbols:
55 GD_ALL_ENTRIES (=0)
57 Match entries of all types.
58 GD_ALIAS_ENTRIES
60 Match only aliases. This is the only way to match
61 aliases which do not point to valid field codes.
62 GD_SCALAR_ENTRIES
64 Match only scalar field types (CONST, CARRAY, SARRAY,
65 STRING).
66 GD_VECTOR_ENTRIES
68 Match only numeric-valued vector field types (all field
69 types except SINDIR and the scalar field types listed
70 above).
71 • The flags argument should be zero or more of the following
73 flags, bitwise or'd together:
74 GD_ENTRIES_HIDDEN
76 Match hidden entries (see gd_hidden(3)): normally hidden
77 entries are ignored;
78 GD_ENTRIES_NOALIAS
80 Don't match aliases: normally aliases are matched as if
81 they had the entry type of their target.
82 If regex is non-NULL, these flags may further be bitwise-or'd
84 with the following flags which affect the interpretation of the
85 supplied regular expression:
86 GD_REGEX_PCRE, GD_REGEX_EXTENDED, GD_REGEX_ICASE,
88 GD_REGEX_CASELESS, GD_REGEX_JAVASCRIPT, GD_REGEX_UNICODE
89 See the REGULAR EXPRESSIONS section below for details. If regex
91 is NULL, these additional regular-expression-specific flags are
92 ignored.
93
96 Upon successful completion, gd_match_entries() returns the number of
97 entries successfully matched. In this case, if entries is non-NULL,
98 this function sets *entries to a pointer to a list of the matching en‐
99 try names. This list is terminated by a NULL pointer. Memory for the
100 list, and for the strings it contains, is managed by GetData. None of
101 the returned pointers should be free'd by the caller. The pointers re‐
102 turned are only valid until this function is called again, and the as‐
103 sociated memory will be deallocated when dirfile is closed (see
104 gd_close(3)).
105 If no entries match, but no error occurs, zero is returned. In this
107 case, if entries is non-NULL, *entries is still set to a non-NULL
108 pointer, which points to a list containing only the terminating NULL.
109 On error, this function also returns zero. If entries is non-NULL,
111 *entries is set to NULL in this case (which can be used to distinguish
112 this case from the zero-match case). This function furthermore stores a
113 negative-valued error code in the DIRFILE object which may be retrieved
114 by a subsequent call to gd_error(3). Possible error codes are:
115 GD_E_ARGUMENT
117 There was an error in the supplied regular expression. See the
118 REGULAR EXPRESSION section below for details.
119 GD_E_BAD_CODE
121 The supplied parent field code was not found, or referred to a
122 metafield itself.
123 GD_E_BAD_DIRFILE
125 The supplied dirfile was invalid.
126 GD_E_BAD_ENTRY
128 The type parameter supplied was not one of the symbols listed
129 above.
130 GD_E_UNSUPPORTED
132 The regex parameter was non-NULL, but the library lacked sup‐
133 port for the specified regular expression grammar. See the REG‐
134 ULAR EXPRESSION section below for details.
135 A descriptive error string for the error may be obtained by calling
137 gd_error_string(3).
138
141 Regular expression support in GetData is provided by external libraries
142 and is optional. Whether a particular regular expression library is
143 supported by GetData is determined when the library is built. Pre‐
144 processor symbols are present in getdata.h to provide compile-time sup‐
145 port to programs building against GetData indicating what support the
146 GetData library was built with.
147 GetData supports the following regular expression libraries:
149 • The POSIX.2 regular expression library, which provides support
151 for both basic and extended POSIX regular expressions. See
152 regex(7) for details. The POSIX regular expression library is
153 derived from Henry Spencer's original regex package found in
154 BSD. If GetData lacks support for POSIX regular expressions, the
155 symbol GD_NO_REGEX will be defined in getdata.h.
156 • Perl-compatible Regular Expressions (PCRE), which provides a
158 modern, full-featured regular expression grammar. See pcre(3)
159 for details. If GetData lacks support for PCREs, the symbol
160 GD_NO_PCRE will be defined in getdata.h.
161 Support for one, both, or neither library may be enabled in the GetData
163 library when it is built.
164 When calling gd_match_entries(), the choice of regular expression gram‐
166 mar to use is controlled by bitwise-or'ing flags with zero or more of
167 the following symbols:
168 GD_REGEX_PCRE
170 Use the Perl-compatible Regular Expression (PCRE) library for
171 regular expression matching. Without this flag, the POSIX regex
172 library is used.
173 GD_REGEX_CASELESS
175 GD_REGEX_ICASE
176 Perform case-insensitive matching. These two symbols are syn‐
177 onyms. This is equivalent to the REG_ICASE flag in regex(3) and
178 the PCRE_CASELESS flag in pcreapi(3).
179 The following flags are only supported when using the PCRE library
181 (i.e., when GD_REGEX_PCRE is also specified):
182 GD_REGEX_JAVASCRIPT
184 Enable Javascript compatibility mode in the PCRE library. This
185 results in a regular expression grammar that mimics more close‐
186 ly Javascript's regular expressions than Perl's. See the
187 PCRE_JAVASCRIPT_COMPAT flag in pcreapi(3) for details.
188 GD_REGEX_UNICODE
190 Interpret the supplied regex, as well as the Dirfile's entry
191 names, as UTF-8 sequences. Without this flag, they are all as‐
192 sumed to be ASCII sequences. When this flag is specified, the
193 flags PCRE_UTF8 and BPCRE_BSR_UNICODE are passed to the PCRE
194 library. Without it, the flags PCRE_BSR_ANYCRLF is used in‐
195 stead. See pcreapi(3) for details.
196 In addition to the above, the flags PCRE_DOLLAR_ENDONLY and PCRE_DOTALL
198 are always passed to the PCRE library. Note, however, that the PCRE
199 grammar also permits overriding most of these flags by specifying dif‐
200 ferent options in the regex pattern itself.
201 GetData does not return captured substrings to the caller, nor does it
203 support PCRE callouts.
204 If the caller attempts to use a regular expression library for which
206 support has not been built into GetData, GD_E_UNSUPPORTED will be re‐
207 turned. It is always possible for the caller avoid this error at run‐
208 time by checking for GD_NO_REGEX or GD_NO_PCRE at compile time.
209 Errors returned by the regular expression compiler itself will be re‐
211 ported to the caller with GD_E_ARGUMENT.
212
215 The gd_match_entries() function appeared in GetData-0.10.0.
216
219 gd_entry_list(3), gd_error(3), gd_error_string(3), gd_hidden(3),
220 gd_match_entries(3), gd_nentries(3), gd_open(3), dirfile(5)
221Version 0.10.0 25 December 2016 gd_match_entries(3)