Unix/Linux Go Back    


Linux 2.6 - man page for update-alternatives (linux section 8)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

NAME
       update-alternatives - maintain symbolic links determining default commands

SYNOPSIS
       update-alternatives [options] command

DESCRIPTION
       update-alternatives  creates,  removes,	maintains and displays information about the sym-
       bolic 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 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 alternative.  Instead, it
       is a symbolic link to a name in the alternatives 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 /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-alternatives 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-alternatives  is run on the changed link's group, and the
       group will automatically 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 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 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-alter-
       natives mechanism.

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 symlinks.

       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  mas-
	      ter 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 priority 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 settings.

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 introduced for the master link.  The arguments after  --slave
	      are  the	generic name, symlink name in the alternatives directory and the alterna-
	      tive 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  corresponding
	      slave  alternative  link will simply not be installed (a warning will still be dis-
	      played). 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 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 sym-
	      links will be updated to point to the newly added alternatives.

       --set name path
	      Set the program path as alternative for name.  This is equivalent 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.	Associated 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 alter-
	      natives is to call yes '' | update-alternatives --force --all.

       --auto name
	      Switch  the  link  group behind the alternative for name to automatic mode.  In the
	      process, the master symlink and its slaves are updated to point to the highest pri-
	      ority installed alternatives.

       --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 alterna-
	      tives), and the highest priority alternative currently installed.

       --get-selections
	      List all master alternative names (those controlling a link group) and  their  sta-
	      tus. 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 "auto" or "man-
	      ual"),  and  the	last  one contains the current choice in the alternative (beware:
	      it's a filename and thus might contain spaces).

       --set-selections
	      Read configuration of alternatives on standard input in  the  format  generated  by
	      update-alternatives --get-selections and reconfigure 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 different from the
	      default.

       --admindir directory
	      Specifies the administrative directory, when this  is  to  be  different	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  alterna-
	      tive link has to be installed.

       --skip-auto
	      Skip  configuration  prompt for alternatives which are properly configured in auto-
	      matic 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.

ENVIRONMENT
       DPKG_ADMINDIR
	      If set and the --admindir option has not been specified, it will	be  used  as  the
	      base administrative directory.

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 following 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 contains one space, the generic name of the slave alterna-
	      tive, another space, and the path to the slave alternative.

       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 mes-
       sages on its standard 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	compatible  with  vi,  for
       example	nvi  and  vim. Which one is used is controlled by the link group vi, which
       includes links for the program itself and the associated manpage.

       To display the available packages which provide vi and the current 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-tracking 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 version 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				    2011-03-04			   update-alternatives(8)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:17 PM.