gd_match_entries—search the entry list of a Dirfile
unsigned int gd_match_entries(DIRFILE *dirfile, const char *regex, int fragment, int type, unsigned int flags, const char ***entries);
The gd_match_entries() function queries a dirfile(5) database specified by dirfile and all the fields satisfying the provided criteria. If entries is not NULL, a list of matched entries will be returned in *entries.
The match criteria are:
GD_BIT_ENTRY, GD_CARRAY_ENTRY, GD_CONST_ENTRY, GD_DIVIDE_ENTRY, GD_INDEX_ENTRY, GD_INDIR_ENTRY, GD_LINCOM_ENTRY, GD_LINTERP_ENTRY, GD_MPLEX_ENTRY, GD_MULTIPLY_ENTRY, GD_PHASE_ENTRY, GD_POLYNOM_ENTRY, GD_RAW_ENTRY, GD_RECIP_ENTRY, GD_SARRAY_ENTRY, GD_SBIT_ENTRY, GD_SINDIR_ENTRY, GD_STRING_ENTRY, GD_WINDOW_ENTRY.
(GD_INDEX_ENTRY is a special field type for the implicit INDEX field) or else one of the following special symbols:
If regex is non-NULL, these flags may further be bitwise-or'd with the following flags which affect the interpretation of the supplied regular expression:
See the REGULAR EXPRESSIONS section below for details. If regex is NULL, these additional regular-expression-specific flags are ignored.
Upon successful completion, gd_match_entries() returns the number of entries successfully matched. In this case, if entries is non-NULL, this function sets *entries to a pointer to a list of the matching entry names. This list is terminated by a NULL pointer. Memory for the list, and for the strings it contains, is managed by GetData. None of the returned pointers should be free'd by the caller. The pointers returned are only valid until this function is called again, and the associated memory will be deallocated when dirfile is closed (see gd_close(3)).
If no entries match, but no error occurs, zero is returned. In this case, if entries is non-NULL, *entries is still set to a non-NULL pointer, which points to a list containing only the terminating NULL.
On error, this function also returns zero. If entries is non-NULL, *entries is set to NULL in this case (which can be used to distinguish this case from the zero-match case). This function furthermore stores a negative-valued error code in the DIRFILE object which may be retrieved by a subsequent call to gd_error(3). Possible error codes are:
A descriptive error string for the error may be obtained by calling gd_error_string(3).
Regular expression support in GetData is provided by external libraries and is optional. Whether a particular regular expression library is supported by GetData is determined when the library is built. Preprocessor symbols are present in getdata.h to provide compile-time support to programs building against GetData indicating what support the GetData library was built with.
GetData supports the following regular expression libraries:
Support for one, both, or neither library may be enabled in the GetData library when it is built.
When calling gd_match_entries(), the choice of regular expression grammar to use is controlled by bitwise-or'ing flags with zero or more of the following symbols:
The following flags are only supported when using the PCRE library (i.e., when GD_REGEX_PCRE is also specified):
In addition to the above, the flags PCRE_DOLLAR_ENDONLY and PCRE_DOTALL are always passed to the PCRE library. Note, however, that the PCRE grammar also permits overriding most of these flags by specifying different options in the regex pattern itself.
GetData does not return captured substrings to the caller, nor does it support PCRE callouts.
If the caller attempts to use a regular expression library for which support has not been built into GetData, GD_E_UNSUPPORTED will be returned. It is always possible for the caller avoid this error at runtime by checking for GD_NO_REGEX or GD_NO_PCRE at compile time.
Errors returned by the regular expression compiler itself will be reported to the caller with GD_E_BAD_ARGUMENT.
The gd_match_entries() function appeared in GetData-0.10.0.