update-alternatives man page on Debian

Man page or keyword search:  
man Server   8174 pages
apropos Keyword Search (all sections)
Output format
Debian logo
[printable version]

update-alternatives(8)		dpkg utilities		update-alternatives(8)

NAME
       update-alternatives  - maintain symbolic links determining default com‐
       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,
       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  update-alterna‐
       tives  is run on the changed link's group, and the group will automati‐
       cally be switched to manual mode.

       Each alternative has a 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 --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
	      When a link group is in automatic mode, the alternatives	system
	      ensures  that the links in the group point to the highest prior‐
	      ity alternative appropriate for the group.

       manual mode
	      When a link group is in manual  mode,  the  alternatives	system
	      will  not	 make  any  changes to the system administrator's set‐
	      tings.

COMMANDS
       --install link name path priority [--slave link name path]...
	      Add a group of alternatives to the system.  link is the  generic
	      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
	      Display information about the link group.	 Information displayed
	      includes	the  group's  mode (auto or manual), 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.

       --get-selections
	      List all master alternative  names  (those  controlling  a  link
	      group) and their status. Each line contains up to 3 fields (sep‐
	      arated by one or more spaces). The first field is	 the  alterna‐
	      tive  name, the second one is the status (either "auto" or "man‐
	      ual"), and the last one  contains	 the  current  choice  in  the
	      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/alternatives.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
       /etc/alternatives/
	      The  default  alternatives  directory.  Can be overridden by the
	      --altdir option.

       /var/lib/dpkg/alternatives/
	      The default administration directory.  Can be overridden by  the
	      --admindir option.

EXIT STATUS
       0      The requested action was successfully performed.

       2      Problems	were  encountered  whilst  parsing the command line or
	      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
	      Slaves:
	       editor.1.gz /usr/share/man/man1/vim.1.gz
	       editor.ru.1.gz /usr/share/man/ru/man1/vim.1.gz
	       editor.pl.ISO8859-2.1.gz /usr/share/man/pl.ISO8859-2/man1/vim.1.gz
	       editor.it.ISO8859-1.1.gz /usr/share/man/it.ISO8859-1/man1/vim.1.gz
	       editor.pl.UTF-8.1.gz /usr/share/man/pl.UTF-8/man1/vim.1.gz
	       editor.it.1.gz /usr/share/man/it/man1/vim.1.gz
	       editor.fr.UTF-8.1.gz /usr/share/man/fr.UTF-8/man1/vim.1.gz
	       editor.fr.1.gz /usr/share/man/fr/man1/vim.1.gz
	       editor.it.UTF-8.1.gz /usr/share/man/it.UTF-8/man1/vim.1.gz
	       editor.pl.1.gz /usr/share/man/pl/man1/vim.1.gz
	       editor.fr.ISO8859-1.1.gz /usr/share/man/fr.ISO8859-1/man1/vim.1.gz

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 © 1995 Ian Jackson
       Copyright © 2009 Raphaël 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.

Debian Project			  2009-04-13		update-alternatives(8)
[top]

List of man pages available for Debian

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net