source: ombilin/dpkg/man/update-alternatives.8 @ dpkg,2

Revision dpkg,2, 15.7 KB checked in by Rahman Yusri Aftian <aftian@…>, 4 years ago (diff)

add file source

Line 
1.\" update\-alternatives.8
2.\" This man page is copyright 1997 Charles Briscoe-Smith
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.  There is NO WARRANTY.  You can
7.\" find the GNU GPL in /usr/share/common-licenses/GPL on any Debian system.
8.TH update\-alternatives 8 "2009-04-13" "Debian Project" "dpkg utilities"
9.SH NAME
10update\-alternatives \- maintain symbolic links determining default commands
11.
12.SH SYNOPSIS
13.B update\-alternatives
14.RI [ options ]
15.I command
16.
17.SH DESCRIPTION
18.B update\-alternatives
19creates, removes, maintains and displays information about the symbolic
20links comprising the Debian alternatives system.
21.PP
22It is possible for several programs fulfilling the same or similar
23functions to be installed on a single system at the same time.
24For example, many systems have several text editors installed at once.
25This gives choice to the users of a system, allowing each to use a
26different editor, if desired, but makes it difficult for a program
27to make a good choice for an editor to invoke if the
28user has not specified a particular preference.
29.PP
30Debian's alternatives system aims to solve this problem.
31A generic name in the filesystem is
32shared by all files providing interchangeable functionality.
33The alternatives system and the system administrator
34together determine which actual file is referenced by this generic name.
35For example, if the text editors
36.BR ed (1)
37and
38.BR nvi (1)
39are both installed on the system, the alternatives system will cause
40the generic name
41.I /usr/bin/editor
42to refer to
43.I /usr/bin/nvi
44by default. The system administrator can override this and cause
45it
46to refer to
47.I /usr/bin/ed
48instead,
49and the alternatives system will not alter this setting until explicitly
50requested to do so.
51.PP
52The generic name is not a direct symbolic link to the selected alternative.
53Instead, it is a symbolic link to a name in the
54.I alternatives
55.IR directory ,
56which in turn is a symbolic link to the actual file referenced.
57This is done so that the system administrator's changes can be confined
58within the
59.I /etc
60directory: the FHS (q.v.) gives reasons why this is a Good Thing.
61.PP
62When each package
63providing a file with a particular functionality is
64installed, changed or removed,
65.B update\-alternatives
66is called to update information about that file in the alternatives system.
67.B update\-alternatives
68is usually called from the
69.B postinst
70(configure) or
71.B prerm
72(install) scripts in Debian packages.
73.PP
74It is often useful for a number of alternatives to be synchronised,
75so that they are changed as a group; for example, when several versions
76of the
77.BR vi (1)
78editor are installed, the man page referenced by
79.I /usr/share/man/man1/vi.1
80should correspond to the executable referenced by
81.IR /usr/bin/vi .
82.B update\-alternatives
83handles this by means of
84.I master
85and
86.I slave
87links; when the master is changed, any associated slaves are changed
88too.
89A master link and its associated slaves make up a
90.I link
91.IR group .
92.PP
93Each link group is, at any given time,
94in one of two modes: automatic or manual.
95When a group is in automatic mode, the alternatives system will
96automatically decide, as packages are installed and removed,
97whether and how to update the links.
98In manual mode, the alternatives system will retain the choice of
99the administrator and avoid changing the links (except when something is
100broken).
101.PP
102Link groups are in automatic mode when they are first introduced to
103the system.
104If the system administrator makes changes to the system's
105automatic settings,
106this will be noticed the next time
107.B update\-alternatives
108is run on the changed link's group,
109and the group will automatically be switched to manual mode.
110.PP
111Each alternative has a
112.I priority
113associated with it.
114When a link group is in automatic mode,
115the alternatives pointed to by members of the group
116will be those which have the highest priority.
117.PP
118When using the
119.I \-\-config
120option,
121.B update\-alternatives
122will list all of the choices for the link group
123of which given
124.I name
125is the master alternative name. The current choice is marked with a '*'.
126You will then be prompted for your choice regarding this link group.
127Depending on the choice made, the link group might no longer be in
128.I auto
129mode. You will need to use the
130.I \-\-auto
131option in order to return to the automatic mode (or you can rerun
132.I \-\-config
133and select the entry marked as automatic).
134.PP
135If you want to configure non-interactively you can use the
136.I \-\-set
137option instead (see below).
138.PP
139Different packages providing the same file need to do so
140.BR cooperatively .
141In other words, the usage of
142.B update\-alternatives
143is
144.B mandatory
145for all involved packages in such case. It is not possible to
146override some file in a package that does not employ the
147.B update\-alternatives
148mechanism.
149.
150.SH TERMINOLOGY
151Since the activities of
152.B update\-alternatives
153are quite involved, some specific terms will help to explain its
154operation.
155.TP
156generic name (or alternative link)
157A name, like
158.IR /usr/bin/editor ,
159which refers, via the alternatives system, to one of a number of
160files of similar function.
161.TP
162alternative name
163The name of a symbolic link in the alternatives directory.
164.TP
165alternative (or alternative path)
166The name of a specific file in the filesystem, which may be made
167accessible via a generic name using the alternatives system.
168.TP
169alternatives directory
170A directory, by default
171.IR /etc/alternatives ,
172containing the symlinks.
173.TP
174administrative directory
175A directory, by default
176.IR /var/lib/dpkg/alternatives ,
177containing
178.BR update\-alternatives '
179state information.
180.TP
181link group
182A set of related symlinks, intended to be updated as a group.
183.TP
184master link
185The alternative link in a link group which determines how the other links in the
186group are configured.
187.TP
188slave link
189An alternative link in a link group which is controlled by the setting of
190the master link.
191.TP
192automatic mode
193When a link group is in automatic mode,
194the alternatives system ensures that the links in the group
195point to the highest priority alternative
196appropriate for the group.
197.TP
198manual mode
199When a link group is in manual mode,
200the alternatives system will not make any changes
201to the system administrator's settings.
202.
203.SH COMMANDS
204.TP
205\fB\-\-install\fR \fIlink name path priority\fR [\fB\-\-slave\fR \fIlink name path\fR]...
206Add a group of alternatives to the system.
207.I link
208is the generic name for the master link,
209.I name
210is the name of its symlink in the alternatives directory, and
211.I path
212is the alternative being introduced for the master link.
213The arguments after \fB\-\-slave\fR are the generic name, symlink name in the
214alternatives directory and the alternative path for a slave link.
215Zero or more
216.B \-\-slave
217options, each followed by three arguments,
218may be specified. Note that the master alternative must exist or the call
219will fail. However if a slave alternative doesn't exist, the corresponding
220slave alternative link will simply not be installed (a warning will still
221be displayed). If some real file is installed where an alternative link
222has to be installed, it is kept unless \fB\-\-force\fR is used.
223.IP
224If the alternative name specified exists already
225in the alternatives system's records,
226the information supplied will be added as a new
227set of alternatives for the group.
228Otherwise, a new group, set to automatic mode,
229will be added with this information.
230If the group is in automatic mode,
231and the newly added alternatives' priority is higher than
232any other installed alternatives for this group,
233the symlinks will be updated to point to the newly added alternatives.
234.TP
235\fB\-\-set\fR \fIname path\fR
236Set the program
237.I path
238as alternative for
239.I name.
240This is equivalent to
241.IB \-\-config
242but is non-interactive and thus scriptable.
243.TP
244\fB\-\-remove\fR \fIname path\fR
245Remove an alternative and all of its associated slave links.
246.I name
247is a name in the alternatives directory, and
248.I path
249is an absolute filename to which
250.I name
251could be linked. If
252.I name
253is indeed linked to
254.IR path ,
255.I name
256will be updated to point to another appropriate alternative
257(and the group is put back in automatic mode), or
258removed if there is no such alternative left.
259Associated slave links will be updated or removed, correspondingly.
260If the link is not currently pointing to
261.IR path ,
262no links are changed;
263only the information about the alternative is removed.
264.TP
265\fB\-\-remove\-all\fR \fIname\fR
266Remove all alternatives and all of their associated slave links.
267.I name
268is a name in the alternatives directory.
269.TP
270.B \-\-all
271Call \fB\-\-config\fP on all alternatives. It can be usefully combined with
272\fB\-\-skip\-auto\fP to review and configure all alternatives which are
273not configured in automatic mode. Broken alternatives are also displayed.
274Thus a simple way to fix all broken alternatives is to call
275\fByes \[aq]\[aq] | update-alternatives \-\-force \-\-all\fR.
276.TP
277\fB\-\-auto\fR \fIname\fR
278Switch the link group behind the alternative for
279.I name
280to automatic mode.
281In the process, the master symlink and its slaves are updated
282to point to the highest priority installed alternatives.
283.TP
284\fB\-\-display\fR \fIname\fR
285Display information about the link group.
286Information displayed includes the group's mode
287(auto or manual),
288which alternative the master link currently points to,
289what other alternatives are available
290(and their corresponding slave alternatives),
291and the highest priority alternative currently installed.
292.TP
293\fB\-\-get\-selections\fR
294List all master alternative names (those controlling a link group)
295and their status. Each line contains up to 3 fields (separated by
296one or more spaces). The first field is the alternative name, the second
297one is the status (either "auto" or "manual"), and the last one contains
298the current choice in the alternative (beware: it's a filename and thus
299might contain spaces).
300.TP
301\fB\-\-set\-selections\fR
302Read configuration of alternatives on standard input in the format
303generated by \fBupdate-alternatives \-\-get\-selections\fR and reconfigure
304them accordingly.
305.TP
306\fB\-\-query\fR \fIname\fR
307Display information about the link group
308like \-\-display does, but in a machine parseable way
309(see section \fBQUERY FORMAT\fR below).
310.TP
311\fB\-\-list\fR \fIname\fR
312Display all targets of the link group.
313.TP
314\fB\-\-config\fR \fIname\fR
315Show available alternatives for a link group and allow the user to
316interactively select which one to use. The link group is updated.
317.TP
318.B \-\-help
319Show the usage message and exit.
320.TP
321.B \-\-version
322Show the version and exit.
323.
324.SH OPTIONS
325.TP
326.BI \-\-altdir " directory"
327Specifies the alternatives directory, when this is to be
328different from the default.
329.TP
330.BI \-\-admindir " directory"
331Specifies the administrative directory, when this is to be
332different from the default.
333.TP
334.BI \-\-log " file"
335Specifies the log file, when this is to be different from the default
336(/var/log/dpkg.log).
337.TP
338.BI \-\-force
339Let \fBupdate-alternatives\fR replace any real file that is installed
340where an alternative link has to be installed.
341.TP
342.BI \-\-skip\-auto
343Skip configuration prompt for alternatives which are properly configured
344in automatic mode. This option is only relevant with \fB\-\-config\fR or
345\fB\-\-all\fR.
346.TP
347.B \-\-verbose
348Generate more comments about what
349.B update\-alternatives
350is doing.
351.TP
352.B \-\-quiet
353Don't generate any comments unless errors occur.
354.
355.SH FILES
356.TP
357.I /etc/alternatives/
358The default alternatives directory.
359Can be overridden by the
360.B \-\-altdir
361option.
362.TP
363.I /var/lib/dpkg/alternatives/
364The default administration directory.
365Can be overridden by the
366.B \-\-admindir
367option.
368.
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.
376.SH "QUERY FORMAT"
377The \fBupdate\-alternatives\fP \fI\-\-query\fP format is using an
378RFC822-like flat format. It's made of \fIn\fP + 1 blocks where \fIn\fP is
379the number of alternatives available in the queried link group. The first
380block contains the following fields:
381.TP
382.BR Link: " <link>"
383The generic name of the alternative.
384.TP
385.BR Status: " <status>"
386The status of the alternative (\fBauto\fR or \fBmanual\fR).
387.TP
388.BR Best: " <best choice>"
389The path of the best alternative for this link group. Not present if
390there is no alternatives available.
391.TP
392.BR Value: " <currently selected alternative> "
393The path of the currently selected alternative. It can also take the magic
394value \fBnone\fR. It is used if the link doesn't exist.
395.TP
396.TP
397The other blocks describe the available alternatives in the queried link group:
398.TP
399.BR Alternative: " <path of this alternative>"
400Path to this block's alternative.
401.TP
402.BR Priority: " <priority value>"
403Value of the priority of this alternative.
404.TP
405.BR Slaves: " <list of slaves>"
406When this header is present, the \fBnext\fR lines hold all slave alternatives
407associated to the master link of the alternative. There is one slave per
408line. Each line contains one space, the generic name of the slave
409alternative, another space, and the path to the slave alternative.
410.
411.TP
412.BR Example
413.nf
414$ update\-alternatives \-\-query editor
415Link: editor
416Status: auto
417Best: /usr/bin/vim.gtk
418Value: /usr/bin/vim.gtk
419
420Alternative: /bin/ed
421Priority: \-100
422Slaves:
423 editor.1.gz /usr/share/man/man1/ed.1.gz
424
425Alternative: /usr/bin/vim.gtk
426Priority: 50
427Slaves:
428 editor.1.gz /usr/share/man/man1/vim.1.gz
429 editor.ru.1.gz /usr/share/man/ru/man1/vim.1.gz
430 editor.pl.ISO8859-2.1.gz /usr/share/man/pl.ISO8859-2/man1/vim.1.gz
431 editor.it.ISO8859-1.1.gz /usr/share/man/it.ISO8859-1/man1/vim.1.gz
432 editor.pl.UTF-8.1.gz /usr/share/man/pl.UTF-8/man1/vim.1.gz
433 editor.it.1.gz /usr/share/man/it/man1/vim.1.gz
434 editor.fr.UTF-8.1.gz /usr/share/man/fr.UTF-8/man1/vim.1.gz
435 editor.fr.1.gz /usr/share/man/fr/man1/vim.1.gz
436 editor.it.UTF-8.1.gz /usr/share/man/it.UTF-8/man1/vim.1.gz
437 editor.pl.1.gz /usr/share/man/pl/man1/vim.1.gz
438 editor.fr.ISO8859-1.1.gz /usr/share/man/fr.ISO8859-1/man1/vim.1.gz
439.fi
440.
441.SH DIAGNOSTICS
442With \fI--verbose\fR
443.B update\-alternatives
444chatters incessantly about its activities on its standard output channel.
445If problems occur,
446.B update\-alternatives
447outputs error messages on its standard error channel and
448returns an exit status of 2.
449These diagnostics should be self-explanatory;
450if you do not find them so, please report this as a bug.
451.
452.SH EXAMPLES
453There are several packages which provide a text editor compatible
454with \fBvi\fP, for example \fBnvi\fP and \fBvim\fP. Which one is used
455is controlled by the link group \fBvi\fP, which includes links for the
456program itself and the associated manpage.
457.PP
458To display the available packages which provide \fBvi\fP and the current
459setting for it, use the \fI\-\-display\fP action:
460.RS
461.PP
462.B update\-alternatives \-\-display vi
463.RE
464.PP
465To choose a particular \fBvi\fP implementation, use this command as root
466and then select a number from the list:
467.RS
468.PP
469.B update\-alternatives \-\-config vi
470.RE
471.PP
472To go back to having the \fBvi\fP implementation chosen automatically, do
473this as root:
474.RS
475.PP
476.B update\-alternatives \-\-auto vi
477.RE
478.
479.SH BUGS
480If you find a bug, please report it using the Debian bug-tracking system.
481.PP
482If you find any discrepancy between the operation of
483.B update\-alternatives
484and this manual page, it is a bug,
485either in the implementation or the documentation; please report it.
486.
487.SH AUTHORS
488Copyright \(co 1995 Ian Jackson
489.br
490Copyright \(co 2009 Rapha\[:e]l Hertzog
491.sp
492This is free software; see the GNU General Public Licence version 2 or
493later for copying conditions. There is NO WARRANTY.
494.PP
495This manual page is copyright 1997,1998 Charles Briscoe-Smith and
496others.
497.sp
498This is free documentation; see the GNU General Public Licence version 2 or
499later for copying conditions. There is NO WARRANTY.
500.
501.SH "SEE ALSO"
502.BR ln (1),
503FHS, the Filesystem Hierarchy Standard.
Note: See TracBrowser for help on using the repository browser.