From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.71) id 1U08VP-00075v-JK for mharc-grub-devel@gnu.org; Tue, 29 Jan 2013 05:33:31 -0500 Received: from eggs.gnu.org ([208.118.235.92]:55735) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U08VE-00072i-LI for grub-devel@gnu.org; Tue, 29 Jan 2013 05:33:29 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1U08VB-00065g-5r for grub-devel@gnu.org; Tue, 29 Jan 2013 05:33:20 -0500 Received: from mail-lb0-f181.google.com ([209.85.217.181]:33392) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1U08VA-00063B-Ds for grub-devel@gnu.org; Tue, 29 Jan 2013 05:33:17 -0500 Received: by mail-lb0-f181.google.com with SMTP id gm6so503968lbb.26 for ; Tue, 29 Jan 2013 02:33:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=x-received:date:from:to:subject:message-id:in-reply-to:references :x-mailer:mime-version:content-type:content-transfer-encoding; bh=5HbSlnZcTPzAPBOgMSxwX4aq8XiymsNmqxTuRUtJ8Fo=; b=GWNE6k52C1bebPkatyyfNSVyU2BJyB1+0PnuMEOuvT4BRmIvqs7zEPQoophsMYIOj1 R9VAgQ5iPLa7FvGkMfv+gazOox6Mch4A7qcNW9yLoX+DWBgeoZXX4PkNvxLfE8YIJyB6 mrkl6Zw0285jDIRue1KwcxWUA+qE2zyfcJkST51fiWHROxyrW9aFviKDZeGFC3i6txeh fKxO1UrXfz04r+K96ETl2h5KN7pFcWC72HC0CNcmjRM2Gw1eRm/zY5XtyWlloyG7ssi8 cufi0oY6ZusTgI7CNDTKSd4oawI9rVDlLKfasiFZZVRzKmL36AtAy9UTiBkLWqf2OuMA lxVg== X-Received: by 10.152.114.66 with SMTP id je2mr587680lab.40.1359455121200; Tue, 29 Jan 2013 02:25:21 -0800 (PST) Received: from opensuse.site (ppp91-78-198-46.pppoe.mtu-net.ru. [91.78.198.46]) by mx.google.com with ESMTPS id ft8sm4728720lab.9.2013.01.29.02.25.19 (version=SSLv3 cipher=RC4-SHA bits=128/128); Tue, 29 Jan 2013 02:25:19 -0800 (PST) Date: Tue, 29 Jan 2013 14:25:17 +0400 From: Andrey Borzenkov To: grub-devel@gnu.org Subject: Command documentation part 1. Message-ID: <20130129142517.44838703@opensuse.site> In-Reply-To: <20130122171218.GA9543@riva.dynamic.greenend.org.uk> References: <20130122170851.1bb50f87@opensuse.site> <20130122171218.GA9543@riva.dynamic.greenend.org.uk> X-Mailer: Claws Mail 3.9.0 (GTK+ 2.24.10; x86_64-suse-linux-gnu) Mime-Version: 1.0 Content-Type: text/plain; charset=KOI8-R Content-Transfer-Encoding: 8bit X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 209.85.217.181 X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list Reply-To: The development of GNU GRUB List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Jan 2013 10:33:29 -0000 В Tue, 22 Jan 2013 17:12:18 +0000 Colin Watson пишет: > 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). 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 - 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? Patch follows From: Andrey Borzenkov Subject: [PATCH] document grub commands Add documentation for grub commands Signed-off-by: Andrey Borzenkov --- docs/grub.texi | 262 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 259 insertions(+), 3 deletions(-) diff --git a/docs/grub.texi b/docs/grub.texi index 9941b47..8329ee1 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}] ... +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 @@ -3323,16 +3327,22 @@ 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 * 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 +3351,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) @@ -3352,26 +3363,44 @@ you forget a command, you can run the command @command{help} * load_env:: Load variables from environment block * loopback:: Make a device from a filesystem image * ls:: List devices or files +* 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 +* 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 +3422,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 agruments remove currently loaded background image. +@end deffn + + @node badram @subsection badram @@ -3465,6 +3523,14 @@ 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 cmp @subsection cmp @@ -3515,8 +3581,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 ... +Alias for @code{hashsum --hash crc32 arg ...}. 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 neccessary, 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 +3741,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 ... +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 @@ -3813,6 +3913,23 @@ name syntax}), then list the contents of that directory. @end deffn +@node lsmod +@subsection lsmod + +@deffn Command lsmod +Show list of loaded modules. +@end deffn + + +@node md5sum +@subsection md5sum + +@deffn Command md5sum arg ... +Alias for @code{hashsum --hash md5 arg ...}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + @node normal @subsection normal @@ -3914,6 +4031,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 +4068,14 @@ Reboot the computer. @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 +4268,43 @@ arguments, print all environment variables with their values. @end deffn +@node sha1sum +@subsection sha1sum + +@deffn Command sha1sum arg ... +Alias for @code{hashsum --hash sha1 arg ...}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + +@node sha256sum +@subsection sha256sum + +@deffn Command sha256sum arg ... +Alias for @code{hashsum --hash sha256 arg ...}. See command @command{hashsum} +(@pxref{hashsum}) for full description. +@end deffn + + +@node sha512sum +@subsection sha512sum + +@deffn Command sha512sum arg ... +Alias for @code{hashsum --hash sha512 arg ...}. 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} of 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 +4318,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 +4408,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 mathing modes. +@end deffn + @node Internationalisation @chapter Charset GRUB uses UTF-8 internally other than in rendering where some GRUB-specific @@ -4269,7 +4525,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: (cd8fd59..) u/cmd-doc (depends on: master)