From 16cc9f03a01a526bd9d156129befeb9ae0939d00 Mon Sep 17 00:00:00 2001 From: Andrey Borzenkov Date: Fri, 5 Apr 2013 10:18:42 +0200 Subject: [PATCH] * docs/grub.texi: Document more user commands. --- ChangeLog | 4 + docs/grub.texi | 352 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 347 insertions(+), 9 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6113a394f..d63c0e558 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2013-04-04 Andrey Borzenkov + + * docs/grub.texi: Document more user commands. + 2013-04-04 Andrey Borzenkov * docs/grub.texi: Document menuentry --id option. diff --git a/docs/grub.texi b/docs/grub.texi index 742d40601..bd366a67d 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -1554,6 +1554,10 @@ Causes a function to exit with the return value specified by @code{n}. If in the function body. If used outside a function the return status is false. +@item setparams [@code{arg}] @dots{} +Replace positional parameters starting with @code{$1} with arguments to +@command{setparams}. + @item shift [@code{n}] The positional parameters from @code{n}+1 @dots{} are renamed to @code{$1}@dots{}. Parameters represented by the numbers @code{$#} down to @@ -1751,8 +1755,8 @@ Colors can be specified in several ways: The fonts GRUB uses ``PFF2 font format'' bitmap fonts. Fonts are specified with full font names. Currently there is no provision for a preference list of fonts, or deriving one font from another. -Fonts are loaded with the ``loadfont'' command in GRUB. To see the list of -loaded fonts, execute the ``lsfonts'' command. If there are too many fonts to +Fonts are loaded with the ``loadfont'' command in GRUB (@ref{loadfont}). To see the list of +loaded fonts, execute the ``lsfonts'' command (@ref{lsfonts}). If there are too many fonts to fit on screen, do ``set pager=1'' before executing ``lsfonts''. @@ -3365,16 +3369,25 @@ you forget a command, you can run the command @command{help} (@pxref{help}). @menu +* [:: Check file types and compare values * acpi:: Load ACPI tables +* authenticate:: Check whether user is in user list +* background_color:: Set background color for active terminal +* background_image:: Load background image for active terminal * badram:: Filter out bad regions of RAM * blocklist:: Print a block list * boot:: Start up your operating system * cat:: Show the contents of a file * chainloader:: Chain-load another boot loader +* clear:: Clear the screen +* cmosclean:: Clear bit in CMOS +* cmosdump:: Dump CMOS contents +* cmostest:: Test bit in CMOS * cmp:: Compare two files * configfile:: Load a configuration file * cpuid:: Check for CPU features -* crc:: Calculate CRC32 checksums +* crc:: Compute or check CRC32 checksums +* cryptomount:: Mount a crypto device * date:: Display or set current date and time * drivemap:: Map a drive to another * echo:: Display a line of text @@ -3383,6 +3396,7 @@ you forget a command, you can run the command @command{help} * gettext:: Translate a string * gptsync:: Fill an MBR based on GPT entries * halt:: Shut down your computer +* hashsum:: Compute or check hash checksum * help:: Show help messages * initrd:: Load a Linux initrd * initrd16:: Load a Linux initrd (16-bit mode) @@ -3391,29 +3405,50 @@ you forget a command, you can run the command @command{help} * linux:: Load a Linux kernel * linux16:: Load a Linux kernel (16-bit mode) * list_env:: List variables in environment block +* loadfont:: Load font files * load_env:: Load variables from environment block * loopback:: Make a device from a filesystem image * ls:: List devices or files +* lsfonts:: List loaded fonts +* lsmod:: Show loaded modules +* md5sum:: Compute or check MD5 hash * normal:: Enter normal mode * normal_exit:: Exit from normal mode * parttool:: Modify partition table entries * password:: Set a clear-text password * password_pbkdf2:: Set a hashed password * play:: Play a tune +* probe:: Retrieve device info * pxe_unload:: Unload the PXE environment * read:: Read user input * reboot:: Reboot your computer +* regexp:: Test if regular expression matches string +* rmmod:: Remove a module * save_env:: Save variables to environment block * search:: Search devices by file, label, or UUID * sendkey:: Emulate keystrokes * set:: Set an environment variable +* sha1sum:: Compute or check SHA1 hash +* sha256sum:: Compute or check SHA256 hash +* sha512sum:: Compute or check SHA512 hash +* sleep:: Wait for a specified number of seconds * source:: Read a configuration file in same context +* test:: Check file types and compare values * true:: Do nothing, successfully * unset:: Unset an environment variable * uppermem:: Set the upper memory size +@comment * vbeinfo:: List available video modes +* videoinfo:: List available video modes @end menu +@node [ +@subsection [ +@deffn Command @code{[} expression @code{]} +Alias for @code{test @var{expression}} (@pxref{test}). +@end deffn + + @node acpi @subsection acpi @@ -3435,6 +3470,42 @@ Normally, this command will replace the Root System Description Pointer GRUB, but may be used by GRUB's EFI emulation. @end deffn + +@node authenticate +@subsection authenticate +@deffn Command authenticate [userlist] +Check whether user is in @var{userlist} or listed in the value of variable +@samp{superusers}. See @pxref{superusers} for valid user list format. +If @samp{superusers} is empty, this command returns true. @xref{Security}. +@end deffn + + +@node background_color +@subsection background_color + +@deffn Command background_color color +Set background color for active terminal. For valid color specifications see +@pxref{Theme file format, ,Colors}. Background color can be changed only when +using @samp{gfxterm} for terminal output. + +This command sets color of empty areas without text. Text background color +is controlled by environment variables @var{color_normal}, @var{color_highlight}, +@var{menu_color_normal}, @var{menu_color_highlight}. @xref{Special environment variables}. +@end deffn + + +@node background_image +@subsection background_image + +@deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file] +Load background image for active terminal from @var{file}. Image is stretched +to fill up entire screen unless option @option{--mode} @samp{normal} is given. +Without arguments remove currently loaded background image. Background image +can be changed only when using @samp{gfxterm} for terminal output. + +@end deffn + + @node badram @subsection badram @@ -3507,6 +3578,42 @@ load a defective boot loader, such as SCO UnixWare 7.1. @end deffn +@node clear +@subsection clear + +@deffn Command clear +Clear the screen. +@end deffn + + +@node cmosclean +@subsection cmosclean + +@deffn Command cmosclean byte:bit +Clear value of bit in CMOS at location @var{byte}:@var{bit}. This command +is available only on platforms that support CMOS. +@end deffn + + +@node cmosdump +@subsection cmosdump + +@deffn Dump CMOS contents +Dump full CMOS contents as hexadecimal values. This command is available only +on platforms that support CMOS. +@end deffn + + +@node cmostest +@subsection cmostest + +@deffn Command cmostest byte:bit +Test value of bit in CMOS at location @var{byte}:@var{bit}. Exit status +is zero if bit is set, non zero otherwise. This command is available only +on platforms that support CMOS. +@end deffn + + @node cmp @subsection cmp @@ -3557,8 +3664,24 @@ invoked with @option{-l}. This may change in the future. @node crc @subsection crc -@deffn Command crc file -Display the CRC32 checksum of @var{file}. +@deffn Command crc arg @dots{} +Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + +@node cryptomount +@subsection cryptomount + +@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b} +Setup access to encrypted device. If necessary, passphrase +is requested interactively. Option @var{device} configures specific grub device +(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device +with specified @var{uuid}; option @option{-a} configures all detected encrypted +devices; option @option{-b} configures all geli containers that have boot flag set. + +GRUB suports devices encrypted using LUKS and geli. Note that necessary modules (@var{luks} and @var{geli}) have to be loaded manually before this command can +be used. @end deffn @@ -3704,6 +3827,29 @@ is shut down using APM. @end deffn +@node hashsum +@subsection hashsum + +@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{} +Compute or verify file hashes. Hash type is selected with option @option{--hash}. +Supported hashes are: @samp{adler32}, @samp{crc64}, @samp{crc32}, +@samp{crc32rfc1510}, @samp{crc24rfc2440}, @samp{md4}, @samp{md5}, +@samp{ripemd160}, @samp{sha1}, @samp{sha224}, @samp{sha256}, @samp{sha512}, +@samp{sha384}, @samp{tiger192}, @samp{tiger}, @samp{tiger2}, @samp{whirlpool}. +Option @option{--uncompress} uncompresses files before computing hash. + +When list of files is given, hash of each file is computed and printed, +followed by file name, each file on a new line. + +When option @option{--check} is given, it points to a file that contains +list of @var{hash name} pairs in the same format as used by UNIX +@command{md5sum} command. Option @option{--prefix} +may be used to give directory where files are located. Hash verification +stops after the first mismatch was found unless option @option{--keep-going} +was given. +@end deffn + + @node help @subsection help @@ -3822,6 +3968,16 @@ block. @end deffn +@node loadfont +@subsection loadfont + +@deffn Command loadfont file @dots{} +Load specified font files. Unless absolute pathname is given, @var{file} +is assumed to be in directory @samp{$prefix/fonts} with +suffix @samp{.pf2} appended. @xref{Theme file format,,Fonts}. +@end deffn + + @node loopback @subsection loopback @@ -3855,6 +4011,31 @@ name syntax}), then list the contents of that directory. @end deffn +@node lsfonts +@subsection lsfonts + +@deffn Command lsfonts +List loaded fonts. +@end deffn + + +@node lsmod +@subsection lsmod + +@deffn Command lsmod +Show list of loaded modules. +@end deffn + + +@node md5sum +@subsection md5sum + +@deffn Command md5sum arg @dots{} +Alias for @code{hashsum --hash md5 arg @dots{}}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + @node normal @subsection normal @@ -3940,7 +4121,7 @@ to generate password hashes. @xref{Security}. @node play @subsection play -@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] ... +@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] @dots{} Plays a tune If the argument is a file name (@pxref{File name syntax}), play the tune @@ -3956,6 +4137,15 @@ a rest. @end deffn +@node probe +@subsection probe + +@deffn Command probe [@option{--set} var] @option{--driver}|@option{--partmap}|@option{--fs}|@option{--fs-uuid}|@option{--label} device +Retrieve device information. If option @option{--set} is given, assign result +to variable @var{var}, otherwise print information on the screen. +@end deffn + + @node pxe_unload @subsection pxe_unload @@ -3984,6 +4174,26 @@ Reboot the computer. @end deffn +@node regexp +@subsection regexp + +@deffn Command regexp [@option{--set} [number:]var] regexp string +Test if regular expression @var{regexp} matches @var{string}. Supported +regular expressions are POSIX.2 Extended Regular Expressions. If option +@option{--set} is given, store @var{number}th matched subexpression in +variable @var{var}. Subexpressions are numbered in order of their opening +parentheses starting from @samp{1}. @var{number} defaults to @samp{1}. +@end deffn + + +@node rmmod +@subsection rmmod + +@deffn Command rmmod module +Remove a loaded @var{module}. +@end deffn + + @node save_env @subsection save_env @@ -4176,6 +4386,43 @@ arguments, print all environment variables with their values. @end deffn +@node sha1sum +@subsection sha1sum + +@deffn Command sha1sum arg @dots{} +Alias for @code{hashsum --hash sha1 arg @dots{}}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + +@node sha256sum +@subsection sha256sum + +@deffn Command sha256sum arg @dots{} +Alias for @code{hashsum --hash sha256 arg @dots{}}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + +@node sha512sum +@subsection sha512sum + +@deffn Command sha512sum arg @dots{} +Alias for @code{hashsum --hash sha512 arg @dots{}}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + +@node sleep +@subsection sleep + +@deffn Command sleep [@option{--verbose}] [@option{--interruptible}] count +Sleep for @var{count} seconds. If option @option{--interruptible} is given, +allow @key{ESC} to interrupt sleep. With @option{--verbose} show countdown +of remaining seconds. +@end deffn + + @node source @subsection source @@ -4189,6 +4436,74 @@ will not be shown immediately. @end deffn +@node test +@subsection test + +@deffn Command test expression +Evaluate @var{expression} and return zero exit status if result is true, +non zero status otherwise. + +@var{expression} is one of: + +@table @asis +@item @var{string1} @code{==} @var{string2} +the strings are equal +@item @var{string1} @code{!=} @var{string2} +the strings are not equal +@item @var{string1} @code{<} @var{string2} +@var{string1} is lexicographically less than @var{string2} +@item @var{string1} @code{<=} @var{string2} +@var{string1} is lexicographically less or equal than @var{string2} +@item @var{string1} @code{>} @var{string2} +@var{string1} is lexicographically greater than @var{string2} +@item @var{string1} @code{>=} @var{string2} +@var{string1} is lexicographically greater or equal than @var{string2} +@item @var{integer1} @code{-eq} @var{integer2} +@var{integer1} is equal to @var{integer2} +@item @var{integer1} @code{-ge} @var{integer2} +@var{integer1} is greater than or equal to @var{integer2} +@item @var{integer1} @code{-gt} @var{integer2} +@var{integer1} is greater than @var{integer2} +@item @var{integer1} @code{-le} @var{integer2} +@var{integer1} is less than or equal to @var{integer2} +@item @var{integer1} @code{-lt} @var{integer2} +@var{integer1} is less than @var{integer2} +@item @var{integer1} @code{-ne} @var{integer2} +@var{integer1} is not equal to @var{integer2} +@item @var{prefix}@var{integer1} @code{-pgt} @var{prefix}@var{integer2} +@var{integer1} is greater than @var{integer2} after stripping off common non-numeric @var{prefix}. +@item @var{prefix}@var{integer1} @code{-plt} @var{prefix}@var{integer2} +@var{integer1} is less than @var{integer2} after stripping off common non-numeric @var{prefix}. +@item @var{file1} @code{-nt} @var{file2} +@var{file1} is newer than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-nt} in which case it is added to the first file modification time. +@item @var{file1} @code{-ot} @var{file2} +@var{file1} is older than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-ot} in which case it is added to the first file modification time. +@item @code{-d} @var{file} +@var{file} exists and is a directory +@item @code{-e} @var{file} +@var{file} exists +@item @code{-f} @var{file} +@var{file} exists and is not a directory +@item @code{-s} @var{file} +@var{file} exists and has a size greater than zero +@item @code{-n} @var{string} +the length of @var{string} is nonzero +@item @var{string} +@var{string} is equivalent to @code{-n @var{string}} +@item @code{-z} @var{string} +the length of @var{string} is zero +@item @code{(} @var{expression} @code{)} +@var{expression} is true +@item @code{!} @var{expression} +@var{expression} is false +@item @var{expression1} @code{-a} @var{expression2} +both @var{expression1} and @var{expression2} are true +@item @var{expression1} @code{-o} @var{expression2} +either @var{expression1} or @var{expression2} is true +@end table +@end deffn + + @node true @subsection true @@ -4211,6 +4526,25 @@ Unset the environment variable @var{envvar}. This command is not yet implemented for GRUB 2, although it is planned. + +@ignore +@node vbeinfo +@subsection vbeinfo + +@deffn Command vbeinfo [[WxH]xD] +Alias for command @command{videoinfo} (@pxref{videoinfo}). It is available +only on PC BIOS platforms. +@end deffn +@end ignore + + +@node videoinfo +@subsection videoinfo + +@deffn Command videoinfo [[WxH]xD] +List available video modes. If resolution is given, show only matching modes. +@end deffn + @node Internationalisation @chapter Charset GRUB uses UTF-8 internally other than in rendering where some GRUB-specific @@ -4311,7 +4645,7 @@ Identifiers containing non-ASCII may work but aren't supported. Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and LF U+000a) are recognised. Other unicode space characters aren't a valid field separator. -@command{test} tests <, >, <=, >=, -pgt and -plt compare the strings in the +@command{test} (@pxref{test}) tests <, >, <=, >=, -pgt and -plt compare the strings in the lexicographical order of unicode codepoints, replicating the behaviour of test from coreutils. environment variables and commands are listed in the same order. @@ -4769,8 +5103,8 @@ Installing to the whole disk device is normally more robust. @item Check that GRUB actually knows how to read from the device and file system containing @file{/boot/grub}. It will not be able to read from encrypted -devices, nor from file systems for which support has not yet been added to -GRUB. +devices with unsupported encryption scheme, nor from file systems for which +support has not yet been added to GRUB. @end itemize