Permalink
Switch branches/tags
yaf-2.1.0 xmlrpc_epi_0_51_merge_pt php5_5_0 php4 php_ibase_before_split oci8-1.4.3 oci8-1.4.0 init help dev before-sapi-split ZO_B1 ZEND_OPTIMIZER_B1 SQLITE_4_3_20041227 SPL_ALPHA SAFEGUARD_3_0_BETA1_RC1_26062002 RETURN_REF_BP RELEASE_2_0_2 RELEASE_2_0_1 RELEASE_2_0_0 RELEASE_2_0_0b1 RELEASE_2_0_0a2 RELEASE_2_0_0a1 RELEASE_2_0_0RC1 RELEASE_1_5 RELEASE_1_4 RELEASE_1_3_5 RELEASE_1_3_1 RELEASE_1_3 RELEASE_1_3b6 RELEASE_1_3b3 RELEASE_1_3b2 RELEASE_1_2_5 RELEASE_1_2_4 RELEASE_1_2_3 RELEASE_1_2_2 RELEASE_1_2_1 RELEASE_1_2_0 RELEASE_1_2 RELEASE_1_2b5 RELEASE_1_1_1 RELEASE_1_1_0 RELEASE_1_1 RELEASE_1_0_4 RELEASE_1_0_3 RELEASE_1_0_2 RELEASE_1_0_1 RELEASE_1_0_0RC1 RELEASE_1_0 RELEASE_1_0b3 RELEASE_1_0b2 RELEASE_1_0b1 RELEASE_1_0RC2 RELEASE_1_0RC1 RELEASE_0_91 RELEASE_0_90 RELEASE_0_11 RELEASE_0_10 RELEASE_0_9_4 RELEASE_0_9_3 RELEASE_0_9_2 RELEASE_0_9_1 RELEASE_0_9_0 RELEASE_0_9 RELEASE_0_9b RELEASE_0_7 RELEASE_0_6 RELEASE_0_5_3 RELEASE_0_5_2 RELEASE_0_5 RELEASE_0_4 RELEASE_0_3 RELEASE_0_2_4 RELEASE_0_2_3 RELEASE_0_2_2 RELEASE_0_2_1 RELEASE_0_2_0 RELEASE_0_2 RELEASE_0_1_1 RELEASE_0_1 PRE_ZEND_VM_DISPATCH_PATCH PRE_USED_RETURN_VALUE_PATCH PRE_TSRM_MERGE_PATCH PRE_SUBST_Z_MACROS PRE_RETURN_REF_PATCH PRE_RETURN_REF_MERGE PRE_PARAMETER_PARSING_API PRE_NEW_VM_GEN_PATCH PRE_NEW_OCI8_EXTENSION PRE_METHOD_DEREFERENCE_PATCH PRE_METHOD_CALL_SEPERATE_FIX_PATCH PRE_LIBZEND_TO_ZEND PRE_LIBMYSQL_REVERT PRE_ISSET_TYPE PRE_ISSET_PATCH PRE_GRANULAR_GARBAGE_FIX PRE_FUNC_RETURNS_OBJECT_PATCH PRE_FILE_COMPILE_API_CHANGE PRE_FETCH_READ_PATCH PRE_ENGINE2_SPLIT
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
235 lines (184 sloc) 7.47 KB
New parameter parsing functions
===============================
It should be easier to parse input parameters to an extension function.
Hence, borrowing from Python's example, there are now a set of functions
that given the string of type specifiers, can parse the input parameters
and store the results in the user specified variables. This avoids most
of the IS_* checks and convert_to_* conversions. The functions also
check for the appropriate number of parameters, and try to output
meaningful error messages.
Prototypes
----------
/* Implemented. */
int zend_parse_parameters(int num_args TSRMLS_DC, char *type_spec, ...);
int zend_parse_parameters_ex(int flags, int num_args TSRMLS_DC, char *type_spec, ...);
The zend_parse_parameters() function takes the number of parameters
passed to the extension function, the type specifier string, and the
list of pointers to variables to store the results in. The _ex() version
also takes 'flags' argument -- current only ZEND_PARSE_PARAMS_QUIET can
be used as 'flags' to specify that the function should operate quietly
and not output any error messages.
Both functions return SUCCESS or FAILURE depending on the result.
The auto-conversions are performed as necessary. Arrays, objects, and
resources cannot be auto-converted.
PHP 5.5 includes a new function:
int zend_parse_parameter(int flags, int arg_num TSRMLS_DC, zval **arg, const char *spec, ...);
This function behaves like zend_parse_parameters_ex() except that instead of
reading the arguments from the stack, it receives a single zval to convert
(passed with double indirection). The passed zval may be changed in place as
part of the conversion process.
See also https://wiki.php.net/rfc/zpp_improv#expose_zend_parse_arg_as_zend_parse_parameter
Type specifiers
---------------
The following list shows the type specifier, its meaning and the parameter
types that need to be passed by address. All passed parameters are set
if the PHP parameter is non optional and untouched if optional and the
parameter is not present. The only exception is O where the zend_class_entry*
has to be provided on input and is used to verify the PHP parameter is an
instance of that class.
a - array (zval*)
A - array or object (zval *)
b - boolean (zend_bool)
C - class (zend_class_entry*)
d - double (double)
f - function or array containing php method call info (returned as
zend_fcall_info and zend_fcall_info_cache)
h - array (returned as HashTable*)
H - array or HASH_OF(object) (returned as HashTable*)
l - long (long)
L - long, limits out-of-range numbers to LONG_MAX/LONG_MIN (long)
o - object of any type (zval*)
O - object of specific type given by class entry (zval*, zend_class_entry)
p - valid path (string without null bytes in the middle) and its length (char*, int)
r - resource (zval*)
s - string (with possible null bytes) and its length (char*, int)
z - the actual zval (zval*)
Z - the actual zval (zval**)
* - variable arguments list (0 or more)
+ - variable arguments list (1 or more)
The following characters also have a meaning in the specifier string:
| - indicates that the remaining parameters are optional, they
should be initialized to default values by the extension since they
will not be touched by the parsing function if they are not
passed to it.
/ - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
! - the parameter it follows can be of specified type or NULL. If NULL is
passed and the output for such type is a pointer, then the output
pointer is set to a native NULL pointer.
For 'b', 'l' and 'd', an extra argument of type zend_bool* must be
passed after the corresponding bool*, long* or double* arguments,
respectively. A non-zero value will be written to the zend_bool iif a
PHP NULL is passed.
Note on 64bit compatibility
---------------------------
Please do not forget that int and long are two different things on 64bit
OSes (int is 4 bytes and long is 8 bytes), so make sure you pass longs to "l"
and ints to strings length (i.e. for "s" you need to pass char * and int),
not the other way round!
Remember: "l" is the only case when you need to pass long (and that's why
it's "l", not "i" btw).
Both mistakes cause memory corruptions and segfaults on 64bit OSes:
1)
char *str;
long str_len; /* XXX THIS IS WRONG!! Use int instead. */
zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &str, &str_len)
2)
int num; /* XXX THIS IS WRONG!! Use long instead. */
zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &num)
If you're in doubt, use check_parameters.php script to the parameters
and their types (it can be found in ./scripts/dev/ directory of PHP sources):
# php ./scripts/dev/check_parameters.php /path/to/your/sources/
Examples
--------
/* Gets a long, a string and its length, and a zval */
long l;
char *s;
int s_len;
zval *param;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz",
&l, &s, &s_len, &param) == FAILURE) {
return;
}
/* Gets an object of class specified by my_ce, and an optional double. */
zval *obj;
double d = 0.5;
zend_class_entry *my_ce;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
&obj, my_ce, &d) == FAILURE) {
return;
}
/* Gets an object or null, and an array.
If null is passed for object, obj will be set to NULL. */
zval *obj;
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o!a",
&obj, &arr) == FAILURE) {
return;
}
/* Gets a separated array which can also be null. */
zval *arr;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
&arr) == FAILURE) {
return;
}
/* Get either a set of 3 longs or a string. */
long l1, l2, l3;
char *s;
/*
* The function expects a pointer to a integer in this case, not a long
* or any other type. If you specify a type which is larger
* than a 'int', the upper bits might not be initialized
* properly, leading to random crashes on platforms like
* Tru64 or Linux/Alpha.
*/
int length;
if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
"lll", &l1, &l2, &l3) == SUCCESS) {
/* manipulate longs */
} else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
"s", &s, &length) == SUCCESS) {
/* manipulate string */
} else {
/* output error */
return;
}
/* Function that accepts only varargs (0 or more) */
int i, num_varargs;
zval ***varargs = NULL;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "*", &varargs, &num_varargs) == FAILURE) {
return;
}
for (i = 0; i < num_varargs; i++) {
/* do something with varargs[i] */
}
if (varargs) {
efree(varargs);
}
/* Function that accepts a string, followed by varargs (1 or more) */
char *str;
int str_len;
int i, num_varargs;
zval ***varargs = NULL;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
return;
}
for (i = 0; i < num_varargs; i++) {
/* do something with varargs[i] */
}
if (varargs) {
efree(varargs);
}
/* Function that takes an array, followed by varargs, and ending with a long */
long num;
zval *array;
int i, num_varargs;
zval ***varargs = NULL;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
return;
}
for (i = 0; i < num_varargs; i++) {
/* do something with varargs[i] */
}
if (varargs) {
efree(varargs);
}