/* [<][>][^][v][top][bottom][index][help] */
DEFINITIONS
This source file includes following definitions.
- pretty_print
- summary_print
- get_help
- get_command
- PHPDBG_COMMAND
- PHPDBG_HELP
/*
+----------------------------------------------------------------------+
| PHP Version 5 |
+----------------------------------------------------------------------+
| Copyright (c) 1997-2015 The PHP Group |
+----------------------------------------------------------------------+
| This source file is subject to version 3.01 of the PHP license, |
| that is bundled with this package in the file LICENSE, and is |
| available through the world-wide-web at the following url: |
| http://www.php.net/license/3_01.txt |
| If you did not receive a copy of the PHP license and are unable to |
| obtain it through the world-wide-web, please send a note to |
| license@php.net so we can mail you a copy immediately. |
+----------------------------------------------------------------------+
| Authors: Felipe Pena <felipe@php.net> |
| Authors: Joe Watkins <joe.watkins@live.co.uk> |
| Authors: Bob Weinand <bwoebi@php.net> |
| Authors: Terry Ellison <terry@ellisons.org.uk> |
+----------------------------------------------------------------------+
*/
#include "phpdbg.h"
#include "phpdbg_help.h"
#include "phpdbg_prompt.h"
#include "zend.h"
ZEND_EXTERN_MODULE_GLOBALS(phpdbg);
/* {{{ Commands Table */
#define PHPDBG_COMMAND_HELP_D(name, tip, alias, action) \
{PHPDBG_STRL(#name), tip, sizeof(tip)-1, alias, action, NULL, 0}
const phpdbg_command_t phpdbg_help_commands[] = {
PHPDBG_COMMAND_HELP_D(aliases, "show alias list", 'a', phpdbg_do_help_aliases),
PHPDBG_COMMAND_HELP_D(options, "command line options", 0, NULL),
PHPDBG_COMMAND_HELP_D(overview, "help overview", 0, NULL),
PHPDBG_COMMAND_HELP_D(phpdbginit, "phpdbginit file format", 0, NULL),
PHPDBG_COMMAND_HELP_D(syntax, "syntax overview", 0, NULL),
PHPDBG_END_COMMAND
}; /* }}} */
/* {{{ pretty_print. Formatting escapes and wrapping text in a string before printing it. */
void pretty_print(char *text TSRMLS_DC)
{
char *new, *p, *q;
const char *prompt_escape = phpdbg_get_prompt(TSRMLS_C);
unsigned int prompt_escape_len = strlen(prompt_escape);
unsigned int prompt_len = strlen(PHPDBG_G(prompt)[0]);
const char *bold_on_escape = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[1m" : "";
const char *bold_off_escape = PHPDBG_G(flags) & PHPDBG_IS_COLOURED ? "\033[0m" : "";
unsigned int bold_escape_len = strlen(bold_on_escape);
unsigned int term_width = phpdbg_get_terminal_width(TSRMLS_C);
unsigned int size = 0;
int in_bold = 0;
char *last_new_blank = NULL; /* position in new buffer of last blank char */
unsigned int last_blank_count = 0; /* printable char offset of last blank char */
unsigned int line_count = 0; /* number printable chars on current line */
/* First pass calculates a safe size for the pretty print version */
for (p = text; *p; p++) {
if (UNEXPECTED(p[0] == '*') && p[1] == '*') {
size += bold_escape_len - 2;
p++;
} else if (UNEXPECTED(p[0] == '$') && p[1] == 'P') {
size += prompt_escape_len - 2;
p++;
} else if (UNEXPECTED(p[0] == '\\')) {
p++;
}
}
size += (p-text)+1;
new = emalloc(size);
/*
* Second pass substitutes the bold and prompt escape sequences and line wrap
*
* ** toggles bold on and off if PHPDBG_IS_COLOURED flag is set
* $P substitutes the prompt sequence
* Lines are wrapped by replacing the last blank with a CR before <term width>
* characters. (This defaults to 100 if the width can't be detected). In the
* pathelogical case where no blanks are found, then the wrap occurs at the
* first blank.
*/
for (p = text, q = new; *p; p++) {
if (UNEXPECTED(*p == ' ')) {
last_new_blank = q;
last_blank_count = line_count++;
*q++ = ' ';
} else if (UNEXPECTED(*p == '\n')) {
last_new_blank = NULL;
*q++ = *p;
last_blank_count = 0;
line_count = 0;
} else if (UNEXPECTED(p[0] == '*') && p[1] == '*') {
if (bold_escape_len) {
in_bold = !in_bold;
memcpy (q, in_bold ? bold_on_escape : bold_off_escape, bold_escape_len);
q += bold_escape_len;
/* bold on/off has zero print width so line count is unchanged */
}
p++;
} else if (UNEXPECTED(p[0] == '$') && p[1] == 'P') {
memcpy (q, prompt_escape, prompt_escape_len);
q += prompt_escape_len;
line_count += prompt_len;
p++;
} else if (UNEXPECTED(p[0] == '\\')) {
p++;
*q++ = *p;
line_count++;
} else {
*q++ = *p;
line_count++;
}
if (UNEXPECTED(line_count>=term_width) && last_new_blank) {
*last_new_blank = '\n';
last_new_blank = NULL;
line_count -= last_blank_count;
last_blank_count = 0;
}
}
*q++ = '\0';
if ((q-new)>size) {
phpdbg_error("Output overrun of %lu bytes", ((q-new) - size));
}
phpdbg_write("%s\n", new);
efree(new);
} /* }}} */
/* {{{ summary_print. Print a summary line giving, the command, its alias and tip */
void summary_print(phpdbg_command_t const * const cmd TSRMLS_DC)
{
char *summary;
spprintf(&summary, 0, "Command: **%s** Alias: **%c** **%s**\n", cmd->name, cmd->alias, cmd->tip);
pretty_print(summary TSRMLS_CC);
efree(summary);
}
/* {{{ get_help. Retries and formats text from the phpdbg help text table */
static char *get_help(const char * const key TSRMLS_DC)
{
phpdbg_help_text_t *p;
/* Note that phpdbg_help_text is not assumed to be collated in key order. This is an
inconvience that means that help can't be logically grouped Not worth
the savings */
for (p = phpdbg_help_text; p->key; p++) {
if (!strcmp(p->key, key)) {
return p->text;
}
}
return ""; /* return empty string to denote no match found */
} /* }}} */
/* {{{ get_command. Return number of matching commands from a command table.
* Unlike the command parser, the help search is sloppy that is partial matches can occur
* * Any single character key is taken as an alias.
* * Other keys are matched again the table on the first len characters.
* * This means that non-unique keys can generate multiple matches.
* * The first matching command is returned as an OUT parameter. *
* The rationale here is to assist users in finding help on commands. So unique matches
* will be used to generate a help message but non-unique one will be used to list alternatives.
*/
static int get_command(
const char *key, size_t len, /* pointer and length of key */
phpdbg_command_t const **command, /* address of first matching command */
phpdbg_command_t const * commands /* command table to be scanned */
TSRMLS_DC)
{
const phpdbg_command_t *c;
unsigned int num_matches = 0;
if (len == 1) {
for (c=commands; c->name; c++) {
if (c->alias == key[0]) {
num_matches++;
if ( num_matches == 1 && command) {
*command = c;
}
}
}
} else {
for (c=commands; c->name; c++) {
if (!strncmp(c->name, key, len)) {
++num_matches;
if ( num_matches == 1 && command) {
*command = c;
}
}
}
}
return num_matches;
} /* }}} */
PHPDBG_COMMAND(help) /* {{{ */
{
phpdbg_command_t const *cmd;
int n;
if (!param || param->type == EMPTY_PARAM) {
pretty_print(get_help("overview!" TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
}
if (param && param->type == STR_PARAM) {
n = get_command(param->str, param->len, &cmd, phpdbg_prompt_commands TSRMLS_CC);
if (n==1) {
summary_print(cmd TSRMLS_CC);
pretty_print(get_help(cmd->name TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
} else if (n>1) {
if (param->len > 1) {
for (cmd=phpdbg_prompt_commands; cmd->name; cmd++) {
if (!strncmp(cmd->name, param->str, param->len)) {
summary_print(cmd TSRMLS_CC);
}
}
pretty_print(get_help("duplicate!" TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
} else {
phpdbg_error("Internal help error, non-unique alias \"%c\"", param->str[0]);
return FAILURE;
}
} else { /* no prompt command found so try help topic */
n = get_command( param->str, param->len, &cmd, phpdbg_help_commands TSRMLS_CC);
if (n>0) {
if (cmd->alias == 'a') { /* help aliases executes a canned routine */
return cmd->handler(param TSRMLS_CC);
} else {
pretty_print(get_help(cmd->name TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
}
}
}
}
return FAILURE;
} /* }}} */
PHPDBG_HELP(aliases) /* {{{ */
{
const phpdbg_command_t *c, *c_sub;
int len;
/* Print out aliases for all commands except help as this one comes last */
phpdbg_writeln("Below are the aliased, short versions of all supported commands");
for(c = phpdbg_prompt_commands; c->name; c++) {
if (c->alias && c->alias != 'h') {
phpdbg_writeln(" %c %-20s %s", c->alias, c->name, c->tip);
if (c->subs) {
len = 20 - 1 - c->name_len;
for(c_sub = c->subs; c_sub->alias; c_sub++) {
if (c_sub->alias) {
phpdbg_writeln(" %c %c %s %-*s %s",
c->alias, c_sub->alias, (char *)c->name, len, c_sub->name, c_sub->tip);
}
}
}
}
}
/* Print out aliases for help as this one comes last, with the added text on how aliases are used */
get_command("h", 1, &c, phpdbg_prompt_commands TSRMLS_CC);
phpdbg_writeln(" %c %-20s %s\n", c->alias, c->name, c->tip);
len = 20 - 1 - c->name_len;
for(c_sub = c->subs; c_sub->alias; c_sub++) {
if (c_sub->alias) {
phpdbg_writeln(" %c %c %s %-*s %s",
c->alias, c_sub->alias, c->name, len, c_sub->name, c_sub->tip);
}
}
pretty_print(get_help("aliases!" TSRMLS_CC) TSRMLS_CC);
return SUCCESS;
} /* }}} */
/* {{{ Help Text Table
* Contains help text entries keyed by a lowercase ascii key.
* Text is in ascii and enriched by a simple markup:
* ** toggles bold font emphasis.
* $P insert an bold phpdbg> prompt.
* \ escapes the following character. Note that this is itself escaped inside string
* constants so \\\\ is required to output a single \ e.g. as in namespace names.
*
* Text will be wrapped according to the STDOUT terminal width, so paragraphs are
* flowed using the C stringizing and the CR definition. Also note that entries
* are collated in alphabetic order on key.
*
* Also note the convention that help text not directly referenceable as a help param
* has a key ending in !
*/
#define CR "\n"
phpdbg_help_text_t phpdbg_help_text[] = {
/******************************** General Help Topics ********************************/
{"overview!", CR
"**phpdbg** is a lightweight, powerful and easy to use debugging platform for PHP5.4+" CR
"It supports the following commands:" CR CR
"**Information**" CR
" **list** list PHP source" CR
" **info** displays information on the debug session" CR
" **print** show opcodes" CR
" **frame** select a stack frame and print a stack frame summary" CR
" **back** shows the current backtrace" CR
" **help** provide help on a topic" CR CR
"**Starting and Stopping Execution**" CR
" **exec** set execution context" CR
" **run** attempt execution" CR
" **step** continue execution until other line is reached" CR
" **continue** continue execution" CR
" **until** continue execution up to the given location" CR
" **finish** continue up to end of the current execution frame" CR
" **leave** continue up to end of the current execution frame and halt after the calling instruction" CR
" **break** set a breakpoint at the specified target" CR
" **watch** set a watchpoint on $variable" CR
" **clear** clear one or all breakpoints" CR
" **clean** clean the execution environment" CR CR
"**Miscellaneous**" CR
" **set** set the phpdbg configuration" CR
" **source** execute a phpdbginit script" CR
" **register** register a phpdbginit function as a command alias" CR
" **sh** shell a command" CR
" **ev** evaluate some code" CR
" **quit** exit phpdbg" CR CR
"Type **help <command>** or (**help alias**) to get detailed help on any of the above commands, "
"for example **help list** or **h l**. Note that help will also match partial commands if unique "
"(and list out options if not unique), so **help clea** will give help on the **clean** command, "
"but **help cl** will list the summary for **clean** and **clear**." CR CR
"Type **help aliases** to show a full alias list, including any registered phpdginit functions" CR
"Type **help syntax** for a general introduction to the command syntax." CR
"Type **help options** for a list of phpdbg command line options." CR
"Type **help phpdbginit** to show how to customise the debugger environment."
},
{"options", CR
"Below are the command line options supported by phpdbg" CR CR
/* note the extra 4 space index in because of the extra **** */
"**Command Line Options and Flags**" CR
" **Option** **Example Argument** **Description**" CR
" **-c** **-c**/my/php.ini Set php.ini file to load" CR
" **-d** **-d**memory_limit=4G Set a php.ini directive" CR
" **-n** Disable default php.ini" CR
" **-q** Supress welcome banner" CR
" **-v** Enable oplog output" CR
" **-s** Enable stepping" CR
" **-b** Disable colour" CR
" **-i** **-i**my.init Set .phpdbginit file" CR
" **-I** Ignore default .phpdbginit" CR
" **-O** **-O**my.oplog Sets oplog output file" CR
" **-r** Run execution context" CR
" **-rr** Run execution context and quit after execution" CR
" **-E** Enable step through eval, careful!" CR
" **-S** **-S**cli Override SAPI name, careful!" CR
" **-l** **-l**4000 Setup remote console ports" CR
" **-a** **-a**192.168.0.3 Setup remote console bind address" CR
" **-V** Print version number" CR
" **--** **--** arg1 arg2 Use to delimit phpdbg arguments and php $argv; append any $argv "
"argument after it" CR CR
"**Remote Console Mode**" CR CR
"This mode is enabled by specifying the **-a** option. Phpdbg will bind only to the loopback "
"interface by default, and this can only be overridden by explicitly setting the remote console "
"bind address using the **-a** option. If **-a** is specied without an argument, then phpdbg "
"will bind to all available interfaces. You should be aware of the security implications of "
"doing this, so measures should be taken to secure this service if bound to a publicly accessible "
"interface/port." CR CR
"Specify both stdin and stdout with -lstdin/stdout; by default stdout is stdin * 2."
},
{"phpdbginit", CR
"Phpdgb uses an debugger script file to initialize the debugger context. By default, phpdbg looks "
"for the file named **.phpdbginit** in the current working directory. This location can be "
"overridden on the command line using the **-i** switch (see **help options** for a more "
"details)." CR CR
"Debugger scripts can also be executed using the **source** command." CR CR
"A script file can contain a sequence of valid debugger commands, comments and embedded PHP "
"code. " CR CR
"Comment lines are prefixed by the **#** character. Note that comments are only allowed in script "
"files and not in interactive sessions." CR CR
"PHP code is delimited by the start and end escape tags **<:** and **:>**. PHP code can be used "
"to define application context for a debugging session and also to extend the debugger by defining "
"and **register** PHP functions as new commands." CR CR
"Also note that executing a **clear** command will cause the current **phpdbginit** to be reparsed "
"/ reloaded."
},
{"syntax", CR
"Commands start with a keyword, and some (**break**, "
"**info**, **set**, **print** and **list**) may include a subcommand keyword. All keywords are "
"lower case but also have a single letter alias that may be used as an alternative to typing in the"
"keyword in full. Note some aliases are uppercase, and that keywords cannot be abbreviated other "
"than by substitution by the alias." CR CR
"Some commands take an argument. Arguments are typed according to their format:" CR
" * **omitted**" CR
" * **address** **0x** followed by a hex string" CR
" * **number** an optionally signed number" CR
" * **method** a valid **Class::methodName** expression" CR
" * **func#op** a valid **Function name** follow by # and an integer" CR
" * **method#op** a valid **Class::methodName** follow by # and an integer" CR
" * **string** a general string" CR
" * **function** a valid **Function name**" CR
" * **file:line** a valid **filename** follow by : and an integer" CR CR
"In some cases the type of the argument enables the second keyword to be omitted." CR CR
"Type **help** for an overview of all commands and type **help <command>** to get detailed help "
"on any specific command." CR CR
"**Valid Examples**" CR CR
" $P quit" CR
" $P q" CR
" Quit the debugger" CR CR
" $P ev $total[2]" CR
" Evaluate and print the variable $total[2] in the current stack frame" CR
" " CR
" $P break 200" CR
" $P b my_source.php:200" CR
" Break at line 200 in the current source and in file **my_source.php**. " CR CR
" $P b @ ClassX::get_args if $arg[0] == \"fred\"" CR
" $P b ~ 3" CR
" Break at ClassX::get_args() if $arg[0] == \"fred\" and delete breakpoint 3" CR CR
"**Examples of invalid commands**" CR
" $P #This is a comment" CR
" Comments introduced by the **#** character are only allowed in **phpdbginit** script files."
},
/******************************** Help Codicils ********************************/
{"aliases!", CR
"Note that aliases can be used for either command or sub-command keywords or both, so **info b** "
"is a synomyn for **info break** and **l func** for **list func**, etc." CR CR
"Note that help will also accept any alias as a parameter and provide help on that command, for example **h p** will provide help on the print command."
},
{"duplicate!", CR
"Parameter is not unique. For detailed help select help on one of the above commands."
},
/******************************** Help on Commands ********************************/
{"back",
"Provide a formatted backtrace using the standard debug_backtrace() functionality. An optional "
"unsigned integer argument specifying the maximum number of frames to be traced; if omitted then "
"a complete backtrace is given." CR CR
"**Examples**" CR CR
" $P back 5" CR
" $P t " CR
" " CR
"A backtrace can be executed at any time during execution."
},
{"break",
"Breakpoints can be set at a range of targets within the execution environment. Execution will "
"be paused if the program flow hits a breakpoint. The break target can be one of the following "
"types:" CR CR
" **Target** **Alias** **Purpose**" CR
" **at** **A** specify breakpoint by location and condition" CR
" **del** **d** delete breakpoint by breakpoint identifier number" CR CR
"**Break at** takes two arguments. The first is any valid target. The second "
"is a valid PHP expression which will trigger the break in "
"execution, if evaluated as true in a boolean context at the specified target." CR CR
"Note that breakpoints can also be disabled and re-enabled by the **set break** command." CR CR
"**Examples**" CR CR
" $P break test.php:100" CR
" $P b test.php:100" CR
" Break execution at line 100 of test.php" CR CR
" $P break 200" CR
" $P b 200" CR
" Break execution at line 200 of the currently PHP script file" CR CR
" $P break \\\\mynamespace\\\\my_function" CR
" $P b \\\\mynamespace\\\\my_function" CR
" Break execution on entry to \\\\mynamespace\\\\my_function" CR CR
" $P break classX::method" CR
" $P b classX::method" CR
" Break execution on entry to classX::method" CR CR
" $P break 0x7ff68f570e08" CR
" $P b 0x7ff68f570e08" CR
" Break at the opline at the address 0x7ff68f570e08" CR CR
" $P break my_function#14" CR
" $P b my_function#14" CR
" Break at the opline #14 of the function my_function" CR CR
" $P break \\\\my\\\\class::method#2" CR
" $P b \\\\my\\\\class::method#2" CR
" Break at the opline #2 of the method \\\\my\\\\class::method" CR CR
" $P break test.php:#3" CR
" $P b test.php:#3" CR
" Break at opline #3 in test.php" CR CR
" $P break if $cnt > 10" CR
" $P b if $cnt > 10" CR
" Break when the condition ($cnt > 10) evaluates to true" CR CR
" $P break at phpdbg::isGreat if $opt == 'S'" CR
" $P break @ phpdbg::isGreat if $opt == 'S'" CR
" Break at any opcode in phpdbg::isGreat when the condition ($opt == 'S') is true" CR CR
" $P break at test.php:20 if !isset($x)" CR
" Break at every opcode on line 20 of test.php when the condition evaluates to true" CR CR
" $P break ZEND_ADD" CR
" $P b ZEND_ADD" CR
" Break on any occurence of the opcode ZEND_ADD" CR CR
" $P break del 2" CR
" $P b ~ 2" CR
" Remove breakpoint 2" CR CR
"Note: Conditional breaks are costly in terms of runtime overhead. Use them only when required "
"as they significantly slow execution." CR CR
"Note: An address is only valid for the current compilation."
},
{"clean",
"Classes, constants or functions can only be declared once in PHP. You may experience errors "
"during a debug session if you attempt to recompile a PHP source. The clean command clears "
"the Zend runtime tables which holds the sets of compiled classes, constants and functions, "
"releasing any associated storage back into the storage pool. This enables recompilation to "
"take place." CR CR
"Note that you cannot selectively trim any of these resource pools. You can only do a complete "
"clean."
},
{"clear",
"Clearing breakpoints means you can once again run code without interruption." CR CR
"Note: use break delete N to clear a specific breakpoint." CR CR
"Note: if all breakpoints are cleared, then the PHP script will run until normal completion."
},
{"ev",
"The **ev** command takes a string expression which it evaluates and then displays. It "
"evaluates in the context of the lowest (that is the executing) frame, unless this has first "
"been explicitly changed by issuing a **frame** command. " CR CR
"**Examples**" CR CR
" $P ev $variable" CR
" Will print_r($variable) on the console, if it is defined" CR CR
" $P ev $variable = \"Hello phpdbg :)\"" CR
" Will set $variable in the current scope" CR CR
"Note that **ev** allows any valid PHP expression including assignments, function calls and "
"other write statements. This enables you to change the environment during execution, so care "
"is needed here. You can even call PHP functions which have breakpoints defined. " CR CR
"Note: **ev** will always show the result, so do not prefix the code with **return**"
},
{"exec",
"The **exec** command sets the execution context, that is the script to be executed. The "
"execution context must be defined either by executing the **exec** command or by using the "
"**-e** command line option." CR CR
"Note that the **exec** command also can be used to replace a previously defined execution "
"context." CR CR
"**Examples**" CR CR
" $P exec /tmp/script.php" CR
" $P e /tmp/script.php" CR
" Set the execution context to **/tmp/script.php**"
},
//*********** Does F skip any breakpoints lower stack frames or only the current??
{"finish",
"The **finish** command causes control to be passed back to the vm, continuing execution. Any "
"breakpoints that are encountered within the current stack frame will be skipped. Execution "
"will then continue until the next breakpoint after leaving the stack frame or until "
"completion of the script" CR CR
"Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
"skipped. "CR CR
"Note **finish** will trigger a \"not executing\" error if not executing."
},
{"frame",
"The **frame** takes an optional integer argument. If omitted, then the current frame is displayed "
"If specified then the current scope is set to the corresponding frame listed in a **back** trace. " "This can be used to allowing access to the variables in a higher stack frame than that currently "
"being executed." CR CR
"**Examples**" CR CR
" $P frame 2" CR
" $P ev $count" CR
" Go to frame 2 and print out variable **$count** in that frame" CR CR
"Note that this frame scope is discarded when execution continues, with the execution frame "
"then reset to the lowest executiong frame."
},
{"info",
"**info** commands provide quick access to various types of information about the PHP environment" CR
"Specific info commands are show below:" CR CR
" **Target** **Alias** **Purpose**" CR
" **break** **b** show current breakpoints" CR
" **files** **F** show included files" CR
" **classes** **c** show loaded classes" CR
" **funcs** **f** show loaded classes" CR
" **error** **e** show last error" CR
" **vars** **v** show active variables" CR
" **literal** **l** show active literal constants" CR
" **memory** **m** show memory manager stats"
},
// ******** same issue about breakpoints in called frames
{"leave",
"The **leave** command causes control to be passed back to the vm, continuing execution. Any "
"breakpoints that are encountered within the current stack frame will be skipped. In effect a "
"temporary breakpoint is associated with any return opcode, so that a break in execution occurs "
"before leaving the current stack frame. This allows inspection / modification of any frame "
"variables including the return value before it is returned" CR CR
"**Examples**" CR CR
" $P leave" CR
" $P L" CR CR
"Note when **step**ping is enabled, any opcode steps within the current stack frame are also "
"skipped. "CR CR
"Note **leave** will trigger a \"not executing\" error if not executing."
},
{"list",
"The list command displays source code for the given argument. The target type is specficied by "
"a second subcommand keyword:" CR CR
" **Type** **Alias** **Purpose**" CR
" **lines** **l** List N lines from the current execution point" CR
" **func** **f** List the complete source for a specified function" CR
" **method** **m** List the complete source for a specified class::method" CR
" **class** **c** List the complete source for a specified class" CR CR
"Note that the context of **lines**, **func** and **method** can be determined by parsing the "
"argument, so these subcommands are optional. However, you must specify the **class** keyword "
"to list off a class." CR CR
"**Examples**" CR CR
" $P list 2" CR
" $P l l 2" CR
" List the next 2 lines from the current file" CR CR
" $P list my_function" CR
" $P l f my_function" CR
" List the source of the function **my_function**" CR CR
//************ ????
" $P list func .mine" CR
" $P l f .mine" CR
" List the source of the method **mine** from the active class in scope" CR CR
" $P list m my::method" CR
" $P l my::method" CR
" List the source of **my::method**" CR CR
" $P list c myClass" CR
" $P l c myClass" CR
" List the source of **myClass**" CR CR
"Note that functions and classes can only be listed if the corresponding classes and functions "
"table in the Zend executor has a corresponding entry. You can use the compile command to "
"populate these tables for a given execution context."
},
{"continue",
"Continue with execution after hitting a break or watchpoint" CR CR
"**Examples**" CR CR
" $P continue" CR
" $P c" CR
" Continue executing until the next break or watchpoint" CR CR
"Note **continue** will trigger a \"not running\" error if not executing."
},
{"print",
"By default, print will show information about the current execution context." CR
"Other printing commands give access to instruction information." CR
"Specific printers loaded are show below:" CR CR
" **Type** **Alias** **Purpose**" CR
" **exec** **e** print out the instructions in the execution context" CR
" **opline** **o** print out the instruction in the current opline" CR
" **class** **c** print out the instructions in the specified class" CR
" **method** **m** print out the instructions in the specified method" CR
" **func** **f** print out the instructions in the specified function" CR
" **stack** **s** print out the instructions in the current stack" CR CR
"**Examples**" CR CR
" $P print class \\\\my\\\\class" CR
" $P p c \\\\my\\\\class" CR
" Print the instructions for the methods in \\\\my\\\\class" CR CR
" $P print method \\\\my\\\\class::method" CR
" $P p m \\\\my\\\\class::method" CR
" Print the instructions for \\\\my\\\\class::method" CR CR
" $P print func .getSomething" CR
" $P p f .getSomething" CR
//************* Check this local method scope
" Print the instructions for ::getSomething in the active scope" CR CR
" $P print func my_function" CR
" $P p f my_function" CR
" Print the instructions for the global function my_function" CR CR
" $P print opline" CR
" $P p o" CR
" Print the instruction for the current opline" CR CR
" $P print exec" CR
" $P p e" CR
" Print the instructions for the execution context" CR CR
" $P print stack" CR
" $P p s" CR
" Print the instructions for the current stack"
},
{"register",
//******* Needs a general explanation of the how registered functions work
"Register any global function for use as a command in phpdbg console" CR CR
"**Examples**" CR CR
" $P register scandir" CR
" $P R scandir" CR
" Will register the scandir function for use in phpdbg" CR CR
"Note: arguments passed as strings, return (if present) print_r'd on console"
},
{"run",
"Enter the vm, startinging execution. Execution will then continue until the next breakpoint "
"or completion of the script. Add parameters you want to use as $argv"
"**Examples**" CR CR
" $P run" CR
" $P r" CR
" Will cause execution of the context, if it is set" CR CR
" $P r test" CR
" Will execute with $argv[1] == \"test\"" CR CR
"Note that the execution context must be set. If not previously compiled, then the script will "
"be compiled before execution." CR CR
"Note that attempting to run a script that is already executing will result in an \"execution "
"in progress\" error."
},
{"set",
"The **set** command is used to configure how phpdbg looks and behaves. Specific set commands "
"are as follows:" CR CR
" **Type** **Alias** **Purpose**" CR
" **prompt** **p** set the prompt" CR
" **color** **c** set color <element> <color>" CR
" **colors** **C** set colors [<on|off>]" CR
" **oplog** **O** set oplog [output]" CR
" **break** **b** set break **id** <on|off>" CR
" **breaks** **B** set breaks [<on|off>]" CR
" **quiet** **q** set quiet [<on|off>]" CR
" **stepping** **s** set stepping [<opcode|line>]" CR
" **refcount** **r** set refcount [<on|off>] " CR CR
"Valid colors are **none**, **white**, **red**, **green**, **yellow**, **blue**, **purple**, "
"**cyan** and **black**. All colours except **none** can be followed by an optional "
"**-bold** or **-underline** qualifier." CR CR
"Color elements can be one of **prompt**, **notice**, or **error**." CR CR
"**Examples**" CR CR
" $P S C on" CR
" Set colors on" CR CR
" $P set p >" CR
" $P set color prompt white-bold" CR
" Set the prompt to a bold >" CR CR
" $P S c error red-bold" CR
" Use red bold for errors" CR CR
" $P S refcount on" CR
" Enable refcount display when hitting watchpoints" CR CR
" $P S b 4 off" CR
" Temporarily disable breakpoint 4. This can be subsequently reenabled by a **s b 4 on**." CR
//*********** check oplog syntax
},
{"sh",
"Direct access to shell commands saves having to switch windows/consoles" CR CR
"**Examples**" CR CR
" $P sh ls /usr/src/php-src" CR
" Will execute ls /usr/src/php-src, displaying the output in the console"
//*********** what does this mean????Note: read only commands please!
},
{"source",
"Sourcing a **phpdbginit** script during your debugging session might save some time." CR CR
"**Examples**" CR CR
" $P source /my/init" CR
" $P < /my/init" CR
" Will execute the phpdbginit file at /my/init" CR CR
},
{"export",
"Exporting breakpoints allows you to share, and or save your current debugging session" CR CR
"**Examples**" CR CR
" $P export /my/exports" CR
" $P > /my/exports" CR
" Will export all breakpoints to /my/exports" CR CR
},
{"step",
"Execute opcodes until next line" CR CR
"**Examples**" CR CR
" $P s" CR
" Will continue and break again in the next encountered line" CR CR
},
{"until",
"The **until** command causes control to be passed back to the vm, continuing execution. Any "
"breakpoints that are encountered before the next source line will be skipped. Execution "
"will then continue until the next breakpoint or completion of the script" CR CR
"Note when **step**ping is enabled, any opcode steps within the current line are also skipped. "CR CR
"Note that if the next line is **not** executed then **all** subsequent breakpoints will be "
"skipped. " CR CR
"Note **until** will trigger a \"not executing\" error if not executing."
},
{"watch",
"Sets watchpoints on variables as long as they are defined" CR
"Passing no parameter to **watch**, lists all actually active watchpoints" CR CR
"**Format for $variable**" CR CR
" **$var** Variable $var" CR
" **$var[]** All array elements of $var" CR
" **$var->** All properties of $var" CR
" **$var->a** Property $var->a" CR
" **$var[b]** Array element with key b in array $var" CR CR
"Subcommands of **watch**:" CR CR
" **Type** **Alias** **Purpose**" CR
" **array** **a** Sets watchpoint on array/object to observe if an entry is added or removed" CR
" **recursive** **r** Watches variable recursively and automatically adds watchpoints if some entry is added to an array/object" CR
" **delete** **d** Removes watchpoint" CR CR
"Note when **recursive** watchpoints are removed, watchpoints on all the children are removed too" CR CR
"**Examples**" CR CR
" $P watch" CR
" List currently active watchpoints" CR CR
" $P watch $array" CR
" $P w $array" CR
" Set watchpoint on $array" CR CR
" $P watch recursive $obj->" CR
" $P w r $obj->" CR
" Set recursive watchpoint on $obj->" CR CR
" $P watch delete $obj->a" CR
" $P w d $obj->a" CR
" Remove watchpoint $obj->a" CR CR
"Technical note: If using this feature with a debugger, you will get many segmentation faults, each time when a memory page containing a watched address is hit." CR
" You then you can continue, phpdbg will remove the write protection, so that the program can continue." CR
" If phpdbg could not handle that segfault, the same segfault is triggered again and this time phpdbg will abort."
},
{NULL, NULL /* end of table marker */}
}; /* }}} */