shisa_enumerate_principals(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_principals — the shishi page, bestie edition 💖

okay so you're reading the shisa_enumerate_principals(3) manual page, part of shishi, and honestly? it's a lil bop. it does exactly one thing and it does it well. let's get into it 🦋

✨ NAME ✨

shisa_enumerate_principals — literally just an API function, no cap 💅

🌸 SYNOPSIS 🌸

#include <shisa.h>

int shisa_enumerate_principals(Shisa * dbh, const char * realm, char ***
principals, size_t * nprincipals);

yes she's a long signature, she's got range, we love her for it 😌

🎀 ARGUMENTS 🎀

  • Shisa * dbh — the Shisa library handle, and you get one of these from shisa(). like, you can't just show up without your invite, bestie 🫶
  • const char * realm — the name of the realm, served as a null-terminated UTF-8 string. that's the vibe.
  • char *** principals — this is the returned pointer, and it points to a newly allocated array of just-allocated, null-terminated UTF-8 strings holding the principal names. so. many. asterisks. 😭 she's giving triple-pointer main character energy and honestly, iconic.
  • size_t * nprincipals — a pointer to an integer that gets updated with the number of principal names that were just allocated and handed back to you. a lil count, a lil receipt, we stan 🧚

💜 DESCRIPTION 💜

so what does she do? she extracts a list of all the principal names in the backend that belong to the realm realm, and hands them to you as null-terminated UTF-8 strings. all of them. the whole roster. periodt ✨

⚠️ real talk though: you, the caller, are responsible for deallocating all the strings and the array *principals. she gives, but she does not clean up after you. that's your job, babes. free your memory or it will simply haunt you 💀

🔥 RETURN VALUE 🔥

  • SHISA_OK on success — slay, we love a happy ending 💖
  • SHISA_NO_REALM if the realm you specified doesn't exist — it's giving "who? never heard of her" 🙈
  • or an error code otherwise. anything else means something went sideways, and you should go investigate.

🐛 REPORTING BUGS 🐛

found a bug? spill the tea, but do it politely and to the right place:

they want to hear from you, fr fr 🌈

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.

(read that again: no royalty, no fuss, just keep the notice. generous queen behavior 💅)

🌟 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 the extended lore, iykyk 📚

and that's the whole page, bestie!! every flag, every arg, every return code — nothing left out, all vibes intact ✨

🌸 signing off from shishi, version 1.0.3, on the shisa_enumerate_principals(3) page — go enumerate some principals, you absolute legend 👑💖

📦 where this page comes from