Fix heredoc/nowdoc bugs with large docs, docs crossing buffer boundaries
[hiphop-php.git] / hphp / idl / function.idl.php
blobcbe996f351ba0dc26ee09f93d602251b36f3a47e
1 <?php
2 /**
3 * Automatically generated by running "php schema.php function".
5 * You may modify the file, but re-running schema.php against this file will
6 * standardize the format without losing your schema changes. It does lose
7 * any changes that are not part of schema. Use "note" field to comment on
8 * schema itself, and "note" fields are not used in any code generation but
9 * only staying within this file.
11 * @nolint
13 ///////////////////////////////////////////////////////////////////////////////
14 // Preamble: C++ code inserted at beginning of ext_{name}.h
16 DefinePreamble(<<<CPP
18 CPP
21 ///////////////////////////////////////////////////////////////////////////////
22 // Constants
24 // array (
25 // 'name' => name of the constant
26 // 'type' => type of the constant
27 // 'note' => additional note about this constant's schema
28 // )
31 ///////////////////////////////////////////////////////////////////////////////
32 // Functions
34 // array (
35 // 'name' => name of the function
36 // 'desc' => description of the function's purpose
37 // 'flags' => attributes of the function, see base.php for possible values
38 // 'opt' => optimization callback function's name for compiler
39 // 'note' => additional note about this function's schema
40 // 'return' =>
41 // array (
42 // 'type' => return type, use Reference for ref return
43 // 'desc' => description of the return value
44 // )
45 // 'args' => arguments
46 // array (
47 // 'name' => name of the argument
48 // 'type' => type of the argument, use Reference for output parameter
49 // 'value' => default value of the argument
50 // 'desc' => description of the argument
51 // )
52 // )
54 DefineFunction(
55 array(
56 'name' => "get_defined_functions",
57 'desc' => "Gets an array of all defined functions.",
58 'flags' => HasDocComment,
59 'return' => array(
60 'type' => VariantMap,
61 'desc' => "Returns an multidimensional array containing a list of all defined functions, both built-in (internal) and user-defined. The internal functions will be accessible via \$arr[\"internal\"], and the user defined ones using \$arr[\"user\"] (see example below).",
63 'taint_observer' => false,
64 ));
66 DefineFunction(
67 array(
68 'name' => "function_exists",
69 'desc' => "Checks the list of defined functions, both built-in (internal) and user-defined, for function_name.",
70 'flags' => HasDocComment,
71 'return' => array(
72 'type' => Boolean,
73 'desc' => "Returns TRUE if function_name exists and is a function, FALSE otherwise.\n\nThis function will return FALSE for constructs, such as include_once() and echo().",
75 'args' => array(
76 array(
77 'name' => "function_name",
78 'type' => String,
79 'desc' => "The function name, as a string.",
81 array(
82 'name' => "autoload",
83 'type' => Boolean,
84 'value' => "true",
85 'desc' => "Whether to try to autoload.",
88 'taint_observer' => false,
89 ));
91 DefineFunction(
92 array(
93 'name' => "is_callable",
94 'desc' => "Verify that the contents of a variable can be called as a function. This can check that a simple variable contains the name of a valid function, or that an array contains a properly encoded object and function name.",
95 'flags' => HasDocComment | HasOptFunction | ContextSensitive,
96 'opt' => "hphp_opt_is_callable",
97 'return' => array(
98 'type' => Boolean,
99 'desc' => "Returns TRUE if name is callable, FALSE otherwise.",
101 'args' => array(
102 array(
103 'name' => "v",
104 'type' => Any,
105 'desc' => "Can be either the name of a function stored in a string variable, or an object and the name of a method within the object, like this: array(\$SomeObject, 'MethodName')",
107 array(
108 'name' => "syntax",
109 'type' => Boolean,
110 'value' => "false",
111 'desc' => "If set to TRUE the function only verifies that name might be a function or method. It will only reject simple variables that are not strings, or an array that does not have a valid structure to be used as a callback. The valid ones are supposed to have only 2 entries, the first of which is an object or a string, and the second a string.",
113 array(
114 'name' => "name",
115 'type' => Variant | Reference,
116 'value' => "null",
117 'desc' => "Receives the \"callable name\". In the example below it is \"someClass::someMethod\". Note, however, that despite the implication that someClass::SomeMethod() is a callable static method, this is not the case.",
120 'taint_observer' => false,
123 DefineFunction(
124 array(
125 'name' => "call_user_func_array",
126 'desc' => "Call a user defined function with the parameters in params.",
127 'flags' => HasDocComment | HasOptFunction | NoProfile | ContextSensitive,
128 'opt' => "hphp_opt_call_user_func",
129 'return' => array(
130 'type' => Variant,
131 'desc' => "Returns the function result, or FALSE on error.",
133 'args' => array(
134 array(
135 'name' => "function",
136 'type' => Variant,
137 'desc' => "The function to be called.",
139 array(
140 'name' => "params",
141 'type' => VariantVec,
142 'desc' => "The parameters to be passed to the function, as an indexed array.",
145 'taint_observer' => false,
148 DefineFunction(
149 array(
150 'name' => "call_user_func",
151 'desc' => "Call a user defined function given by the function parameter.",
152 'flags' => HasDocComment | VariableArguments | HasOptFunction | NoProfile | ContextSensitive,
153 'opt' => "hphp_opt_call_user_func",
154 'return' => array(
155 'type' => Variant,
156 'desc' => "Returns the function result, or FALSE on error.",
158 'args' => array(
159 array(
160 'name' => "function",
161 'type' => Variant,
162 'desc' => "The function to be called. Class methods may also be invoked statically using this function by passing array(\$classname, \$methodname) to this parameter. Additionally class methods of an object instance may be called by passing array(\$objectinstance, \$methodname) to this parameter.",
165 'taint_observer' => false,
168 DefineFunction(
169 array(
170 'name' => "call_user_func_array_async",
171 'desc' => "Same as call_user_func_array(), but returns an object immediately without waiting for the function to finish. The object can be used with end_user_func_async() to eventually retrieve function's return, if needed.",
172 'flags' => HasDocComment | HipHopSpecific | ContextSensitive,
173 'return' => array(
174 'type' => Object,
175 'desc' => "An object end_user_func_async() uses for final waiting of function's return.",
177 'args' => array(
178 array(
179 'name' => "function",
180 'type' => Variant,
181 'desc' => "The function to be called, same as in call_user_func_array().",
183 array(
184 'name' => "params",
185 'type' => VariantVec,
186 'desc' => "Parameters, same as in call_user_func_array().",
189 'taint_observer' => false,
192 DefineFunction(
193 array(
194 'name' => "call_user_func_async",
195 'desc' => "Same as call_user_func(), but returns an object immediately without waiting for the function to finish. The object can be used with end_user_func_async() to eventually retrieve function's return, if needed.",
196 'flags' => HasDocComment | HipHopSpecific | MixedVariableArguments | ContextSensitive,
197 'return' => array(
198 'type' => Object,
199 'desc' => "An object end_user_func_async() uses for final waiting of function's return.",
201 'args' => array(
202 array(
203 'name' => "function",
204 'type' => Variant,
205 'desc' => "The function to be called, same as in call_user_func_array().",
208 'taint_observer' => false,
211 DefineFunction(
212 array(
213 'name' => "check_user_func_async",
214 'desc' => "Check to see if any specified jobs are done or not.",
215 'flags' => HasDocComment | HipHopSpecific,
216 'return' => array(
217 'type' => Variant,
218 'desc' => "An array of finished jobs if an array of jobs was specified, otherwise TRUE for finished and FALSE for not finished.",
220 'args' => array(
221 array(
222 'name' => "handles",
223 'type' => Variant,
224 'desc' => "An array of objects returned from call_user_func_async() or call_user_func_array_async(), or a single object for a simple TRUE/FALSE return.",
226 array(
227 'name' => "timeout",
228 'type' => Int32,
229 'value' => "-1",
230 'desc' => "In milli-seconds. -1 to return job status immediately without blocking; positive numbers for blocking until some of the specified jobs are done; 0 for infinite waiting until some of the specified jobs are done.",
233 'taint_observer' => false,
236 DefineFunction(
237 array(
238 'name' => "end_user_func_async",
239 'desc' => "Block until function returns. Used with call_user_func_async() or call_user_func_array_async().",
240 'flags' => HasDocComment | HipHopSpecific,
241 'return' => array(
242 'type' => Variant,
243 'desc' => "Function's return value.",
245 'args' => array(
246 array(
247 'name' => "handle",
248 'type' => Object,
249 'desc' => "The object returned from call_user_func_async() or call_user_func_array_async().",
251 array(
252 'name' => "default_strategy",
253 'type' => Int32,
254 'value' => "k_GLOBAL_STATE_IGNORE",
255 'desc' => "GLOBAL_STATE_ constants to specify how to treat global states. Please read documentation for more details.",
257 array(
258 'name' => "additional_strategies",
259 'type' => Variant,
260 'value' => "null",
261 'desc' => "Extra strategy for individual variables. Please read documentation for more details.",
264 'taint_observer' => false,
267 DefineFunction(
268 array(
269 'name' => "call_user_func_serialized",
270 'desc' => "Invoke a function with serialized function and parameters by calling serialize(array(\"func\" => \$func, \"params\" => \$params)), and returns function return in serialized format of array(\"ret\" => \$ret, \"exception\" => \$exception). Useful for over-network invocation.",
271 'flags' => HasDocComment | HipHopSpecific,
272 'return' => array(
273 'type' => String,
274 'desc' => "Serialized return.",
276 'args' => array(
277 array(
278 'name' => "input",
279 'type' => String,
280 'desc' => "Serialized callback and parameters.",
283 'taint_observer' => false,
286 DefineFunction(
287 array(
288 'name' => "call_user_func_array_rpc",
289 'desc' => "Same as call_user_func_array(), but executes on a remote HipHop RPC server",
290 'flags' => HasDocComment | HipHopSpecific,
291 'return' => array(
292 'type' => Variant,
293 'desc' => "Returns the function result, or FALSE on error.",
295 'args' => array(
296 array(
297 'name' => "host",
298 'type' => String,
299 'desc' => "Remote RPC server's address.",
301 array(
302 'name' => "port",
303 'type' => Int32,
304 'desc' => "Remote RPC server's port.",
306 array(
307 'name' => "auth",
308 'type' => String,
309 'desc' => "Remote RPC server's authentication password.",
311 array(
312 'name' => "timeout",
313 'type' => Int32,
314 'desc' => "How many seconds to wait for response.",
316 array(
317 'name' => "function",
318 'type' => Variant,
319 'desc' => "The function to be called, same as in call_user_func_array().",
321 array(
322 'name' => "params",
323 'type' => VariantVec,
324 'desc' => "Parameters, same as in call_user_func_array().",
327 'taint_observer' => false,
330 DefineFunction(
331 array(
332 'name' => "call_user_func_rpc",
333 'desc' => "Same as call_user_func(), but executes on a remote HipHop RPC server",
334 'flags' => HasDocComment | HipHopSpecific | MixedVariableArguments,
335 'return' => array(
336 'type' => Variant,
337 'desc' => "Returns the function result, or FALSE on error.",
339 'args' => array(
340 array(
341 'name' => "host",
342 'type' => String,
343 'desc' => "Remote RPC server's address.",
345 array(
346 'name' => "port",
347 'type' => Int32,
348 'desc' => "Remote RPC server's port.",
350 array(
351 'name' => "auth",
352 'type' => String,
353 'desc' => "Remote RPC server's authentication password.",
355 array(
356 'name' => "timeout",
357 'type' => Int32,
358 'desc' => "How many seconds to wait for response.",
360 array(
361 'name' => "function",
362 'type' => Variant,
363 'desc' => "The function to be called, same as in call_user_func_array().",
366 'taint_observer' => false,
369 DefineFunction(
370 array(
371 'name' => "forward_static_call_array",
372 'desc' => "Calls a user defined function or method given by the function parameter. This function must be called within a method context, it can't be used outside a class. All arguments of the forwarded method are passed as values, and as an array, similarly to call_user_func_array().",
373 'flags' => HasDocComment | ContextSensitive,
374 'return' => array(
375 'type' => Variant,
376 'desc' => "Returns the function result, or FALSE on error.",
378 'args' => array(
379 array(
380 'name' => "function",
381 'type' => Variant,
382 'desc' => "The function or method to be called. This parameter may be an array, with the name of the class, and the method, or a string, with a function name.",
384 array(
385 'name' => "params",
386 'type' => VariantVec,
387 'desc' => "One parameter, gathering all the method parameter in one array.\n\nNote that the parameters for forward_static_call_array() are not passed by reference.",
390 'taint_observer' => false,
393 DefineFunction(
394 array(
395 'name' => "forward_static_call",
396 'desc' => "Calls a user defined function or method given by the function parameter, with the following arguments. This function must be called within a method context, it can't be used outside a class.",
397 'flags' => HasDocComment | VariableArguments | ContextSensitive,
398 'return' => array(
399 'type' => Variant,
400 'desc' => "Returns the function result, or FALSE on error.",
402 'args' => array(
403 array(
404 'name' => "function",
405 'type' => Variant,
406 'desc' => "The function or method to be called. This parameter may be an array, with the name of the class, and the method, or a string, with a function name.",
409 'taint_observer' => false,
412 DefineFunction(
413 array(
414 'name' => "get_called_class",
415 'desc' => "Gets the name of the class the static method is called in.",
416 'flags' => HasDocComment,
417 'return' => array(
418 'type' => Variant,
419 'desc' => "Returns the class name. Returns FALSE if called from outside a class.",
421 'taint_observer' => false,
424 DefineFunction(
425 array(
426 'name' => "create_function",
427 'desc' => "Creates an anonymous function from the parameters passed, and returns a unique name for it.\nUsually these parameters will be passed as single quote delimited strings. The reason for using single quoted strings, is to protect the variable names from parsing, otherwise, if you use double quotes there will be a need to escape the variable names, e.g. \\\$avar.",
428 'flags' => HasDocComment,
429 'return' => array(
430 'type' => String,
431 'desc' => "Returns a unique function name as a string, or FALSE on error.",
433 'args' => array(
434 array(
435 'name' => "args",
436 'type' => String,
437 'desc' => "The function arguments.",
439 array(
440 'name' => "code",
441 'type' => String,
442 'desc' => "The function code.",
445 'taint_observer' => false,
448 DefineFunction(
449 array(
450 'name' => "func_get_arg",
451 'desc' => "Gets the specified argument from a user-defined function's argument list.\n\nThis function may be used in conjunction with func_get_args() and func_num_args() to allow user-defined functions to accept variable-length argument lists.",
452 'flags' => HasDocComment,
453 'return' => array(
454 'type' => Variant,
455 'desc' => "Returns the specified argument, or FALSE on error.",
457 'args' => array(
458 array(
459 'name' => "arg_num",
460 'type' => Int32,
461 'desc' => "The argument offset. Function arguments are counted starting from zero.",
464 'taint_observer' => false,
467 DefineFunction(
468 array(
469 'name' => "func_get_args",
470 'desc' => "Gets an array of the function's argument list.\n\nThis function may be used in conjunction with func_get_arg() and func_num_args() to allow user-defined functions to accept variable-length argument lists.",
471 'flags' => HasDocComment,
472 'return' => array(
473 'type' => VariantVec,
474 'desc' => "Returns an array in which each element is a copy of the corresponding member of the current user-defined function's argument list.",
476 'taint_observer' => false,
479 DefineFunction(
480 array(
481 'name' => "func_num_args",
482 'desc' => "Gets the number of arguments passed to the function.\n\nThis function may be used in conjunction with func_get_arg() and func_get_args() to allow user-defined functions to accept variable-length argument lists.",
483 'flags' => HasDocComment,
484 'return' => array(
485 'type' => Int64,
486 'desc' => "Returns the number of arguments passed into the current user-defined function.",
488 'taint_observer' => false,
491 DefineFunction(
492 array(
493 'name' => "register_postsend_function",
494 'desc' => "Registers functions to call after HTTP response is completely sent to browser.",
495 'flags' => HasDocComment | HipHopSpecific | VariableArguments,
496 'return' => array(
497 'type' => null,
499 'args' => array(
500 array(
501 'name' => "function",
502 'type' => Variant,
503 'desc' => "The callback to register.",
506 'taint_observer' => false,
509 DefineFunction(
510 array(
511 'name' => "register_shutdown_function",
512 'desc' => "Registers the function named by function to be executed when script processing is complete or when exit() is called.\n\nMultiple calls to register_shutdown_function() can be made, and each will be called in the same order as they were registered. If you call exit() within one registered shutdown function, processing will stop completely and no other registered shutdown functions will be called.",
513 'flags' => HasDocComment | VariableArguments,
514 'return' => array(
515 'type' => null,
516 'desc' => "No value is returned.",
518 'args' => array(
519 array(
520 'name' => "function",
521 'type' => Variant,
522 'desc' => "The shutdown function to register.\n\nThe shutdown functions are called as the part of the request so that it's possible to send the output from them. There is currently no way to process the data with output buffering functions in the shutdown function.\n\nShutdown functions are called after closing all opened output buffers thus, for example, its output will not be compressed if zlib.output_compression is enabled.",
525 'taint_observer' => false,
528 DefineFunction(
529 array(
530 'name' => "register_cleanup_function",
531 'desc' => "Registers functions to call at very end of a web page to clean up and free system resources.",
532 'flags' => HasDocComment | HipHopSpecific | VariableArguments,
533 'return' => array(
534 'type' => null,
536 'args' => array(
537 array(
538 'name' => "function",
539 'type' => Variant,
540 'desc' => "The callback to register.",
543 'taint_observer' => false,
546 DefineFunction(
547 array(
548 'name' => "register_tick_function",
549 'flags' => HasDocComment | VariableArguments,
550 'return' => array(
551 'type' => Boolean,
552 'desc' => "Returns TRUE on success or FALSE on failure.",
554 'args' => array(
555 array(
556 'name' => "function",
557 'type' => Variant,
558 'desc' => "The function name as a string, or an array consisting of an object and a method.",
561 'taint_observer' => false,
564 DefineFunction(
565 array(
566 'name' => "unregister_tick_function",
567 'flags' => HasDocComment,
568 'return' => array(
569 'type' => null,
570 'desc' => "No value is returned.",
572 'args' => array(
573 array(
574 'name' => "function_name",
575 'type' => Variant,
576 'desc' => "The function name, as a string.",
579 'taint_observer' => false,
583 ///////////////////////////////////////////////////////////////////////////////
584 // Classes
586 // BeginClass
587 // array (
588 // 'name' => name of the class
589 // 'desc' => description of the class's purpose
590 // 'flags' => attributes of the class, see base.php for possible values
591 // 'note' => additional note about this class's schema
592 // 'parent' => parent class name, if any
593 // 'ifaces' => array of interfaces tihs class implements
594 // 'bases' => extra internal and special base classes this class requires
595 // 'footer' => extra C++ inserted at end of class declaration
596 // )
598 // DefineConstant(..)
599 // DefineConstant(..)
600 // ...
601 // DefineFunction(..)
602 // DefineFunction(..)
603 // ...
604 // DefineProperty
605 // DefineProperty
607 // array (
608 // 'name' => name of the property
609 // 'type' => type of the property
610 // 'flags' => attributes of the property
611 // 'desc' => description of the property
612 // 'note' => additional note about this property's schema
613 // )
615 // EndClass()