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 [--follower
10       link name path]...  [--initscript service] [--family name]
11
12       alternatives [options] --remove name path
13
14       alternatives [options] --set name path/family
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-follower  name  path  follower_link  fol‐
27       lower_name follower_path
28
29       alternatives [options] --remove-follower name path follower_name
30

DESCRIPTION

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

TERMINOLOGY

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

OPTIONS

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

FILES

284       /etc/alternatives/
285              The  default  alternatives  directory.  Can be overridden by the
286              --altdir option.
287
288       /var/lib/alternatives/
289              The default administration directory.  Can be overridden by  the
290              --admindir option.
291

EXIT STATUS

293       0      The requested action was successfully performed.
294
295       2      Problems  were  encountered  whilst  parsing the command line or
296              performing the action.
297

DIAGNOSTICS

299       alternatives chatters incessantly about its activities on its  standard
300       output channel.  If problems occur, alternatives outputs error messages
301       on its standard error channel and returns an exit status of  2.   These
302       diagnostics  should  be  self-explanatory;  if you do not find them so,
303       please report this as a bug.
304

BUGS

306       If you find a bug, please report it using the Red Hat bug tracking sys‐
307       tem at http://bugzilla.redhat.com.
308
309       If  you  find any discrepancy between the operation of alternatives and
310       this manual page, it is a bug, either in the implementation or the doc‐
311       umentation; please report it.  Any significant differences between this
312       implementation and Debian's is also a bug and should be  reported,  un‐
313       less otherwise noted in this man page.
314

AUTHOR

316       alternatives is copyright 2002 Red Hat, Inc..  It is free software; see
317       the GNU General Public Licence version 2 or later  for  copying  condi‐
318       tions.  There is NO warranty.
319
320       This  manual  page  is copyright 1997/98 Charles Briscoe-Smith and 2002
321       Red Hat, Inc.  This is free documentation; see the GNU  General  Public
322       Licence  version  2  or later for copying conditions.  There is NO WAR‐
323       RANTY.
324

SEE ALSO

326       ln(1), FHS, the Filesystem Hierarchy Standard.
327
328
329
330                                27 January 2001         UPDATE-ALTERNATIVES(8)
Impressum