View source for Directives/special keys

[[Category:Directives]]
== Introduction and disambiguation ==

This document is about combining certain directives, together with special keys, affecting the way Syslinux behaves, specially during the initial boot time.

This document is <u>'''not'''</u> about:<br />
* keyboard layout (language);
* [[Cli|usage of keys in the command line interface]] nor in boot menus.

The directives mentioned here are not sorted alphabetically, but rather in an attempt to help the reader understand their relations and differences.
Each section in this page adds information or alternatives to a prior one.
This document does not include every single detail about the directives mentioned here.
Additional information about each individual directive is provided in the [[config]]uration wiki page and/or in the [[Menu]] wiki page.


== Behavior ==
The following directives affect the way Syslinux behaves depending on the status (on/off) of certain keys.
<br />

=== Basic case ===
Using the following basic configuration, Syslinux will ''automatically'' launch ''mylabel'':

<pre>
  DEFAULT mylabel
  
  LABEL mylabel
  KERNEL mykernel
</pre>

=== Escape keys ===
To avoid the automatic launch of the DEFAULT command, press any one of the [Shift] or [Alt] keys, or set {{nowrap|[Caps Lock]}} or {{nowrap|[Scroll lock]}}, during boot time.

Under certain conditions (such as specific hardware or BIOS versions), some of the alternative "escape" keys might not trigger the desired behavior.
In such case, the other alternative "escape" keys should be used (instead of assuming that the feature does not work at all).
For example, if [Shift] does not work, try [Alt].

Note: The goal of certain directives (some of them are mentioned in this document) is to change the behavior of Syslinux according to the status (on/off) of the "escape" keys during boot time.
If a particular firmware (BIOS / UEFI) version is not capable of identifying (reading, sensing) the status of ''any'' of these "escape" keys during boot time, then at least part of the expected behavior of such directives will fail.
The same consideration could be valid for a serial console.
Please consider these potential situations when including such directives in a configuration file.

Note: If not even one of the alternative "escape" keys works as expected, please report it to the Syslinux [[Contact|Mailing List]], including specific hardware and firmware details.

=== PROMPT ===
Alternatively, adding "<tt>PROMPT 1</tt>" will avoid the automatic launch of the DEFAULT command, without having to press any special keys.
The following configuration will force Syslinux to display a {{nowrap|"<tt>boot:</tt>"}} [[Cli|prompt]], instead of automatically launching the DEFAULT command:

<pre>
  DEFAULT mylabel
  PROMPT 1
  
  LABEL mylabel
  KERNEL mykernel
</pre>

=== NOESCAPE ===
On the other hand, to ''force'' the automatic launch of the DEFAULT command we would need to: <br />
1_ <u>not</u> use <tt>PROMPT 1</tt>; and <br />
2_ ignore the aforementioned "escape" keys' status (i.e. whether any of the [Shift] or [Alt] keys is pressed, or whether either {{nowrap|[Caps Lock]}} or {{nowrap|[Scroll lock]}} is set).

To accomplish the second condition, use <tt>NOESCAPE 1</tt>:

<pre>
  DEFAULT mylabel
  PROMPT 0
  NOESCAPE 1
  
  LABEL mylabel
  KERNEL mykernel
</pre>

The "<tt>NOESCAPE 1</tt>" statement also disables the effects of the [Esc] key.

=== UI ===
UI overrides the PROMPT directive and takes precedence over the DEFAULT directive.
Therefore, if UI is used, the PROMPT directive is ignored and the UI command - not the DEFAULT command - is automatically launched:

<pre>
  UI menu.c32
  DEFAULT mylabel
  # Even if present, the PROMPT directive is ignored when UI is used.
  
  LABEL mylabel
  KERNEL mykernel
</pre>

=== UI and escape keys ===
Although the PROMPT directive is ignored when UI is used, the NOESCAPE directive is still considered.

If all the following conditions apply: <br />
1_ UI is present; and, <br />
2_ <tt>NOESCAPE 1</tt> is <u>not</u> present; and <br />
3_ any of the "escape" keys is used during boot time;

then the precise behavior might vary depending on the version of Syslinux.
Under these conditions, with some versions the {{nowrap|"<tt>boot:</tt>"}} prompt will be displayed, whereas with other versions the boot menu will be displayed in accordance to the UI directive.
In either case, the DEFAULT command is not automatically launched, which is the main goal for using these "escape" keys.

=== MENU SHIFTKEY ===
While the typical goal of using the UI directive is to automatically display a user-friendly {{nowrap|''boot menu''}} with several choices - instead of automatically booting the DEFAULT label - the opposite situation is also possible.
Frequently, a user might want to normally launch the DEFAULT label, whereas only rarely the other choices in the boot menu are selected.

The <tt>MENU SHIFTKEY</tt> directive, when used together with UI, allows for the DEFAULT label to be launched directly without having to show first the boot menu.
Under this configuration, the boot menu is displayed only when using the "escape" keys during boot time.

=== MENU HIDDEN ===
Similarly to <tt>MENU SHIFTKEY</tt>, the <tt>MENU HIDDEN</tt> directive also hides the initial boot menu, which can then be displayed when pressing some key.
For {{nowrap|<tt>MENU SHIFTKEY</tt>}} to show the boot menu, the aforementioned "escape" keys are used.
For {{nowrap|<tt>MENU HIDDEN</tt>}} to show the boot menu, pressing ''any'' key displays the menu.

Usually a TIMEOUT directive is also used in conjunction with {{nowrap|<tt>MENU HIDDEN</tt>}}.

=== MENU HIDDENKEY ===
The [[Menu#MENU_HIDDENKEY|<tt>MENU HIDDENKEY</tt>]] directive modifies the behavior of specific keys (or a combination of keys): instead of showing the boot menu when pressing a key - as it happens with {{nowrap|<tt>MENU HIDDEN</tt>}} alone - a specific command can be directly triggered.

The [[Menu#MENU_HIDDENKEY|<tt>MENU HIDDENKEY</tt>]] directive requires  the {{nowrap|<tt>MENU HIDDEN</tt>}} directive to be also present.

Using the caret symbol (^) in front of a ''key'' in a <tt>MENU HIDDENKEY</tt> statement means that the combination of [Ctrl] with such ''key'' would trigger the relevant command.

In the following example,
* pressing [a] (lowercase) or [A] (uppercase) would automatically execute "mylabel_a"; 
* pressing [b] (lowercase) or [Ctrl-B] (uppercase) or [Ctrl-b] (lowercase) would automatically execute "mylabel_b"; 
* note that pressing [B] (uppercase) alone (without [Ctrl])  would trigger no specific action other than the menu.

<pre>
  UI menu.c32
  TIMEOUT 40
  MENU HIDDEN
  MENU HIDDENKEY a,A mylabel_a
  MENU HIDDENKEY b,^B mylabel_b
  
  LABEL mydefault
  KERNEL mykernel
  
  LABEL mylabel_a
  KERNEL mykernel_a
  
  LABEL mylabel_b
  KERNEL mykernel_b
</pre>

=== MENU LABEL hotkeys ===
The caret symbol (^) in a <tt>MENU LABEL</tt> statement defines a hotkey.
While displaying the boot menu, hotkeys are highlighted and pressing a hotkey will move the selection to the corresponding menu item.

=== MENU IMMEDIATE ===
Allow hotkeys to activate immediately without needing to press [Enter].

<!-- -->
<!-- <nowiki> == SAY === </nowiki> -->
<!-- Although this directive slightly affects -->
<!-- the user's experience during boot time, -->
<!-- there is no special key directly involved, -->
<!-- so there is nothing specific -->
<!-- to comment about it in this document. -->
<!-- Yet, the usage of special keys during boot time -->
<!-- could still affect the user's experience -->
<!-- regarding this directive. -->
<!-- -->
<!-- -->
<!-- <nowiki> == DISPLAY === </nowiki> -->
<!-- Although this directive slightly affects -->
<!-- the user's experience during boot time, -->
<!-- there is no special key directly involved, -->
<!-- so there is nothing specific -->
<!-- to comment about it in this document. -->
<!-- Yet, the usage of special keys during boot time -->
<!-- could still affect the user's experience -->
<!-- regarding this directive. -->
<!-- -->


== Others ==
The following directives are not necessarily related to how Syslinux behaves, but rather to what the user is {{nowrap|(dis)allowed.}}
In other words, the following directives {{nowrap|(dis)allow}} the user (to be able) to perform certain actions.

=== F1..F12 ===
Load the respective [[Config#DISPLAY_file_format|DISPLAY]] file.

=== NOCOMPLETE ===
Using "<tt>NOCOMPLETE 1</tt>", the [Tab] key does not display labels at the {{nowrap|"<tt>boot:</tt>"}} prompt.

=== ALLOWOPTIONS ===
Please [[contact]] the Syslinux mailing list regarding this directive.

=== MENU PASSWD ===
Set a password on a particular menu entry.

=== MENU MASTER PASSWD ===
Set a master password.  
This password can be used to boot any menu entry (in comparison to <tt>MENU PASSWD</tt>).
If this directive is used, then the master password is required for the [Tab] and [Esc] keys to work.

=== Novice protection ===
Syslinux will attempt to detect booting on a machine with too little memory, which means the Linux boot sequence cannot be completed. 
If so, a message is displayed and the boot sequence is aborted. 
Holding down the [Ctrl] key while booting, disables this feature.