--- name: "gd_match_entries" section: "3" platform: "linux" package: "libgetdata-doc" version: "0.11.0-15" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gd_match_entries" --- # gd\_match\_entries(3) search the entry list of a Dirfile ## NAME gd\_match\_entries — search the entry list of a Dirfile ## SYNOPSIS **#include \** **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)](/dirfile/5.md) 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:\ .TP 8 **GD\_ALL\_ENTRIES (=0)** Match entries of all types.\ .TP 8 **GD\_ALIAS\_ENTRIES** Match only aliases. This is the only way to match aliases which do not point to valid field codes.\ .TP 8 **GD\_SCALAR\_ENTRIES** Match only scalar field types (**CONST**, **CARRAY**, **SARRAY**, **STRING**).\ .TP 8 **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: .TP 8 **GD\_ENTRIES\_HIDDEN** Match hidden entries (see [**gd\_hidden**(3)](/gd_hidden/3.md)): normally hidden entries are ignored;\ .TP 8 **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)](/gd_close/3.md)). 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)](/gd_error/3.md). Possible error codes are:\ .TP 8 **GD\_E\_ARGUMENT** There was an error in the supplied regular expression. See the **REGULAR EXPRESSION** section below for details.\ .TP 8 **GD\_E\_BAD\_CODE** The supplied parent field code was not found, or referred to a metafield itself.\ .TP 8 **GD\_E\_BAD\_DIRFILE** The supplied dirfile was invalid.\ .TP 8 **GD\_E\_BAD\_ENTRY** The *type* parameter supplied was not one of the symbols listed above.\ .TP 8 **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)](/gd_error_string/3.md). ## 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)](/regex/7.md) 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)](/pcre/3.md) 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:\ .TP 8 **GD\_REGEX\_PCRE** Use the Perl-compatible Regular Expression (PCRE) library for regular expression matching. Without this flag, the POSIX regex library is used.\ .PP **GD\_REGEX\_CASELESS**\ .TP 8 **GD\_REGEX\_ICASE** Perform case-insensitive matching. These two symbols are synonyms. This is equivalent to the **REG\_ICASE** flag in [**regex**(3)](/regex/3.md) and the **PCRE\_CASELESS** flag in [**pcreapi**(3)](/pcreapi/3.md). The following flags are only supported when using the PCRE library (i.e., when **GD\_REGEX\_PCRE** is also specified):\ .TP 8 **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)](/pcreapi/3.md) for details.\ .TP 8 **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)](/pcreapi/3.md) 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_entry_list/3.md), [**gd\_error**(3)](/gd_error/3.md), [**gd\_error\_string**(3)](/gd_error_string/3.md), [**gd\_hidden**(3)](/gd_hidden/3.md), [**gd\_match\_entries**(3)](/gd_match_entries/3.md), [**gd\_nentries**(3)](/gd_nentries/3.md), [**gd\_open**(3)](/gd_open/3.md), [dirfile(5)](/dirfile/5.md)