Name

userenv — set the "user" environment variables from the current UID and GID

Synopsis

userenv [--set-path] [--set-tools] [--set-term] [--set-locale] [--set-xdg] [--set-dbus] [--set-timezone] [--set-other] {next-prog}

Description

userenv is a chain-loading utility that sets environment variables and then chain loads to next-prog with the execvp(3) function.

next-prog may contain its own command line options, which userenv will ignore.

Universal variables

The following environment variables are always set:

UID

Set to the (decimal) numeric value of the process's effective user ID.

GID

Set to the (decimal) numeric value of the process's effective group ID.

HOME

Set to the pathname of the user's home directory, as given in the system account database, falling back if the field is blank to unset.

SHELL

Set to the pathname of the user's shell program, as given in the system account database, falling back if the field is blank to the system's default "B" shell name that is hardwired into the C library. (This fallback is in line with the behaviour of login(1).)

USER and LOGNAME

Set to the user's name, as given in the system account database, falling back if the field is blank to unset.

Path variables

The following environment variables are set from the login.conf(5) database if the --set-path command-line option is used:

PATH

Set to the value of the path capability, defaulting if there is no capability to the system's default path that is hardwired into the C library.

MANPATH

Set to the value of the manpath capability, defaulting to unset if there is no capability.

Tools variables

The following environment variables are set from the login.conf(5) database if the --set-tools command-line option is used:

EDITOR

Set to the value of the editor capability, defaulting if there is no capability to ex. (POSIX gives two choices of universally available line editor. This is the one that is not ed(1).)

VISUAL

Set to the value of the visual capability, defaulting if there is no capability to vi. (POSIX gives one choice of universally available full-screen editor.)

PAGER

Set to the value of the pager capability, defaulting if there is no capability to more.

Terminal variables

The following environment variables are set from the login.conf(5) database if the --set-term command-line option is used:

TERM

Set to the value of the term capability, defaulting to unset if there is no capability. Generally, this is inappropriate, as the TERM variable will have been set for the login session by the TTY login system. Moreover: The login.conf(5) database usually does not have a term capability configured, which ends up unsetting the environment variable instead of leaving it as it was.

Locale variables

The following environment variables are set from the login.conf(5) database if the --set-locale command-line option is used:

LANG

Set to the value of the lang capability, defaulting to POSIX if there is no capability.

MM_CHARSET

Set to the value of the charset capability, defaulting to UTF-8 if there is no capability.

Timezone variables

The following environment variables are set from the login.conf(5) database if the --set-timezone command-line option is used:

TZ

Set to the value of the timezone capability, defaulting to UTC if there is no capability.

XDG variables

The following environment variables are set if the --set-xdg command-line option is used:

XDG_RUNTIME_DIR

Set to /run/user/username/.

XDG_CONFIG_DIRS

Set to /usr/local/etc/xdg on the BSDs, unset (so applications use the default of /etc/xdg) on other operating systems.

XDG_CONFIG_HOME

Unset, so that applications use the default of $HOME/.config.

XDG_DATA_DIRS

Set to /usr/local/share:/usr/share:/share. The addition of /share comes from TrueOS Desktop. Note that TrueOS Desktop orders the directories the other way around, giving operating system data files priority over "site local" ones. This ordering, on the other hand, is the ordering that is used in the XDG Desktop Specification.

XDG_DATA_HOME

Unset, so that applications use the default of $HOME/.local/share.

Desktop Bus variables

The following environment variables are set if the --set-dbus command-line option is used:

DBUS_SESSION_BUS_ADDRESS

Set to unix:path=/run/user/username/bus. (In practice, unix:runtime=yes is not actually supported yet by most operating systems.)

Other variables

If the --set-other command-line option is used, all environment variables are set from the setenv capability in the login.conf(5) database. Both the system and user databases are processed. In line with the behaviour of login(1), any conflicting environment variables set here will be overridden by the variables taken from other capabilities and from the user account database, with the exceptions of the tools, XDG, and Desktop Bus variables, which will conversely be overriden by any settings here. This ordering is because the tools, XDG, and Desktop Bus variables are an extension, setting variables for which people will have been using setenv.

bugs and compatibility

As of version 1.34 this program no longer employs the GNU C library nor the BSD C library for environment variable handling. The previously documented workaround for those libraries' have memory leaks in their setenv(3) and clearenv(3) functions, is therefore no longer necessary.

The FreeBSD login_getpath(3) library function has a bug that makes it impossible to specify paths containing space characters. This command implements the OpenBSD mechanism of allowing space characters, in the path and manpath capabilities, to be escaped with a backslash.

The FreeBSD login_getcaplist(3) library function has several bugs, one of which makes it impossible to specify paths containing comma characters. This command implements the OpenBSD mechanism of allowing comma characters, in the setenv capability, to be escaped with a backslash.

In both cases, the backslash must be itself escaped again in the actual capability file text, as this is two levels of escaping. First the comma/space is escaped to make an escape sequence in the unencoded capability string, then the capability string is encoded with a second level of escaping in order to store it as text in the capability file.

Unlike the OpenBSD behaviour, this command does not restrict the expansion of ~ and $ to certain places in the aforementioned environment list and path strings. To include literal tildes and dollar characters anywhere in environment lists and paths, those characters too must always be (double) escaped with a backslash.

See also

  • machineenv(1)

  • setenv(1)

  • envuidgid(1)

  • clearenv(1)

Author

Jonathan de Boyne Pollard