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 ex‐
41       ample, many systems have several text editors installed at once.   This
42       gives choice to the users of a system, allowing each to use a different
43       editor, if desired, but makes it difficult for a program to make a good
44       choice  of  editor to invoke if the user has not specified a particular
45       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  to‐
50       gether  determine which actual file is referenced by this generic name.
51       For example, if the text editors ed(1) and nvi(1) are both installed on
52       the  system,  the  alternatives  system  will  cause  the  generic name
53       /usr/bin/editor to refer to /usr/bin/nvi by default.  The system admin‐
54       istrator  can  override  this  and cause it to refer to /usr/bin/ed in‐
55       stead, 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 di‐
60       rectory,  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 au‐
87       tomatic 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 to‐
151       gether 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 im‐
174              plementation.  It prevents issues  with  missing  files  due  to
175              switching between versions.
176
177       --keep-foreign
178              When  removing,  adding or switching between alternatives, check
179              if the link does not point to some other  location  than  altdir
180              (/etc/alternatives/  by  default).  In such case the link is not
181              modified.
182
183       --altdir directory
184              Specifies the alternatives directory, when this is to be differ‐
185              ent from the default.
186
187       --admindir directory
188              Specifies  the administrative directory, when this is to be dif‐
189              ferent from the default.
190
191   ACTIONS
192       --install  link  name  path  priority  [--slave  slink   sname   spath]
193       [--initscript service]...
194              Add  a group of alternatives to the system.  name is the generic
195              name for the master link, link is the name of its symlink,  path
196              is  the  alternative  being  introduced for the master link, and
197              priority is the priority of the alternatives group. Higher  pri‐
198              orities take precendence if no alternative is manually selected.
199              sname, slink and spath are the generic name,  symlink  name  and
200              alternative for a slave link, and service is the name of any as‐
201              sociated initscript for the alternative.  NOTE: --initscript and
202              --family  are  a  Red  Hat Linux specific options.  Zero or more
203              --slave options, each followed by three arguments, may be speci‐
204              fied.
205
206              If  the  master symlink specified exists already in the alterna‐
207              tives system's records, the information supplied will  be  added
208              as  a  new  set of alternatives for the group.  Otherwise, a new
209              group, set to automatic mode, will be added with  this  informa‐
210              tion.   If  the  group is in automatic mode, and the newly added
211              alternatives' priority is higher than any other installed alter‐
212              natives for this group, the symlinks will be updated to point to
213              the newly added alternatives.
214
215              If --initscript is used, the alternatives system will manage the
216              initscript associated with the alternative via chkconfig, regis‐
217              tering and unregistering the init script depending on which  al‐
218              ternative is active.
219
220              NOTE: --initscript is a Red Hat Linux specific option.
221
222
223              --family can be used to group similar alternatives. If the group
224              is in manual mode and the alternative currently used is removed,
225              alternatives will try to change links to different one with same
226              family and highest priority.
227
228              NOTE: --family is a Red Hat Linux specific option.
229
230       --remove name path
231              Remove an alternative and all of  its  associated  slave  links.
232              name is a name in the alternatives directory, and path is an ab‐
233              solute filename to which name could be linked.  If name  is  in‐
234              deed  linked  to  path, name will be updated to point to another
235              appropriate alternative, or removed if there is no such alterna‐
236              tive  left.   Associated slave links will be updated or removed,
237              correspondingly.  If the link is not a  symlink,  no  links  are
238              changed; only the information about the alternative is removed.
239
240       --set name path
241              The  symbolic  link  and slaves for link group name set to those
242              configured for path, and the link group is set to  manual  mode.
243              This option is not in the original Debian implementation.
244
245       --config name
246              Present the user with a configuration menu for choosing the mas‐
247              ter link and slaves for link group name. Once chosen,  the  link
248              group is set to manual mode.
249
250       --auto name
251              Switch  the  master  symlink  name  to  automatic  mode.  In the
252              process, this symlink and its slaves are updated to point to the
253              highest priority installed alternatives.
254
255       --display name
256              Display  information  about  the link group of which name is the
257              master link.  Information displayed includes  the  group's  mode
258              (auto or manual), which alternative the symlink currently points
259              to, what other alternatives are available (and their correspond‐
260              ing  slave  alternatives),  and the highest priority alternative
261              currently installed.
262
263       --list Display information about all link groups.
264
265       --remove-all name
266              Remove the whole link group name. Use with caution.
267
268       --add-slave name path slink sname spath
269              Add a slave link to an alternative identified by name and  path.
270              sname,  slink  and  spath are the generic name, symlink name and
271              alternative for the slave.
272
273       --remove-slave name path sname
274              Remove slave with generic name sname from alternative identified
275              by name and path.
276

FILES

278       /etc/alternatives/
279              The  default  alternatives  directory.  Can be overridden by the
280              --altdir option.
281
282       /var/lib/alternatives/
283              The default administration directory.  Can be overridden by  the
284              --admindir option.
285

EXIT STATUS

287       0      The requested action was successfully performed.
288
289       2      Problems  were  encountered  whilst  parsing the command line or
290              performing the action.
291

DIAGNOSTICS

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

BUGS

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

AUTHOR

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

SEE ALSO

320       ln(1), FHS, the Filesystem Hierarchy Standard.
321
322
323
324                                27 January 2001         UPDATE-ALTERNATIVES(8)
Impressum