/chkconfig-1.3.59/alternatives.8

  1.\" alternatives.8
  2.\" This man page is copyright 1997 Charles Briscoe-Smith, 2002 Red Hat, Inc.
  3.\" This is free documentation; you can redistribute it and/or modify
  4.\" it under the terms of the GNU General Public License as published
  5.\" by the Free Software Foundation; either version 2 of the License, or
  6.\" (at your option) any later version. 
  7.TH UPDATE-ALTERNATIVES 8 "27 January 2001"
  8.SH NAME
  9alternatives \- maintain symbolic links determining default commands
 10.SH SYNOPSIS
 11.B alternatives
 12.RI [ options ]
 13.B --install
 14.I link name path priority
 15.RB [ --slave
 16.I link name
 17.IR path ]...
 18.RB [ --initscript
 19.IR service ]
 20.PP
 21.B alternatives
 22.RI [ options ]
 23.B --remove
 24.I name path
 25.PP
 26.B alternatives
 27.RI [ options ]
 28.B --set
 29.I name path
 30.PP
 31.B alternatives
 32.RI [ options ]
 33.B --auto
 34.I name
 35.PP
 36.B alternatives
 37.RI [ options ]
 38.B --display
 39.I name
 40.PP
 41.B alternatives
 42.RI [ options ]
 43.B --config
 44.I name
 45.SH DESCRIPTION
 46.B alternatives
 47creates, removes, maintains and displays information about the symbolic
 48links comprising the alternatives system. The alternatives system is
 49a reimplementation of the Debian alternatives system. It was rewritten
 50primarily to remove the dependence on perl; it is intended to be a drop
 51in replacement for Debian's \fBupdate-dependencies\fR script. This man
 52page is a slightly modified version of the man page from the Debian project.
 53.PP
 54It is possible for several programs fulfilling the same or similar
 55functions to be installed on a single system at the same time.
 56For example, many systems have several text editors installed at once.
 57This gives choice to the users of a system, allowing each to use a
 58different editor, if desired, but makes it difficult for a program
 59to make a good choice of editor to invoke if the
 60user has not specified a particular preference.
 61.PP
 62The alternatives system aims to solve this problem.
 63A generic name in the filesystem is
 64shared by all files providing interchangeable functionality.
 65The alternatives system and the system administrator
 66together determine which actual file is referenced by this generic name.
 67For example, if the text editors
 68.BR ed (1)
 69and
 70.BR nvi (1)
 71are both installed on the system, the alternatives system will cause
 72the generic name
 73.I /usr/bin/editor
 74to refer to
 75.I /usr/bin/nvi
 76by default.  The system administrator can override this and cause
 77it
 78to refer to
 79.I /usr/bin/ed
 80instead,
 81and the alternatives system will not alter this setting until explicitly
 82requested to do so.
 83.PP
 84The generic name is not a direct symbolic link to the selected alternative.
 85Instead, it is a symbolic link to a name in the
 86.I alternatives
 87.IR directory ,
 88which in turn is a symbolic link to the actual file referenced.
 89This is done so that the system administrator's changes can be confined
 90within the
 91.I /etc
 92directory: the FHS (q.v.) gives reasons why this is a Good Thing.
 93.PP
 94When each package
 95providing a file with a particular functionality is
 96installed, changed or removed,
 97.B alternatives
 98is called to update information about that file in the alternatives system.
 99.B alternatives
100is usually called from the
101.B %post
102or
103.B %pre
104scripts in RPM packages.
105.PP
106It is often useful for a number of alternatives to be synchronised,
107so that they are changed as a group; for example, when several versions
108of the
109.BR vi (1)
110editor are installed, the man page referenced by
111.I /usr/share/man/man1/vi.1
112should correspond to the executable referenced by
113.IR /usr/bin/vi .
114.B alternatives
115handles this by means of
116.I master
117and
118.I slave
119links; when the master is changed, any associated slaves are changed
120too.
121A master link and its associated slaves make up a
122.I link
123.IR group .
124.PP
125Each link group is, at any given time,
126in one of two modes: automatic or manual.
127When a group is in automatic mode, the alternatives system will
128automatically decide, as packages are installed and removed,
129whether and how to update the links.
130In manual mode, the alternatives system will not change the links;
131it will leave all the decisions to the system administrator.
132.PP
133Link groups are in automatic mode when they are first introduced to
134the system.
135If the system administrator makes changes to the system's
136automatic settings,
137this will be noticed the next time
138.B alternatives
139is run on the changed link's group,
140and the group will automatically be switched to manual mode.
141.PP
142Each alternative has a
143.I priority
144associated with it.
145When a link group is in automatic mode,
146the alternatives pointed to by members of the group
147will be those which have the highest priority.
148.PP
149When using the
150.I --config
151option,
152.B alternatives
153will list all of the choices for the link group
154of which given
155.I name
156is the master link.
157You will then be prompted for which of the choices to use
158for the link group. Once you make a change, the link group will no
159longer be in
160.I auto
161mode. You will need to use the
162.I --auto
163option in order to return to the automatic state.
164.SH TERMINOLOGY
165Since the activities of
166.B alternatives
167are quite involved, some specific terms will help to explain its
168operation.
169.TP
170generic name
171A name, like
172.IR /usr/bin/editor ,
173which refers, via the alternatives system, to one of a number of
174files of similar function.
175.TP
176symlink
177Without any further qualification, this means a symbolic link in the
178alternatives directory: one which the system administrator is expected
179to adjust.
180.TP
181alternative
182The name of a specific file in the filesystem, which may be made
183accessible via a generic name using the alternatives system.
184.TP
185alternatives directory
186A directory, by default
187.IR /etc/alternatives ,
188containing the symlinks.
189.TP
190administrative directory
191A directory, by default
192.IR /var/lib/alternatives ,
193containing
194.BR alternatives '
195state information.
196.TP
197link group
198A set of related symlinks, intended to be updated as a group.
199.TP
200master link
201The link in a link group which determines how the other links in the
202group are configured.
203.TP
204slave link
205A link in a link group which is controlled by the setting of
206the master link.
207.TP
208automatic mode
209When a link group is in automatic mode,
210the alternatives system ensures that the links in the group
211point to the highest priority alternatives
212appropriate for the group.
213.TP
214manual mode
215When a link group is in manual mode,
216the alternatives system will not make any changes
217to the system administrator's settings.
218.SH OPTIONS
219Exactly one action must be specified if
220.B alternatives
221is to perform any meaningful task.
222Any number of the common options may be specified together with any action.
223.SS "COMMON OPTIONS"
224.TP
225.B --verbose
226Generate more comments about what
227.B alternatives
228is doing.
229.TP
230.B --quiet
231Don't generate any comments unless errors occur.
232This option is not yet implemented.
233.TP
234.B --test
235Don't actually do anything, just say what would be done.
236This option is not yet implemented.
237.TP
238.B --help
239Give some usage information (and say which version of
240.B alternatives
241this is).
242.TP
243.B --version
244Tell which version of
245.B alternatives
246this is (and give some usage information).
247.TP
248\fB--altdir\fR \fIdirectory\fR
249Specifies the alternatives directory, when this is to be
250different from the default.
251.TP
252\fB--admindir\fR \fIdirectory\fR
253Specifies the administrative directory, when this is to be
254different from the default.
255.SS ACTIONS
256.\" The names of the arguments should be identical with the ones
257.\" in SYNOPSIS section.
258.TP
259\fB--install\fR \fIlink name path priority\fR [\fB--slave\fR \fIslink sname spath\fR] [\fB--initscript\fR \fIservice\fR]...
260Add a group of alternatives to the system.
261.I name
262is the generic name for the master link,
263.I link
264is the name of its symlink,
265.I path
266is the alternative being introduced for the master link, and
267.I priority
268is the priority of the alternatives group. Higher priorities
269take precendence if no alternative is manually selected.
270.IR sname ,
271.I slink
272and
273.I spath
274are the generic name, symlink name and alternative
275for a slave link, and
276.I service
277is the name of any associated initscript for the alternative.
278.B NOTE:
279.B --initscript
280is a Red Hat Linux specific option.
281Zero or more
282.B --slave
283options, each followed by three arguments,
284may be specified.
285.IP
286If the master symlink specified exists already
287in the alternatives system's records,
288the information supplied will be added as a new
289set of alternatives for the group.
290Otherwise, a new group, set to automatic mode,
291will be added with this information.
292If the group is in automatic mode,
293and the newly added alternatives' priority is higher than
294any other installed alternatives for this group,
295the symlinks will be updated to point to the newly added alternatives.
296
297If
298.B --initscript
299is used, the alternatives system will manage the initscript
300associated with the alternative via
301.B chkconfig,
302registering and unregistering the init script depending on
303which alternative is active.
304
305.B NOTE:
306.B --initscript
307is a Red Hat Linux specific option.
308.TP
309\fB--remove\fR \fIname path\fR
310Remove an alternative and all of its associated slave links.
311.I name
312is a name in the alternatives directory, and
313.I path
314is an absolute filename to which
315.I name
316could be linked.  If
317.I name
318is indeed linked to
319.IR path ,
320.I name
321will be updated to point to another appropriate alternative, or
322removed if there is no such alternative left.
323Associated slave links will be updated or removed, correspondingly.
324If the link is not currently pointing to
325.IR path ,
326no links are changed;
327only the information about the alternative is removed.
328.TP
329\fB--set\fR \fIname path\fR
330The symbolic link and slaves for link group \fIname\fR set to those
331configured for \fIpath\fR, and the link group is set to manual mode.
332This option is not in the original Debian implementation.
333.TP
334\fB--config\fR \fIname\fR
335Present the user with a configuration menu for choosing
336the master link and slaves for link group \fIname\fR. Once
337chosen, the link group is set to manual mode.
338.TP
339\fB--auto\fR \fIname\fR
340Switch the master symlink
341.I name
342to automatic mode.
343In the process, this symlink and its slaves are updated
344to point to the highest priority installed alternatives.
345.TP
346\fB--display\fR \fIname\fR
347Display information about the link group of which
348.I name
349is the master link.
350Information displayed includes the group's mode
351(auto or manual),
352which alternative the symlink currently points to,
353what other alternatives are available
354(and their corresponding slave alternatives),
355and the highest priority alternative currently installed.
356.SH FILES
357.TP
358.I /etc/alternatives/
359The default alternatives directory.
360Can be overridden by the
361.B --altdir
362option.
363.TP
364.I /var/lib/alternatives/
365The default administration directory.
366Can be overridden by the
367.B --admindir
368option.
369.SH "EXIT STATUS"
370.IP 0
371The requested action was successfully performed.
372.IP 2
373Problems were encountered whilst parsing the command line
374or performing the action.
375.SH DIAGNOSTICS
376.B alternatives
377chatters incessantly about its activities on its standard output channel.
378If problems occur,
379.B alternatives
380outputs error messages on its standard error channel and
381returns an exit status of 2.
382These diagnostics should be self-explanatory;
383if you do not find them so, please report this as a bug.
384.SH BUGS
385If you find a bug, please report it using the Red Hat bug tracking system
386at \fBhttp://bugzilla.redhat.com\fR.
387.PP
388If you find any discrepancy between the operation of
389.B alternatives
390and this manual page, it is a bug,
391either in the implementation or the documentation; please report it.
392Any significant differences between this implementation and Debian's is
393also a bug and should be reported, unless otherwise noted in this man page.
394.SH AUTHOR
395alternatives is copyright 2002
396Red Hat, Inc..  It is free software; see the GNU General Public Licence
397version 2 or later for copying conditions.  There is NO warranty.
398.PP
399This manual page is copyright 1997/98 Charles Briscoe-Smith and
4002002 Red Hat, Inc.
401This is free documentation; see the GNU General Public Licence
402version 2 or later for copying conditions.  There is NO WARRANTY.
403.SH "SEE ALSO"
404.BR ln (1),
405FHS, the Filesystem Hierarchy Standard.
406alternatives.c
407chkconfig.c
408COPYING
409leveldb.c
410leveldb.h
411Makefile
412ntsysv.c
413ook