1 files changed, 637 insertions, 0 deletions
diff --git a/man/update-alternatives.pod b/man/update-alternatives.pod
new file mode 100644
index 0000000..9dee3d6
--- /dev/null
+++ b/man/update-alternatives.pod
@@ -0,0 +1,637 @@
+# 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> I<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> I<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>» if B<%ADMINDIR_ENVVAR%> has not
+been set.
+
+=item B<--instdir> I<directory>
+
+Specifies the installation directory where alternatives links will be created
+(since version 1.20.1).
+Defaults to «I</>» if B<%INSTDIR_ENVVAR%> has not been set.
+
+=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 «I</>» if B<%INSTDIR_ENVVAR%> has not been set.
+
+=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<%INSTDIR_ENVVAR%>
+
+If set and the B<--instdir> or B<--root> options have not been
+specified, it will be used as the filesystem root directory.
+
+=item B<%ADMINDIR_ENVVAR%>
+
+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 stanzas where I<n> is
+the number of alternatives available in the queried link group. The first
+stanza 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 stanzas describe the available alternatives in the queried
+link group:
+
+=over
+
+=item B<Alternative:> I<path-of-this-alternative>
+
+Path to this stanza'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).