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