release/src/router/php/README.PARAMETER_PARSING_API

   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. */
  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, ...);
  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
  26 Both functions return SUCCESS or FAILURE depending on the result.
  27
  28 The auto-conversions are performed as necessary. Arrays, objects, and
  29 resources cannot be auto-converted.
  30
  31 PHP 5.5 includes a new function:
  32
  33 int zend_parse_parameter(int flags, int arg_num TSRMLS_DC, zval **arg, const char *spec, ...);
  34
  35 This function behaves like zend_parse_parameters_ex() except that instead of
  36 reading the arguments from the stack, it receives a single zval to convert
  37 (passed with double indirection). The passed zval may be changed in place as
  38 part of the conversion process.
  39
  40 See also https://wiki.php.net/rfc/zpp_improv#expose_zend_parse_arg_as_zend_parse_parameter
  41
  42
  43 Type specifiers
  44 ---------------
  45  The following list shows the type specifier, its meaning and the parameter
  46  types that need to be passed by address. All passed parameters are set
  47  if the PHP parameter is non optional and untouched if optional and the
  48  parameter is not present. The only exception is O where the zend_class_entry*
  49  has to be provided on input and is used to verify the PHP parameter is an
  50  instance of that class.
  51
  52  a  - array (zval*)
  53  A  - array or object (zval *)
  54  b  - boolean (zend_bool)
  55  C  - class (zend_class_entry*)
  56  d  - double (double)
  57  f  - function or array containing php method call info (returned as
  58       zend_fcall_info and zend_fcall_info_cache)
  59  h  - array (returned as HashTable*)
  60  H  - array or HASH_OF(object) (returned as HashTable*)
  61  l  - long (long)
  62  L  - long, limits out-of-range numbers to LONG_MAX/LONG_MIN (long)
  63  o  - object of any type (zval*)
  64  O  - object of specific type given by class entry (zval*, zend_class_entry)
  65  p  - valid path (string without null bytes in the middle) and its length (char*, int)
  66  r  - resource (zval*)
  67  s  - string (with possible null bytes) and its length (char*, int)
  68  z  - the actual zval (zval*)
  69  Z  - the actual zval (zval**)
  70  *  - variable arguments list (0 or more)
  71  +  - variable arguments list (1 or more)
  72
  73  The following characters also have a meaning in the specifier string:
  74     | - indicates that the remaining parameters are optional, they
  75         should be initialized to default values by the extension since they
  76         will not be touched by the parsing function if they are not
  77         passed to it.
  78     / - use SEPARATE_ZVAL_IF_NOT_REF() on the parameter it follows
  79     ! - the parameter it follows can be of specified type or NULL. If NULL is
  80                 passed and the output for such type is a pointer, then the output
  81                 pointer is set to a native NULL pointer.
  82                 For 'b', 'l' and 'd', an extra argument of type zend_bool* must be
  83                 passed after the corresponding bool*, long* or double* arguments,
  84                 respectively. A non-zero value will be written to the zend_bool iif a
  85                 PHP NULL is passed.
  86
  87
  88 Note on 64bit compatibility
  89 ---------------------------
  90 Please do not forget that int and long are two different things on 64bit
  91 OSes (int is 4 bytes and long is 8 bytes), so make sure you pass longs to "l"
  92 and ints to strings length (i.e. for "s" you need to pass char * and int),
  93 not the other way round!
  94 Remember: "l" is the only case when you need to pass long (and that's why
  95 it's "l", not "i" btw).
  96
  97 Both mistakes cause memory corruptions and segfaults on 64bit OSes:
  98 1)
  99   char *str;
 100   long str_len; /* XXX THIS IS WRONG!! Use int instead. */
 101   zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &str, &str_len)
 102
 103 2)
 104   int num; /* XXX THIS IS WRONG!! Use long instead. */
 105   zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "l", &num)
 106
 107 If you're in doubt, use check_parameters.php script to the parameters
 108 and their types (it can be found in ./scripts/dev/ directory of PHP sources):
 109
 110 # php ./scripts/dev/check_parameters.php /path/to/your/sources/
 111
 112
 113 Examples
 114 --------
 115 /* Gets a long, a string and its length, and a zval */
 116 long l;
 117 char *s;
 118 int s_len;
 119 zval *param;
 120 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "lsz",
 121                           &l, &s, &s_len, &param) == FAILURE) {
 122     return;
 123 }
 124
 125
 126 /* Gets an object of class specified by my_ce, and an optional double. */
 127 zval *obj;
 128 double d = 0.5;
 129 zend_class_entry *my_ce;
 130 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "O|d",
 131                           &obj, my_ce, &d) == FAILURE) {
 132     return;
 133 }
 134
 135
 136 /* Gets an object or null, and an array.
 137    If null is passed for object, obj will be set to NULL. */
 138 zval *obj;
 139 zval *arr;
 140 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "o!a",
 141                           &obj, &arr) == FAILURE) {
 142     return;
 143 }
 144
 145
 146 /* Gets a separated array which can also be null. */
 147 zval *arr;
 148 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a/!",
 149                           &arr) == FAILURE) {
 150     return;
 151 }
 152
 153 /* Get either a set of 3 longs or a string. */
 154 long l1, l2, l3;
 155 char *s;
 156 /*
 157  * The function expects a pointer to a integer in this case, not a long
 158  * or any other type.  If you specify a type which is larger
 159  * than a 'int', the upper bits might not be initialized
 160  * properly, leading to random crashes on platforms like
 161  * Tru64 or Linux/Alpha.
 162  */
 163 int length;
 164
 165 if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
 166                              "lll", &l1, &l2, &l3) == SUCCESS) {
 167     /* manipulate longs */
 168 } else if (zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS() TSRMLS_CC,
 169                                     "s", &s, &length) == SUCCESS) {
 170     /* manipulate string */
 171 } else {
 172     /* output error */
 173
 174     return;
 175 }
 176
 177
 178 /* Function that accepts only varargs (0 or more) */
 179
 180 int i, num_varargs;
 181 zval ***varargs = NULL;
 182
 183
 184 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "*", &varargs, &num_varargs) == FAILURE) {
 185     return;
 186 }
 187
 188 for (i = 0; i < num_varargs; i++) {
 189     /* do something with varargs[i] */
 190 }
 191
 192 if (varargs) {
 193     efree(varargs);
 194 }
 195
 196
 197 /* Function that accepts a string, followed by varargs (1 or more) */
 198
 199 char *str;
 200 int str_len;
 201 int i, num_varargs;
 202 zval ***varargs = NULL;
 203
 204 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s+", &str, &str_len, &varargs, &num_varargs) == FAILURE) {
 205     return;
 206 }
 207
 208 for (i = 0; i < num_varargs; i++) {
 209     /* do something with varargs[i] */
 210 }
 211
 212 if (varargs) {
 213     efree(varargs);
 214 }
 215
 216
 217 /* Function that takes an array, followed by varargs, and ending with a long */
 218 long num;
 219 zval *array;
 220 int i, num_varargs;
 221 zval ***varargs = NULL;
 222
 223 if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "a*l", &array, &varargs, &num_varargs, &num) == FAILURE) {
 224     return;
 225 }
 226
 227 for (i = 0; i < num_varargs; i++) {
 228     /* do something with varargs[i] */
 229 }
 230
 231 if (varargs) {
 232     efree(varargs);
 233 }
 234