com php-src: further writing on PECL_PORTING: compat/PECL _PORTING

From: Date: Mon, 13 Jan 2014 09:44:36 +0000
Subject: com php-src: further writing on PECL_PORTING: compat/PECL _PORTING
Groups: php.cvs 
Request: Send a blank email to php-cvs+get-75585@lists.php.net to get a copy of this message
Commit: f7e5a97076eecc7b728a0a3739764925e28901b4 Author: Anatol Belski <ab@php.net> Mon, 13 Jan 2014 10:44:36 +0100 Parents: 4560d412bb891933cb092e59a2034fd2e0ddfc03 Branches: str_size_and_int64 Link: http://git.php.net/?p=php-src.git;a=commitdiff;h=f7e5a97076eecc7b728a0a3739764925e28901b4 Log: further writing on PECL_PORTING Changed paths: M compat/PECL_PORTING Diff: diff --git a/compat/PECL_PORTING b/compat/PECL_PORTING index d1086d7..71074e9 100644 --- a/compat/PECL_PORTING +++ b/compat/PECL_PORTING @@ -8,11 +8,11 @@ I. Basic changes in <str_size_and_int64> v. Functions II. Porting steps i. Automatic replacements - ii. Explicit compilation enablement - iii. Compatibility header - iv. zend_parse_parameters() - v. Manual code fixes - vi. Library dependencies + ii. Compatibility header + iii. zend_parse_parameters() + iv. Manual code fixes + v. Library dependencies + vi. spprintf() formats III. Pitfalls i. size_t usage ii. zend_parse_parameters() @@ -22,34 +22,123 @@ III. Pitfalls I. Basic changes in <str_size_and_int64> ======================================== + For extended information, please look at the compat.h header and the wiki RFC page + https://wiki.php.net/rfc/size_t_and_int64 + i. String length + + String lengths do no more depend on the firm 'int' datatype. The replacement + is a platform dependent size_t datatype. String length is defined as zend_size_t inside Zend and aliased as php_size_t anywhere else. The inclusion of php.h is necessary. ii. Integer types + + Integers do no more depend on the firm 'long' type. Instead a platform + dependent integer type is used. That datatype is defined dynamically to + guarantee the consistent 64 bit support. Signed integer is defined as zend_int_t, unsigned integer as zend_uint_t inside Zend. Both are aliased as php_int_t, php_uint_t anywhere else. The inclusion of php.h is necessary. iii. Other datatypes + zend_off_t - portable file offsets + zend_stat_t - portable 'struct stat' + + These datatypes are declared to be portable across platforms. Thus, direct + usage of the functions like fseek, stat, etc. is strongly not recommended. + Instead the portable macros should be used. + iv. Macros + Z_STRSIZE - replacement for Z_STRLEN family + Z_IVAL - replacement for Z_LVAL family + Z_I - initialize signed integer constant + Z_UI - initialize unsigned integer constant + ZEND_INT_MAX, ZEND_INT_MIN, ZEND_UINT_MAX, ZEND_SIZE_MAX + IS_INT - replacement for IS_LONG + ZVAL_INT - replacement for ZVAL_LONG + RETVAL_INT - RETVAL_LONG + RETURN_INT - RETURN_LONG + v. Functions + Various functions became syntactic renames, it concerns functions containing + the 'long' keyword. The new portable aliases also was added. + + zend_fseek - portable fseek equivalent + zend_ftell - portable ftell equivalent + zend_lseek - portable lseek equivalent + zend_fstat - portable fstat equivalent + zend_stat - portable stat equivalent + convert_to_int, add_assoc_int, zend_ini_int, etc. + ================= II. Porting steps ================= i. Automatic replacements - ii. Explicit compilation enablement + The tool replace.php will automatically replace a number of syntactic changes + in the old style extension. + + ii. Compatibility header + The compat.h header has to be included after all the other headers and in any + using the new syntax. + + iii. zend_parse_parameters() + + The arg specs 'l', 'L', 's' and 'p' are not available anymore. As their + replacements 'i', 'I', 'S' and 'P' was invented. The integer specs expect a + variable of php_int_t to be passed. The string/path length are expected to be + of type php_size_t. + + The recommended way to declare the argument specs is using a ternary operator, + eq. + + php_int_t i0, i1; + char *s0, p0; + php_size_t s0_len, p0_len; + + if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, (COMPAT ? "lLsp" : "iISP"), &i0, &i1, &s0, &s0_len, &p0, &p0_len) == FAILURE) { + return; + } + + iv. Manual code fixes + + While for many extensions the mechanic replacements will be already enough to retain + the compatibility, the manual code fixes might be necessary. This likely the + case for extensions with library dependencies, see also the pitfalls section. + + v. Library dependencies + + Libraries using incompatible data types for string sizes and integers require + additional checks to ensure the correct value range. This is easy done as in the + example below (assumed a dependency library expects a value in integer range) + + if (INT_MAX < input_arg || INT_MIN > input_arg) { + return; + } + + vi. spprintf() formats + + New printf modifier 'p' was implemented to platform independently output + php_int_t datatype. That modifier can be used with 'd', 'u', 'x' and 'o' printf + format specs with spprintf, snprintf and the wrapping printf implementations. + To ensure compatibility, the macros ZEND_INT_FMT and ZEND_UINT_FMT should be + used - #define PHP_CONSISTENT_x64 1 + php_int_t i0, i1; + char *s0, p0; + php_size_t s0_len, p0_len; - iii. Compatibility header - iv. zend_parse_parameters() - v. Manual code fixes - vi. Library dependencies + if(zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, (COMPAT ? "lLsp" : "iISP"), &i0, &i1, &s0, &s0_len, &p0, &p0_len) == FAILURE) { + return; + } + if (INT_MAX < i0 || INT_MIN > i0) { + php_error_docref(NULL TSRMLS_CC, E_WARNING, "Value '" ZEND_INT_FMT "' is out of range", i0); + return; + } ============= III. Pitfalls

« previous php.cvs (#75585) next »