Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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