Provided by: libgetdata-doc_0.11.0-6_all bug

NAME

       gd_match_entries — search the entry list of a Dirfile

SYNOPSIS

       #include <getdata.h>

       unsigned int gd_match_entries(DIRFILE *dirfile, const char *regex, int fragment, int type,
              unsigned int flags, const char ***entries);

DESCRIPTION

       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:

       •      If regex is non-NULL, it is a regular expression to match against the entry  names.
              Various regular expression grammars (or none) may be supported by the library.  See
              the REGULAR EXPRESSIONS section below for details.

       •      If the fragment argument is GD_ALL_FRAGMENTS, entries defined in all fragments  are
              matched.  Otherwise  only entries specified in the fragment indexed by fragment are
              matched.

       •      The type argument should be one of the following  symbols  indicating  an  explicit
              entry type to match:

                     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:

              GD_ALL_ENTRIES (=0)
                      Match entries of all types.

              GD_ALIAS_ENTRIES
                      Match only aliases.  This is the only way to match  aliases  which  do  not
                      point to valid field codes.

              GD_SCALAR_ENTRIES
                      Match only scalar field types (CONST, CARRAY, SARRAY, STRING).

              GD_VECTOR_ENTRIES
                      Match only numeric-valued vector field types (all field types except SINDIR
                      and the scalar field types listed above).

       •      The flags argument should be zero or more of  the  following  flags,  bitwise  or'd
              together:

              GD_ENTRIES_HIDDEN
                      Match  hidden  entries  (see  gd_hidden(3)):  normally  hidden  entries are
                      ignored;

              GD_ENTRIES_NOALIAS
                      Don't match aliases: normally aliases are matched as if they had the  entry
                      type of their target.

              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:

                     GD_REGEX_PCRE, GD_REGEX_EXTENDED, GD_REGEX_ICASE, GD_REGEX_CASELESS,
                     GD_REGEX_JAVASCRIPT, GD_REGEX_UNICODE

              See  the  REGULAR  EXPRESSIONS  section  below for details. If regex is NULL, these
              additional regular-expression-specific flags are ignored.

RETURN VALUE

       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:

       GD_E_ARGUMENT
               There  was an error in the supplied regular expression. See the REGULAR EXPRESSION
               section below for details.

       GD_E_BAD_CODE
               The supplied parent field code was not found, or referred to a metafield itself.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_ENTRY
               The type parameter supplied was not one of the symbols listed above.

       GD_E_UNSUPPORTED
               The regex parameter was non-NULL, but the library lacked support for the specified
               regular expression grammar. See the REGULAR EXPRESSION section below for details.

       A descriptive error string for the error may be obtained by calling gd_error_string(3).

REGULAR EXPRESSIONS

       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:

       •      The  POSIX.2  regular expression library, which provides support for both basic and
              extended POSIX regular expressions. See regex(7) for  details.  The  POSIX  regular
              expression  library is derived from Henry Spencer's original regex package found in
              BSD. If GetData lacks support for POSIX regular expressions, the symbol GD_NO_REGEX
              will be defined in getdata.h.

       •      Perl-compatible  Regular Expressions (PCRE), which provides a modern, full-featured
              regular expression grammar. See pcre(3) for details. If GetData lacks  support  for
              PCREs, the symbol GD_NO_PCRE will be defined in getdata.h.

       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:

       GD_REGEX_PCRE
               Use  the  Perl-compatible Regular Expression (PCRE) library for regular expression
               matching. Without this flag, the POSIX regex library is used.

       GD_REGEX_CASELESS
       GD_REGEX_ICASE
               Perform case-insensitive  matching.  These  two  symbols  are  synonyms.  This  is
               equivalent  to  the  REG_ICASE  flag  in  regex(3)  and  the PCRE_CASELESS flag in
               pcreapi(3).

       The  following  flags  are  only  supported  when  using  the  PCRE  library  (i.e.,  when
       GD_REGEX_PCRE is also specified):

       GD_REGEX_JAVASCRIPT
               Enable  Javascript  compatibility  mode  in  the  PCRE  library. This results in a
               regular  expression  grammar  that  mimics  more  closely   Javascript's   regular
               expressions  than  Perl's.  See  the PCRE_JAVASCRIPT_COMPAT flag in pcreapi(3) for
               details.

       GD_REGEX_UNICODE
               Interpret the supplied regex, as well as  the  Dirfile's  entry  names,  as  UTF-8
               sequences.  Without  this  flag,  they are all assumed to be ASCII sequences. When
               this flag is specified, the flags PCRE_UTF8 and BPCRE_BSR_UNICODE  are  passed  to
               the  PCRE  library.  Without  it,  the flags PCRE_BSR_ANYCRLF is used instead. See
               pcreapi(3) for details.

       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_ARGUMENT.

HISTORY

       The gd_match_entries() function appeared in GetData-0.10.0.

SEE ALSO

       gd_entry_list(3),   gd_error(3),  gd_error_string(3),  gd_hidden(3),  gd_match_entries(3),
       gd_nentries(3), gd_open(3), dirfile(5)