| Index: trunk/php/luasandbox/luasandbox.c |
| — | — | @@ -56,7 +56,7 @@ |
| 57 | 57 | * * pcall, xpcall: Changing the protected environment won't work with our |
| 58 | 58 | * current timeout method. |
| 59 | 59 | * * loadfile: insecure. |
| 60 | | - * * load, loadstring: Probably creates a protected environment so can't has |
| | 60 | + * * load, loadstring: Probably creates a protected environment so has |
| 61 | 61 | * the same problem as pcall. Also omitting these makes analysis of the |
| 62 | 62 | * code for runtime etc. feasible. |
| 63 | 63 | * * print: Not compatible with a sandbox environment |
| — | — | @@ -99,6 +99,7 @@ |
| 100 | 100 | |
| 101 | 101 | zend_class_entry *luasandbox_ce; |
| 102 | 102 | zend_class_entry *luasandboxerror_ce; |
| | 103 | +zend_class_entry *luasandboxemergencytimeout_ce; |
| 103 | 104 | zend_class_entry *luasandboxplaceholder_ce; |
| 104 | 105 | zend_class_entry *luasandboxfunction_ce; |
| 105 | 106 | |
| — | — | @@ -129,7 +130,7 @@ |
| 130 | 131 | ZEND_ARG_INFO(0, ...) |
| 131 | 132 | ZEND_END_ARG_INFO() |
| 132 | 133 | |
| 133 | | -ZEND_BEGIN_ARG_INFO(arginfo_luasandbox_register, 0) |
| | 134 | +ZEND_BEGIN_ARG_INFO(arginfo_luasandbox_registerLibrary, 0) |
| 134 | 135 | ZEND_ARG_INFO(0, libname) |
| 135 | 136 | ZEND_ARG_INFO(0, functions) |
| 136 | 137 | ZEND_END_ARG_INFO() |
| — | — | @@ -154,7 +155,7 @@ |
| 155 | 156 | PHP_ME(LuaSandbox, setMemoryLimit, arginfo_luasandbox_setMemoryLimit, 0) |
| 156 | 157 | PHP_ME(LuaSandbox, setCPULimit, arginfo_luasandbox_setCPULimit, 0) |
| 157 | 158 | PHP_ME(LuaSandbox, callFunction, arginfo_luasandbox_callFunction, 0) |
| 158 | | - PHP_ME(LuaSandbox, register, arginfo_luasandbox_register, 0) |
| | 159 | + PHP_ME(LuaSandbox, registerLibrary, arginfo_luasandbox_registerLibrary, 0) |
| 159 | 160 | {NULL, NULL, NULL} |
| 160 | 161 | }; |
| 161 | 162 | |
| — | — | @@ -212,6 +213,10 @@ |
| 213 | 214 | luasandboxerror_ce = zend_register_internal_class_ex( |
| 214 | 215 | &ce, zend_exception_get_default(TSRMLS_C), NULL TSRMLS_CC); |
| 215 | 216 | |
| | 217 | + INIT_CLASS_ENTRY(ce, "LuaSandboxEmergencyTimeout", luasandbox_empty_methods); |
| | 218 | + luasandboxemergencytimeout_ce = zend_register_internal_class_ex( |
| | 219 | + &ce, luasandboxerror_ce, NULL TSRMLS_CC); |
| | 220 | + |
| 216 | 221 | zend_declare_class_constant_long(luasandboxerror_ce, |
| 217 | 222 | "RUN", sizeof("RUN"), LUA_ERRRUN); |
| 218 | 223 | zend_declare_class_constant_long(luasandboxerror_ce, |
| — | — | @@ -271,6 +276,7 @@ |
| 272 | 277 | /* }}} */ |
| 273 | 278 | |
| 274 | 279 | /** {{{ luasandbox_enter_php |
| | 280 | + * |
| 275 | 281 | * This function must be called each time a C function is entered from Lua |
| 276 | 282 | * and the PHP state needs to be accessed in any way. Before exiting the |
| 277 | 283 | * function, luasandbox_leave_php() must be called. |
| — | — | @@ -290,6 +296,9 @@ |
| 291 | 297 | /* }}} */ |
| 292 | 298 | |
| 293 | 299 | /** {{{ luasandbox_leave_php |
| | 300 | + * |
| | 301 | + * This function must be called after luasandbox_enter_php, before the callback |
| | 302 | + * from Lua returns. |
| 294 | 303 | */ |
| 295 | 304 | static inline void luasandbox_leave_php(lua_State * L, php_luasandbox_obj * intern) |
| 296 | 305 | { |
| — | — | @@ -297,7 +306,10 @@ |
| 298 | 307 | } |
| 299 | 308 | /* }}} */ |
| 300 | 309 | |
| 301 | | -/** {{{ luasandbox_new */ |
| | 310 | +/** {{{ luasandbox_new |
| | 311 | + * |
| | 312 | + * "new" handler for the LuaSandbox class |
| | 313 | + */ |
| 302 | 314 | static zend_object_value luasandbox_new(zend_class_entry *ce TSRMLS_DC) |
| 303 | 315 | { |
| 304 | 316 | php_luasandbox_obj * intern; |
| — | — | @@ -322,7 +334,11 @@ |
| 323 | 335 | } |
| 324 | 336 | /* }}} */ |
| 325 | 337 | |
| 326 | | -/** {{{ luasandbox_newstate */ |
| | 338 | +/** {{{ luasandbox_newstate |
| | 339 | + * |
| | 340 | + * Create a new lua_State which is suitable for running sandboxed scripts in. |
| | 341 | + * Initialise libraries and any necessary registry entries. |
| | 342 | + */ |
| 327 | 343 | static lua_State * luasandbox_newstate(php_luasandbox_obj * intern) |
| 328 | 344 | { |
| 329 | 345 | lua_State * L; |
| — | — | @@ -385,7 +401,10 @@ |
| 386 | 402 | } |
| 387 | 403 | /* }}} */ |
| 388 | 404 | |
| 389 | | -/** {{{ luasandbox_free_storage */ |
| | 405 | +/** {{{ luasandbox_free_storage |
| | 406 | + * |
| | 407 | + * "Free storage" handler for LuaSandbox objects. |
| | 408 | + */ |
| 390 | 409 | static void luasandbox_free_storage(void *object TSRMLS_DC) |
| 391 | 410 | { |
| 392 | 411 | php_luasandbox_obj * intern = (php_luasandbox_obj*)object; |
| — | — | @@ -396,7 +415,13 @@ |
| 397 | 416 | } |
| 398 | 417 | /* }}} */ |
| 399 | 418 | |
| 400 | | -/** {{{ luasandboxfunction_new */ |
| | 419 | +/** {{{ luasandboxfunction_new |
| | 420 | + * |
| | 421 | + * "new" handler for the LuaSandboxFunction class. |
| | 422 | + * |
| | 423 | + * TODO: Make it somehow impossible to construct these objects from user code. |
| | 424 | + * Only LuaSandbox methods should be constructing them. |
| | 425 | + */ |
| 401 | 426 | static zend_object_value luasandboxfunction_new(zend_class_entry *ce TSRMLS_CC) |
| 402 | 427 | { |
| 403 | 428 | php_luasandboxfunction_obj * intern; |
| — | — | @@ -418,7 +443,12 @@ |
| 419 | 444 | } |
| 420 | 445 | /* }}} */ |
| 421 | 446 | |
| 422 | | -/** {{{ luasandboxfunction_destroy */ |
| | 447 | +/** {{{ luasandboxfunction_destroy |
| | 448 | + * |
| | 449 | + * Destructor for the LuaSandboxFunction class. Deletes the chunk from the |
| | 450 | + * registry and decrements the reference counter for the parent LuaSandbox |
| | 451 | + * object. |
| | 452 | + */ |
| 423 | 453 | static void luasandboxfunction_destroy(void *object, zend_object_handle handle TSRMLS_DC) |
| 424 | 454 | { |
| 425 | 455 | php_luasandboxfunction_obj * func = (php_luasandboxfunction_obj*)object; |
| — | — | @@ -441,7 +471,10 @@ |
| 442 | 472 | } |
| 443 | 473 | /* }}} */ |
| 444 | 474 | |
| 445 | | -/** {{{ luasandboxfunction_free_storage */ |
| | 475 | +/** {{{ luasandboxfunction_free_storage |
| | 476 | + * |
| | 477 | + * "Free storage" handler for LuaSandboxFunction objects. |
| | 478 | + */ |
| 446 | 479 | static void luasandboxfunction_free_storage(void *object TSRMLS_DC) |
| 447 | 480 | { |
| 448 | 481 | php_luasandboxfunction_obj * func = (php_luasandboxfunction_obj*)object; |
| — | — | @@ -451,6 +484,7 @@ |
| 452 | 485 | /* }}} */ |
| 453 | 486 | |
| 454 | 487 | /** {{{ luasandbox_free_zval_userdata |
| | 488 | + * |
| 455 | 489 | * Free a zval given to Lua by luasandbox_push_zval_userdata. |
| 456 | 490 | */ |
| 457 | 491 | static int luasandbox_free_zval_userdata(lua_State * L) |
| — | — | @@ -467,7 +501,12 @@ |
| 468 | 502 | } |
| 469 | 503 | /* }}} */ |
| 470 | 504 | |
| 471 | | -/** {{{ luasandbox_alloc */ |
| | 505 | +/** {{{ luasandbox_alloc |
| | 506 | + * |
| | 507 | + * The Lua allocator function. Use PHP's request-local allocator as a backend. |
| | 508 | + * Account for memory usage and deny the allocation request if the amount |
| | 509 | + * allocated is above the user-specified limit. |
| | 510 | + */ |
| 472 | 511 | static void *luasandbox_alloc(void *ud, void *ptr, size_t osize, size_t nsize) |
| 473 | 512 | { |
| 474 | 513 | php_luasandbox_obj * obj = (php_luasandbox_obj*)ud; |
| — | — | @@ -499,7 +538,22 @@ |
| 500 | 539 | } |
| 501 | 540 | /* }}} */ |
| 502 | 541 | |
| 503 | | -/** {{{ luasandbox_panic */ |
| | 542 | +/** {{{ luasandbox_panic |
| | 543 | + * |
| | 544 | + * The Lua panic function. It is necessary to raise an E_ERROR, and thus do a |
| | 545 | + * longjmp(), since if this function returns, Lua will call exit(), breaking |
| | 546 | + * the Apache child. |
| | 547 | + * |
| | 548 | + * Generally, a panic will happen if the Lua API is used incorrectly in an |
| | 549 | + * unprotected environment. Currently this means C code which is called from |
| | 550 | + * PHP, not directly or indirectly from lua_pcall(). Sandboxed Lua code is run |
| | 551 | + * under lua_pcall() so can't cause a panic. |
| | 552 | + * |
| | 553 | + * Note that sandboxed Lua code may be executed in an unprotected environment |
| | 554 | + * if C code accesses a variable with a metamethod defined by the sandboxed |
| | 555 | + * code. For this reason, the "raw" functions such as lua_rawget() should be |
| | 556 | + * used where this is a possibility. |
| | 557 | + */ |
| 504 | 558 | static int luasandbox_panic(lua_State * L) |
| 505 | 559 | { |
| 506 | 560 | php_error_docref(NULL TSRMLS_CC, E_ERROR, |
| — | — | @@ -509,7 +563,11 @@ |
| 510 | 564 | } |
| 511 | 565 | /* }}} */ |
| 512 | 566 | |
| 513 | | -/** {{{ luasandbox_state_from_zval */ |
| | 567 | +/** {{{ luasandbox_state_from_zval |
| | 568 | + * |
| | 569 | + * Get a lua state from a zval* containing a LuaSandbox object. If the zval* |
| | 570 | + * contains something else, bad things will happen. |
| | 571 | + */ |
| 514 | 572 | static lua_State * luasandbox_state_from_zval(zval * this_ptr TSRMLS_DC) |
| 515 | 573 | { |
| 516 | 574 | php_luasandbox_obj * intern = (php_luasandbox_obj*) |
| — | — | @@ -518,16 +576,25 @@ |
| 519 | 577 | } |
| 520 | 578 | /* }}} */ |
| 521 | 579 | |
| 522 | | -/** {{{ luasandbox_load_helper */ |
| | 580 | +/** {{{ luasandbox_load_helper |
| | 581 | + * |
| | 582 | + * Common code for LuaSandbox::loadString() and LuaSandbox::loadBinary(). The |
| | 583 | + * "binary" parameter will be 1 for loadBinary() and 0 for loadString(). |
| | 584 | + */ |
| 523 | 585 | static void luasandbox_load_helper(int binary, INTERNAL_FUNCTION_PARAMETERS) |
| 524 | 586 | { |
| 525 | 587 | char *code, *chunkName = NULL; |
| 526 | 588 | int codeLength, chunkNameLength; |
| 527 | 589 | int status; |
| 528 | | - lua_State * L = luasandbox_state_from_zval(getThis() TSRMLS_CC); |
| | 590 | + lua_State * L; |
| 529 | 591 | size_t index; |
| 530 | 592 | php_luasandboxfunction_obj * func_obj; |
| 531 | 593 | int have_mark; |
| | 594 | + php_luasandbox_obj * sandbox; |
| | 595 | + |
| | 596 | + sandbox = (php_luasandbox_obj*) |
| | 597 | + zend_object_store_get_object(this_ptr TSRMLS_CC); |
| | 598 | + L = sandbox->state; |
| 532 | 599 | |
| 533 | 600 | if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s|s", |
| 534 | 601 | &code, &codeLength, &chunkName, &chunkNameLength) == FAILURE) { |
| — | — | @@ -564,13 +631,12 @@ |
| 565 | 632 | lua_getfield(L, LUA_REGISTRYINDEX, "php_luasandbox_chunks"); |
| 566 | 633 | |
| 567 | 634 | // Get the next free index |
| 568 | | - index = lua_objlen(L, -1); |
| | 635 | + index = ++(sandbox->function_index); |
| 569 | 636 | if (index >= INT_MAX) { |
| 570 | 637 | php_error_docref(NULL TSRMLS_CC, E_WARNING, |
| 571 | 638 | "too many chunks loaded already"); |
| 572 | 639 | RETURN_FALSE; |
| 573 | 640 | } |
| 574 | | - index++; |
| 575 | 641 | |
| 576 | 642 | // Parse the string into a function on the stack |
| 577 | 643 | status = luaL_loadbuffer(L, code, codeLength, chunkName); |
| — | — | @@ -594,7 +660,15 @@ |
| 595 | 661 | } |
| 596 | 662 | /* }}} */ |
| 597 | 663 | |
| 598 | | -/** {{{ proto LuaSandboxFunction LuaSandbox::loadString(string code, string chunkName) */ |
| | 664 | +/** {{{ proto LuaSandboxFunction LuaSandbox::loadString(string code, string chunkName) |
| | 665 | + * |
| | 666 | + * Load a string into the LuaSandbox object. Returns a LuaSandboxFunction object |
| | 667 | + * which can be called or dumped. |
| | 668 | + * |
| | 669 | + * Note that global functions and variables defined in the chunk will not be |
| | 670 | + * present in the Lua state until the chunk is executed. Function definitions |
| | 671 | + * in Lua are a kind of executable statement. |
| | 672 | + */ |
| 599 | 673 | PHP_METHOD(LuaSandbox, loadString) |
| 600 | 674 | { |
| 601 | 675 | luasandbox_load_helper(0, INTERNAL_FUNCTION_PARAM_PASSTHRU); |
| — | — | @@ -602,7 +676,11 @@ |
| 603 | 677 | |
| 604 | 678 | /* }}} */ |
| 605 | 679 | |
| 606 | | -/** {{{ proto LuaSandboxFunction LuaSandbox::loadBinary(string bin, string chunkName) */ |
| | 680 | +/** {{{ proto LuaSandboxFunction LuaSandbox::loadBinary(string bin, string chunkName) |
| | 681 | + * Load a string containing a precompiled binary chunk from |
| | 682 | + * LuaSandboxFunction::dump() or the Lua compiler luac. Returns a |
| | 683 | + * LuaSandboxFunction object. |
| | 684 | + */ |
| 607 | 685 | PHP_METHOD(LuaSandbox, loadBinary) |
| 608 | 686 | { |
| 609 | 687 | luasandbox_load_helper(1, INTERNAL_FUNCTION_PARAM_PASSTHRU); |
| — | — | @@ -623,7 +701,14 @@ |
| 624 | 702 | } |
| 625 | 703 | /* }}} */ |
| 626 | 704 | |
| 627 | | -/** {{{ proto void LuaSandbox::setMemoryLimit(int limit) */ |
| | 705 | +/** {{{ proto void LuaSandbox::setMemoryLimit(int limit) |
| | 706 | + * |
| | 707 | + * Set the memory limit for the Lua state. If the memory limit is exceeded, |
| | 708 | + * the allocator will return NULL. When running protected code, this will |
| | 709 | + * result in a LuaSandboxError exception being thrown. If this occurs in |
| | 710 | + * unprotected code, say due to loading too many functions with loadString(), |
| | 711 | + * a panic will be triggered, leading to a PHP fatal error. |
| | 712 | + */ |
| 628 | 713 | PHP_METHOD(LuaSandbox, setMemoryLimit) |
| 629 | 714 | { |
| 630 | 715 | long limit; |
| — | — | @@ -641,7 +726,23 @@ |
| 642 | 727 | /* }}} */ |
| 643 | 728 | |
| 644 | 729 | |
| 645 | | -/** {{{ proto void LuaSandbox::setCPULimit(mixed normal_limit, mixed emergency_limit = false) */ |
| | 730 | +/** {{{ proto void LuaSandbox::setCPULimit(mixed normal_limit, mixed emergency_limit = false) |
| | 731 | + * |
| | 732 | + * Set the limit of CPU time (user+system) for LuaSandboxFunction::call() |
| | 733 | + * calls. There are two time limits, which are both specified in seconds. Set |
| | 734 | + * a time limit to false to disable it. |
| | 735 | + * |
| | 736 | + * When the "normal" time limit expires, a flag will be set which causes |
| | 737 | + * a LuaSandboxError exception to be thrown when the currently-running Lua |
| | 738 | + * statement finishes. |
| | 739 | + * |
| | 740 | + * When the "emergency" time limit expires, execution is terminated immediately. |
| | 741 | + * If PHP code was running, this results in the current PHP request being in an |
| | 742 | + * undefined state, so a PHP fatal error is raised. If PHP code was not |
| | 743 | + * running, the Lua state is destroyed and then recreated with an empty state. |
| | 744 | + * Any LuaSandboxFunction objects which referred to the old state will stop |
| | 745 | + * working. A LuaSandboxEmergencyTimeout exception is thrown. |
| | 746 | + */ |
| 646 | 747 | PHP_METHOD(LuaSandbox, setCPULimit) |
| 647 | 748 | { |
| 648 | 749 | zval **zpp_normal = NULL, **zpp_emergency = NULL; |
| — | — | @@ -694,7 +795,10 @@ |
| 695 | 796 | } |
| 696 | 797 | /* }}} */ |
| 697 | 798 | |
| 698 | | -/** {{{ luasandbox_set_timespec */ |
| | 799 | +/** {{{ luasandbox_set_timespec |
| | 800 | + * Initialise a timespec structure with the time in seconds given by the source |
| | 801 | + * argument. |
| | 802 | + */ |
| 699 | 803 | static void luasandbox_set_timespec(struct timespec * dest, double source) |
| 700 | 804 | { |
| 701 | 805 | double fractional, integral; |
| — | — | @@ -714,7 +818,20 @@ |
| 715 | 819 | |
| 716 | 820 | /* }}} */ |
| 717 | 821 | |
| 718 | | -/*** {{{ proto array LuaSandbox::callFunction(string name, ...) |
| | 822 | +/** {{{ proto array LuaSandbox::callFunction(string name, ...) |
| | 823 | + * |
| | 824 | + * Call a function in the global variable with the given name. The name may |
| | 825 | + * contain "." characters, in which case the function is located via recursive |
| | 826 | + * table accesses, as if the name were a Lua expression. |
| | 827 | + * |
| | 828 | + * If the variable does not exist, or is not a function, false will be returned |
| | 829 | + * and a warning issued. |
| | 830 | + * |
| | 831 | + * Any arguments specified after the name will be passed through as arguments |
| | 832 | + * to the function. |
| | 833 | + * |
| | 834 | + * For more information about calling Lua functions and the return values, see |
| | 835 | + * LuaSandboxFunction::call(). |
| 719 | 836 | */ |
| 720 | 837 | PHP_METHOD(LuaSandbox, callFunction) |
| 721 | 838 | { |
| — | — | @@ -751,6 +868,7 @@ |
| 752 | 869 | /* }}} */ |
| 753 | 870 | |
| 754 | 871 | /** {{{ luasandbox_function_init |
| | 872 | + * |
| 755 | 873 | * Common initialisation for LuaSandboxFunction methods. Initialise the |
| 756 | 874 | * function, state and sandbox pointers, and push the function to the stack. |
| 757 | 875 | */ |
| — | — | @@ -779,6 +897,19 @@ |
| 780 | 898 | /* }}} */ |
| 781 | 899 | |
| 782 | 900 | /** {{{ proto array LuaSandboxFunction::call(...) |
| | 901 | + * |
| | 902 | + * Call a LuaSandboxFunction. The arguments to this function are passed through |
| | 903 | + * to Lua. |
| | 904 | + * |
| | 905 | + * Errors considered to be the fault of the PHP code will result in the |
| | 906 | + * function returning false and E_WARNING being raised, for example, a |
| | 907 | + * resource type being used as an argument. Lua errors will result in a |
| | 908 | + * LuaSandboxError exception being thrown. |
| | 909 | + * |
| | 910 | + * Lua functions inherently return an list of results. So on success, this |
| | 911 | + * function returns an array containing all of the values returned by Lua, |
| | 912 | + * with integer keys starting from zero. Lua may return no results, in which |
| | 913 | + * case an empty array is returned. |
| 783 | 914 | */ |
| 784 | 915 | PHP_METHOD(LuaSandboxFunction, call) |
| 785 | 916 | { |
| — | — | @@ -812,6 +943,7 @@ |
| 813 | 944 | /** }}} */ |
| 814 | 945 | |
| 815 | 946 | /** {{{ luasandbox_call_helper |
| | 947 | + * |
| 816 | 948 | * Call the function at the top of the stack and then pop it. Set return_value |
| 817 | 949 | * to an array containing all the results. |
| 818 | 950 | */ |
| — | — | @@ -866,7 +998,7 @@ |
| 867 | 999 | lua_close(L); |
| 868 | 1000 | L = sandbox->state = luasandbox_newstate(sandbox); |
| 869 | 1001 | sandbox->emergency_timed_out = 0; |
| 870 | | - zend_throw_exception(luasandboxerror_ce, |
| | 1002 | + zend_throw_exception(luasandboxemergencytimeout_ce, |
| 871 | 1003 | "The maximum execution time was exceeded " |
| 872 | 1004 | "and the current Lua statement failed to return, leading to " |
| 873 | 1005 | "destruction of the Lua state", LUA_ERRRUN); |
| — | — | @@ -898,6 +1030,7 @@ |
| 899 | 1031 | /* }}} */ |
| 900 | 1032 | |
| 901 | 1033 | /** {{{ luasandbox_find_field |
| | 1034 | + * |
| 902 | 1035 | * Given a string in the format "a.b.c.d" find the relevant variable in the |
| 903 | 1036 | * table at the given stack position. If it is found, 1 is returned |
| 904 | 1037 | * and the variable will be pushed to the stack. If not, 0 is returned |
| — | — | @@ -944,6 +1077,7 @@ |
| 945 | 1078 | /* }}} */ |
| 946 | 1079 | |
| 947 | 1080 | /** {{{ luasandbox_push_zval |
| | 1081 | + * |
| 948 | 1082 | * Convert a zval to an appropriate Lua type and push the resulting value on to |
| 949 | 1083 | * the stack. |
| 950 | 1084 | */ |
| — | — | @@ -986,6 +1120,7 @@ |
| 987 | 1121 | /* }}} */ |
| 988 | 1122 | |
| 989 | 1123 | /** {{{ luasandbox_push_zval_userdata |
| | 1124 | + * |
| 990 | 1125 | * Push a full userdata on to the stack, which stores a zval* in its block. |
| 991 | 1126 | * Increment its reference count and set its metatable so that it will be freed |
| 992 | 1127 | * at the appropriate time. |
| — | — | @@ -1002,7 +1137,11 @@ |
| 1003 | 1138 | } |
| 1004 | 1139 | /* }}} */ |
| 1005 | 1140 | |
| 1006 | | -/** {{{ luasandbox_push_hashtable */ |
| | 1141 | +/** {{{ luasandbox_push_hashtable |
| | 1142 | + * |
| | 1143 | + * Helper function for luasandbox_push_zval. Create a new table on the top of |
| | 1144 | + * the stack and add the zvals in the HashTable to it. |
| | 1145 | + */ |
| 1007 | 1146 | static int luasandbox_push_hashtable(lua_State * L, HashTable * ht) |
| 1008 | 1147 | { |
| 1009 | 1148 | Bucket * p; |
| — | — | @@ -1143,7 +1282,8 @@ |
| 1144 | 1283 | } |
| 1145 | 1284 | /* }}} */ |
| 1146 | 1285 | |
| 1147 | | -/** {{{ luasandbox_lua_to_array |
| | 1286 | +/** {{{ luasandbox_lua_to_array |
| | 1287 | + * |
| 1148 | 1288 | * Append the elements of the table in the specified index to the given HashTable. |
| 1149 | 1289 | */ |
| 1150 | 1290 | static void luasandbox_lua_to_array(HashTable *ht, lua_State *L, int index, |
| — | — | @@ -1174,6 +1314,7 @@ |
| 1175 | 1315 | /* }}} */ |
| 1176 | 1316 | |
| 1177 | 1317 | /** {{{ luasandbox_get_php_obj |
| | 1318 | + * |
| 1178 | 1319 | * Get the object data for a lua state. |
| 1179 | 1320 | */ |
| 1180 | 1321 | static php_luasandbox_obj * luasandbox_get_php_obj(lua_State * L) |
| — | — | @@ -1187,9 +1328,24 @@ |
| 1188 | 1329 | } |
| 1189 | 1330 | /* }}} */ |
| 1190 | 1331 | |
| 1191 | | -/** {{{ proto void LuaSandbox::register(string libname, array functions) |
| | 1332 | +/** {{{ proto void LuaSandbox::registerLibrary(string libname, array functions) |
| | 1333 | + * |
| | 1334 | + * Register a set of PHP functions as a Lua library, so that Lua can call the |
| | 1335 | + * relevant PHP code. |
| | 1336 | + * |
| | 1337 | + * The first parameter is the name of the library. In the Lua state, the global |
| | 1338 | + * variable of this name will be set to the table of functions. |
| | 1339 | + * |
| | 1340 | + * The second parameter is an array, where each key is a function name, and |
| | 1341 | + * each value is a corresponding PHP callback. |
| | 1342 | + * |
| | 1343 | + * Both Lua and PHP allow functions to be called with any number of arguments. |
| | 1344 | + * The parameters to the Lua function will be passed through to the PHP. A |
| | 1345 | + * single value will always be returned to Lua, which is the return value from |
| | 1346 | + * the PHP function. If the PHP function does not return any value, Lua will |
| | 1347 | + * see a return value of nil. |
| 1192 | 1348 | */ |
| 1193 | | -PHP_METHOD(LuaSandbox, register) |
| | 1349 | +PHP_METHOD(LuaSandbox, registerLibrary) |
| 1194 | 1350 | { |
| 1195 | 1351 | lua_State * L = luasandbox_state_from_zval(getThis() TSRMLS_CC); |
| 1196 | 1352 | char * libname = NULL; |
| — | — | @@ -1245,6 +1401,9 @@ |
| 1246 | 1402 | /* }}} */ |
| 1247 | 1403 | |
| 1248 | 1404 | /** {{{ luasandbox_call_php |
| | 1405 | + * |
| | 1406 | + * The Lua callback for calling PHP functions. See the doc comment on |
| | 1407 | + * LuaSandbox::registerLibrary() for information about calling conventions. |
| 1249 | 1408 | */ |
| 1250 | 1409 | static int luasandbox_call_php(lua_State * L) |
| 1251 | 1410 | { |
| — | — | @@ -1316,7 +1475,12 @@ |
| 1317 | 1476 | } |
| 1318 | 1477 | /* }}} */ |
| 1319 | 1478 | |
| 1320 | | -/** {{{ string LuaSandboxFunction::dump() */ |
| | 1479 | +/** {{{ string LuaSandboxFunction::dump() |
| | 1480 | + * |
| | 1481 | + * Dump the function as a precompiled binary blob. Returns a string which may |
| | 1482 | + * later be loaded by LuaSandbox::loadBinary(), in the same or a different |
| | 1483 | + * sandbox object. |
| | 1484 | + */ |
| 1321 | 1485 | PHP_METHOD(LuaSandboxFunction, dump) |
| 1322 | 1486 | { |
| 1323 | 1487 | php_luasandboxfunction_obj * func; |
| — | — | @@ -1345,7 +1509,10 @@ |
| 1346 | 1510 | } |
| 1347 | 1511 | /* }}} */ |
| 1348 | 1512 | |
| 1349 | | -/** {{{ luasandbox_dump_writer */ |
| | 1513 | +/** {{{ luasandbox_dump_writer |
| | 1514 | + * |
| | 1515 | + * Writer function for LuaSandboxFunction::dump(). |
| | 1516 | + */ |
| 1350 | 1517 | static int luasandbox_dump_writer(lua_State * L, const void * p, size_t sz, void * ud) |
| 1351 | 1518 | { |
| 1352 | 1519 | smart_str * buf = (smart_str *)ud; |
| — | — | @@ -1355,6 +1522,7 @@ |
| 1356 | 1523 | /* }}} */ |
| 1357 | 1524 | |
| 1358 | 1525 | /** {{{ luasandbox_base_tostring |
| | 1526 | + * |
| 1359 | 1527 | * This is identical to luaB_tostring except that it does not call lua_topointer(). |
| 1360 | 1528 | */ |
| 1361 | 1529 | static int luasandbox_base_tostring(lua_State * L) |
| Index: trunk/php/luasandbox/php_luasandbox.h |
| — | — | @@ -31,7 +31,7 @@ |
| 32 | 32 | PHP_METHOD(LuaSandbox, setMemoryLimit); |
| 33 | 33 | PHP_METHOD(LuaSandbox, setCPULimit); |
| 34 | 34 | PHP_METHOD(LuaSandbox, callFunction); |
| 35 | | -PHP_METHOD(LuaSandbox, register); |
| | 35 | +PHP_METHOD(LuaSandbox, registerLibrary); |
| 36 | 36 | |
| 37 | 37 | PHP_METHOD(LuaSandboxFunction, call); |
| 38 | 38 | PHP_METHOD(LuaSandboxFunction, dump); |
| — | — | @@ -59,6 +59,7 @@ |
| 60 | 60 | int is_cpu_limited; |
| 61 | 61 | struct timespec cpu_normal_limit; |
| 62 | 62 | struct timespec cpu_emergency_limit; |
| | 63 | + int function_index; |
| 63 | 64 | }; |
| 64 | 65 | typedef struct _php_luasandbox_obj php_luasandbox_obj; |
| 65 | 66 | |