xref: /PHP-5.3/README.PARAMETER_PARSING_API (revision b907aa43)
1New parameter parsing functions
2===============================
3
4It should be easier to parse input parameters to an extension function.
5Hence, borrowing from Python's example, there are now a set of functions
6that given the string of type specifiers, can parse the input parameters
7and store the results in the user specified variables. This avoids most
8of the IS_* checks and convert_to_* conversions. The functions also
9check for the appropriate number of parameters, and try to output
10meaningful error messages.
11
12
13Prototypes
14----------
15/* Implemented. */
16int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);
17int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);
18
19The zend_parse_parameters() function takes the number of parameters
20passed to the extension function, the type specifier string, and the
21list of pointers to variables to store the results in. The _ex() version
22also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
23be used as 'flags' to specify that the function should operate quietly
24and not output any error messages.
25
26Both functions return SUCCESS or FAILURE depending on the result.
27
28The auto-conversions are performed as necessary. Arrays, objects, and
29resources cannot be auto-converted.
30
31
32Type specifiers
33---------------
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 A  - array or object (zval *)
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*)
49 H  - array or HASH_OF(object) (returned as HashTable*)
50 l  - long (long)
51 L  - long, limits out-of-range numbers to LONG_MAX/LONG_MIN (long)
52 o  - object of any type (zval*)
53 O  - object of specific type given by class entry (zval*, zend_class_entry)
54 r  - resource (zval*)
55 s  - string (with possible null bytes) and its length (char*, int)
56 z  - the actual zval (zval*)
57 Z  - the actual zval (zval**)
58 *  - variable arguments list (0 or more)
59 +  - variable arguments list (1 or more)
60
61 The following characters also have a meaning in the specifier string:
62    | - indicates that the remaining parameters are optional, they
63        should be initialized to default values by the extension since they
64        will not be touched by the parsing function if they are not
65        passed to it.
66    / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
67    ! - the parameter it follows can be of specified type or NULL (applies
68		to all specifiers except for 'b', 'l', and 'd'). If NULL is passed, the
69		results pointer is set to NULL as well.
70
71
72Note on 64bit compatibility
73---------------------------
74Please do not forget that int and long are two different things on 64bit
75OSes (int is 4 bytes and long is 8 bytes), so make sure you pass longs to "l"
76and ints to strings length (i.e. for "s" you need to pass char * and int),
77not the other way round!
78Remember: "l" is the only case when you need to pass long (and that's why
79it's "l", not "i" btw).
80
81Both mistakes cause memory corruptions and segfaults on 64bit OSes:
821)
83  char *str;
84  long str_len; /* XXX THIS IS WRONG!! Use int instead. */
85  zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &str, &str_len)
86
872)
88  int num; /* XXX THIS IS WRONG!! Use long instead. */
89  zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &num)
90
91If you're in doubt, use check_parameters.php script to the parameters
92and their types (it can be found in ./scripts/dev/ directory of PHP sources):
93
94# php ./scripts/dev/check_parameters.php /path/to/your/sources/
95
96
97Examples
98--------
99/* Gets a long, a string and its length, and a zval */
100long l;
101char *s;
102int s_len;
103zval *param;
104if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz",
105                          &l, &s, &s_len, &param) == FAILURE) {
106    return;
107}
108
109
110/* Gets an object of class specified by my_ce, and an optional double. */
111zval *obj;
112double d = 0.5;
113zend_class_entry *my_ce;
114if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
115                          &obj, my_ce, &d) == FAILURE) {
116    return;
117}
118
119
120/* Gets an object or null, and an array.
121   If null is passed for object, obj will be set to NULL. */
122zval *obj;
123zval *arr;
124if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o!a",
125                          &obj, &arr) == FAILURE) {
126    return;
127}
128
129
130/* Gets a separated array which can also be null. */
131zval *arr;
132if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
133                          &arr) == FAILURE) {
134    return;
135}
136
137/* Get either a set of 3 longs or a string. */
138long l1, l2, l3;
139char *s;
140/*
141 * The function expects a pointer to a integer in this case, not a long
142 * or any other type.  If you specify a type which is larger
143 * than a 'int', the upper bits might not be initialized
144 * properly, leading to random crashes on platforms like
145 * Tru64 or Linux/Alpha.
146 */
147int length;
148
149if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
150                             "lll", &l1, &l2, &l3) == SUCCESS) {
151    /* manipulate longs */
152} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
153                                    "s", &s, &length) == SUCCESS) {
154    /* manipulate string */
155} else {
156    /* output error */
157
158    return;
159}
160
161
162/* Function that accepts only varargs (0 or more) */
163
164int i, num_varargs;
165zval ***varargs = NULL;
166
167
168if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "*", &varargs, &num_varargs) == FAILURE) {
169    return;
170}
171
172for (i = 0; i < num_varargs; i++) {
173    /* do something with varargs[i] */
174}
175
176if (varargs) {
177    efree(varargs);
178}
179
180
181/* Function that accepts a string, followed by varargs (1 or more) */
182
183char *str;
184int str_len;
185int i, num_varargs;
186zval ***varargs = NULL;
187
188if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
189    return;
190}
191
192for (i = 0; i < num_varargs; i++) {
193    /* do something with varargs[i] */
194}
195
196if (varargs) {
197    efree(varargs);
198}
199
200
201/* Function that takes an array, followed by varargs, and ending with a long */
202long num;
203zval *array;
204int i, num_varargs;
205zval ***varargs = NULL;
206
207if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
208    return;
209}
210
211for (i = 0; i < num_varargs; i++) {
212    /* do something with varargs[i] */
213}
214
215if (varargs) {
216    efree(varargs);
217}
218
219