diff options
Diffstat (limited to 'doc/README.DGAWK')
| -rw-r--r-- | doc/README.DGAWK | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/doc/README.DGAWK b/doc/README.DGAWK new file mode 100644 index 00000000..ac54e29c --- /dev/null +++ b/doc/README.DGAWK @@ -0,0 +1,304 @@ +INVOKING: + + Invoking dgawk is similar to gawk. Run dgawk with all options and arguments as +you would supply to gawk. Command line scripts can not be debugged using dgawk. +dgawk expects at least one program text included via the -f option. If you include +programs using the --source option, dgawk will not stop at instructions originating +from that source. + +USAGE: + + $> dgawk -f foo.awk + dgawk> list + ... + dgawk> break 5 + ... + dgawk> run + ... + dgawk> next + ... + dgawk> continue + ... + dgawk> quit + + +COMMANDS: + + * help [command] + prints a list of all commands and short descriptions. + 'help command' prints the information about command 'command'. + + * info source|sources|variables|functions|break|frame|args|locals|display|watch + * source + name of the current source file. Each time the program stops, the + current source file is the file containing the current instruction. + When dgawk first starts, the current source file is the first file + included via the -f option. The 'list filename:lineno' command can + be used at any time to change the current source. + * sources + list all program sources. + * variables + list all global variables. + * functions + list all function definitions including source file names and + line numbers. + * break + list all currently set breakpoints. + * frame + description of the selected stack frame. + * args + arguments of the selected frame. + * locals + local variables of the selected frame. + * display + list of all items in the automatic display list. + * watch + list of all items in the watch list. + + * list [-|+|n|filename:n|m-n|function] + prints specified lines (default 15) from the current source file + or file named 'filename'. + - print lines before the lines last printed. + + print lines after the lines last printed. + list without any argument does the same thing. + n print lines centered around line number 'n'. + m-n print lines from 'm' to 'n'. + filename:n print lines centered around line number 'n' in + source file 'filename'. May change current source file. + function print lines centered around beginning of the + function 'function'. May change current source file. + + * break [[filename:]n|function] + Without any argument, sets a breakpoint at the next instruction + to be executed in the selected stack frame. + n set a breakpoint at line number 'n' in the current + source file. + filename:n set a breakpoint at line number 'n' in source file + 'filename'. + function set a breakpoint at entry to function (first instruction) + 'function'. + + * tbreak [[filename:]n|function] + set a temporary breakpoint (enabled for only one stop). + + * disable [n1 n2 ...] [m-n] + disable specified breakpoints or a range of breakpoints. Without + any argument, disables all breakpoints. + + * enable [once|del] [n1 n2 ...] [m-n] + enable specified breakpoints or a range of breakpoints. Without + any argument, enables all breakpoints. + once enable breakpoint(s) temporarily, then disable it when + the program stops at the breakpoint. + del enable breakpoint(s) tempoarily, then delete it when + the program stops at the breakpoint. + + * delete [n1 n2 ...] [m-n] + delete specified breakpoints or a range of breakpoints. Deletes + all defined breakpoints if no argument is supplied. + + * clear [[filename:]n|function] + without any argument, deletes any breakpoint at the next instruction + to be executed in the selected stack frame. If the program stops at + a breakpoint, this will delete that breakpoint so that the program + does not stop at that location again. + n delete breakpoint(s) set at line number 'n' in current + source file. + filename:n delete breakpoint(s) set at line number 'n' in source + file 'filename'. + function delete breakpoint(s) set at entry to function 'function'. + + * ignore N COUNT + ignore breakpoint N COUNT times before stopping. + + * run + starts/restarts execution of the program. When restarting, dgawk retains + current breakpoints, watchpoints, command history, automatic display + variables and debugger options. + + * frame [N] + select and print (frame number, function and argument names, source file, + and the source line) stack frame N. Frame 0 is the currently executing + or innermost frame (function call), frame 1 is the frame that called the + innermost one. The highest numbered frame is the one for 'main'. + + * up [COUNT] + move COUNT (default 1) frames up the stack toward the outermost frame. + selects and prints the frame. + + * down [COUNT] + move COUNT (default 1) frames down the stack toward the innermost frame. + selects and prints the frame. + + * backtrace [COUNT] + print backtrace of all function calls (stack frames), or innermost COUNT + frames if COUNT > 0. Prints outermost -COUNT frames for COUNT < 0. + Displays name and arguments to each function, source filename and line number. + + * continue [COUNT] + resume program execution. If continued from a breakpoint and COUNT is + specified, ignores the breakpoint at that location next COUNT times before + stopping. + + * step [COUNT] + continue execution until control reaches a different source line in the + current stack frame. Step steps inside any function called within the line. + If the argument COUNT is supplied, steps that many times before stopping, + unless it encounters a breakpoint (or watchpoint). + + * next [COUNT] + continue execution to the next source line, stepping over function calls. + The argument COUNT controls how many times to repeat the action as + in step. + + * stepi [COUNT] + execute one (or COUNT) instruction(s), stepping inside function calls. + + * nexti [COUNT] + execute one (or COUNT) instruction(s), stepping over function calls. + + * finish + execute program until the selected stack frame returns. + Prints the returned value. + + * return [value] + cancel execution of a function call. If 'value' (either string or number) + is specified, it is used as the function's return value. If used in a + frame other than the the innermost one (currently executing function i.e. + frame number 0), discards all outer frames in addition to the selected one, + and the caller of that frame becomes the innermost frame. + + * until [[filename:]n|function] + without any argument, continues execution until a line past the current + line in current stack frame is reached. With argument, + continues execution until the specified location is reached, or the current + stack frame returns. + + * print var1[,|\s|\t var2 ...] + print the value of a gawk variable or field. Fields must be referenced by + constants: + dgawk> print $3 + prints the third field in the input record (if the specified field does not + exist, it will print 'Null field'). Variable can be an array element, with + the subscripts being constant values. To print the contents of an array, + prefix the name of the array with the '@' symbol: + gawk> print @a + prints the index and the corresponding value for all elements in array 'a'. + + * printf format, [arg], ... + print formatted text. May include escape sequences, such as `\n'. + No newline is printed unless specified one. + + * set var=value + assign a constant (number or string) value to a gawk variable or field. + String values must be enclosed between double quotes("). + + * display [var|$n] + add variable 'var' (or field $n) to the automatic display list. The + value of the variable or field is displayed each time the program stops. + Each variable added to the list is identified by a unique number: + dgawk> display x + 10: x = 1 + displays the assigned item number, the variable name and its current value. + If the display variable refers to a function parameter, it is silently + deleted from the list as soon as the execution reaches a context where + no such variable of the given name exists. + Without argument, displays the current values of items on the list. + + * undisplay [N] + remove item number N (or all items) from the automatic display list. + + * watch var|$n + add variable 'var' (or field $n) to the watch list. dgawk will stop whenever + the value of the variable or field changes. Each watched item is assigned a + number which can be used to delete it from the watch list using the + unwatch command. + + * unwatch [N] + remove item number N (or all items) from the watch list. + + * option [name[=value]] + without argument, displays the available debugger options + and their current values. 'option name' shows the current + value of the named option. 'option name=value' assigns + a new value to the named option. + Available options: + * listsize + the number of lines that list prints. The default is 15. + * prompt + debugger prompt. The default is "dgawk> ". + * trace [on|off] + turns instruction tracing on or off. The default is off. + * outfile + sends gawk output to a file; debugger output still goes + to stdout. An empty string ("") resets output to stdout. + * save_history [on|off] + save command history to file ./.dgawk_history. The default is 'on'. + * history_size + maximum no of lines to keep in history file ./.dgawk_history. + The default is 100. + * save_options [on|off] + save current options to file ./.dgawkrc on quit. The default is 'on'. + Options are read back in next session on startup. + + * commands [N] + * silent + * end + 'commands' sets list of commands to be executed when stopped at + a breakpoint or watchpoint. N is the breakpoint or watchpoint number. + Without a number, refers to the last one set. The actual commands follow + starting on the next line and are terminated by the 'end' command. + If the command 'silent' is in the list, the usual messages about stopping + at a breakpoint and the sourceline are not printed. Any command + in the list that resumes execution (e.g. continue) terminates the list + (an implicit end), and subsequent commands are ignored. + + dgawk> commands + > silent + > printf "A silent breakpoint; i = %d\n", i + > info locals + > set i = 10 + > continue + > end + dgawk> + + * source filename + run command(s) from a file; an error in any command does not + terminate execution of subsequent commands. Comments (lines starting + with #) are allowed in a command file. Empty lines are ignored, does not + repeat last command. Can't restart program by having more than one run + command in the file. + Can also use the '-R file' OR '--command=file' command line option to + execute commands from a file non-interactively. + + * save filename + saves the commands from the current session to the given filename, + so it can be replayed using the source command. + + * quit + quit debugger. + + +READLINE SUPPORT: + + If compiled with readline library, you can take advantage of its command +completion and history expansion feature. The following types of completion +are available: + * command completion + command names. + * source filename completion + source file names. Relevant commands are list, break, tbreak, until, + and clear. + * argument completion + non-number arguments to a command. Relevant commands are info and enable. + * variable name completion + global variable names, and function arguments in the current context + if the program is running. Relevant commands are print, set, watch, + and display. + +REFERENCES: + + * Debugging with GDB, the manual for the GNU Source-Level Debugger. + Much of the contents of this README shamelessly stolen and adapted from it. + * GNU Readline User's Manual + * GNU History User's Manual |