Re: Command documentation part 1.

[Andrey Borzenkov <arvidjaar@gmail.com>]

В Sat, 09 Feb 2013 12:48:19 +0100
Francesco Lavra <francescolavra.fl@gmail.com> пишет:

Thank you for review!

> Hi,
> 
> On 01/29/2013 11:25 AM, Andrey Borzenkov wrote:
> > В Tue, 22 Jan 2013 17:12:18 +0000
> > Colin Watson <cjwatson@ubuntu.com> пишет:
> > 
> >> On Tue, Jan 22, 2013 at 05:08:51PM +0400, Andrey Borzenkov wrote:
> >>> Quit a number of commands are not documented. Is it intentional
> >>> (because they are not considered "user level API")? Should
> >>> documentation for them go into grub or grub-dev?
> >>
> >> I spent some time documenting the list of commands a while back, but I
> >> never completed the project: what you're seeing is simply how far I got
> >> before getting distracted by other things.  IMO all commands should be
> >> documented in grub.texi.
> >>
> > 
> > Below is attempt to document most of user-relevant commands (I may have
> > missed a couple of them). Please review (formatting, language).
> > 

Well, after some examination there were more left, so version with some
more commands added and typo fixed.

> > What is left are
> > 
> > - new file signature checks. I need some time to understand how to
> >   describe them
> > 
> > - non-Linux loaders. I do not have experience myself, so it will need
> >   some help probably
> > 

- net commands are missing

- legacy commands are missing

> > - the rest of commands which are more or less low-level, not normally
> >   expected to be used daily. I have the following suggestion:
> > 
> > * merge General commands and Command-line and menu entry commands into
> >   General commands. Current split seems to be artificial. Let normal
> >   user commands go into this section
> > 
> > * Add Advanced commands section where all the more exotic ones are described.
> > 
> >   Does it make sense?
> > 


From: Andrey Borzenkov <arvidjaar@gmail.com>
Subject: [PATCH v2] document grub commands

Add documentation for grub commands

Signed-off-by: Andrey Borzenkov <arvidjaar@gmail.com>

---
 docs/grub.texi |  322 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 316 insertions(+), 6 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index 9941b47..494a59d 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -1553,6 +1553,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
@@ -1750,8 +1754,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''.
 
 
@@ -3323,16 +3327,24 @@ 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
+* cmostest::                    Test bit in CMOS
 * cmp::                         Compare two files
 * configfile::                  Load a configuration file
 * cpuid::                       Check for CPU features
 * crc::                         Calculate 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
@@ -3341,6 +3353,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)
@@ -3349,29 +3362,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::                      Calculate 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::                     Calculate SHA1 hash
+* sha256sum::                   Calculate SHA256 hash
+* sha512sum::                   Calculate 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
+* 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
 
@@ -3393,6 +3427,35 @@ 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}.
+@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.
+@end deffn
+
+
 @node badram
 @subsection badram
 
@@ -3465,6 +3528,33 @@ 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 PC BIOS platform.
+@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 PC BIOS platform.
+@end deffn
+
+
 @node cmp
 @subsection cmp
 
@@ -3515,8 +3605,21 @@ 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 encrypted devices;
+option @option{-b} configures all partitions that have boot flag set.
 @end deffn
 
 
@@ -3662,6 +3765,27 @@ 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{crc32}, @samp{md5}, @samp{sha1}, @samp{sha256},
+@samp{sha512}. 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. File hash and file name are separated by
+single @key{SPACE} or @key{TAB}, one pair on a line. 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
 
@@ -3780,6 +3904,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
 
@@ -3813,6 +3947,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
 
@@ -3898,7 +4057,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
@@ -3914,6 +4073,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
 
@@ -3942,6 +4110,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
 
@@ -4134,6 +4322,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
 
@@ -4147,6 +4372,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
 
@@ -4169,6 +4462,23 @@ Unset the environment variable @var{envvar}.
 
 This command is not yet implemented for GRUB 2, although it is planned.
 
+
+@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
+
+
+@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
@@ -4269,7 +4579,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.
-- 
tg: (cc35b49..) u/cmd-doc (depends on: master)