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 name
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       --altdir directory
172              Specifies the alternatives directory, when this is to be differ‐
173              ent from the default.
174
175       --admindir directory
176              Specifies  the administrative directory, when this is to be dif‐
177              ferent from the default.
178
179   ACTIONS
180       --install  link  name  path  priority  [--slave  slink   sname   spath]
181       [--initscript service]...
182              Add  a group of alternatives to the system.  name is the generic
183              name for the master link, link is the name of its symlink,  path
184              is  the  alternative  being  introduced for the master link, and
185              priority is the priority of the alternatives group. Higher  pri‐
186              orities take precendence if no alternative is manually selected.
187              sname, slink and spath are the generic name,  symlink  name  and
188              alternative  for  a  slave  link, and service is the name of any
189              associated initscript for the alternative.   NOTE:  --initscript
190              and --family are a Red Hat Linux specific options.  Zero or more
191              --slave options, each followed by three arguments, may be speci‐
192              fied.
193
194              If  the  master symlink specified exists already in the alterna‐
195              tives system's records, the information supplied will  be  added
196              as  a  new  set of alternatives for the group.  Otherwise, a new
197              group, set to automatic mode, will be added with  this  informa‐
198              tion.   If  the  group is in automatic mode, and the newly added
199              alternatives' priority is higher than any other installed alter‐
200              natives for this group, the symlinks will be updated to point to
201              the newly added alternatives.
202
203              If --initscript is used, the alternatives system will manage the
204              initscript associated with the alternative via chkconfig, regis‐
205              tering and unregistering the  init  script  depending  on  which
206              alternative is active.
207
208              NOTE: --initscript is a Red Hat Linux specific option.
209
210
211              --family can be used to group similar alternatives. If the group
212              is in manual mode and the alternative currently used is removed,
213              alternatives will try to change links to different one with same
214              family and highest priority.
215
216              NOTE: --family is a Red Hat Linux specific option.
217
218       --remove name path
219              Remove an alternative and all of  its  associated  slave  links.
220              name  is  a  name  in the alternatives directory, and path is an
221              absolute filename to which name could be  linked.   If  name  is
222              indeed  linked to path, name will be updated to point to another
223              appropriate alternative, or removed if there is no such alterna‐
224              tive  left.   Associated slave links will be updated or removed,
225              correspondingly.  If the link is not currently pointing to path,
226              no links are changed; only the information about the alternative
227              is removed.
228
229       --set name path
230              The symbolic link and slaves for link group name  set  to  those
231              configured  for  path, and the link group is set to manual mode.
232              This option is not in the original Debian implementation.
233
234       --config name
235              Present the user with a configuration menu for choosing the mas‐
236              ter  link  and slaves for link group name. Once chosen, the link
237              group is set to manual mode.
238
239       --auto name
240              Switch the master  symlink  name  to  automatic  mode.   In  the
241              process, this symlink and its slaves are updated to point to the
242              highest priority installed alternatives.
243
244       --display name
245              Display information about the link group of which  name  is  the
246              master  link.   Information  displayed includes the group's mode
247              (auto or manual), which alternative the symlink currently points
248              to, what other alternatives are available (and their correspond‐
249              ing slave alternatives), and the  highest  priority  alternative
250              currently installed.
251
252       --list Display information about all link groups.
253
254       --remove-all name
255              Remove the whole link group name. Use with caution.
256
257       --add-slave name path slink sname spath
258              Add  a slave link to an alternative identified by name and path.
259              sname, slink and spath are the generic name,  symlink  name  and
260              alternative for the slave.
261
262       --remove-slave name path sname
263              Remove slave with generic name sname from alternative identified
264              by name and path.
265

FILES

267       /etc/alternatives/
268              The default alternatives directory.  Can be  overridden  by  the
269              --altdir option.
270
271       /var/lib/alternatives/
272              The  default administration directory.  Can be overridden by the
273              --admindir option.
274

EXIT STATUS

276       0      The requested action was successfully performed.
277
278       2      Problems were encountered whilst parsing  the  command  line  or
279              performing the action.
280

DIAGNOSTICS

282       alternatives  chatters incessantly about its activities on its standard
283       output channel.  If problems occur, alternatives outputs error messages
284       on  its  standard error channel and returns an exit status of 2.  These
285       diagnostics should be self-explanatory; if you do  not  find  them  so,
286       please report this as a bug.
287

BUGS

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

AUTHOR

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

SEE ALSO

309       ln(1),  FHS, the Filesystem Hierarchy Standard.  alternatives.c chkcon‐
310       fig.c COPYING leveldb.c leveldb.h Makefile ntsysv.c ook
311
312
313
314                                27 January 2001         UPDATE-ALTERNATIVES(8)
Impressum