Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 216 lines (169 sloc) 6.687 kb
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
1 New parameter parsing functions
2 ===============================
3
4 It should be easier to parse input parameters to an extension function.
5 Hence, borrowing from Python's example, there are now a set of functions
6 that given the string of type specifiers, can parse the input parameters
7 and store the results in the user specified variables. This avoids most
8 of the IS_* checks and convert_to_* conversions. The functions also
9 check for the appropriate number of parameters, and try to output
10 meaningful error messages.
11
12
13 Prototypes
14 ----------
15 /* Implemented. */
b31c3e0 Fix-up.
Andrei Zmievski authored
16 int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);
17 int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
18
19 The zend_parse_parameters() function takes the number of parameters
20 passed to the extension function, the type specifier string, and the
21 list of pointers to variables to store the results in. The _ex() version
22 also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
23 be used as 'flags' to specify that the function should operate quietly
24 and not output any error messages.
25
b31c3e0 Fix-up.
Andrei Zmievski authored
26 Both functions return SUCCESS or FAILURE depending on the result.
27
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
28 The auto-conversions are performed as necessary. Arrays, objects, and
fd4d1f2 @jparise Formatting nit: "autoconverted" to "auto-converted"
jparise authored
29 resources cannot be auto-converted.
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
30
31
32 Type specifiers
33 ---------------
a541bb8 - Fix tests
Jani Taskinen authored
34 The following list shows the type specifier, its meaning and the parameter
35 types that need to be passed by address. All passed paramaters are set
36 if the PHP parameter is non optional and untouched if optional and the
37 parameter is not present. The only exception is O where the zend_class_entry*
38 has to be provided on input and is used to verify the PHP parameter is an
39 instance of that class.
40
41 a - array (zval*)
42 b - boolean (zend_bool)
43 C - class (zend_class_entry*)
44 d - double (double)
45 f - function or array containing php method call info (returned as
46 zend_fcall_info and zend_fcall_info_cache)
47 h - array (returned as HashTable*)
48 l - long (long)
49 o - object of any type (zval*)
50 O - object of specific type given by class entry (zval*, zend_class_entry)
51 r - resource (zval*)
52 s - string (with possible null bytes) and its length (char*, int)
53 z - the actual zval (zval*)
54 Z - the actual zval (zval**)
a506a10 MFH
Jani Taskinen authored
55 * - variable arguments list (0 or more)
56 + - variable arguments list (1 or more)
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
57
58 The following characters also have a meaning in the specifier string:
a541bb8 - Fix tests
Jani Taskinen authored
59 | - indicates that the remaining parameters are optional, they
60 should be initialized to default values by the extension since they
61 will not be touched by the parsing function if they are not
62 passed to it.
63 / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
64 ! - the parameter it follows can be of specified type or NULL (applies
65 to all specifiers except for 'b', 'l', and 'd'). If NULL is passed, the
66 results pointer is set to NULL as well.
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
67
991ae6e @tony2001 MFH: add note on 64bit compatibility and mention check_parameters.php
tony2001 authored
68
69 Note on 64bit compatibility
70 ---------------------------
71 Please do not forget that int and long are two different things on 64bit
72 OSes (int is 4bit and long is 8bit), so make sure you pass longs to "l"
73 and ints to strings length (i.e. for "s" you need to pass char * and int),
74 not the other way round!
75 Remember: "l" is the only case when you need to pass long (and that's why
76 it's "l", not "i" btw).
77
78 Both mistakes cause memory corruptions and segfaults on 64bit OSes:
79 1)
80 char *str;
81 long str_len; /* XXX THIS IS WRONG!! Use int instead. */
82 zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &str, &str_len)
83
84 2)
85 int num; /* XXX THIS IS WRONG!! Use long instead. */
86 zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &num)
87
88 If you're in doubt, use check_parameters.php script to the parameters
89 and their types (it can be found in ./scripts/dev/ directory of PHP sources):
90
91 # php ./scripts/dev/check_parameters.php /path/to/your/sources/
92
93
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
94 Examples
95 --------
96 /* Gets a long, a string and its length, and a zval */
97 long l;
98 char *s;
99 int s_len;
100 zval *param;
b31c3e0 Fix-up.
Andrei Zmievski authored
101 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz",
a541bb8 - Fix tests
Jani Taskinen authored
102 &l, &s, &s_len, &param) == FAILURE) {
103 return;
b31c3e0 Fix-up.
Andrei Zmievski authored
104 }
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
105
106
107 /* Gets an object of class specified by my_ce, and an optional double. */
108 zval *obj;
109 double d = 0.5;
e9dd6fa @johannes - MFH: Fix type in example
johannes authored
110 zend_class_entry *my_ce;
b31c3e0 Fix-up.
Andrei Zmievski authored
111 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
a541bb8 - Fix tests
Jani Taskinen authored
112 &obj, my_ce, &d) == FAILURE) {
113 return;
b31c3e0 Fix-up.
Andrei Zmievski authored
114 }
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
115
116
117 /* Gets an object or null, and an array.
118 If null is passed for object, obj will be set to NULL. */
119 zval *obj;
120 zval *arr;
550550f @rlerdorf Minor tweaks
rlerdorf authored
121 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o!a",
a541bb8 - Fix tests
Jani Taskinen authored
122 &obj, &arr) == FAILURE) {
123 return;
b31c3e0 Fix-up.
Andrei Zmievski authored
124 }
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
125
126
550550f @rlerdorf Minor tweaks
rlerdorf authored
127 /* Gets a separated array which can also be null. */
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
128 zval *arr;
550550f @rlerdorf Minor tweaks
rlerdorf authored
129 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
a541bb8 - Fix tests
Jani Taskinen authored
130 &arr) == FAILURE) {
131 return;
b31c3e0 Fix-up.
Andrei Zmievski authored
132 }
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
133
134 /* Get either a set of 3 longs or a string. */
135 long l1, l2, l3;
136 char *s;
ad8b425 Please note that you need to use 'int' as a length type when
Sascha Schumann authored
137 /*
138 * The function expects a pointer to a integer in this case, not a long
139 * or any other type. If you specify a type which is larger
140 * than a 'int', the upper bits might not be initialized
141 * properly, leading to random crashes on platforms like
142 * Tru64 or Linux/Alpha.
143 */
144 int length;
dfd8ea7 - Fix README
Derick Rethans authored
145
b31c3e0 Fix-up.
Andrei Zmievski authored
146 if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
a541bb8 - Fix tests
Jani Taskinen authored
147 "lll", &l1, &l2, &l3) == SUCCESS) {
148 /* manipulate longs */
b31c3e0 Fix-up.
Andrei Zmievski authored
149 } else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
a541bb8 - Fix tests
Jani Taskinen authored
150 "s", &s, &length) == SUCCESS) {
151 /* manipulate string */
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
152 } else {
a541bb8 - Fix tests
Jani Taskinen authored
153 /* output error */
154
155 return;
156 }
157
158
159 /* Function that accepts only varargs (0 or more) */
160
161 int i, num_varargs;
162 zval ***varargs = NULL;
163
164
165 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "*", &varargs, &num_varargs) == FAILURE) {
166 return;
167 }
168
169 for (i = 0; i < num_varargs; i++) {
170 /* do something with varargs[i] */
171 }
172
173 if (varargs) {
174 efree(varargs);
175 }
b31c3e0 Fix-up.
Andrei Zmievski authored
176
a541bb8 - Fix tests
Jani Taskinen authored
177
178 /* Function that accepts a string, followed by varargs (1 or more) */
179
180 char *str;
181 int str_len;
182 int i, num_varargs;
183 zval ***varargs = NULL;
184
185 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
186 return;
187 }
188
189 for (i = 0; i < num_varargs; i++) {
190 /* do something with varargs[i] */
191 }
192
193 if (varargs) {
194 efree(varargs);
195 }
196
197
198 /* Function that takes an array, followed by varargs, and ending with a long */
199 long num;
200 zval *array;
201 int i, num_varargs;
202 zval ***varargs = NULL;
203
204 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
205 return;
206 }
207
208 for (i = 0; i < num_varargs; i++) {
209 /* do something with varargs[i] */
210 }
211
212 if (varargs) {
213 efree(varargs);
27d63c5 Adding some docs for new parameter parsing API. They really should be…
Andrei Zmievski authored
214 }
a541bb8 - Fix tests
Jani Taskinen authored
215
Something went wrong with that request. Please try again.