GETLOCALBASE(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 GETLOCALBASE(3) — ok so this is the getlocalbase manual page, section 3, and honestly bestie it's a little cutie

🌸 NAME

getlocalbase — returns the path to the local software directory. That's it, that's the whole vibe ✨

🎀 LIBRARY

System Utilities Library (libutil, -lutil) — yeah you gotta link it, no cap 🫶

✨ SYNOPSIS

#include <libutil.h>

const char*
getlocalbase(void);

💖 DESCRIPTION

okay so the getlocalbase() function returns the path to the local software base directory. Normally this is the /usr/local directory — like, the standard one, the default girlie 🌈

But here's the tea, it does NOT just grab one thing, it checks stuff in order:

  1. First the LOCALBASE environment variable is checked 👀
  2. If that does not exist, then the user.localbase sysctl is checked
  3. If that also does not exist, then the value of the LOCALBASE_PATH compile-time variable is used
  4. If that is undefined, then the system default, _PATH_LOCALBASE, is used 🎯
⚠️ okay listen: the contents of the string returned by the getlocalbase() function shall not be modified. Do not touch. Not yours. Hands off 🙈

🔥 IMPLEMENTATION NOTES

  • Calls to getlocalbase() will perform a setugid check on the running binary before checking the environment. Safety first, always 💅
  • The address returned by getlocalbase() will point into:
    • the executing process's environment, if it's the result of getenv(LOCALBASE)
    • a static buffer, if it's the result of sysctl(user.localbase)
    • a constant string, if the compiled-in default value is returned
  • The same value will be returned on successive calls during the run-time of the program — and yes, that's ignoring any changes to the environment variable or the sysctl value that might have been made. So don't come back later expecting a different answer, she's committed 😌
  • The getlocalbase() function can be compiled with a non-default value of LOCALBASE_CTL_LEN:
    • A value of 0 will disable fetching of the sysctl value
    • A value less than MAXPATHLEN will put a limit on the maximum string length supported for this sysctl value
💀 lowkey important: if built with a non-default value of LOCALBASE_CTL_LEN, a value of the user.localbase sysctl variable longer than this value will make getlocalbase() return a valid string that is not a valid path prefix in any filesystem. Like, it's a real string, it's just not a usable path. Wild. Be aware fr fr.

⭐ RETURN VALUES

The getlocalbase() function returns a pointer to a string, whose length may exceed MAXPATHLEN, if it has been obtained from the environment. Yeah, she can be long, we don't gatekeep 🦋

👑 ENVIRONMENT

  • The getlocalbase() library function retrieves the LOCALBASE environment variable. That's her source of truth 🎀

💜 ERRORS

The getlocalbase() function always succeeds and returns a valid pointer to a string. Iconic behavior honestly, zero drama, she just works periodt ✨

🌟 SEE ALSO

🌈 HISTORY

The getlocalbase library function first appeared in FreeBSD 13.0 🎉

🫶 AUTHORS

This manual page was written by Scott Long <scottl@FreeBSD.org> and Stefan Eßer <se@FreeBSD.org> — ty besties for the docs 🥹

k that's the whole page!! 💖 oh and the footer info: this one's from the Debian source/version, dated July 11, 2023 — so if you cite her, that's the receipt 🎀✨

📦 where this page comes from