1UPDATE-ALTERNATIVES(8)      System Manager's Manual     UPDATE-ALTERNATIVES(8)
2
3
4

NAME

6       alternatives - maintain symbolic links determining default commands
7

SYNOPSIS

9       alternatives  [options] --install link name path priority [--slave link
10       name path]...  [--initscript service] [--family name]
11
12       alternatives [options] --remove name path
13
14       alternatives [options] --set name path
15
16       alternatives [options] --auto name
17
18       alternatives [options] --display name
19
20       alternatives [options] --config name
21
22       alternatives [options] --list
23
24       alternatives [options] --remove-all name
25
26       alternatives [options] --add-slave name path slink sname spath
27
28       alternatives [options] --remove-slave name path sname
29

DESCRIPTION

31       alternatives creates, removes, maintains and displays information about
32       the symbolic links comprising the alternatives system. The alternatives
33       system is a reimplementation of the Debian alternatives system. It  was
34       rewritten primarily to remove the dependence on perl; it is intended to
35       be a drop in replacement for Debian's update-dependencies script.  This
36       man page is a slightly modified version of the man page from the Debian
37       project.
38
39       It is possible for several programs  fulfilling  the  same  or  similar
40       functions  to  be  installed  on a single system at the same time.  For
41       example, many systems have several  text  editors  installed  at  once.
42       This gives choice to the users of a system, allowing each to use a dif‐
43       ferent editor, if desired, but makes it difficult for a program to make
44       a  good choice of editor to invoke if the user has not specified a par‐
45       ticular preference.
46
47       The alternatives system aims to solve this problem.  A generic name  in
48       the  filesystem  is shared by all files providing interchangeable func‐
49       tionality.   The  alternatives  system  and  the  system  administrator
50       together  determine  which  actual  file  is referenced by this generic
51       name.  For example, if the text  editors  ed(1)  and  nvi(1)  are  both
52       installed on the system, the alternatives system will cause the generic
53       name /usr/bin/editor to refer to /usr/bin/nvi by default.   The  system
54       administrator  can  override  this and cause it to refer to /usr/bin/ed
55       instead, and the alternatives system will not alter this setting  until
56       explicitly requested to do so.
57
58       The generic name is not a direct symbolic link to the selected alterna‐
59       tive.  Instead, it is a symbolic link to a  name  in  the  alternatives
60       directory,  which  in turn is a symbolic link to the actual file refer‐
61       enced.  This is done so that the system administrator's changes can  be
62       confined  within  the  /etc directory: the FHS (q.v.) gives reasons why
63       this is a Good Thing.
64
65       When each package providing a file with a particular  functionality  is
66       installed,  changed or removed, alternatives is called to update infor‐
67       mation about that file in the  alternatives  system.   alternatives  is
68       usually called from the %post or %pre scripts in RPM packages.
69
70       It  is often useful for a number of alternatives to be synchronised, so
71       that they are changed as a group; for example, when several versions of
72       the   vi(1)   editor   are   installed,  the  man  page  referenced  by
73       /usr/share/man/man1/vi.1 should correspond to the executable referenced
74       by /usr/bin/vi.  alternatives handles this by means of master and slave
75       links; when the master is changed, any associated  slaves  are  changed
76       too.  A master link and its associated slaves make up a link group.
77
78       Each  link  group is, at any given time, in one of two modes: automatic
79       or manual.  When a group is in automatic mode, the alternatives  system
80       will  automatically  decide,  as  packages  are  installed and removed,
81       whether and how to update the links.  In manual mode, the  alternatives
82       system  will  not  change the links; it will leave all the decisions to
83       the system administrator.
84
85       Link groups are in automatic mode when they are first introduced to the
86       system.   If  the  system  administrator  makes changes to the system's
87       automatic settings, this will be noticed the next time alternatives  is
88       run  on  the  changed link's group, and the group will automatically be
89       switched to manual mode.
90
91       Each alternative has a priority associated with it.  When a link  group
92       is  in  automatic  mode,  the alternatives pointed to by members of the
93       group will be those which have the highest priority.
94
95       When using the --config option,  alternatives  will  list  all  of  the
96       choices for the link group of which given name is the master link.  You
97       will then be prompted for which of the choices  to  use  for  the  link
98       group. Once you make a change, the link group will no longer be in auto
99       mode. You will need to use the --auto option in order to return to  the
100       automatic state.
101

TERMINOLOGY

103       Since  the activities of alternatives are quite involved, some specific
104       terms will help to explain its operation.
105
106       generic name
107              A name, like /usr/bin/editor, which refers, via the alternatives
108              system, to one of a number of files of similar function.
109
110       symlink
111              Without any further qualification, this means a symbolic link in
112              the alternatives directory: one which the  system  administrator
113              is expected to adjust.
114
115       alternative
116              The name of a specific file in the filesystem, which may be made
117              accessible via a generic name using the alternatives system.
118
119       alternatives directory
120              A directory, by default /etc/alternatives, containing  the  sym‐
121              links.
122
123       administrative directory
124              A directory, by default /var/lib/alternatives, containing alter‐
125              natives' state information.
126
127       link group
128              A set of related symlinks, intended to be updated as a group.
129
130       master link
131              The link in a link group which determines how the other links in
132              the group are configured.
133
134       slave link
135              A link in a link group which is controlled by the setting of the
136              master link.
137
138       automatic mode
139              When a link group is in automatic mode, the alternatives  system
140              ensures  that the links in the group point to the highest prior‐
141              ity alternatives appropriate for the group.
142
143       manual mode
144              When a link group is in manual  mode,  the  alternatives  system
145              will  not  make  any  changes to the system administrator's set‐
146              tings.
147

OPTIONS

149       Exactly one action must be specified if alternatives is to perform  any
150       meaningful  task.   Any  number  of the common options may be specified
151       together with any action.
152
153   COMMON OPTIONS
154       --verbose
155              Generate more comments about what alternatives is doing.
156
157       --quiet
158              Don't generate any comments unless errors occur.  This option is
159              not yet implemented.
160
161       --test Don't  actually  do anything, just say what would be done.  This
162              option is not yet implemented.
163
164       --help Give some usage information (and say which version  of  alterna‐
165              tives this is).
166
167       --version
168              Tell  which version of alternatives this is (and give some usage
169              information).
170
171       --keep-missing
172              When switching between alternatives, if the new variant does not
173              provide  some  files,  keep  the  links  pointed to the previous
174              implementation.  It prevents issues with missing  files  due  to
175              switching between versions.
176
177       --altdir directory
178              Specifies the alternatives directory, when this is to be differ‐
179              ent from the default.
180
181       --admindir directory
182              Specifies the administrative directory, when this is to be  dif‐
183              ferent from the default.
184
185   ACTIONS
186       --install   link   name  path  priority  [--slave  slink  sname  spath]
187       [--initscript service]...
188              Add a group of alternatives to the system.  name is the  generic
189              name  for the master link, link is the name of its symlink, path
190              is the alternative being introduced for  the  master  link,  and
191              priority  is the priority of the alternatives group. Higher pri‐
192              orities take precendence if no alternative is manually selected.
193              sname,  slink  and  spath are the generic name, symlink name and
194              alternative for a slave link, and service is  the  name  of  any
195              associated  initscript  for the alternative.  NOTE: --initscript
196              and --family are a Red Hat Linux specific options.  Zero or more
197              --slave options, each followed by three arguments, may be speci‐
198              fied.
199
200              If the master symlink specified exists already in  the  alterna‐
201              tives  system's  records, the information supplied will be added
202              as a new set of alternatives for the group.   Otherwise,  a  new
203              group,  set  to automatic mode, will be added with this informa‐
204              tion.  If the group is in automatic mode, and  the  newly  added
205              alternatives' priority is higher than any other installed alter‐
206              natives for this group, the symlinks will be updated to point to
207              the newly added alternatives.
208
209              If --initscript is used, the alternatives system will manage the
210              initscript associated with the alternative via chkconfig, regis‐
211              tering  and  unregistering  the  init  script depending on which
212              alternative is active.
213
214              NOTE: --initscript is a Red Hat Linux specific option.
215
216
217              --family can be used to group similar alternatives. If the group
218              is in manual mode and the alternative currently used is removed,
219              alternatives will try to change links to different one with same
220              family and highest priority.
221
222              NOTE: --family is a Red Hat Linux specific option.
223
224       --remove name path
225              Remove  an  alternative  and  all of its associated slave links.
226              name is a name in the alternatives directory,  and  path  is  an
227              absolute  filename  to  which  name could be linked.  If name is
228              indeed linked to path, name will be updated to point to  another
229              appropriate alternative, or removed if there is no such alterna‐
230              tive left.  Associated slave links will be updated  or  removed,
231              correspondingly.  If the link is not currently pointing to path,
232              no links are changed; only the information about the alternative
233              is removed.
234
235       --set name path
236              The  symbolic  link  and slaves for link group name set to those
237              configured for path, and the link group is set to  manual  mode.
238              This option is not in the original Debian implementation.
239
240       --config name
241              Present the user with a configuration menu for choosing the mas‐
242              ter link and slaves for link group name. Once chosen,  the  link
243              group is set to manual mode.
244
245       --auto name
246              Switch  the  master  symlink  name  to  automatic  mode.  In the
247              process, this symlink and its slaves are updated to point to the
248              highest priority installed alternatives.
249
250       --display name
251              Display  information  about  the link group of which name is the
252              master link.  Information displayed includes  the  group's  mode
253              (auto or manual), which alternative the symlink currently points
254              to, what other alternatives are available (and their correspond‐
255              ing  slave  alternatives),  and the highest priority alternative
256              currently installed.
257
258       --list Display information about all link groups.
259
260       --remove-all name
261              Remove the whole link group name. Use with caution.
262
263       --add-slave name path slink sname spath
264              Add a slave link to an alternative identified by name and  path.
265              sname,  slink  and  spath are the generic name, symlink name and
266              alternative for the slave.
267
268       --remove-slave name path sname
269              Remove slave with generic name sname from alternative identified
270              by name and path.
271

FILES

273       /etc/alternatives/
274              The  default  alternatives  directory.  Can be overridden by the
275              --altdir option.
276
277       /var/lib/alternatives/
278              The default administration directory.  Can be overridden by  the
279              --admindir option.
280

EXIT STATUS

282       0      The requested action was successfully performed.
283
284       2      Problems  were  encountered  whilst  parsing the command line or
285              performing the action.
286

DIAGNOSTICS

288       alternatives chatters incessantly about its activities on its  standard
289       output channel.  If problems occur, alternatives outputs error messages
290       on its standard error channel and returns an exit status of  2.   These
291       diagnostics  should  be  self-explanatory;  if you do not find them so,
292       please report this as a bug.
293

BUGS

295       If you find a bug, please report it using the Red Hat bug tracking sys‐
296       tem at http://bugzilla.redhat.com.
297
298       If  you  find any discrepancy between the operation of alternatives and
299       this manual page, it is a bug, either in the implementation or the doc‐
300       umentation; please report it.  Any significant differences between this
301       implementation and Debian's is also  a  bug  and  should  be  reported,
302       unless otherwise noted in this man page.
303

AUTHOR

305       alternatives is copyright 2002 Red Hat, Inc..  It is free software; see
306       the GNU General Public Licence version 2 or later  for  copying  condi‐
307       tions.  There is NO warranty.
308
309       This  manual  page  is copyright 1997/98 Charles Briscoe-Smith and 2002
310       Red Hat, Inc.  This is free documentation; see the GNU  General  Public
311       Licence  version  2  or later for copying conditions.  There is NO WAR‐
312       RANTY.
313

SEE ALSO

315       ln(1), FHS, the Filesystem Hierarchy Standard.
316
317
318
319                                27 January 2001         UPDATE-ALTERNATIVES(8)
Impressum