1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Commands In Guile</title> 18 19<meta name="description" content="Debugging with GDB: Commands In Guile"> 20<meta name="keywords" content="Debugging with GDB: Commands In Guile"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Guile-API.html#Guile-API" rel="up" title="Guile API"> 29<link href="Parameters-In-Guile.html#Parameters-In-Guile" rel="next" title="Parameters In Guile"> 30<link href="Writing-a-Guile-Pretty_002dPrinter.html#Writing-a-Guile-Pretty_002dPrinter" rel="previous" title="Writing a Guile Pretty-Printer"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Commands-In-Guile"></a> 65<div class="header"> 66<p> 67Next: <a href="Parameters-In-Guile.html#Parameters-In-Guile" accesskey="n" rel="next">Parameters In Guile</a>, Previous: <a href="Writing-a-Guile-Pretty_002dPrinter.html#Writing-a-Guile-Pretty_002dPrinter" accesskey="p" rel="previous">Writing a Guile Pretty-Printer</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Commands-In-Guile-1"></a> 71<h4 class="subsubsection">23.3.3.11 Commands In Guile</h4> 72 73<a name="index-commands-in-guile"></a> 74<a name="index-guile-commands-1"></a> 75<p>You can implement new <small>GDB</small> CLI commands in Guile. A CLI 76command object is created with the <code>make-command</code> Guile function, 77and added to <small>GDB</small> with the <code>register-command!</code> Guile function. 78This two-step approach is taken to separate out the side-effect of adding 79the command to <small>GDB</small> from <code>make-command</code>. 80</p> 81<p>There is no support for multi-line commands, that is commands that 82consist of multiple lines and are terminated with <code>end</code>. 83</p> 84<dl> 85<dt><a name="index-_0028make_002dcommand"></a>Scheme Procedure: <strong>(make-command</strong> <em>name <span class="roman">[</span>#:invoke invoke] <span class="roman">[</span>#:command-class command-class<span class="roman">]</span> <span class="roman">[</span>#:completer-class completer] <span class="roman">[</span>#:prefix? prefix<span class="roman">]</span> <span class="roman">[</span>#:doc doc-string])</em></dt> 86<dd> 87<p>The argument <var>name</var> is the name of the command. If <var>name</var> consists of 88multiple words, then the initial words are looked for as prefix 89commands. In this case, if one of the prefix commands does not exist, 90an exception is raised. 91</p> 92<p>The result is the <code><gdb:command></code> object representing the command. 93The command is not usable until it has been registered with <small>GDB</small> 94with <code>register-command!</code>. 95</p> 96<p>The rest of the arguments are optional. 97</p> 98<p>The argument <var>invoke</var> is a procedure of three arguments: <var>self</var>, 99<var>args</var> and <var>from-tty</var>. The argument <var>self</var> is the 100<code><gdb:command></code> object representing the command. 101The argument <var>args</var> is a string representing the arguments passed to 102the command, after leading and trailing whitespace has been stripped. 103The argument <var>from-tty</var> is a boolean flag and specifies whether the 104command should consider itself to have been originated from the user 105invoking it interactively. If this function throws an exception, 106it is turned into a <small>GDB</small> <code>error</code> call. 107Otherwise, the return value is ignored. 108</p> 109<p>The argument <var>command-class</var> is one of the ‘<samp>COMMAND_</samp>’ constants 110defined below. This argument tells <small>GDB</small> how to categorize the 111new command in the help system. The default is <code>COMMAND_NONE</code>. 112</p> 113<p>The argument <var>completer</var> is either <code>#f</code>, one of the ‘<samp>COMPLETE_</samp>’ 114constants defined below, or a procedure, also defined below. 115This argument tells <small>GDB</small> how to perform completion 116for this command. If not provided or if the value is <code>#f</code>, 117then no completion is performed on the command. 118</p> 119<p>The argument <var>prefix</var> is a boolean flag indicating whether the new 120command is a prefix command; sub-commands of this command may be 121registered. 122</p> 123<p>The argument <var>doc-string</var> is help text for the new command. 124If no documentation string is provided, the default value “This command is 125not documented.” is used. 126</p></dd></dl> 127 128<dl> 129<dt><a name="index-register_002dcommand_0021"></a>Scheme Procedure: <strong>register-command!</strong> <em>command</em></dt> 130<dd><p>Add <var>command</var>, a <code><gdb:command></code> object, to <small>GDB</small>’s 131list of commands. 132It is an error to register a command more than once. 133The result is unspecified. 134</p></dd></dl> 135 136<dl> 137<dt><a name="index-command_003f"></a>Scheme Procedure: <strong>command?</strong> <em>object</em></dt> 138<dd><p>Return <code>#t</code> if <var>object</var> is a <code><gdb:command></code> object. 139Otherwise return <code>#f</code>. 140</p></dd></dl> 141 142<a name="index-don_0027t-repeat-Guile-command"></a> 143<dl> 144<dt><a name="index-dont_002drepeat"></a>Scheme Procedure: <strong>dont-repeat</strong></dt> 145<dd><p>By default, a <small>GDB</small> command is repeated when the user enters a 146blank line at the command prompt. A command can suppress this 147behavior by invoking the <code>dont-repeat</code> function. This is similar 148to the user command <code>dont-repeat</code>, see <a href="Define.html#Define">dont-repeat</a>. 149</p></dd></dl> 150 151<dl> 152<dt><a name="index-string_002d_003eargv"></a>Scheme Procedure: <strong>string->argv</strong> <em>string</em></dt> 153<dd><p>Convert a string to a list of strings split up according to 154<small>GDB</small>’s argv parsing rules. 155It is recommended to use this for consistency. 156Arguments are separated by spaces and may be quoted. 157Example: 158</p> 159<div class="smallexample"> 160<pre class="smallexample">scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"") 161$1 = ("1" "2 \"3" "4 \"5" "6 '7") 162</pre></div> 163</dd></dl> 164 165<dl> 166<dt><a name="index-throw_002duser_002derror"></a>Scheme Procedure: <strong>throw-user-error</strong> <em>message . args</em></dt> 167<dd><p>Throw a <code>gdb:user-error</code> exception. 168The argument <var>message</var> is the error message as a format string, like the 169<var>fmt</var> argument to the <code>format</code> Scheme function. 170See <a href="http://www.gnu.org/software/guile/manual/html_node/Formatted-Output.html#Formatted-Output">Formatted Output</a> in <cite>GNU Guile Reference Manual</cite>. 171The argument <var>args</var> is a list of the optional arguments of <var>message</var>. 172</p> 173<p>This is used when the command detects a user error of some kind, 174say a bad command argument. 175</p> 176<div class="smallexample"> 177<pre class="smallexample">(gdb) guile (use-modules (gdb)) 178(gdb) guile 179(register-command! (make-command "test-user-error" 180 #:command-class COMMAND_OBSCURE 181 #:invoke (lambda (self arg from-tty) 182 (throw-user-error "Bad argument ~a" arg)))) 183end 184(gdb) test-user-error ugh 185ERROR: Bad argument ugh 186</pre></div> 187</dd></dl> 188 189<a name="index-completion-of-Guile-commands"></a> 190<dl> 191<dt><a name="index-self"></a>completer: <strong>self</strong> <em>text word</em></dt> 192<dd><p>If the <var>completer</var> option to <code>make-command</code> is a procedure, 193it takes three arguments: <var>self</var> which is the <code><gdb:command></code> 194object, and <var>text</var> and <var>word</var> which are both strings. 195The argument <var>text</var> holds the complete command line up to the cursor’s 196location. The argument <var>word</var> holds the last word of the command line; 197this is computed using a word-breaking heuristic. 198</p> 199<p>All forms of completion are handled by this function, that is, 200the <tt class="key">TAB</tt> and <tt class="key">M-?</tt> key bindings (see <a href="Completion.html#Completion">Completion</a>), 201and the <code>complete</code> command (see <a href="Help.html#Help">complete</a>). 202</p> 203<p>This procedure can return several kinds of values: 204</p> 205<ul> 206<li> If the return value is a list, the contents of the list are used as the 207completions. It is up to <var>completer</var> to ensure that the 208contents actually do complete the word. An empty list is 209allowed, it means that there were no completions available. Only 210string elements of the list are used; other elements in the 211list are ignored. 212 213</li><li> If the return value is a <code><gdb:iterator></code> object, it is iterated over to 214obtain the completions. It is up to <code>completer-procedure</code> to ensure 215that the results actually do complete the word. Only 216string elements of the result are used; other elements in the 217sequence are ignored. 218 219</li><li> All other results are treated as though there were no available 220completions. 221</li></ul> 222</dd></dl> 223 224<p>When a new command is registered, it will have been declared as a member of 225some general class of commands. This is used to classify top-level 226commands in the on-line help system; note that prefix commands are not 227listed under their own category but rather that of their top-level 228command. The available classifications are represented by constants 229defined in the <code>gdb</code> module: 230</p> 231<dl compact="compact"> 232<dt><code>COMMAND_NONE</code> 233<a name="index-COMMAND_005fNONE-1"></a> 234</dt> 235<dd><p>The command does not belong to any particular class. A command in 236this category will not be displayed in any of the help categories. 237This is the default. 238</p> 239</dd> 240<dt><code>COMMAND_RUNNING</code> 241<a name="index-COMMAND_005fRUNNING-1"></a> 242</dt> 243<dd><p>The command is related to running the inferior. For example, 244<code>start</code>, <code>step</code>, and <code>continue</code> are in this category. 245Type <kbd>help running</kbd> at the <small>GDB</small> prompt to see a list of 246commands in this category. 247</p> 248</dd> 249<dt><code>COMMAND_DATA</code> 250<a name="index-COMMAND_005fDATA-1"></a> 251</dt> 252<dd><p>The command is related to data or variables. For example, 253<code>call</code>, <code>find</code>, and <code>print</code> are in this category. Type 254<kbd>help data</kbd> at the <small>GDB</small> prompt to see a list of commands 255in this category. 256</p> 257</dd> 258<dt><code>COMMAND_STACK</code> 259<a name="index-COMMAND_005fSTACK-1"></a> 260</dt> 261<dd><p>The command has to do with manipulation of the stack. For example, 262<code>backtrace</code>, <code>frame</code>, and <code>return</code> are in this 263category. Type <kbd>help stack</kbd> at the <small>GDB</small> prompt to see a 264list of commands in this category. 265</p> 266</dd> 267<dt><code>COMMAND_FILES</code> 268<a name="index-COMMAND_005fFILES-1"></a> 269</dt> 270<dd><p>This class is used for file-related commands. For example, 271<code>file</code>, <code>list</code> and <code>section</code> are in this category. 272Type <kbd>help files</kbd> at the <small>GDB</small> prompt to see a list of 273commands in this category. 274</p> 275</dd> 276<dt><code>COMMAND_SUPPORT</code> 277<a name="index-COMMAND_005fSUPPORT-1"></a> 278</dt> 279<dd><p>This should be used for “support facilities”, generally meaning 280things that are useful to the user when interacting with <small>GDB</small>, 281but not related to the state of the inferior. For example, 282<code>help</code>, <code>make</code>, and <code>shell</code> are in this category. Type 283<kbd>help support</kbd> at the <small>GDB</small> prompt to see a list of 284commands in this category. 285</p> 286</dd> 287<dt><code>COMMAND_STATUS</code> 288<a name="index-COMMAND_005fSTATUS-1"></a> 289</dt> 290<dd><p>The command is an ‘<samp>info</samp>’-related command, that is, related to the 291state of <small>GDB</small> itself. For example, <code>info</code>, <code>macro</code>, 292and <code>show</code> are in this category. Type <kbd>help status</kbd> at the 293<small>GDB</small> prompt to see a list of commands in this category. 294</p> 295</dd> 296<dt><code>COMMAND_BREAKPOINTS</code> 297<a name="index-COMMAND_005fBREAKPOINTS-1"></a> 298</dt> 299<dd><p>The command has to do with breakpoints. For example, <code>break</code>, 300<code>clear</code>, and <code>delete</code> are in this category. Type <kbd>help 301breakpoints</kbd> at the <small>GDB</small> prompt to see a list of commands in 302this category. 303</p> 304</dd> 305<dt><code>COMMAND_TRACEPOINTS</code> 306<a name="index-COMMAND_005fTRACEPOINTS-1"></a> 307</dt> 308<dd><p>The command has to do with tracepoints. For example, <code>trace</code>, 309<code>actions</code>, and <code>tfind</code> are in this category. Type 310<kbd>help tracepoints</kbd> at the <small>GDB</small> prompt to see a list of 311commands in this category. 312</p> 313</dd> 314<dt><code>COMMAND_USER</code> 315<a name="index-COMMAND_005fUSER-1"></a> 316</dt> 317<dd><p>The command is a general purpose command for the user, and typically 318does not fit in one of the other categories. 319Type <kbd>help user-defined</kbd> at the <small>GDB</small> prompt to see 320a list of commands in this category, as well as the list of gdb macros 321(see <a href="Sequences.html#Sequences">Sequences</a>). 322</p> 323</dd> 324<dt><code>COMMAND_OBSCURE</code> 325<a name="index-COMMAND_005fOBSCURE-1"></a> 326</dt> 327<dd><p>The command is only used in unusual circumstances, or is not of 328general interest to users. For example, <code>checkpoint</code>, 329<code>fork</code>, and <code>stop</code> are in this category. Type <kbd>help 330obscure</kbd> at the <small>GDB</small> prompt to see a list of commands in this 331category. 332</p> 333</dd> 334<dt><code>COMMAND_MAINTENANCE</code> 335<a name="index-COMMAND_005fMAINTENANCE-1"></a> 336</dt> 337<dd><p>The command is only useful to <small>GDB</small> maintainers. The 338<code>maintenance</code> and <code>flushregs</code> commands are in this category. 339Type <kbd>help internals</kbd> at the <small>GDB</small> prompt to see a list of 340commands in this category. 341</p></dd> 342</dl> 343 344<p>A new command can use a predefined completion function, either by 345specifying it via an argument at initialization, or by returning it 346from the <code>completer</code> procedure. These predefined completion 347constants are all defined in the <code>gdb</code> module: 348</p> 349<dl compact="compact"> 350<dt><code>COMPLETE_NONE</code> 351<a name="index-COMPLETE_005fNONE-1"></a> 352</dt> 353<dd><p>This constant means that no completion should be done. 354</p> 355</dd> 356<dt><code>COMPLETE_FILENAME</code> 357<a name="index-COMPLETE_005fFILENAME-1"></a> 358</dt> 359<dd><p>This constant means that filename completion should be performed. 360</p> 361</dd> 362<dt><code>COMPLETE_LOCATION</code> 363<a name="index-COMPLETE_005fLOCATION-1"></a> 364</dt> 365<dd><p>This constant means that location completion should be done. 366See <a href="Specify-Location.html#Specify-Location">Specify Location</a>. 367</p> 368</dd> 369<dt><code>COMPLETE_COMMAND</code> 370<a name="index-COMPLETE_005fCOMMAND-1"></a> 371</dt> 372<dd><p>This constant means that completion should examine <small>GDB</small> 373command names. 374</p> 375</dd> 376<dt><code>COMPLETE_SYMBOL</code> 377<a name="index-COMPLETE_005fSYMBOL-1"></a> 378</dt> 379<dd><p>This constant means that completion should be done using symbol names 380as the source. 381</p> 382</dd> 383<dt><code>COMPLETE_EXPRESSION</code> 384<a name="index-COMPLETE_005fEXPRESSION-1"></a> 385</dt> 386<dd><p>This constant means that completion should be done on expressions. 387Often this means completing on symbol names, but some language 388parsers also have support for completing on field names. 389</p></dd> 390</dl> 391 392<p>The following code snippet shows how a trivial CLI command can be 393implemented in Guile: 394</p> 395<div class="smallexample"> 396<pre class="smallexample">(gdb) guile 397(register-command! (make-command "hello-world" 398 #:command-class COMMAND_USER 399 #:doc "Greet the whole world." 400 #:invoke (lambda (self args from-tty) (display "Hello, World!\n")))) 401end 402(gdb) hello-world 403Hello, World! 404</pre></div> 405 406<hr> 407<div class="header"> 408<p> 409Next: <a href="Parameters-In-Guile.html#Parameters-In-Guile" accesskey="n" rel="next">Parameters In Guile</a>, Previous: <a href="Writing-a-Guile-Pretty_002dPrinter.html#Writing-a-Guile-Pretty_002dPrinter" accesskey="p" rel="previous">Writing a Guile Pretty-Printer</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 410</div> 411 412 413 414</body> 415</html> 416