gd_entry_list(3)

💖 gd_entry_list — the GetData girlies' field-listing era 💖

okay so bestie, welcome to gd_entry_list(3), the <getdata.h> manual page from the GETDATA section, and honestly? she's a baddie. let me put you on.

---

✨ NAME ✨

gd_entry_list, gd_field_list, gd_field_list_by_type, gd_mfield_list, gd_mfield_list_by_type, gd_mvector_list, gd_vector_list — literally just listing field entries in a Dirfile. that's the whole job. she's a lister. an icon. 👑

---

🌸 SYNOPSIS 🌸

#include <getdata.h>

const char **gd_entry_list(DIRFILE *dirfile, const char *parent, int type,
       unsigned int flags);

const char **gd_field_list(DIRFILE *dirfile);

const char **gd_field_list_by_type(DIRFILE *dirfile, gd_entype_t type);

const char **gd_mfield_list(DIRFILE *dirfile, const char *parent);

const char **gd_mfield_list_by_type(DIRFILE *dirfile, const char *parent,
       gd_entype_t type);

const char **gd_mvector_list(DIRFILE *dirfile, const char *parent);

const char **gd_vector_list(DIRFILE *dirfile);

---

🦋 DESCRIPTION 🦋

so gd_entry_list() goes and queries a dirfile(5) database — the one you hand it in dirfile — and finds all the fields that match the criteria you gave it. she's thorough. she's picky. she serves. 💅

here's the tea on parent: if parent is non-NULL, then metafields under the field that parent names get considered. if parent is NULL? top-level fields only, and metafields get completely ignored. no metafield crumbs for you, sorry babe. 🙈

💜 the type argument 💜

type should be one of these symbols, and each one means "list this specific entry type, queen":

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.

(quick side quest: GD_INDEX_ENTRY is a special field type for the implicit INDEX field. she's not like the other girls. ✨)

orrrr you can use one of these special symbols instead:

• GD_ALL_ENTRIES (=0) — list entries of all types. everyone's invited to the party 🎉
• GD_ALIAS_ENTRIES — list only aliases. and ngl this is the only way to get a list that includes aliases which don't point to valid field codes. special girl behaviour only. 👑
• GD_SCALAR_ENTRIES — list only scalar field types (CONST, CARRAY, SARRAY, STRING). small but mighty 🎀
• GD_VECTOR_ENTRIES — list only numeric-valued vector field types. that's literally all field types except SINDIR and the scalar field types listed right above. yes bestie, read that twice. 🫶

💅 the flags argument 💅

flags should be zero or more of these, bit-wise or'd together. mix and match, do your thing:

• GD_ENTRIES_HIDDEN — include hidden entries (peep gd_hidden(3)) in the list. because normally? hidden entries get skipped. shy girlies stay hidden. 🙈
• GD_ENTRIES_NOALIAS — exclude aliases from the list. because normally aliases are considered the same as their target, meaning: if a field satisfies the criteria, then both its canonical name and all its aliases show up in the list. very "she brought her whole friend group" energy.

🧚 the fine print (read it, bestie) 🧚

the array that comes back gets de-allocated by a call to gd_close(3) — and you should not be de-allocating it yourself, okay? hands off. 🙅

the list returned should not be assumed to be in any particular order. she's chaotic. she's free. she's not alphabetised. 💀

the array is terminated by a NULL pointer. the number of elements in the array — not counting that terminating NULL — can be obtained from an equivalent call to gd_nentries(3).

⚠️ the caller may not modify any strings in the array, or the array itself. doing so may cause database corruption. i am so serious right now. do not touch. 😭

the pointer returned is guaranteed to be valid at least until gd_entry_list() is called again on the same DIRFILE object, or until the array is de-allocated by a call to gd_close(3). (although, lowkey, the data may have become obsolete if metadata have been modified in the interrim. she's valid, not clairvoyant. ✨)

also, this function has a subset of the functionality of the gd_match_entries(3) function (q.v.). she's the mini version. the travel-size icon. 🎀

---

🌈 Special Cases 🌈

the way that these wrappers are all just gd_entry_list() in a cute outfit, i'm obsessed:

the call

gd_field_list(dirfile);

is equivalent to

gd_entry_list(dirfile, NULL, GD_ALL_ENTRIES, 0);

the call

gd_field_list_by_type(dirfile, type);

is equivalent to

gd_entry_list(dirfile, NULL, type, 0);

the call

gd_mfield_list(dirfile, parent);

is equivalent to

gd_entry_list(dirfile, parent, GD_ALL_ENTRIES, 0);

the call

gd_mfield_list_by_type(dirfile, parent, type);

is equivalent to

gd_entry_list(dirfile, parent, type, 0);

the call

gd_mvector_list(dirfile, parent);

is equivalent to

gd_entry_list(dirfile, parent, GD_VECTOR_ENTRIES, 0);

the call

gd_vector_list(dirfile);

is equivalent to

gd_entry_list(dirfile, NULL, GD_VECTOR_ENTRIES, 0);

---

⭐ RETURN VALUE ⭐

upon successful completion, these functions return a pointer to an array of strings containing the names of all the entries in the database satisfying the supplied criteria. main character delivery, fr fr. 👑

the array is terminated with a NULL pointer. and if there are no matching entries? you still get an array — it just contains only the terminating NULL pointer. an empty plate, but a plate nonetheless. 🍓

on error, these functions return NULL and store a negative-valued error code in the DIRFILE object, which you can retrieve with a subsequent call to gd_error(3). possible error codes are:

• GD_E_BAD_CODE — the supplied parent field code was not found, or it referred to a metafield itself. rude of it honestly.
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. 💀
• GD_E_BAD_ENTRY — the type parameter you supplied was not one of the symbols listed above. bestie. the list was right there.

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

---

🎀 HISTORY 🎀

she's got lore. a whole glow-up timeline:

• the get_field_list() function appeared in GetData-0.3.0.
• the get_field_list_by_type(), get_mfield_list(), get_mfield_list_by_type(), get_mvector_list(), and get_vector_list() functions appeared in GetData-0.4.0.
• in GetData-0.7.0, these functions were renamed to gd_field_list(), gd_field_list_by_type(), gd_mfield_list(), gd_mfield_list_by_type(), gd_mvector_list(), and gd_vector_list(). rebrand era. 💅
• the gd_entry_list() function appeared in GetData-0.8.0.

---

👑 SEE ALSO 👑

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 is Version 0.10.1, dated 4 October 2017, and she ate, no crumbs left. go forth and list those entries. periodt. 💖✨🦋🌸💅🫶