gd_carrays(3)

💖 gd_carrays — bestie, it's the GetData manual page (section 3) 💖

okay so. you want ALL the CARRAY values out of a Dirfile in one go? say less. gd_carrays and gd_mcarrays are literally the group-chat pull-up of the GetData library, and yes they live in section 3 of the manual, and yes we're gonna go through the whole thing together. grab a snack. 🍓

---

✨ SYNOPSIS ✨

#include <getdata.h>

const gd_carray_t *gd_carrays(DIRFILE *dirfile, gd_type_t return_type);

const gd_carray_t *gd_mcarrays(DIRFILE *dirfile, const char *parent,
       gd_type_t return_type);

like, that's the whole vibe. two functions, one header, periodt. 💅

---

🌸 DESCRIPTION 🌸

the tea on gd_carrays()

gd_carrays() goes and queries a dirfile(5) database — the one you point at with dirfile — and generates a read-only list of the values of all the top-level CARRAY fields defined in that database. and because it's a whole serve, it does type conversion first, into whatever data type you asked for with return_type. want the full menu of valid symbols for return_type? that's on the gd_get_carray(3) manual page, go look, it's all there bestie 🫶

and gd_mcarrays()?

same energy, different lane. gd_mcarrays() behaves similarly but it builds a list of the values of CARRAY subfields sitting under the parent field parent. that's the "m" — it's giving multi-level, it's giving nested, iykyk. 🌈

one thing you cannot skip

dirfile must point to a valid DIRFILE object that was created earlier by a call to gd_open(3). no open, no service. that's the rule. 🔥

psst, want the names too?

a corresponding list of names for these fields can be got by calling gd_field_list_by_type(3) or gd_mfield_list_by_type(3). names and values, a matching set, iconic behavior honestly. 👑

---

💀 RETURN VALUE 💀

okay so on a successful completion, gd_carrays() and gd_mcarrays(3) return a pointer to an array of gd_carray_t objects holding the values of all the CARRAYs defined in the dirfile database. and the gd_carray_t structure is defined exactly like this, no edits, no notes:

typedef struct {
  size_t       n;              /* array_len */
  void        *d;              /* CARRAY data */
} gd_carray_t;

so let's break that down because it's lowkey important:

• n — specifies the length of the CARRAY data
• d — an array of the data values themselves

and if return_type was GD_NULL, then d will be NULL. no data, no drama, just vibes. otherwise, you (the caller) should cast that void pointer to a type appropriate for the return_type you specified. it's your cast, bestie, own it. ✨

the list is terminated by an end-of-list marker — that's a gd_carray_t item with n set to zero. that's how you know the party's over. 🎀

and if no CARRAYs are defined in the database at all? you still get a list back. it just contains only the end-of-list marker. empty but valid. it's giving "no thoughts, head empty, still correct". 🦋

⚠️ the array returned will be de-allocated by a call to gd_close(3) and should NOT be de-allocated by the caller. do not free it. do not touch it. let the library handle its own business.

the list returned should not be assumed to be in any particular order — except that it is guaranteed to be in the same order as the list of CARRAY fields returned by gd_field_list_by_type(3) or gd_mfield_list_by_type(3). so the order is chaotic but consistent chaos. the number of values in the array can be obtained from a call to gd_nfields_by_type(3) or gd_nmfields_by_type(3). 💜

🚨 the caller may not modify any values in the array, nor the array itself. doing so may cause database corruption. that is not a drill, that is a "you will regret this" moment. read-only means read-only fr fr.

and the pointer you get back is guaranteed to be valid only until:

• the function is called again, or
• the dirfile's metadata is modified (by adding, modifying or deleting an entry), or
• the array is de-allocated by a call to gd_close(3) or gd_discard(3).

so screenshot it, copy it, use it now. the pointer does not stay cute forever. 😭

---

🚨 when it goes wrong (error codes) 🚨

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

• GD_E_ALLOC — the library was unable to allocate memory. (the allocator said no 💀)
• GD_E_BAD_DIRFILE — the supplied dirfile was invalid. (bestie that dirfile is not real)
• GD_E_BAD_TYPE — the return_type specified was invalid. (that type? not a type.)
• GD_E_INTERNAL_ERROR — an internal error occurred in the library while trying to perform the task. this indicates a bug in the library. please report the incident to the GetData developers. (not your fault, go tell on us 🫶)

and a descriptive error string for the error may be obtained by calling gd_error_string(3). because a number alone is not a personality, you want the string. 💅

---

📜 HISTORY 📜

the gd_carrays() and gd_mcarrays() functions appeared in GetData-0.7.0. old money. 👑

---

👀 SEE ALSO 👀

dirfile(5), gd_error(3), gd_error_string(3), gd_field_list_by_type(3), gd_get_carray(3), gd_mfield_list_by_type(3), gd_nfields_by_type(3), gd_nmfields_by_type(3), gd_open(3)

like, read those too. they're the supporting cast and honestly they ate. 🌟

---

and that's the page bestie!! this was Version 0.10.0, dated 25 December 2016 — a lil Christmas gift from the GetData girlies 🎀✨ go cast some pointers, stay in your lane, and do not modify the array. mwah 💖