Ubuntu Manpage: gd_match_entries — search the entry list of a Dirfile

name
synopsis
description
return value
regular expressions
history
see also

Provided by: libgetdata-doc_0.11.0-14ubuntu1_all

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.