1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright 2020 Scott Long 5.\" Copyright 2020 Stefan Eßer 6.\" Copyright (c) 2026 Dag-Erling Smørgrav 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd July 20, 2026 30.Dt GETLOCALBASE 3 31.Os 32.Sh NAME 33.Nm getlocalbase 34.Nd "return the path to the local software base directory" 35.Sh LIBRARY 36.Lb libutil 37.Sh SYNOPSIS 38.In libutil.h 39.Ft "const char *" 40.Fn getlocalbase "void" 41.Sh DESCRIPTION 42The 43.Nm 44function returns the path to the local software base directory, 45normally 46.Pa /usr/local . 47.Pp 48First the 49.Ev LOCALBASE 50environment variable is checked. 51If that variable is undefined or empty, the 52.Va user.localbase 53sysctl is checked. 54If that returns an empty string or an error occurs, the value of 55.Dv _PATH_LOCALBASE 56is used as a last resort. 57.Pp 58If the value obtained through these means is not a valid absolute path 59shorter than 60.Dv MAXPATHLEN , 61a constant string which has been deliberately chosen to cause any file 62system operation using it to fail is returned instead. 63.Pp 64The contents of the string returned by 65.Nm 66shall not be modified by the caller. 67.Sh IMPLEMENTATION NOTES 68The 69.Ev LOCALBASE 70environment variable will only be used if the process calling 71.Nm 72is not setugid. 73.Pp 74Successive calls to 75.Nm 76will return the same value throughout the lifetime of the process, 77regardless of any subsequent changes to the environment or sysctl 78variables. 79.Pp 80The 81.Nm 82function is thread-safe if and only if it has been called at least 83once already. 84.Sh RETURN VALUES 85The 86.Fn getlocalbase 87function returns a pointer to a null-terminated string. 88.Sh ENVIRONMENT 89.Bl -tag -width ".Ev LOCALBASE" 90.It Ev LOCALBASE 91Path to the local software base directory 92.El 93.Sh SEE ALSO 94.Xr environ 7 , 95.Xr sysctl 8 96.Sh HISTORY 97The 98.Nm 99function first appeared in 100.Fx 13.0 . 101.Sh AUTHORS 102.An -nosplit 103The 104.Nm 105function was originally written by 106.An Stefan Eßer Aq Mt se@FreeBSD.org 107and was later reimplemented by 108.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 109This manual page was originally written by 110.An Scott Long Aq Mt scottl@FreeBSD.org 111and 112.An Stefan Eßer Aq Mt se@FreeBSD.org 113and was later substantially rewritten by 114.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 115