gd_match_entries(3)

💖 NAME 💖

gd_match_entries — bestie, this is literally the function that searches the entry list of a Dirfile. It's giving "find my people" energy for your dirfile(5) database. 👑

---

✨ 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 🎀

okay so. gd_match_entries() goes and queries a dirfile(5) database — that's the one you passed as dirfile — and it pulls up all the fields that satisfy the criteria you gave it. And if entries is not NULL? It drops a whole list of the matched entries into *entries. 🫶

Here's the vibe check on your match criteria:

• If regex is non-NULL, it's a regular expression that gets matched against the entry names. Various regular expression grammars (or, like, none at all 🙈) may be supported by the library. Peep the REGULAR EXPRESSIONS section below for the deets.
• If the fragment argument is GD_ALL_FRAGMENTS, then entries defined in all fragments get matched. Otherwise, only entries specified in the fragment indexed by fragment are matched. no cap.
• The type argument should be one of these 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, iykyk) — or else one of these special symbols:

• GD_ALL_ENTRIES (=0) — Match entries of all types. the whole roster, periodt. 🌈
• GD_ALIAS_ENTRIES — Match only aliases. and fr fr, this is the only way to match aliases which don't point to valid field codes. like, the sole method. 💅
• 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 these 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.

And if regex is non-NULL, these flags may further be bitwise-or'd with the following flags, which affect how the supplied regular expression gets interpreted:

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. And if regex is NULL, these extra regular-expression-specific flags just get ignored. shrug. 🤷

---

🌸 RETURN VALUE 🌸

Upon successful completion, gd_match_entries() returns the number of entries successfully matched. And in that case, if entries is non-NULL, this function sets *entries to a pointer to a list of the matching entry names. That list is terminated by a NULL pointer. ✨

Memory for the list, and for the strings inside it, is managed by GetData. None of the returned pointers should be free'd by the caller. And 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)). so don't get attached, bestie. 😭

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 you can use to distinguish this case from the zero-match case — iconic little trick 💅). 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 to 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)

---

and that's the whole page, bestie!! 🫶 this one's from Version 0.10.0, dated 25 December 2016, and it's the gd_match_entries(3) page from the GETDATA manual. slay, go match some entries, you've got this 💅✨