shisa_enumerate_realms(3)

📦
version 1.0.3 · 2 versions
  • 1.0.3 · debian bookworm, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 1.0.2 · ubuntu jammy
, in debian bookworm, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 shisa_enumerate_realms — the shishi manual, section 3, bestie edition 💖

okay so. welcome to shisa_enumerate_realms(3), a lil function page from the shishi manual (section 3, the library-calls girlies ✨). buckle up, we're getting every realm name out of a backend and it's gonna be adorable.

✨ NAME ✨

shisa_enumerate_realms — it's an API function, bestie. that's the whole name, no notes 💅

🌸 SYNOPSIS 🌸

#include <shisa.h>

int shisa_enumerate_realms(Shisa * dbh, char *** realms, size_t *
nrealms);

like. yes. three args, one int back. iconic behavior fr fr.

🎀 ARGUMENTS 🎀

  • Shisa * dbh — the Shisa library handle, and you get it from shisa(). no handle, no vibes, no realms.
  • char *** realms — this is where the magic lands 🦋 it's a returned pointer to a newly allocated array, and the strings inside are also allocated and null-terminated, in UTF-8, and they're realm names. so much allocation. so much responsibility.
  • size_t * nrealms — a pointer to a number, and that number gets updated with how many realm strings were just allocated and handed back to you. it's giving headcount. it's giving census. we love a count 🔢

💜 DESCRIPTION 💜

so what does it actually do. it extracts a list of all the realm names in the backend, as null-terminated UTF-8 strings. that's it. that's the whole thing. very demure, very mindful 🧚

⚠️ but listen. listen. the caller is responsible for deallocating all the strings as well as the array *realms. that means YOU. you free them. every single string, and then the array itself. do not ghost the memory, bestie, it will come back to haunt your valgrind output 😭

⭐ RETURN VALUE ⭐

returns SHISA_OK when it slays, or an error code when it does not. that's the whole scale. pass or fail. no letter grades 🙈

😭 REPORTING BUGS 😭

found a bug? do not suffer in silence, tell the people:

like genuinely please report them, that's how software gets better 💖

Copyright © 2002-2022 Simon Josefsson.

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

(translation: you can copy it, share it, remix it, whatever, just keep the receipt 🧾 and don't pay anybody. free as in free fr fr.)

🌈 SEE ALSO 🌈

the full documentation for shishi is maintained as a Texinfo manual. if the info and shishi programs are properly installed at your site, the command

info shishi

should give you access to the complete manual. go read it, it's right there, it's free, it's canon 📚

and that's the page!! tysm for reading my little manual rewrite, this was shisa_enumerate_realms(3) from shishi 1.0.3 🫶 stay allocated, free your strings, and i'll see you in the next man page. periodt 💅✨🌸

📦 where this page comes from