xref: /PHP-8.3/sapi/phpdbg/phpdbg_cmd.h (revision 6318040d)
1 /*
2    +----------------------------------------------------------------------+
3    | Copyright (c) The PHP Group                                          |
4    +----------------------------------------------------------------------+
5    | This source file is subject to version 3.01 of the PHP license,      |
6    | that is bundled with this package in the file LICENSE, and is        |
7    | available through the world-wide-web at the following url:           |
8    | https://www.php.net/license/3_01.txt                                 |
9    | If you did not receive a copy of the PHP license and are unable to   |
10    | obtain it through the world-wide-web, please send a note to          |
11    | license@php.net so we can mail you a copy immediately.               |
12    +----------------------------------------------------------------------+
13    | Authors: Felipe Pena <felipe@php.net>                                |
14    | Authors: Joe Watkins <joe.watkins@live.co.uk>                        |
15    | Authors: Bob Weinand <bwoebi@php.net>                                |
16    +----------------------------------------------------------------------+
17 */
18 
19 #ifndef PHPDBG_CMD_H
20 #define PHPDBG_CMD_H
21 
22 #include "TSRM.h"
23 #include "zend_generators.h"
24 
25 /* {{{ Command and Parameter */
26 enum {
27 	NO_ARG = 0,
28 	REQUIRED_ARG,
29 	OPTIONAL_ARG
30 };
31 
32 typedef enum {
33 	EMPTY_PARAM = 0,
34 	ADDR_PARAM,
35 	FILE_PARAM,
36 	NUMERIC_FILE_PARAM,
37 	METHOD_PARAM,
38 	STR_PARAM,
39 	NUMERIC_PARAM,
40 	NUMERIC_FUNCTION_PARAM,
41 	NUMERIC_METHOD_PARAM,
42 	STACK_PARAM,
43 	EVAL_PARAM,
44 	SHELL_PARAM,
45 	COND_PARAM,
46 	OP_PARAM,
47 	ORIG_PARAM,
48 	RUN_PARAM
49 } phpdbg_param_type;
50 
51 typedef struct _phpdbg_param phpdbg_param_t;
52 struct _phpdbg_param {
53 	phpdbg_param_type type;
54 	zend_long num;
55 	zend_ulong addr;
56 	struct {
57 		char *name;
58 		zend_ulong line;
59 	} file;
60 	struct {
61 		char *class;
62 		char *name;
63 	} method;
64 	char *str;
65 	size_t len;
66 	phpdbg_param_t *next;
67 	phpdbg_param_t *top;
68 };
69 
70 #define phpdbg_init_param(v, t) do{ \
71 	(v)->type = (t); \
72 	(v)->addr = 0; \
73 	(v)->num = 0; \
74 	(v)->file.name = NULL; \
75 	(v)->file.line = 0; \
76 	(v)->method.class = NULL; \
77 	(v)->method.name = NULL; \
78 	(v)->str = NULL; \
79 	(v)->len = 0; \
80 	(v)->next = NULL; \
81 	(v)->top = NULL; \
82 } while(0)
83 
84 #define PHPDBG_ASYNC_SAFE 1
85 
86 typedef int (*phpdbg_command_handler_t)(const phpdbg_param_t*);
87 
88 typedef struct _phpdbg_command_t phpdbg_command_t;
89 struct _phpdbg_command_t {
90 	const char *name;                   /* Command name */
91 	size_t name_len;                    /* Command name length */
92 	const char *tip;                    /* Menu tip */
93 	size_t tip_len;                     /* Menu tip length */
94 	char alias;                         /* Alias */
95 	phpdbg_command_handler_t handler;   /* Command handler */
96 	const phpdbg_command_t *subs;       /* Sub Commands */
97 	char *args;                         /* Argument Spec */
98 	const phpdbg_command_t *parent;     /* Parent Command */
99 	bool flags;                    /* General flags */
100 };
101 /* }}} */
102 
103 /* {{{ misc */
104 #define PHPDBG_STRL(s) s, sizeof(s)-1
105 #define PHPDBG_MAX_CMD 500
106 #define PHPDBG_FRAME(v) (PHPDBG_G(frame).v)
107 #define PHPDBG_EX(v) (EG(current_execute_data)->v)
108 
109 typedef struct {
110 	int num;
111 	zend_generator *generator;
112 	zend_execute_data *execute_data;
113 } phpdbg_frame_t;
114 /* }}} */
115 
116 /*
117 * Workflow:
118 * 1) the lexer/parser creates a stack of commands and arguments from input
119 * 2) the commands at the top of the stack are resolved sensibly using aliases, abbreviations and case insensitive matching
120 * 3) the remaining arguments in the stack are verified (optionally) against the handlers declared argument specification
121 * 4) the handler is called passing the top of the stack as the only parameter
122 * 5) the stack is destroyed upon return from the handler
123 */
124 
125 /*
126 * Input Management
127 */
128 PHPDBG_API char *phpdbg_read_input(const char *buffered);
129 PHPDBG_API void phpdbg_destroy_input(char **input);
130 PHPDBG_API int phpdbg_ask_user_permission(const char *question);
131 
132 /**
133  * Stack Management
134  */
135 PHPDBG_API void phpdbg_stack_push(phpdbg_param_t *stack, phpdbg_param_t *param);
136 PHPDBG_API void phpdbg_stack_separate(phpdbg_param_t *param);
137 PHPDBG_API const phpdbg_command_t *phpdbg_stack_resolve(const phpdbg_command_t *commands, const phpdbg_command_t *parent, phpdbg_param_t **top);
138 PHPDBG_API int phpdbg_stack_verify(const phpdbg_command_t *command, phpdbg_param_t **stack);
139 PHPDBG_API int phpdbg_stack_execute(phpdbg_param_t *stack, bool allow_async_unsafe);
140 PHPDBG_API void phpdbg_stack_free(phpdbg_param_t *stack);
141 
142 /*
143 * Parameter Management
144 */
145 PHPDBG_API void phpdbg_clear_param(phpdbg_param_t*);
146 PHPDBG_API void phpdbg_copy_param(const phpdbg_param_t*, phpdbg_param_t*);
147 PHPDBG_API bool phpdbg_match_param(const phpdbg_param_t *, const phpdbg_param_t *);
148 PHPDBG_API zend_ulong phpdbg_hash_param(const phpdbg_param_t *);
149 PHPDBG_API const char* phpdbg_get_param_type(const phpdbg_param_t*);
150 PHPDBG_API char* phpdbg_param_tostring(const phpdbg_param_t *param, char **pointer);
151 PHPDBG_API void phpdbg_param_debug(const phpdbg_param_t *param, const char *msg);
152 
153 /**
154  * Command Declarators
155  */
156 #define PHPDBG_COMMAND_HANDLER(name) phpdbg_do_##name
157 
158 #define PHPDBG_COMMAND_D_EXP(name, tip, alias, handler, children, args, parent, flags) \
159 	{PHPDBG_STRL(#name), tip, sizeof(tip)-1, alias, phpdbg_do_##handler, children, args, parent, flags}
160 
161 #define PHPDBG_COMMAND_D_EX(name, tip, alias, handler, children, args, flags) \
162 	{PHPDBG_STRL(#name), tip, sizeof(tip)-1, alias, phpdbg_do_##handler, children, args, NULL, flags}
163 
164 #define PHPDBG_COMMAND_D(name, tip, alias, children, args, flags) \
165 	{PHPDBG_STRL(#name), tip, sizeof(tip)-1, alias, phpdbg_do_##name, children, args, NULL, flags}
166 
167 #define PHPDBG_COMMAND(name) int phpdbg_do_##name(const phpdbg_param_t *param)
168 
169 #define PHPDBG_COMMAND_ARGS param
170 
171 #define PHPDBG_END_COMMAND {NULL, 0, NULL, 0, '\0', NULL, NULL, NULL, NULL, 0}
172 
173 /*
174 * Default Switch Case
175 */
176 #define phpdbg_default_switch_case() \
177 	default: \
178 		phpdbg_error("Unsupported parameter type (%s) for command", phpdbg_get_param_type(param)); \
179 	break
180 
181 #endif /* PHPDBG_CMD_H */
182