diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/update-alternatives.pod | |
parent | Initial commit. (diff) | |
download | dpkg-b86570f63e533abcbcb97c2572e0e5732a96307b.tar.xz dpkg-b86570f63e533abcbcb97c2572e0e5732a96307b.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/update-alternatives.pod')
-rw-r--r-- | man/update-alternatives.pod | 630 |
1 files changed, 630 insertions, 0 deletions
diff --git a/man/update-alternatives.pod b/man/update-alternatives.pod new file mode 100644 index 0000000..7f3e0e6 --- /dev/null +++ b/man/update-alternatives.pod @@ -0,0 +1,630 @@ +# dpkg manual page - update-alternatives(1) +# +# Copyright © 1997-1998 Charles Briscoe-Smith +# Copyright © 1999 Ben Collins <bcollins@debian.org> +# Copyright © 2000 Wichert Akkerman <wakkerma@debian.org> +# Copyright © 2003 Adam Heath <doogie@debian.org> +# Copyright © 2005 Scott James Remnant <scott@netsplit.com> +# Copyright © 2006-2015 Guillem Jover <guillem@debian.org> +# Copyright © 2008 Pierre Habouzit <madcoder@debian.org> +# Copyright © 2009-2011 Raphaël Hertzog <hertzog@debian.org> +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +=encoding utf8 + +=head1 NAME + +update-alternatives - maintain symbolic links determining default commands + +=head1 SYNOPSIS + +B<update-alternatives> +[I<option>...] I<command> + +=head1 DESCRIPTION + +B<update-alternatives> +creates, removes, maintains and displays information about the symbolic +links comprising the Debian alternatives system. + +It is possible for several programs fulfilling the same or similar +functions to be installed on a single system at the same time. +For example, many systems have several text editors installed at once. +This gives choice to the users of a system, allowing each to use a +different editor, if desired, but makes it difficult for a program +to make a good choice for an editor to invoke if the +user has not specified a particular preference. + +Debian's alternatives system aims to solve this problem. +A generic name in the filesystem is +shared by all files providing interchangeable functionality. +The alternatives system and the system administrator +together determine which actual file is referenced by this generic name. +For example, if the text editors +B<ed>(1) +and +B<nvi>(1) +are both installed on the system, the alternatives system will cause +the generic name +I</usr/bin/editor> +to refer to +I</usr/bin/nvi> +by default. The system administrator can override this and cause +it +to refer to +I</usr/bin/ed> +instead, +and the alternatives system will not alter this setting until explicitly +requested to do so. + +The generic name is not a direct symbolic link to the selected alternative. +Instead, it is a symbolic link to a name in the +I<alternatives> +I<directory>, +which in turn is a symbolic link to the actual file referenced. +This is done so that the system administrator's changes can be confined +within the +I<%CONFDIR%> +directory: the FHS (q.v.) gives reasons why this is a Good Thing. + +When each package +providing a file with a particular functionality is +installed, changed or removed, +B<update-alternatives> +is called to update information about that file in the alternatives system. +B<update-alternatives> +is usually called from the following Debian package maintainer scripts, +B<postinst> +(configure) to install the alternative and from +B<prerm> and B<postrm> +(remove) to remove the alternative. +B<Note:> in most (if not all) cases no other maintainer script actions should +call B<update-alternatives>, in particular neither of B<upgrade> nor +B<disappear>, as any other such action can lose the manual state of an +alternative, or make the alternative temporarily flip-flop, or completely +switch when several of them have the same priority. + +It is often useful for a number of alternatives to be synchronized, +so that they are changed as a group; for example, when several versions +of the +B<vi>(1) +editor are installed, the man page referenced by +I</usr/share/man/man1/vi.1> +should correspond to the executable referenced by +I</usr/bin/vi>. +B<update-alternatives> +handles this by means of +I<master> +and +I<slave> +links; when the master is changed, any associated slaves are changed +too. +A master link and its associated slaves make up a +I<link> +I<group>. + +Each link group is, at any given time, +in one of two modes: automatic or manual. +When a group is in automatic mode, the alternatives system will +automatically decide, as packages are installed and removed, +whether and how to update the links. +In manual mode, the alternatives system will retain the choice of +the administrator and avoid changing the links (except when something is +broken). + +Link groups are in automatic mode when they are first introduced to +the system. +If the system administrator makes changes to the system's +automatic settings, +this will be noticed the next time +B<update-alternatives> +is run on the changed link's group, +and the group will automatically be switched to manual mode. + +Each alternative has a +I<priority> +associated with it. +When a link group is in automatic mode, +the alternatives pointed to by members of the group +will be those which have the highest priority. + +When using the +B<--config> +option, +B<update-alternatives> +will list all of the choices for the link group +of which given +I<name> +is the master alternative name. +The current choice is marked with a ‘*’. +You will then be prompted for your choice regarding this link group. +Depending on the choice made, the link group might no longer be in +I<auto> +mode. You will need to use the +B<--auto> +option in order to return to the automatic mode (or you can rerun +B<--config> +and select the entry marked as automatic). + +If you want to configure non-interactively you can use the +B<--set> +option instead (see below). + +Different packages providing the same file need to do so +B<cooperatively>. +In other words, the usage of +B<update-alternatives> +is +B<mandatory> +for all involved packages in such case. It is not possible to +override some file in a package that does not employ the +B<update-alternatives> +mechanism. + +=head1 TERMINOLOGY + +Since the activities of +B<update-alternatives> +are quite involved, some specific terms will help to explain its +operation. + +=over + +=item generic name (or alternative link) + +A name, like +I</usr/bin/editor>, +which refers, via the alternatives system, to one of a number of +files of similar function. + +=item alternative name + +The name of a symbolic link in the alternatives directory. + +=item alternative (or alternative path) + +The name of a specific file in the filesystem, which may be made +accessible via a generic name using the alternatives system. + +=item alternatives directory + +A directory, by default +I<%CONFDIR%/alternatives>, +containing the symlinks. + +=item administrative directory + +A directory, by default +I<%ADMINDIR%/alternatives>, +containing +B<update-alternatives>' +state information. + +=item link group + +A set of related symlinks, intended to be updated as a group. + +=item master link + +The alternative link in a link group which determines how the other links in the +group are configured. + +=item slave link + +An alternative link in a link group which is controlled by the setting of +the master link. + +=item automatic mode + +When a link group is in automatic mode, +the alternatives system ensures that the links in the group +point to the highest priority alternative +appropriate for the group. + +=item manual mode + +When a link group is in manual mode, +the alternatives system will not make any changes +to the system administrator's settings. + +=back + +=head1 COMMANDS + +=over + +=item B<--install> I<link name path priority> [B<--slave> I<link name path>]... + +Add a group of alternatives to the system. +I<link> +is the generic name for the master link, +I<name> +is the name of its symlink in the alternatives directory, and +I<path> +is the alternative being introduced for the master link. +The arguments after B<--slave> are the generic name, symlink name in the +alternatives directory and the alternative path for a slave link. +Zero or more +B<--slave> +options, each followed by three arguments, +may be specified. Note that the master alternative must exist or the call +will fail. However if a slave alternative doesn't exist, the corresponding +slave alternative link will simply not be installed (a warning will still +be displayed). If some real file is installed where an alternative link +has to be installed, it is kept unless B<--force> is used. + +If the alternative name specified exists already +in the alternatives system's records, +the information supplied will be added as a new +set of alternatives for the group. +Otherwise, a new group, set to automatic mode, +will be added with this information. +If the group is in automatic mode, +and the newly added alternatives' priority is higher than +any other installed alternatives for this group, +the symlinks will be updated to point to the newly added alternatives. + +=item B<--set> I<name path> + +Set the program +I<path> +as alternative for +I<name>. +This is equivalent to +B<--config> +but is non-interactive and thus scriptable. + +=item B<--remove> I<name path> + +Remove an alternative and all of its associated slave links. +I<name> +is a name in the alternatives directory, and +I<path> +is an absolute filename to which +I<name> +could be linked. If +I<name> +is indeed linked to +I<path>, +I<name> +will be updated to point to another appropriate alternative +(and the group is put back in automatic mode), or +removed if there is no such alternative left. +Associated slave links will be updated or removed, correspondingly. +If the link is not currently pointing to +I<path>, +no links are changed; +only the information about the alternative is removed. + +=item B<--remove-all> I<name> + +Remove all alternatives and all of their associated slave links. +I<name> +is a name in the alternatives directory. + +=item B<--all> + +Call B<--config> on all alternatives. It can be usefully combined with +B<--skip-auto> to review and configure all alternatives which are +not configured in automatic mode. Broken alternatives are also displayed. +Thus a simple way to fix all broken alternatives is to call +B<yes '' | update-alternatives --force --all>. + +=item B<--auto> I<name> + +Switch the link group behind the alternative for +I<name> +to automatic mode. +In the process, the master symlink and its slaves are updated +to point to the highest priority installed alternatives. + +=item B<--display> I<name> + +Display information about the link group. +Information displayed includes the group's mode +(auto or manual), +the master and slave links, +which alternative the master link currently points to, +what other alternatives are available +(and their corresponding slave alternatives), +and the highest priority alternative currently installed. + +=item B<--get-selections> + +List all master alternative names (those controlling a link group) +and their status (since version 1.15.0). +Each line contains up to 3 fields (separated by +one or more spaces). The first field is the alternative name, the second +one is the status (either B<auto> or B<manual>), and the last one contains +the current choice in the alternative (beware: it's a filename and thus +might contain spaces). + +=item B<--set-selections> + +Read configuration of alternatives on standard input in the format +generated by B<--get-selections> and reconfigure +them accordingly (since version 1.15.0). + +=item B<--query> I<name> + +Display information about the link group +like B<--display> does, but in a machine parseable way +(since version 1.15.0, see section B<QUERY FORMAT> below). + +=item B<--list> I<name> + +Display all targets of the link group. + +=item B<--config> I<name> + +Show available alternatives for a link group and allow the user to +interactively select which one to use. The link group is updated. + +=item B<--help> + +Show the usage message and exit. + +=item B<--version> + +Show the version and exit. + +=back + +=head1 OPTIONS + +=over + +=item B<--altdir> I<directory> + +Specifies the alternatives directory, when this is to be +different from the default. +Defaults to «I<%CONFDIR%/alternatives>». + +=item B<--admindir> I<directory> + +Specifies the administrative directory, when this is to be +different from the default. +Defaults to «I<%ADMINDIR%/alternatives>» + +=item B<--instdir> I<directory> + +Specifies the installation directory where alternatives links will be created +(since version 1.20.1). +Defaults to «». + +=item B<--root> I<directory> + +Specifies the root directory (since version 1.20.1). +This also sets the alternatives, installation and administrative +directories to match. +Defaults to «». + +=item B<--log> I<file> + +Specifies the log file (since version 1.15.0), when this is to be different +from the default (%LOGDIR%/alternatives.log). + +=item B<--force> + +Allow replacing or dropping any real file that is installed +where an alternative link has to be installed or removed. + +=item B<--skip-auto> + +Skip configuration prompt for alternatives which are properly configured +in automatic mode. This option is only relevant with B<--config> or +B<--all>. + +=item B<--quiet> + +Do not generate any comments unless errors occur. + +=item B<--verbose> + +Generate more comments about what is being done. + +=item B<--debug> + +Generate even more comments, helpful for debugging, about what is being done +(since version 1.19.3). + +=back + +=head1 EXIT STATUS + +=over + +=item B<0> + +The requested action was successfully performed. + +=item B<2> + +Problems were encountered whilst parsing the command line +or performing the action. + +=back + +=head1 ENVIRONMENT + +=over + +=item B<DPKG_ADMINDIR> + +If set and the B<--admindir> option has not been specified, it will +be used as the base administrative directory. + +=back + +=head1 FILES + +=over + +=item I<%CONFDIR%/alternatives/> + +The default alternatives directory. +Can be overridden by the +B<--altdir> +option. + +=item I<%ADMINDIR%/alternatives/> + +The default administration directory. +Can be overridden by the +B<--admindir> +option. + +=back + +=head1 QUERY FORMAT + +The B<--query> format is using an +RFC822-like flat format. It's made of I<n> + 1 blocks where I<n> is +the number of alternatives available in the queried link group. The first +block contains the following fields: + +=over + +=item B<Name:> I<name> + +The alternative name in the alternative directory. + +=item B<Link:> I<link> + +The generic name of the alternative. + +=item B<Slaves:> I<list-of-slaves> + +When this field is present, the B<next> lines hold all slave links +associated to the master link of the alternative. There is one slave per +line. Each line contains one space, the generic name of the slave +alternative, another space, and the path to the slave link. + +=item B<Status:> I<status> + +The status of the alternative (B<auto> or B<manual>). + +=item B<Best:> I<best-choice> + +The path of the best alternative for this link group. Not present if +there is no alternatives available. + +=item B<Value:> I<currently-selected-alternative> + +The path of the currently selected alternative. It can also take the magic +value B<none>. It is used if the link doesn't exist. + +=back + +The other blocks describe the available alternatives in the queried link group: + +=over + +=item B<Alternative:> I<path-of-this-alternative> + +Path to this block's alternative. + +=item B<Priority:> I<priority-value> + +Value of the priority of this alternative. + +=item B<Slaves:> I<list-of-slaves> + +When this field is present, the B<next> lines hold all slave alternatives +associated to the master link of the alternative. There is one slave per +line. Each line contains one space, the generic name of the slave +alternative, another space, and the path to the slave alternative. + +=back + +=head2 Example + + $ update-alternatives --query editor + Name: editor + Link: /usr/bin/editor + Slaves: + editor.1.gz /usr/share/man/man1/editor.1.gz + editor.fr.1.gz /usr/share/man/fr/man1/editor.1.gz + editor.it.1.gz /usr/share/man/it/man1/editor.1.gz + editor.pl.1.gz /usr/share/man/pl/man1/editor.1.gz + editor.ru.1.gz /usr/share/man/ru/man1/editor.1.gz + Status: auto + Best: /usr/bin/vim.basic + Value: /usr/bin/vim.basic + + Alternative: /bin/ed + Priority: -100 + Slaves: + editor.1.gz /usr/share/man/man1/ed.1.gz + + Alternative: /usr/bin/vim.basic + Priority: 50 + Slaves: + editor.1.gz /usr/share/man/man1/vim.1.gz + editor.fr.1.gz /usr/share/man/fr/man1/vim.1.gz + editor.it.1.gz /usr/share/man/it/man1/vim.1.gz + editor.pl.1.gz /usr/share/man/pl/man1/vim.1.gz + editor.ru.1.gz /usr/share/man/ru/man1/vim.1.gz + +=head1 DIAGNOSTICS + +With B<--verbose> +B<update-alternatives> +chatters incessantly about its activities on its standard output channel. +If problems occur, +B<update-alternatives> +outputs error messages on its standard error channel and +returns an exit status of 2. +These diagnostics should be self-explanatory; +if you do not find them so, please report this as a bug. + +=head1 EXAMPLES + +There are several packages which provide a text editor compatible +with B<vi>, for example B<nvi> and B<vim>. Which one is used +is controlled by the link group B<vi>, which includes links for the +program itself and the associated manpage. + +To display the available packages which provide B<vi> and the current +setting for it, use the B<--display> action: + +=over + + update-alternatives --display vi + +=back + +To choose a particular B<vi> implementation, use this command as root +and then select a number from the list: + +=over + + update-alternatives --config vi + +=back + +To go back to having the B<vi> implementation chosen automatically, do +this as root: + +=over + + update-alternatives --auto vi + +=back + +=head1 SEE ALSO + +B<ln>(1), +FHS (the Filesystem Hierarchy Standard). |