update-alternatives

       mands

SYNOPSIS
       update-alternatives [options] command

DESCRIPTION
       update-alternatives creates, removes, maintains and  displays  informa-
       tion  about  the symbolic links comprising the Debian alternatives sys-
       tem.

       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 dif-
       ferent 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  ed(1)  and  nvi(1)  are  both
       installed on the system, the alternatives system will cause the generic
       name /usr/bin/editor to refer to /usr/bin/nvi by  default.  The  system
       administrator  can  override  this and cause it to refer to /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 alterna-
       tive.  Instead, it is a symbolic link to a  name  in  the  alternatives
       directory,  which  in turn is a symbolic link to the actual file refer-
       enced.  This is done so that the system administrator's changes can  be
       confined  within  the  /etc 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, update-alternatives is called to update
       information about that file in the alternatives system.   update-alter-
       natives  is  usually  called  from  the  postinst  (configure) or prerm
       (install) scripts in Debian packages.

       It is often useful for a number of alternatives to be synchronised,  so
       that they are changed as a group; for example, when several versions of
       the  vi(1)  editor  are  installed,  the   man   page   referenced   by
       /usr/share/man/man1/vi.1 should correspond to the executable referenced
       by /usr/bin/vi.  update-alternatives handles this by  means  of  master
       and  slave links; when the master is changed, any associated slaves are
       changed too.  A master link and its associated slaves make  up  a  link
       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,
       group will be those which have the highest priority.

       When using the --config option, update-alternatives will  list  all  of
       the choices for the link group of which given name is the master alter-
       native 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 auto mode.  You  will
       need  to use the --auto option in order to return to the automatic mode
       (or you can rerun --config and select the entry marked as automatic).

       If you want to configure non-interactively you can use the --set option
       instead (see below).

       Different packages providing the same file need to do so cooperatively.
       In other words, the usage of update-alternatives is mandatory  for  all
       involved  packages  in  such  case. It is not possible to override some
       file in a package that does not employ the  update-alternatives  mecha-
       nism.

TERMINOLOGY
       Since  the  activities  of update-alternatives are quite involved, some
       specific terms will help to explain its operation.

       generic name (or alternative link)
              A name, like /usr/bin/editor, which refers, via the alternatives
              system, to one of a number of files of similar function.

       alternative name
              The name of a symbolic link in the alternatives directory.

       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.

       alternatives directory
              A directory, by default /etc/alternatives, containing  the  sym-
              links.

       administrative directory
              A  directory,  by default /var/lib/dpkg/alternatives, containing
              update-alternatives' state information.

       link group
              A set of related symlinks, intended to be updated as a group.

       master link
              The alternative link in a link group which  determines  how  the
              other links in the group are configured.

       slave link
              An  alternative  link in a link group which is controlled by the
              setting of the master link.

       automatic mode
              name for the master link, name is the name of its symlink in the
              alternatives directory, and path is the alternative being intro-
              duced  for the master link.  The arguments after --slave are the
              generic name, symlink name in the alternatives directory and the
              alternative  path  for  a  slave  link.   Zero  or  more --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  corre-
              sponding  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
              --force is used.

              If the alternative name specified exists already in the alterna-
              tives  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 informa-
              tion.  If the group is in automatic mode, and  the  newly  added
              alternatives' priority is higher than any other installed alter-
              natives for this group, the symlinks will be updated to point to
              the newly added alternatives.

       --set name path
              Set  the  program path as alternative for name.  This is equiva-
              lent to --config but is non-interactive and thus scriptable.

       --remove name path
              Remove an alternative and all of  its  associated  slave  links.
              name  is  a  name  in the alternatives directory, and path is an
              absolute filename to which name could  be  linked.  If  name  is
              indeed  linked to path, 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.  Associ-
              ated slave links will be updated  or  removed,  correspondingly.
              If  the  link  is  not  currently pointing to path, no links are
              changed; only the information about the alternative is removed.

       --remove-all name
              Remove all alternatives and all of their associated slave links.
              name is a name in the alternatives directory.

       --all  Call  --config  on all alternatives. It can be usefully combined
              with --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  alterna-
              tives is to call yes '' | update-alternatives --force --all.

       --auto name
              Switch  the  link group behind the alternative for name to auto-
              matic mode.  In the process, the master symlink and  its  slaves
              are  updated to point to the highest priority installed alterna-
              tives.

       --display name
              alternative (beware: it's a filename and thus might contain spa-
              ces).

       --set-selections
              Read configuration of alternatives on standard input in the for-
              mat generated by update-alternatives --get-selections and recon-
              figure them accordingly.

       --query name
              Display information about the link group  like  --display  does,
              but in a machine parseable way (see section QUERY FORMAT below).

       --list name
              Display all targets of the link group.

       --config name
              Show  available alternatives for a link group and allow the user
              to interactively select which one to  use.  The  link  group  is
              updated.

       --help Show the usage message and exit.

       --version
              Show the version and exit.

OPTIONS
       --altdir directory
              Specifies the alternatives directory, when this is to be differ-
              ent from the default.

       --admindir directory
              Specifies the administrative directory, when this is to be  dif-
              ferent from the default.

       --log file
              Specifies  the  log  file, when this is to be different from the
              default (/var/log/dpkg.log).

       --force
              Let update-alternatives replace any real file that is  installed
              where an alternative link has to be installed.

       --skip-auto
              Skip  configuration  prompt  for alternatives which are properly
              configured in automatic mode. This option is only relevant  with
              --config or --all.

       --verbose
              Generate more comments about what update-alternatives is doing.

       --quiet
              Don't generate any comments unless errors occur.

FILES
              performing the action.

QUERY FORMAT
       The update-alternatives --query format is  using  an  RFC822-like  flat
       format. It's made of n + 1 blocks where n is the number of alternatives
       available in the queried link group. The first block contains the  fol-
       lowing fields:

       Link: <link>
              The generic name of the alternative.

       Status: <status>
              The status of the alternative (auto or manual).

       Best: <best choice>
              The  path  of  the  best  alternative  for  this link group. Not
              present if there is no alternatives available.

       Value: <currently selected alternative>
              The path of the currently selected alternative. It can also take
              the magic value none. It is used if the link doesn't exist.


       The  other  blocks  describe  the  available alternatives in the
       queried link group:

       Alternative: <path of this alternative>
              Path to this block's alternative.

       Priority: <priority value>
              Value of the priority of this alternative.

       Slaves: <list of slaves>
              When this header is present,  the  next  lines  hold  all
              slave  alternatives  associated to the master link of the
              alternative. There is one slave per line. Each line  con-
              tains  one  space, the generic name of the slave alterna-
              tive, another space, and the path to the  slave  alterna-
              tive.

       Example
              $ update-alternatives --query editor
              Link: editor
              Status: auto
              Best: /usr/bin/vim.gtk
              Value: /usr/bin/vim.gtk

              Alternative: /bin/ed
              Priority: -100
              Slaves:
               editor.1.gz /usr/share/man/man1/ed.1.gz

              Alternative: /usr/bin/vim.gtk
              Priority: 50

DIAGNOSTICS
       With  --verbose  update-alternatives  chatters incessantly about
       its activities on its  standard  output  channel.   If  problems
       occur,  update-alternatives  outputs error messages on its stan-
       dard error channel and returns an exit status of 2.  These diag-
       nostics  should be self-explanatory; if you do not find them so,
       please report this as a bug.

EXAMPLES
       There are several packages which provide a text editor  compati-
       ble  with vi, for example nvi and vim. Which one is used is con-
       trolled by the link group vi, which includes links for the  pro-
       gram itself and the associated manpage.

       To  display the available packages which provide vi and the cur-
       rent setting for it, use the --display action:

              update-alternatives --display vi

       To choose a particular vi implementation, use  this  command  as
       root and then select a number from the list:

              update-alternatives --config vi

       To go back to having the vi implementation chosen automatically,
       do this as root:

              update-alternatives --auto vi

BUGS
       If you find a bug, please report it using the Debian  bug-track-
       ing system.

       If   you   find   any   discrepancy  between  the  operation  of
       update-alternatives and this manual page, it is a bug, either in
       the implementation or the documentation; please report it.

AUTHORS
       Copyright (C) 1995 Ian Jackson
       Copyright (C) 2009 Raphael Hertzog

       This  is  free software; see the GNU General Public Licence ver-
       sion 2 or later for copying conditions. There is NO WARRANTY.

       This manual page is copyright  1997,1998  Charles  Briscoe-Smith
       and others.

       This  is  free documentation; see the GNU General Public Licence
       version 2 or later for copying conditions. There is NO WARRANTY.

SEE ALSO
       ln(1), FHS, the Filesystem Hierarchy Standard.
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2014 Hurricane Electric. All Rights Reserved.