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 LOCALBASE_PATH compile-time variable is used. If that is undefined then the system default, _PATH_LOCALBASE 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.

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