diff options
Diffstat (limited to 'doc/README.DGAWK')
| -rw-r--r-- | doc/README.DGAWK | 304 |
1 files changed, 0 insertions, 304 deletions
diff --git a/doc/README.DGAWK b/doc/README.DGAWK deleted file mode 100644 index ac54e29c..00000000 --- a/doc/README.DGAWK +++ /dev/null @@ -1,304 +0,0 @@ -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 |