gd_constants(3)

✨ NAME ✨

okay so hi bestie 💖 this is the GetData page for gd_constants(3) — it's gd_constants, gd_mconstants, and their whole thing is retrieving a list of constant values from a Dirfile. iconic behaviour, honestly.

🎀 SYNOPSIS 🎀

#include <getdata.h>

const void *gd_constants(DIRFILE *dirfile, gd_type_t return_type);

const void *gd_mconstants(DIRFILE *dirfile, const char *parent,
       gd_type_t return_type);

🌸 DESCRIPTION 🌸

So gd_constants() looks up a dirfile(5) database — that's the one you hand it as dirfile — and then it goes and compiles a whole lil list of the values of all the CONST fields defined in that database. Meta subfields are NOT invited to this party, okay? Excluded. Periodt. 🙅♀️

Then all those values get converted into whatever data type you asked for with return_type. And return_type has to be one of these symbols, no substitutions bestie:

GD_UINT8, GD_INT8, GD_UINT16, GD_INT16, GD_UINT32, GD_INT32,
GD_UINT64, GD_INT64, GD_FLOAT32, GD_FLOAT64, GD_COMPLEX64,
GD_COMPLEX128.

If you're like "what do these even mean" — go check gd_get_constant(3), it explains every single one 🫶.

Oh and the dirfile argument has to point to a valid DIRFILE object that was already created by a call to gd_open(3). No fake ones, no guessing.

Meanwhile gd_mconstants() is the meta-subfield girlie 💅 — it hands you that same kinda list, but for the CONST meta subfields of the parent field you name in parent.

And if you want the matching list of names for these fields? Call gd_field_list_by_type(3) or gd_mfield_list_by_type(3). Matching set, slay. ✨

👑 RETURN VALUE 👑

When everything goes right, gd_constants() gives you back a pointer to an array holding the values of all the constants defined in the dirfile database. Same deal with gd_mconstants() — pointer to an array, this time with the values of all the meta subfield constants of the parent field you specified. 🎀

okay important: the list that comes back should not be assumed to be in any particular order. BUT — and this is the cute part — it is guaranteed to be in the same order as the list of CONST fields returned by gd_field_list_by_type(3) or gd_mfield_list_by_type(3). So they match up. cute.

Also the array is unterminated — there's no lil sentinel at the end telling you where it stops, so don't go looking for one. The number of values in the array comes from calling gd_nfields_by_type(3) or gd_nmfields_by_type(3), whichever one fits your situation. 🧚

Memory for that returned array is managed by GetData, so do NOT de-allocate it yourself. And the caller may not modify any values in the array — like, actually, doing so may cause database corruption 😭💀 so please don't.

The pointer is guaranteed valid only until the function is called again — with one exception, and it's a good one: since each top-level field maintains its own arrays, calling gd_mconstants() for one parent field does not invalidate the pointer you got back for any other parent. 🫶

If you go and modify the dirfile's metadata, that invalidates any pointer these functions returned. And no pointers stay valid after the dirfile gets de-allocated by a call to gd_close(3) or gd_discard(3). Once a pointer is invalidated, the caller should not dereference it. like, at all. don't. 🙈

If there are no constants of the appropriate class defined in the database, you get NULL back — and ngl, that is not considered an error. it's just a vibe. no constants, no problem.

But on actual error, these functions return NULL and stash a negative-valued error code in the DIRFILE object, which you can grab with a later call to gd_error(3). Possible error codes, here we go:

• GD_E_ALLOC — the library couldn't allocate memory. 😭
• GD_E_BAD_CODE — the parent field code you specified wasn't found, or it referred to a metafield. (This one is gd_mconstants() only, bestie.)
• GD_E_BAD_DIRFILE — the dirfile you handed over was invalid. 🚫
• GD_E_BAD_TYPE — the return_type you specified was not one of the symbols listed above. go pick a real one.
• GD_E_INTERNAL_ERROR — an internal error happened inside the library while it was trying to do the task. This indicates a bug in the library. Please re-port the incident to the GetData developers! 🐛💀

And if you want a descriptive error string for whatever went down, call gd_error_string(3). 💖

🦋 HISTORY 🦋

The functions get_constants() and get_mconstants() appeared way back in GetData-0.4.0. ✨

Then in GetData-0.7.0, they got renamed to gd_constants() and gd_mconstants(). glow-up era. 👑

🌈 SEE ALSO 🌈

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

and that's the whole page bestie!! 💜 this was Version 0.10.0, dated 25 December 2016 — the gd_constants(3) GETDATA moment, no cap. go read your constants. mwah 🎀💅