GETLOCALBASE(3)        FreeBSD Library Functions Manual        GETLOCALBASE(3)

NAME
     getlocalbase - return the path to the local software directory

LIBRARY
     System Utilities Library (libutil, -lutil)

SYNOPSIS
     #include <libutil.h>

     const char*
     getlocalbase(void);

DESCRIPTION
     The getlocalbase() function returns the path to the local software base
     directory.  Normally this is the /usr/local directory.  First the
     LOCALBASE environment variable is checked.  If that does not exist then
     the user.localbase sysctl is checked.  If that also does not exist then
     the value of the _PATH_LOCALBASE compile-time variable is used.  If that
     is undefined then the default of /usr/local is used.

     The contents of the string returned by the getlocalbase() function shall
     not be modified.

IMPLEMENTATION NOTES
     Calls to getlocalbase() will perform a setugid check on the running
     binary before checking the environment.

     The address returned by getlocalbase() will point into the executing
     processes environment if it is the result of getenv(LOCALBASE), to a
     static buffer if it is the result of sysctl(user.localbase), and to 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, ignoring any changes to the environment variable or the
     sysctl value that might have been made.

     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.  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.

RETURN VALUES
     The getlocalbase() function returns a pointer to a string, whose length
     may exceed MAXPATHLEN, if it has been obtained from the environment.

ENVIRONMENT
     The getlocalbase() library function retrieves the LOCALBASE environment
     variable.

ERRORS
     The getlocalbase() function always succeeds and returns a valid pointer
     to a string.

SEE ALSO
     env(1), src.conf(5), sysctl(8)

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
     Esser <se@FreeBSD.org>>.

FreeBSD 13.1-RELEASE-p6        November 25, 2020       FreeBSD 13.1-RELEASE-p6