update-alternatives man page on Hurd

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

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

NAME
       update-alternatives  - maintain symbolic links determining default com‐
       mands

SYNOPSIS
       update-alternatives [option...] 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 synchronized,  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 or drop any real	file  that  is
	      installed	 where	an  alternative	 link  has  to be installed or
	      removed.

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

EXIT STATUS
       0      The requested action was successfully performed.

       2      Problems were encountered whilst parsing	the  command  line  or
	      performing the action.

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.

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:

       Name: name
	      The alternative name in the alternative directory.

       Link: link
	      The generic name of the alternative.

       Slaves: list-of-slaves
	      When  this field is present, the 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.

       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 field is present, the next lines hold all slave
	      alternatives  associated to the master link of the alter‐
	      native. 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.

       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

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

SEE ALSO
       ln(1), FHS, the Filesystem Hierarchy Standard.

Debian Project			  2012-07-31		update-alternatives(8)
[top]

List of man pages available for Hurd

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