Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
update-alternatives(1)		  dpkg suite		update-alternatives(1)

NAME
       update-alternatives  -  maintain	 symbolic  links  determining  default
       commands

SYNOPSIS
       update-alternatives [option...] command

DESCRIPTION
       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	 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 /usr/local/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 (remove and deconfigure) 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-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-alternatives
       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 /usr/local/etc/alternatives, containing
	      the symlinks.

       administrative directory
	      A	directory, by  default	/var/db/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
	      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 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
	      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 --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.

       --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
	      alternatives 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 priority installed
	      alternatives.

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

       --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  auto  or	manual), 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  --get-selections  and  reconfigure	  them
	      accordingly (since version 1.15.0).

       --query name
	      Display  information  about  the link group like --display does,
	      but in a	machine	 parseable  way	 (since	 version  1.15.0,  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 (since version 1.15.0), when this is to
	      be different from	the default (/var/log/alternatives.log).

       --force
	      Allow replacing or dropping 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	is being done.

       --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
       /usr/local/etc/alternatives/
	      The  default  alternatives  directory.  Can be overridden	by the
	      --altdir option.

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

QUERY FORMAT
       The  --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:

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

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

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

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

1.18.24				  2017-05-17		update-alternatives(1)

NAME | SYNOPSIS | DESCRIPTION | TERMINOLOGY | COMMANDS | OPTIONS | EXIT STATUS | ENVIRONMENT | FILES | QUERY FORMAT | DIAGNOSTICS | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=update-alternatives&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help