com php-src: zpp readme adjustment: README.PARAMETER_PARSIN G_API

From: Date: Tue, 25 Feb 2014 10:05:35 +0000
Subject: com php-src: zpp readme adjustment: README.PARAMETER_PARSIN G_API
Groups: php.cvs 
Request: Send a blank email to php-cvs+get-76202@lists.php.net to get a copy of this message
Commit: b643fcddd15dcc41249f003a66bc8cca4326a9b8 Author: Anatol Belski <ab@php.net> Tue, 25 Feb 2014 11:05:35 +0100 Parents: 94cfa3a120f8de63b446f0f9842c21f8bbd8e7bf Branches: str_size_and_int64_56_backport Link: http://git.php.net/?p=php-src.git;a=commitdiff;h=b643fcddd15dcc41249f003a66bc8cca4326a9b8 Log: zpp readme adjustment Changed paths: M README.PARAMETER_PARSING_API Diff: diff --git a/README.PARAMETER_PARSING_API b/README.PARAMETER_PARSING_API index 25a4109..9bcc88c 100644 --- a/README.PARAMETER_PARSING_API +++ b/README.PARAMETER_PARSING_API @@ -58,13 +58,14 @@ Type specifiers 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) + i - php_int_t (zend_int_t), platform dependent + I - php_int_t_int_t, limits out-of-range numbers to ZEND_INT_MAX/ZEND_INT_MIN (zend_int_t), + platform dependent 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) + P - valid path (string without null bytes in the middle) and its length (char*, php_size_t) r - resource (zval*) - s - string (with possible null bytes) and its length (char*, int) + S - string (with possible null bytes) and its length (char*, php_size_t) z - the actual zval (zval*) Z - the actual zval (zval**) * - variable arguments list (0 or more) @@ -79,30 +80,33 @@ Type specifiers ! - 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, + For 'b', 'i' and 'd', an extra argument of type zend_bool* must be + passed after the corresponding bool*, php_int_t* 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). +Please do not forget that php_int_t and php_size_t are platform dependent, +you can consult Zend/zend_int.h for which type exactly these are mapped to. +In previous versions, long was used for integers and int for string +sizes. Now make sure you pass php_int_t to "i" and php_size_t to strings length +(i.e. for "S" you need to pass char * and php_size_t), not the other way round! +Remember: "i" is the only case when you need to pass platform depnedent integer +(and that's why it's "i", not "l" anymore).. The old formats 'l' and 's' aren't +supported anymore. Passing int instead of php_size_t, or long instead of +php_int_t is wrong. 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) + int str_len; /* XXX THIS IS WRONG!! Use php_size_t 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) + long num; /* XXX THIS IS WRONG!! Use php_int_t instead. */ + zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "i", &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): @@ -112,12 +116,12 @@ and their types (it can be found in ./scripts/dev/ directory of PHP sources): Examples -------- -/* Gets a long, a string and its length, and a zval */ -long l; +/* Gets a php_int_t, a string and its length, and a zval */ +php_int_t i; char *s; -int s_len; +php_size_t s_len; zval *param; -if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz", +if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "iSz", &l, &s, &s_len, &param) == FAILURE) { return; } @@ -150,8 +154,8 @@ if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!", return; } -/* Get either a set of 3 longs or a string. */ -long l1, l2, l3; +/* Get either a set of 3 php_int_t vars or a string.. */ +php_int_t i1, i2, i3; char *s; /* * The function expects a pointer to a integer in this case, not a long @@ -160,13 +164,13 @@ char *s; * properly, leading to random crashes on platforms like * Tru64 or Linux/Alpha. */ -int length; +php_size_t length; if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC, - "lll", &l1, &l2, &l3) == SUCCESS) { - /* manipulate longs */ + "iii", &i1, &i2, &i3) == SUCCESS) { + /* manipulate php_int_t */ } else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC, - "s", &s, &length) == SUCCESS) { + "S", &s, &length) == SUCCESS) { /* manipulate string */ } else { /* output error */ @@ -197,11 +201,11 @@ if (varargs) { /* Function that accepts a string, followed by varargs (1 or more) */ char *str; -int str_len; +php_size_t 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) { +if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "S+", &str, &str_len, &varargs, &num_varargs) == FAILURE) { return; } @@ -214,13 +218,13 @@ if (varargs) { } -/* Function that takes an array, followed by varargs, and ending with a long */ -long num; +/* Function that takes an array, followed by varargs, and ending with a php_int_t */ +php_int_t 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) { +if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a*i", &array, &varargs, &num_varargs, &num) == FAILURE) { return; }

« previous php.cvs (#76202) next »