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

NAME

14       gd_match_entries — search the entry list of a Dirfile
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       unsigned int gd_match_entries(DIRFILE *dirfile, const char *regex, int
21              fragment, int type, unsigned int flags, const char ***entries);
22
23

DESCRIPTION

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
30       The match criteria are:
31
32
33       ·      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
38       ·      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
42       ·      The type argument should be one of the following  symbols  indi‐
43              cating an explicit entry type to match:
44
45                     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
53              (GD_INDEX_ENTRY  is  a special field type for the implicit INDEX
54              field) or else one of the following special symbols:
55
56              GD_ALL_ENTRIES (=0)
57                      Match entries of all types.
58
59              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
63              GD_SCALAR_ENTRIES
64                      Match  only  scalar  field types (CONST, CARRAY, SARRAY,
65                      STRING).
66
67              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
72       ·      The flags argument should be  zero  or  more  of  the  following
73              flags, bitwise or'd together:
74
75              GD_ENTRIES_HIDDEN
76                      Match hidden entries (see gd_hidden(3)): normally hidden
77                      entries are ignored;
78
79              GD_ENTRIES_NOALIAS
80                      Don't match aliases: normally  aliases  are  matched  as
81                      ifathey have the entry type of their target.
82
83              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
87                     GD_REGEX_PCRE, GD_REGEX_EXTENDED, GD_REGEX_ICASE,
88                     GD_REGEX_CASELESS, GD_REGEX_JAVASCRIPT, GD_REGEX_UNICODE
89
90              See the REGULAR EXPRESSIONS section below for details. If  regex
91              is  NULL, these additional regular-expression-specific flags are
92              ignored.
93
94

RETURN VALUE

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
106       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
110       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
116       GD_E_ARGUMENT
117               There was an error in the supplied regular expression. See  the
118               REGULAR EXPRESSION section below for details.
119
120       GD_E_BAD_CODE
121               The  supplied parent field code was not found, or referred to a
122               metafield itself.
123
124       GD_E_BAD_DIRFILE
125               The supplied dirfile was invalid.
126
127       GD_E_BAD_ENTRY
128               The type parameter supplied was not one of the  symbols  listed
129               above.
130
131       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
136       A  descriptive  error  string  for the error may be obtained by calling
137       gd_error_string(3).
138
139

REGULAR EXPRESSIONS

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
148       GetData supports the following regular expression libraries:
149
150       ·      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
157       ·      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
162       Support for one, both, or neither library may be enabled in the GetData
163       library when it is built.
164
165       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
169       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
174       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
180       The following flags are only supported  when  using  the  PCRE  library
181       (i.e., when GD_REGEX_PCRE is also specified):
182
183       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
189       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
197       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
202       GetData does not return captured substrings to the caller, nor does  it
203       support PCRE callouts.
204
205       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
210       Errors returned by the regular expression compiler itself will  be  re‐
211       ported to the caller with GD_E_BAD_ARGUMENT.
212
213

HISTORY

215       The gd_match_entries() function appeared in GetData-0.10.0.
216
217

SEE ALSO

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)
221
222
223
224Version 0.10.0                 25 December 2016            gd_match_entries(3)
Impressum