1<?php 2$_SERVER['BASE_PAGE'] = 'manual/phpfi2.php'; 3include_once __DIR__ . '/../include/prepend.inc'; 4site_header('PHP/FI Version 2.0 Documentation'); 5?> 6 7<!-- 8Documentation is like sex: when it is good, it is very, very good; and 9when it is bad, it is better than nothing. 10 ++ Dick Brandon 11--> 12 13 <h1 style="text-align: center;">PHP/FI Version 2.0</h1> 14 15 <h1>Table of Contents</h1> 16 17 <ol> 18 <li><a href="#history">Brief History</a></li> 19 20 <li><a href="#install">Installation Instructions</a></li> 21 22 <li><a href="#starting">So, what can I do with PHP/FI?</a></li> 23 24 <li><a href="#redirect">CGI Redirection</a></li> 25 26 <li><a href="#security">Security Issues</a></li> 27 28 <li><a href="#safemode">Safe Mode</a></li> 29 30 <li><a href="#commandline">Running PHP/FI from the Command 31 Line</a></li> 32 33 <li><a href="#http_auth">HTTP Authentication</a></li> 34 35 <li><a href="#requestvars">Apache Request Variables</a></li> 36 37 <li><a href="#module">Apache Module Notes</a></li> 38 39 <li><a href="#directives">Apache Module Configuration 40 Directives</a></li> 41 42 <li><a href="#fastcgi">FastCGI Support</a></li> 43 44 <li><a href="#access">Access Control</a></li> 45 46 <li><a href="#logging">Access Logging</a></li> 47 48 <li><a href="#relative">Relative vs. Absolute URL's - or, Why 49 do my Images Break?</a></li> 50 51 <li> 52 <a href="#getpost">How PHP/FI handles GET and POST method 53 data</a> 54 55 <ul> 56 <li><a href="#selmul"><code>SELECT MULTIPLE</code> and 57 PHP</a></li> 58 59 <li><a href="#imagecoord"><code>IMAGE SUBMIT</code> and 60 PHP</a></li> 61 </ul> 62 </li> 63 64 <li><a href="#gd_support">GD (a graphics library for GIF 65 creation) Support in PHP</a></li> 66 67 <li><a href="#virtual_hosts">PHP/FI and Virtual Hosts</a></li> 68 69 <li><a href="#upload">File Upload Support</a></li> 70 71 <li><a href="#cookies">Cookie Support</a></li> 72 73 <li><a href="#msql_support">mSQL Support</a></li> 74 75 <li><a href="#pg95_support">Postgres95/PostgreSQL 76 Support</a></li> 77 78 <li><a href="#mysql_support">mysql Support</a></li> 79 80 <li><a href="#solid_support">Solid Support</a></li> 81 82 <li><a href="#sybase_support">Sybase Support</a></li> 83 84 <li><a href="#oracle_support">Oracle Support</a></li> 85 86 <li><a href="#illustra_support">Illustra Support</a></li> 87 88 <li><a href="#adabas_support">Adabas Support</a></li> 89 90 <li><a href="#regexp">Regular Expressions</a></li> 91 92 <li><a href="#escapes">Escape Characters</a></li> 93 94 <li><a href="#octal">Octal notation of Unix file 95 permissions</a></li> 96 97 <li> 98 <a href="#script">PHP/FI Script Language</a> 99 100 <ul> 101 <li><a href="#syntax">Syntax</a></li> 102 103 <li><a href="#vars">Variables</a></li> 104 105 <li><a href="#assoc">Associative Arrays</a></li> 106 107 <li><a href="#varvars">Variable Variables</a></li> 108 109 <li><a href="#lang">Language Constructs</a></li> 110 111 <li><a href="#user_funcs">User-Defined Functions</a></li> 112 113 <li><a href="#scope">Scope of Variables</a></li> 114 115 <li><a href="#math">Mathematical Expressions</a></li> 116 117 <li><a href="#while">While Loops</a></li> 118 119 <li><a href="#switch">Switch Construct</a></li> 120 121 <li><a href="#secure">Secure Variables - Defeating GET 122 method hacks</a></li> 123 124 <li><a href="#overload">Overloaded Operators and dealing 125 with variable types</a></li> 126 127 <li><a href="#quiet">Suppressing Errors from function 128 calls</a></li> 129 130 <li><a href="#funcs">Internal Functions</a></li> 131 </ul> 132 </li> 133 134 <li><a href="#addfunc">Adding your own functions to 135 PHP/FI</a></li> 136 137 <li><a href="#hacknotes">Notes for Code Hacks</a></li> 138 </ol> 139 <hr> 140 141 <h2><a name="history" id="history">Brief History</a></h2> 142 143 <p>PHP began life as a simple little cgi wrapper written in Perl. 144 I wrote it in an afternoon during a period between contracts when 145 I needed a quick tool to get an idea of who was reading my online 146 resume. It was never intended to go beyond my own private use. 147 The web server where I had my resume was extremely overloaded and 148 had constant problems forking processes. I rewrote the Perl 149 wrapper in C to get rid of the considerable overhead of having to 150 fork Perl each time my resume was accessed.</p> 151 152 <p>Eventually other people on the same web server came across my 153 wrapper and asked if they could use it. Then, as inevitably 154 happens, they started asking for more features. I added more 155 features and finally put together a semi-complete distribution 156 along with documentation, a mailing-list and a FAQ. The name of 157 this first package was Personal Home Page Tools, which later 158 became Personal Home Page Construction Kit.</p> 159 160 <p>At the same time I started playing with databases and wrote a 161 tool to easily embed SQL queries into web pages. It was basically 162 another CGI wrapper that parsed SQL queries and made it easy to 163 create forms and tables based on these queries. This tool was 164 named FI (Form Interpreter).</p> 165 166 <p>PHP/FI version 2.0 is a complete rewrite of these two packages 167 combined into a single program. It has now evolved to the point 168 where it is a simple programming language embedded inside HTML 169 files. The original acronym, PHP, has stuck. It isn't really 170 appropriate any longer. PHP/FI is used more for entire web sites 171 today than for small Personal Home Page setups. By whatever name, 172 it eliminates the need for numerous small Perl cgi programs by 173 allowing you to place simple scripts directly in your HTML files. 174 This speeds up the overall performance of your web pages since 175 the overhead of forking Perl several times has been eliminated. 176 It also makes it easier to manage large web sites by placing all 177 components of a web page in a single html file. By including 178 support for various databases, it also makes it trivial to 179 develop database enabled web pages. Many people find the embedded 180 nature much easier to deal with than trying to create separate 181 HTML and CGI files.</p> 182 183 <p>PHP Version 3.0 is yet another rewrite. If you are just 184 starting out with PHP, I suggest that you start with Version 3.0 185 instead of continuing with 2.0 at this point. PHP3 is quickly 186 going to replace PHP/FI 2.0 and all development efforts are now 187 focused on PHP3. Any remaining bugs in PHP/FI 2.0 are unlikely to 188 be fixed unless they are straightforward. More information on 189 PHP3 can be found at <a href= 190 "http://www.lerdorf.on.ca/php3/">http://www.lerdorf.on.ca/php3</a>.</p> 191 192 <p>Throughout this documentation any references to PHP, FI or 193 PHP/FI all refer to the same thing. The difference between PHP 194 and FI is only a conceptual one. Both are built from the same 195 source distribution. When I build the package without any access 196 logging or access restriction support, I call my binary FI. When 197 I build with these options, I call it PHP.</p> 198 <hr> 199 200 <h2><a name="install" id="install">Installation 201 Instructions</a></h2> 202 203 <dl> 204 <dt><span class="big">Before You Begin</span></dt> 205 206 <dd> 207 <p>If you have absolutely no Unix experience, you may want to 208 ask around for someone with a little bit of Unix knowledge to 209 help you through this installation. Every attempt has been 210 made to make it as simple as possible, but since the software 211 is quite involved and relies on a number of different 212 components, it is not realistic to assume it will go smoothly 213 on all systems. You will probably need someone around who 214 knows the particulars of the destination system well.</p> 215 </dd> 216 217 <dt><span class="big">Things You Need To Know Before 218 Installing</span></dt> 219 220 <dd> 221 <p>- Can you run both get and post method cgi programs on 222 your server?<br> 223 <em>This is not relevant if you installing the Apache module 224 version.</em> If not, you can not use this package. On many 225 public ISP's CGI programs are either disallowed or severely 226 restricted. If this is the case on your system, talk to your 227 system administrator and ask him/her to have a look at this 228 package and see if they will install it for you.</p> 229 </dd> 230 231 <dd> 232 <p>- If you have mSQL installed on your system, you need to 233 know the base directory of this installation.</p> 234 </dd> 235 236 <dd> 237 <p>- If you have Postgres95 or PostgreSQL installed on your 238 system, you need to know the base directory of this 239 installation.</p> 240 </dd> 241 242 <dd> 243 <p>- If you are going to be storing log and access 244 configuration files in an NFS-mounted directory and your 245 system does not provide NFS file locking then you will need 246 to define the NFS_HACK variable manually in the src/Makefile 247 and you may want to use a slightly modified version of the 248 gdbm library. See the <strong>nfs_hack.txt</strong> file in 249 the doc directory for more information on this.</p> 250 </dd> 251 252 <dd> 253 <p>- Note that if you are not interested in using PHP to 254 track accesses to your pages, do not compile this option into 255 the binary. You should also leave out the access restriction 256 code. There is considerable overhead in including these 257 options.</p> 258 </dd> 259 260 <dd> 261 <p>- If you are installing the Apache module version, you 262 will need to know the Apache src code directory location.</p> 263 </dd> 264 265 <dt><span class="big">Installation Steps</span></dt> 266 267 <dd> 268 <p><em><strong>Step 1.</strong></em></p> 269 270 <p>Run the install program: <code>./install</code></p> 271 272 <p>You will be asked a number of questions. If you do not 273 understand what is being asked, simply hit return. The 274 default choice should be safe on most systems. This doesn't 275 apply for the questions asking you to specify a directory for 276 your configuration and log files however. Choose any 277 directory to which the httpd (usually "nobody") has write 278 privileges. You may create this directory manually somewhere 279 and simply <strong><code>chown nobody 280 directory</code></strong>.</p> 281 282 <p><em><strong>Step 2.</strong></em></p> 283 284 <p>Go into the src directory: <code>cd src</code></p> 285 286 <p>Have a look at the php.h file. There are a number of 287 compile-time options that can be set here.</p> 288 289 <p><em><strong>Step 3.</strong></em></p> 290 291 <p>type: <code>make</code></p> 292 293 <p>This will create the actual executable program file named 294 <em>php.cgi</em> by default, or if you are installing the 295 Apache module, it will create a <em>libphp.a</em> file.</p> 296 297 <p><em><strong>Step 4. (if you are not installing the Apache 298 module version)</strong></em></p> 299 300 <p>Copy the <strong>php.cgi</strong> binary to your system's 301 cgi-bin directory. If you do not have access to do this and 302 wish to install it in your own personal directory, you may do 303 so, but you should set the setuid bit on the executable with: 304 <code>chmod u+s /path/php.cgi</code></p> 305 306 <p>If you do not make set the setuid bit on the binary then 307 any files created by the binary will be owned by the user id 308 under which the web server runs. If this is acceptable, then 309 you can safely leave the setuid bit off.</p> 310 311 <p><em><strong>Step 4. (if you are installing the Apache 312 module version)</strong></em><br> 313 Change to your Apache src directory where the 314 <em>mod_php.c</em> and <em>mod_php.h</em> files should have 315 been copied to. If they weren't which usually happens because 316 of permission problems, copy these two files there manually. 317 Edit your Apache Configuration file and add the EXTRA_LIBS 318 line which was produced at the end of <strong>Step 319 3</strong>. And add:</p> 320 321 <p><code><strong>Module php_module mod_php.o</strong></code></p> 322 323 <p>to the very end of the file. Then type: 324 <strong>./Configure</strong> and then <strong>make</strong> 325 to rebuild your Apache httpd binary. Install this binary.</p> 326 327 <p>Next you need to edit your Apache conf/srm.conf file and 328 add a line like:</p> 329 330 <p><code><strong>AddType application/x-httpd-php 331 .phtml</strong></code></p> 332 333 <p>This defines a new MIME, application/x-httpd-php, which 334 will trigger the PHP module to parse any file ending with the 335 <em>.phtml</em> extension. You can pick any extension you 336 like for this.</p> 337 338 <p>You may not want to enable everyone to run PHP parsed 339 files. You can place the above AddType line within 340 <Location /path>....</Location> directives in the 341 <em>access.conf</em> file to only allow PHP-parsed documents 342 in certain directories on your server.</p> 343 344 <p>Now you are ready to restart your httpd server. See the 345 <a href="#module">Apache Module Notes</a> for more details on 346 configuring the PHP Module.</p> 347 </dd> 348 349 <dt><span class="big">Testing the software</span></dt> 350 351 <dd> 352 <p>Once installed you can test to see if your executable 353 works by entering a URL similar to the following in your 354 browser:</p> 355 356 <p><code>http://your.site.domain/cgi-bin/php.cgi</code></p> 357 358 <p>This should show you a page which contains the version 359 number along with various other useful information.</p> 360 361 <p>To test the Apache module version, create any file with a 362 .phtml extension and put a tag like: <?phpinfo()> in 363 the file and see if it gets parsed.</p> 364 </dd> 365 366 <dt><span class="big">Using the software</span></dt> 367 368 <dd> 369 <p>To actually use the software on an existing HTML file, you 370 can simply append the path to your file to the above URL. 371 ie.</p> 372 373 <p> 374 <code>http://your.site.domain/cgi-bin/php.cgi/path/file.html</code></p> 375 376 <p>You should have a look at the <a href="#redirect">CGI 377 Redirection</a> section of this documentation. Running PHP/FI 378 through a redirect means you can automatically have a URL 379 like <em>http://your.site.domain/file.phtml</em> be parsed by 380 PHP/FI.</p> 381 382 <p>This does not apply to Apace module users.</p> 383 </dd> 384 </dl> 385 <hr> 386 387 <h2><a name="starting" id="starting">So, what can I do with 388 PHP/FI?</a></h2> 389 390 <p>The first thing you will notice if you run a page through 391 PHP/FI is that it adds a footer with information about the number 392 of times your page has been accessed (if you have compiled access 393 logging into the binary). This is just a very small part of what 394 PHP/FI can do for you. It serves another very important role as a 395 form interpreter cgi, hence the FI part of the name. For example, 396 if you create a form on one of your web pages, you need something 397 to process the information on that form. Even if you just want to 398 pass the information to another web page, you will have to have a 399 cgi program do this for you. PHP/FI makes it extremely easy to 400 take form data and do things with it.</p> 401 402 <p><em><strong>A simple example</strong></em></p> 403 404 <p>Suppose you have a form:</p> 405 406 <p><code><FORM ACTION="/cgi-bin/php.cgi/~userid/display.html" 407 METHOD=POST><br> 408 <INPUT TYPE="text" name="name"><br> 409 <INPUT TYPE="text" name="age"><br> 410 <INPUT TYPE="submit"><br> 411 </FORM></code></p> 412 413 <p>Your display.html file could then contain something like:</p> 414 415 <p><code><?echo "Hi $name, you are $age years 416 old!<p>"></code></p> 417 418 <p>It's that simple! PHP/FI automatically creates a variable for 419 each form input field in your form. You can then use these 420 variables in the ACTION URL file.</p> 421 422 <p>The next step once you have figured out how to use variables 423 is to start playing with some logical flow tags in your pages. 424 For example, if you wanted to display different messages based on 425 something the user inputs, you would use if/else logic. In our 426 above example, we can display different things based on the age 427 the user entered by changing our display.html to:</p> 428 <pre> 429<? 430 if($age>50); 431 echo "Hi $name, you are ancient!<p>"; 432 elseif($age>30); 433 echo "Hi $name, you are very old!<p>"; 434 else; 435 echo "Hi $name."; 436 endif; 437> 438</pre> 439 440 <p>PHP/FI provides a very powerful scripting language which will 441 do much more than what the above simple example demonstrates. See 442 the section on the <a href="#script">PHP/FI Script Language</a> 443 for more information.</p> 444 445 <p>You can also use PHP/FI to configure who is allowed to access 446 your pages. This is done using a built-in configuration screen. 447 With this you could for example specify that only people from 448 certain domains would be allowed to see your pages, or you could 449 create a rule which would password protect certain pages. See the 450 <a href="#access">Access Control</a> section for more 451 details.</p> 452 453 <p>PHP/FI is also capable of receiving file uploads from any 454 RFC-1867 compliant web browser. This feature lets people upload 455 both text and binary files. With PHP/FI's access control and 456 logical functions, you have full control over who is allowed to 457 upload and what is to be done with the file once it has been 458 uploaded. See the <a href="#upload">File Upload</a> section for 459 more details.</p> 460 461 <p>PHP/FI has support for a database package called mSQL. This 462 allows you to put information into a database and access this 463 information through simple embedded SQL queries right in your 464 .HTML files. Adding a database back-end to a web page has never 465 been easier. See the section on <a href="#msql_support">mSQL 466 Support</a> for more information.</p> 467 468 <p>PHP/FI has support for the Postgres95/PostgreSQL database 469 package. It supports embedded SQL queries in your .HTML files. 470 See the section on <a href="#pg95_support">Postgres95/PostgreSQL 471 Support</a> for more information.</p> 472 473 <p>PHP/FI also has support for the mysql database package. It 474 supports embedded SQL queries in your .HTML files. See the 475 section on <a href="#mysql_support">mysql Support</a> for more 476 information.</p> 477 <hr> 478 479 <h2><a name="redirect" id="redirect">CGI Redirection</a></h2> 480 481 <dl> 482 <dt><strong>Apache 1.0.x Notes</strong></dt> 483 484 <dd> 485 <p>A good way to run PHP/FI is by using a cgi redirection 486 module with the Apache server. Please note that you do not 487 need to worry about redirection modules if you are using the 488 Apache module version of PHP/FI. There are two of these 489 redirection modules available. One is developed by Dave 490 Andersen <angio@aros.net> and it is available at 491 <a href= 492 "ftp://ftp.aros.net/pub/util/apache/mod_cgi_redirect.c">ftp://ftp.aros.net/pub/util/apache/mod_cgi_redirect.c</a> 493 and the other comes bundled with Apache and is called 494 mod_actions.c. The modules are extremely similar. They differ 495 slightly in their usage. Both have been tested and both work 496 with PHP/FI.</p> 497 498 <p>One large caveat at the time of this writing (Apr.20/96) 499 is that the current official Apache release (1.0.5) has a 500 severe limitation which prevents cgi redirected requests from 501 having any post-method data associated with them. I have 502 tracked this down and fixed it in my version of Apache, and 503 there is an official patch available in the <a href= 504 "http://php.iquest.net/files/">File Archives</a> on the 505 <a href="http://php.iquest.net/">PHP Home Page</a>.</p> 506 507 <p>A second rather large caveat with Apache 1.0.x is that it 508 does not align double types correctly on most architectures. 509 You may find yourself getting strange bus errors from your 510 httpd when using mod_php, either upgrade to Apache 1.1 or 511 edit the <i>alloc.c</i> Apache source file. In this file you 512 will find the following piece of code:</p> 513 <pre> 514 union align 515 { 516 /* Types which are likely to have the longest RELEVANT alignment 517 * restrictions... we don't do much with doubles. 518 */ 519 520 char *cp; 521 void (*f)(); 522 long l; 523 FILE *fp; 524 }; 525</pre> 526 527 <p>You will need to add a double to this line and recompile 528 your Apache server. The correct block of code is:</p> 529 <pre> 530 union align 531 { 532 /* Types which are likely to have the longest RELEVANT alignment 533 * restrictions... we don't do much with doubles. 534 */ 535 536 char *cp; 537 void (*f)(); 538 long l; 539 FILE *fp; 540 double d; 541 }; 542</pre> 543 544 <p>These problems have all been fixed in later versions of 545 Apache.</p> 546 547 <p>Check the Apache documentation on how to add a module. 548 Generally you add the module name to a file called 549 <em>Configuration</em>. The line to be added if you want to 550 use the mod_actions module is:</p> 551 552 <p><code>Module action_module mod_actions.o</code></p> 553 554 <p>If you are using the mod_cgi_redirect.c module add this 555 line:</p> 556 557 <p><code>Module cgi_redirect_module mod_cgi_redirect.o</code></p> 558 559 <p>Then compile your httpd and install it. To configure the 560 cgi redirection you need to either create a new mime type in 561 your <em>mime.types</em> file or you can use the 562 <strong>AddType</strong> command in your <em>srm.conf</em> 563 file to add the mime type. The mime type to be added should 564 be something like this:</p> 565 566 <p><code>application/x-httpd-php phtml</code></p> 567 568 <p>If you are using the mod_actions.c module you need to add 569 the following line to your <em>srm.conf</em> file:</p> 570 571 <p><code>Action application/x-httpd-php 572 /cgi-bin/php.cgi</code></p> 573 574 <p>If you are using mod_cgi_redirect.c you should add this 575 line to <em>srm.conf</em>:</p> 576 577 <p><code>CgiRedirect application/x-httpd-php 578 /cgi-bin/php.cgi</code></p> 579 580 <p>Don't try to use both mod_actions.c and mod_cgi_redirect.c 581 at the same time.</p> 582 583 <p>Once you have one of these cgi redirection modules 584 installed and configured correctly, you will be able to 585 specify that you want a file parsed by php/fi simply by 586 making the file's extension <strong>.phtml</strong>. 587 Furthermore, if you add <strong>index.phtml</strong> to your 588 <strong>DirectoryIndex</strong> configuration line in your 589 <em>srm.conf</em> file then the top-level page in a directory 590 will be automatically parsed by php if your index file is 591 called index.phtml.</p> 592 </dd> 593 594 <dt><strong>Netscape HTTPD</strong></dt> 595 596 <dd> 597 <p>You can automatically redirect requests for files with a 598 given extension to be handled by PHP/FI by using the Netscape 599 Server CGI Redirection module. This module is available in 600 the <a href="http://php.iquest.net/files/">File Archives</a> 601 on the <a href="http://php.iquest.net/">PHP/FI Home Page</a>. 602 The README in the package explicitly explains how to 603 configure it for use with PHP/FI.</p> 604 </dd> 605 606 <dt><strong>NCSA HTTPD</strong></dt> 607 608 <dd> 609 <p>NCSA does not currently support modules, so in order to do 610 cgi redirection with this server you need to modify your 611 server source code. A patch to do this with NCSA 1.5 is 612 available in the <a href= 613 "http://php.iquest.net/files/">PHP/FI file archives</a>.</p> 614 </dd> 615 </dl> 616 <hr> 617 618 <h2><a name="security" id="security">Security Issues</a></h2> 619 620 <p>The CGI version of PHP/FI does <strong>not</strong> read any 621 <em>.htaccess</em> files which may be present in a directory. 622 This means that if you have files that are protected using the 623 standard .htaccess server-based access control feature, people 624 could potentially circumvent this security by loading the page 625 through PHP/FI. Note that this is not an issue for the Apache 626 module version of PHP/FI.</p> 627 628 <p>A second problem with the CGI version is that if it is placed 629 in the system's cgi-bin directory it can be used to view any file 630 on your system as long as the user id it runs as has access to 631 it.</p> 632 633 <p>There are a couple of different solutions to this problem. The 634 easiest is probably to use the <strong>PATTERN_RESTRICT</strong> 635 feature found in <em>php.h</em>. This lets you define an 636 extension (or a pattern of extensions) which are allowed to be 637 parsed by PHP/FI. If a file does not have this extension and 638 someone tries to load it with PHP/FI, an <em>access denied</em> 639 message will appear.</p> 640 641 <p>Another solution is to use the PHP/FI access control mechanism 642 to mimic the access control setup you have in your .htaccess 643 file. Keeping this information in two places can be tedious 644 though, and the two systems don't share all of the same 645 features.</p> 646 647 <p>The problem can also be solved using file permissions. PHP/FI 648 can be set up to run setuid as any user you wish. Then files that 649 are to be read by PHP/FI can be given appropriate permissions and 650 files not to be read by PHP/FI should be owned by another user id 651 and have their permissions changed accordingly.</p> 652 653 <p>For additional security options related to sites which provide 654 shared access to PHP, see the <a href="#safemode">Safe Mode</a> 655 section.</p> 656 <hr> 657 658 <h2><a name="safemode" id="safemode">Safe Mode</a></h2> 659 660 <p>PHP's Safe Mode tries to solve the common problem faced by 661 many ISP's regarding letting all their users run CGI programs. 662 The common mechanism for making shared CGI access more secure is 663 to use a cgi wrapper like the su_exec utility that comes with 664 Apache. This will not work for PHP when it is running as a module 665 because it is not a separate process that can be setuid'ed.</p> 666 667 <p>It is based on a file permission scheme. Simply put, if a file 668 is either owned by the same user id as the script that is trying 669 to access it, or if the file is in a directory that is owned by 670 the same user as the script that is trying to access it, then the 671 access is allowed. One caveat here is that you must make sure 672 that your OS does not allow non-root user to chown away the 673 ownership on one of their files. Many older SysV systems allow 674 this. The most common one is Irix. It is possible to change this 675 behaviour at the OS level on Irix.</p> 676 677 <p>Safe Mode applies to each function which could possibly be a 678 security risk. Below is the current list of checks applied to 679 each relevant function. In the following list, PHP UID refers to 680 the user id of the owner of the current file being parsed by PHP, 681 and HTTP UID refers to the user id the httpd process is running 682 as (usually nobody).</p> 683 684 <dl> 685 <dt>Include, ReadFile, Fopen, File, Link, Unlink, Symlink, 686 Rename, RmDir, ChMod, ChOwn, ChGrp</dt> 687 688 <dd>Owner of file to be included must either be the PHP UID or 689 the directory in which the file resides must be owned by the 690 PHP UID.</dd> 691 692 <dt>Exec, System, PassThru and Popen</dt> 693 694 <dd>Executables to be forked and executed must reside in the 695 directory defined by the PHP_SAFE_MODE_EXEC_DIR #define in 696 php.h when PHP is compiled.</dd> 697 698 <dt>Mysql_Connect</dt> 699 700 <dd>This function takes an optional username to use to connect 701 to an MySQL database. When in safe mode, this username must 702 either be the username of the owner of the current file being 703 parsed, or the name of the httpd user (usually nobody).</dd> 704 705 <dt>HTTP Authentication</dt> 706 707 <dd>The numerical user id of the owner of the script containing 708 the HTTP Authentication code will be prepended to the 709 authentication realm. This is to prevent someone from writing a 710 password grabbing script which spoofs another authenticated 711 page on the same server.</dd> 712 </dl> 713 <hr> 714 715 <h2><a name="commandline" id="commandline">Running PHP/FI from 716 the command line</a></h2> 717 718 <p>If you build the CGI version of PHP/FI, you can use it from 719 the command line simply typing: <code>php.cgi filename</code> where 720 filename is the file you want to parse. You can also create 721 standalone PHP/FI scripts by making the first line of your script 722 look something like:</p> 723 <pre> 724 #!/usr/local/bin/php.cgi -q 725</pre>The "-q" suppresses the printing of the HTTP headers. You can 726leave off this option if you like. 727 <hr> 728 729 <h2><a name="http_auth" id="http_auth">HTTP 730 Authentication</a></h2> 731 732 <p>The HTTP Authentication hooks in PHP/FI are only available 733 when it is running as an Apache module. In an Apache module 734 PHP/FI script, it is possible to use the Header() command to send 735 an "Authentication Required" message to the client browser 736 causing it to pop up a Username/Password input window. Once the 737 user has filled in a username and a password, the URL containing 738 the PHP/FI script will be called again with the variables, 739 $PHP_AUTH_USER, $PHP_AUTH_PW and $PHP_AUTH_TYPE set to the user 740 name, password and authentication type respectively. Only "Basic" 741 authentication is supported at this point.</p> 742 743 <p>An example script fragment which would force client 744 authentication on a page would be the following:</p> 745 <pre> 746 <? 747 if(!$PHP_AUTH_USER) { 748 Header("WWW-authenticate: basic realm=\"My Realm\""); 749 Header("HTTP/1.0 401 Unauthorized"); 750 echo "Text to send if user hits Cancel button\n" 751 exit; 752 } else { 753 echo "Hello $PHP_AUTH_USER.<P>"; 754 echo "You entered $PHP_AUTH_PW as your password.<P>"; 755 } 756 > 757</pre> 758 759 <p>Instead of simply printing out the $PHP_AUTH_USER and 760 $PHP_AUTH_PW, you would probably want to check the username and 761 password for validity. Perhaps by sending a query to a database, 762 or by looking up the user in a dbm file.</p> 763 764 <p>Watch out for buggy Internet Explorer browsers out there. They 765 seem very picky about the order of the headers. Sending the 766 <b>WWW-authenticate</b> header before the <b>HTTP/1.0 401</b> 767 header seems to do the trick for now.</p> 768 769 <p>In order to prevent someone from writing a script which 770 reveals the password for a page that was authenticated through a 771 traditional external mechanism, the PHP_AUTH variables will not 772 be set if external authentication is enabled for that particular 773 page.</p> 774 775 <p>Note however that the above does not prevent someone who 776 controls a non-authenticated URL from stealing passwords from 777 authenticated URL's on the same server. The PHP_AUTH_VARS define 778 in <em>php.h</em> can be undefined to make sure that these 779 variables will never be set and thus disable anybody from using 780 mod_php to try to steal passwords.</p> 781 <hr> 782 783 <h2><a name="requestvars" id="requestvars">Apache Request 784 Variables</a></h2> 785 786 <p>When running PHP as an Apache module, you may access the 787 request header variables sent by the remote browser by prepending 788 <b>$req_</b> to the beginning of the header value you would like 789 to use. If the request name contains a <b>-</b> character such as 790 User-Agent, then you need to map the - to _ (an underscore). ie. 791 reference it as $req_User_Agent. The <a href= 792 "#phpinfo">phpinfo()</a> function can be used to display all the 793 request headers.</p> 794 795 <p>eg.</p> 796 <pre> 797 < 798 echo "$req_connection<br>"; 799 echo "$req_host<br>"; 800 > 801</pre>The above simple script might output: 802 <pre> 803 Keep-Alive 804 www.host.com 805</pre> 806 <hr> 807 808 <h2><a name="module" id="module">Apache Module Notes</a></h2> 809 810 <p>Running PHP/FI as an Apache module is the most efficient way 811 of using the package. Running it as a module means that the 812 PHP/FI functionality is combined with the Apache server's 813 functionality in a single program. There are a number of 814 advantages to running it as a module:</p> 815 816 <dl> 817 <dt><strong>Performance</strong></dt> 818 819 <dd> 820 <p>Performance-wise it is a lot faster than traditional CGI 821 programs. In fact, when running PHP/FI as a module, there is 822 no CGI involved. The script code in the HTML files is 823 executed directly by the Apache web server process.</p> 824 </dd> 825 826 <dt><strong>Security</strong></dt> 827 828 <dd> 829 <p>When running as a module, the normal httpd-based access 830 restriction rules defined either in the Apache conf files or 831 in private .htaccess files are first applied before the 832 module is allowed to parse the file. Alternatively, you can 833 also create PHP/FI scripts that control the normal 834 httpd-based authentication. See <a href="#http_auth">HTTP 835 Authentication</a>.</p> 836 </dd> 837 838 <dt><strong>Configurability</strong></dt> 839 840 <dd> 841 <p>Since the parser is always active inside the httpd 842 process, it can be configured on startup using the same 843 configuration files used to configure the httpd process. The 844 module can even be configured on a per-directory basis by 845 placing the <a href="#directives">PHP configuration 846 directives</a> in the <em>.htaccess</em> files.</p> 847 </dd> 848 849 <dt><strong>Basis for custom server-based 850 function</strong></dt> 851 852 <dd> 853 <p>For C programmers interested in accessing their functions 854 from within Apache, the PHP/FI framework provides a very 855 simple interface to Apache and to PHP itself. It is much 856 easier to add a function to PHP and call that from a parsed 857 page than it is to write an entire Apache module from 858 scratch. See the <a href="#addfunc">Adding your own internal 859 functions to PHP/FI</a> sections at the end of this document 860 for further details.</p> 861 </dd> 862 </dl> 863 864 <h2><a name="directives" id="directives">Apache Module 865 Configuration Directives</a></h2> 866 867 <p>The following directives can be placed either in the 868 <em>srm.conf</em> file, or within 869 <Directory>...</Directory> tags in 870 <em>access.conf</em> or in <Location 871 /path>...</Location> tags in <em>access.conf</em> or in 872 individual <em>.htaccess</em> files. In order for the directives 873 to work in .htaccess files, the Options override must be set on 874 the AllowOverride Apache directive, with the exception of the 875 phpEngine directive which is only available in the *.conf 876 files.</p> 877 878 <dl> 879 <dt><strong>phpShowInfo <em>on</em>|<em>off</em></strong></dt> 880 881 <dd>Turn the PHP info footers on or off. Default is on.</dd> 882 883 <dt><strong>phpLogging <em>on</em>|<em>off</em></strong></dt> 884 885 <dd>Turn logging on or off. Default is on.</dd> 886 887 <dt><strong>phpDebug <em>on</em>|<em>off</em></strong></dt> 888 889 <dd>Turn automatic ?info debug screen on or off. Default is 890 off.</dd> 891 892 <dt><strong>phpUploadTmpDir <em>directory</em></strong></dt> 893 894 <dd>Set the directory where form-uploaded files will be 895 placed.</dd> 896 897 <dt><strong>phpDbmLogDir <em>directory</em></strong></dt> 898 899 <dd>Set the directory where dbm-based logging files will be 900 written.</dd> 901 902 <dt><strong>phpSQLLogDB <em>database</em></strong></dt> 903 904 <dd>Set name of SQL database to use for logging. Default is 905 "phpfi"</dd> 906 907 <dt><strong>phpSQLLogHost <em>hostname</em></strong></dt> 908 909 <dd>Set hostname where SQL database to use for logging is 910 found. Default is localhost.</dd> 911 912 <dt><strong>phpAccessDir <em>directory</em></strong></dt> 913 914 <dd>Set the directory where PHP-internal access control files 915 are stored.</dd> 916 917 <dt><strong>phpMaxDataSpace <em>KiloBytes</em></strong></dt> 918 919 <dd>Max size a sub-pool can grow to within the PHP module. 920 Setting this value to a low number will minimize the impact 921 that mod_php will have on your system, but it may also limit 922 people from writing complex scripts. The default is 8K.</dd> 923 924 <dt><strong>phpIncludePath <em>colon-separated 925 path</em></strong></dt> 926 927 <dd>A colon-separated list of directories where php will look 928 for files in when running <a href="#include">include()</a>. The 929 default is to look only in the current directory.</dd> 930 931 <dt><strong>phpAutoPrependFile <em>file name</em></strong></dt> 932 933 <dd>Before the actual PHP/FI file is parsed, you may give a 934 file name here that is parsed before the "main file", using 935 PHP's Include() function (which means phpIncludePath applies 936 for the file name). Keep in mind that you can make it difficult 937 for yourself to use the Header() function in the main file if 938 you write HTML from an auto-prepended file.</dd> 939 940 <dt><strong>phpAutoAppendFile <em>file name</em></strong></dt> 941 942 <dd>The name of a file parsed (using PHP's Include() 943 function)after the actual PHP/FI file has been parsed, similar 944 to phpAutoPrependFile.</dd> 945 946 <dt><strong>phpAdaDefDB <em>database</em></strong></dt> 947 948 <dd>Default Adabas database to use. No default value</dd> 949 950 <dt><strong>phpAdaUser <em>username</em></strong></dt> 951 952 <dd>Default Adabas database user. No default value</dd> 953 954 <dt><strong>phpAdaPW <em>password</em></strong></dt> 955 956 <dd>Default Adabas database password. No default value</dd> 957 958 <dt><strong>phpEngine <em>on</em>|<em>off</em></strong></dt> 959 960 <dd>Turn the PHP parsing engine on or off. The default is 961 <em>on</em> and this directive is only useful for sites that 962 wish to allow directives from the AllowOverride Options list of 963 directives to function in .htaccess files while at the same 964 time restricting mod_php access. The common way to handle 965 per-virtual host php installs is to enable the PHP mime type 966 with an AddType directive on a per virtual host basis and then 967 put "phpEngine off" in the non-PHP virtual host blocks. If a 968 non PHP customer tries to circumvent things by placing the PHP 969 mime type in their .htaccess, the phpEngine off setting 970 restricts the PHP parser from functioning.</dd> 971 972 <dt><strong>phpLastModified 973 <em>on</em>|<em>off</em></strong></dt> 974 975 <dd>Since php pages are dynamic, they are processed and sent to 976 the browser each time you access them. But sometimes, when you 977 use php for basic includes, the parsed page does not change as 978 long as the source doesn't. It that case, you may want to avoid 979 page regeneration/reloading. If phpLastModified is turned on 980 Apache will send the Last-Modified tag to the browser, so that 981 the page will only be reloaded when it changes. (not that if 982 you are using page logging, multiple accesses will not be 983 logged!)</dd> 984 </dl> 985 986 <p>All of these directives are optional. If a directive is not 987 specified anywhere, the compile-time default will be used.</p> 988 <hr> 989 990 <h2><a name="fastcgi" id="fastcgi">FastCGI Support</a></h2> 991 992 <p>PHP/FI can be compiled with FastCGI support. You will need 993 fetch and compile <a href="http://www.fastcgi.com">FCGI 994 Development Kit</a> for your platform before compiling PHP/FI. 995 You will also need to get <a href="#redirect">CGI Redirection</a> 996 working. Then follow the instructions in the FastCGI 997 documentation for configuring FastCGI for your platform. If you 998 are using the mod_fastcgi module with the Apache server, here are 999 the step-by-step instructions:</p> 1000 1001 <ul> 1002 <li>Edit your Apache Configuration file and add the mod_fastcgi 1003 module, then recompile Apache.</li> 1004 1005 <li>Edit your <em>srm.conf</em> file and add lines similar 1006 to:<br> 1007 <code>AddType application/x-httpd-fcgi .fcgi<br> 1008 AppClass /usr/local/etc/httpd/fcgi-bin/php.fcgi -processes 1009 4<br> 1010 AddType application/x-httpd-fphp .fhtml<br> 1011 Action application/x-httpd-fphp 1012 /fcgi-bin/php.fcgi<br></code></li> 1013 1014 <li>Copy your <em>php.cgi</em> binary to 1015 <em>/usr/local/etc/httpd/fcgi-bin/php.fcgi</em></li> 1016 </ul> 1017 1018 <p>Now, any pages with the .fhtml extension will be handed off to 1019 the FastCGI php.fcgi process which is already running. The 1020 php.fcgi binary will still work as a normal CGI binary, so you 1021 could just create a symbolic link from php.cgi to php.fcgi.</p> 1022 1023 <p>If you are not using Apache, the above steps will be similar, 1024 but not identical. CGI Redirection mechanisms are available for 1025 NCSA and Netscape servers at the <a href= 1026 "http://php.iquest.net/files/">PHP/FI File Archive</a>.</p> 1027 <hr> 1028 1029 <h2><a name="access" id="access">Access Control</a></h2> 1030 1031 <p>Note that the built-in PHP/FI based access control is likely 1032 to be discontinued in future versions. You should seriously 1033 consider using the security mechanism that comes with your web 1034 server instead.</p> 1035 1036 <p>If you chose to include access control when you compiled the 1037 package, you may append <em>?config</em> to any URL to edit the 1038 access control file. ie.</p> 1039 1040 <p> 1041 <code>http://your.machine.domain/cgi-bin/php.cgi/path/file.html?config</code></p> 1042 1043 <p>Your configuration password will initially be set to your user 1044 id. If your user id does not work as your password, it probably 1045 means that PHP could not read the /etc/passwd file to locate your 1046 user id. If this is the case, the initial password will be set to 1047 "<strong>php</strong>". It is a good idea to change this 1048 password. Note that multiple users may maintain their own 1049 personal configuration files through a single PHP/FI binary.</p> 1050 1051 <p>Access Control can be quite confusing initially. The ?config 1052 screen is divided up into a number of sections. The top section 1053 is for changing the password used to make sure that only people 1054 who know this password can change access control characteristics. 1055 In a system-wide installation, each user has his or her own 1056 configuration screen with his or her own password.</p> 1057 1058 <p>The second section of the ?config screen consists of a number 1059 of tables. Each table defines a rule-set. The first rule-set is 1060 always the default rule-set. This default rule-set is used if a 1061 page does not have a rule-set defined specifically for it. After 1062 the default rule-set, any number of specific rule-set tables will 1063 follow.</p> 1064 1065 <p>To add a rule-set for a specific file, enter the URL of the 1066 file in your browser and add <em><strong>?config</strong></em> to 1067 the end of the URL. On the ?config screen that comes up you will 1068 see that a rule-set has been added for this page, if it wasn't 1069 already there. When a new rule-set is added, it is initially set 1070 to be the same as the default rule-set. The following picture 1071 shows two simple rule-sets. First a default rule-set which just 1072 indicates that hits from all domains should be logged, and 1073 second, for the file /~rasmus/test.html and only that file, any 1074 users coming from a "<em>.edu</em>" domain will not be granted 1075 access.</p> 1076 1077 <p><img src="gifs/config.gif" alt="[Image of ?config screen]"></p> 1078 1079 <p>To edit a rule-set modify the fields until the desired 1080 configuration is reached within a rule-set and then hit the 1081 "<em>Submit Changes</em>" button. If more rules are needed, hit 1082 the "<em>Add Rule</em>" button and then edit the added rule.</p> 1083 1084 <p>To delete a rule, select the checkbox to the right of the rule 1085 and hit the "<em>Submit Changes</em>" button. The screen will 1086 redraw and the rule should disappear.</p> 1087 1088 <p>Note that you need to enter a regular expression in the 1089 pattern field. See the section on regular expressions in this 1090 documentation for more details.</p> 1091 <hr> 1092 1093 <h2><a name="logging" id="logging">Access Logging</a></h2> 1094 1095 <p>Access Logging is another optional feature which can be 1096 enabled at compile-time by answering <em>Yes</em> to the question 1097 in the install script. You may either store your access log data 1098 in dbm files, in an mSQL database, or in an mysql database. The 1099 latter two are more powerful, but is also a bit more difficult to 1100 set up.</p> 1101 1102 <p>To use dbm files for storing your access logs, you will need 1103 to specify a directory in which log files can be written. PHP 1104 will try to create this directory if it doesn't exist, but to 1105 make sure it has the proper permissions, you may want to create 1106 this directory yourself before running PHP for the first time. 1107 The permissions on the directory should be such that the user id 1108 under which the PHP cgi program will run can write to the 1109 directory.</p> 1110 1111 <p>To use an mSQL or mysql database for storing your access log 1112 data, you need to first make sure you have mSQL or mysql 1113 installed and running on your system. Then you need to create a 1114 database. The default name is "phpfi" although this can be 1115 changed in <em>src/php.h</em>. To create this database for mSQL, 1116 type:</p> 1117 <pre> 1118 msqladmin create phpfi 1119</pre> 1120 1121 <p>or for mysql type:</p> 1122 <pre> 1123 mysqladmin create phpfi 1124</pre> 1125 1126 <p>Then for mSQL, edit your <em>msql.acl</em> file and make sure 1127 the permissions on the database are correct. Something like the 1128 following should suffice:</p> 1129 <pre> 1130 database=phpfi 1131 read=* 1132 write=nobody,<your user id> 1133 access=local 1134</pre> 1135 1136 <p>For mysql, you need to make sure the httpd user (usually 1137 "nobody") has access to the database. Unlike mSQL, mysql stores 1138 access control data in a database. Assuming default permissions, 1139 you should be able to simply execute the following command:</p> 1140 <pre> 1141 echo "INSERT INTO user VALUES ('localhost','nobody','','Y','Y','Y','Y','Y','Y','Y','Y','Y');" | mysql mysql 1142</pre> 1143 1144 <p>Don't forget to load this new configuration with:</p> 1145 <pre> 1146 mysqladmin reload 1147</pre> 1148 1149 <p>For each user id for whom you want to store log data, you need 1150 to create two tables. The <em>msqllog</em> shell script in the 1151 scripts directory will do this for you. Simply type:</p> 1152 <pre> 1153 msqllog <user id> 1154</pre> 1155 1156 <p>or for mysql, type:</p> 1157 <pre> 1158 mysqllog <user id> 1159</pre> 1160 1161 <p>and the script will create the appropriate tables. You may 1162 need to edit the script to make it reflect where things are 1163 stored on your system.</p> 1164 1165 <p>You may want to have a look at this script. It defines the 1166 field sizes of your log tables. If, for example, you know that 1167 your file paths exceed 64 characters, you need to bump up the 1168 filename size in both the <em>logN</em> and the <em>lastN</em> 1169 tables in this <em>msqllog</em> or <em>mysqllog</em> file.</p> 1170 1171 <p>Access logging stores information about each "hit" on a page. 1172 This information can then be summarized by examining these log 1173 files. An example log file summarizing script is included in the 1174 package. It is the <code>log.html</code> file in the 1175 <code>examples</code> directory. This is the dbm log file analyzer. 1176 The mSQL log file analyzer is called <code>mlog.html</code>. And the 1177 mysql log file analyzer is called <code>mylog.html</code>. To run it, 1178 copy it and the other mlog.* files to a directory accessible from 1179 your web server and type:</p> 1180 <pre> 1181 http://your.machine.domain/cgi-bin/php.cgi/path/mlog.html 1182</pre> 1183 1184 <p>Or, if you are using the Apache module version, you can give 1185 the script a ".phtml" extension and call it with:</p> 1186 <pre> 1187 http://your.machine.domain/path/mlog.phtml 1188</pre> 1189 1190 <p>By default, if you have compiled PHP with access logging 1191 enabled, then your pages will appear with a footer containing 1192 some access information. You may not want to see this footer, but 1193 still log hits. You can turn off this footer with a "phpShowInfo 1194 off" line in your Apache httpd.conf or .htaccess files if you are 1195 running Apache. If you are not running Apache, you may turn these 1196 log footers off either by creating a rule in the <a href= 1197 "#access">?config</a> section for the page, or by adding a tag 1198 like this to your page:</p> 1199 1200 <p><code><?setshowinfo(0)></code></p> 1201 <hr> 1202 1203 <h2><a name="relative" id="relative">Relative vs. Absolute URL's 1204 - or, Why do my Images Break?</a></h2> 1205 1206 <p>A problem common to all CGI wrappers is that the HTTPD program 1207 changes the current directory to the directory where whatever it 1208 is loading is stored. In the case of a CGI program, the current 1209 directory is set to the directory where the CGI program resides. 1210 This is normally not a problem, except when it comes to relative 1211 URL's.</p> 1212 1213 <p>A relative URL is a URL which relies upon the current 1214 directory being the same as the directory where the current HTML 1215 file is located. So, for example, if I had the URL:</p> 1216 <pre> 1217 http://my.machine/~rasmus/file.html 1218</pre> 1219 1220 <p>the actual HTML file might be:</p> 1221 <pre> 1222 ~rasmus/public_html/file.html 1223</pre> 1224 1225 <p>If within the <code>file.html</code> file I had the tag:</p> 1226 <pre> 1227 <IMG SRC="pic.gif"> 1228</pre> 1229 1230 <p>when loaded normally this file gif file is expected to be in 1231 <code>~rasmus/public_html/pic.gif</code>. However, when loaded 1232 through a CGI wrapper with a URL like:</p> 1233 <pre> 1234 http://my.machine/cgi-bin/php.cgi/~rasmus/file.html 1235</pre> 1236 1237 <p>then HTTPD sets the current directory to <code>/cgi-bin</code> (or 1238 wherever the ScriptAlias might point) and subsequently when the 1239 page is loaded the <code>pic.gif</code> file is expected to be in: 1240 <code>/cgi-bin/pic.gif</code> which is usually not the desired 1241 effect.</p> 1242 1243 <p>The quick way around this problem is to use absolute URL's. In 1244 the above example if the image tag had been:</p> 1245 <pre> 1246 <IMG SRC="/~rasmus/pic.gif"> 1247</pre> 1248 1249 <p>then there would have been no problem. Using absolute URL's is 1250 not always desirable as it makes pages less portable. An obvious 1251 question you may have at this point is, "Why doesn't PHP just 1252 change the current directory to the right place?". The answer is 1253 that PHP actually does change the current directory to the 1254 location of the HTML file it is displaying. Any file paths used 1255 inside PHP Script tags, can be relative. The problem is that tags 1256 outside of PHP's control such as <img > and <a href > 1257 will not be passed through PHP. When they are parsed, PHP is no 1258 longer active and the current working directory has been set back 1259 to the directory specified by the HTTP Daemon.</p> 1260 1261 <p><strong>The Solution</strong> is a compromise. PHP provides a 1262 variable called <strong>PATH_DIR</strong>. It contains the 1263 directory portion of the current HTML file at all times. If this 1264 PATH_DIR variable is used in the <img > and <a href > 1265 tags then the effect of a relative URL can be achieved, although 1266 to the server it will look like an absolute URL when parsed. From 1267 our above example, the only change we would need to make would be 1268 to change the img tag to:</p> 1269 <pre> 1270 <IMG SRC="<?echo $PATH_DIR>/pic.gif"> 1271</pre>By using the above, you can move the file containing this tag 1272around, and the tag will always refer to a <code>pic.gif</code> file in 1273the same directory as the source HTML file. 1274 1275 <p>Another way to handle this is to use the traditional <BASE 1276 HREF=...> in the HTML file.</p> 1277 <hr> 1278 1279 <h2><a name="getpost" id="getpost">How PHP handles GET and POST 1280 method data</a></h2> 1281 1282 <p>PHP will detect both GET and POST method data coming from HTML 1283 forms. One important point to understand is that POST method data 1284 is always treated first if both are present. If a PHP variable is 1285 defined by the POST method data, or if the variable is defined by 1286 the HTTP daemon in the Unix environment, then GET method data 1287 cannot overwrite it. This is to prevent somebody from adding 1288 <em>?REMOTE_HOST=some.bogus.host</em> to their URL's and thus 1289 tricking the PHP logging mechanism into recording this alternate 1290 data. POST method data is however allowed to overwrite these 1291 variables.</p> 1292 1293 <p>Any component of the GET data (the data following a '?' in the 1294 URL) which is of the form, <em>word=something</em> will define 1295 the variable <em>$word</em> to contain the value 1296 <em>something</em>. Even if the data is not of this form, it can 1297 be accessed with the $argv built-in array. For example, in a URL 1298 like:</p> 1299 <pre> 1300 /cgi-bin/php.cgi/file.html?abc+def+EMAIL_ADDR=rasmus@lerdorf.on.ca&var=value 1301</pre>The relevant components of the PHP symbol table will be: 1302 <pre> 1303 $argc = 4 1304 $argv[0] = abc 1305 $argv[1] = def 1306 $argv[2] = EMAIL_ADDR=rasmus@lerdorf.on.ca&var=value 1307 $EMAIL_ADDR = rasmus@lerdorf.on.ca 1308 $var = value 1309</pre> 1310 1311 <p>Notice how the EMAIL_ADDR part of the data shows up both as 1312 $argv[2] where it is unparsed, and the $EMAIL_ADDR variable is 1313 created to contain <em>rasmus@lerdorf.on.ca</em>.</p> 1314 1315 <p>The $EMAIL_ADDR variable was used as an example in the above 1316 because it is a useful variable if you are using the logging 1317 features of PHP. By adding:</p> 1318 <pre> 1319 ?EMAIL_ADDR= 1320</pre> 1321 1322 <p>to any links on a page where the user's email address is 1323 known, you may propagate it to the next page. The PHP logging 1324 system will automatically look for this variable and record its 1325 value as the user's e-mail address in the logs. For any users of 1326 PHP1, the above serves the same function as adding 1327 <em>?<!--$email--></em> to the URL used to do in PHP1. It 1328 looks a little bit more complex now, but it is also completely 1329 general allowing you to build your own complex pages.</p> 1330 1331 <p>In the above example you can also see how multiple variables 1332 can be defined right in the GET method data by separating each 1333 with the "&" character. This "&" separated list of 1334 variables must be the last (or only) component of the GET method 1335 data for it to be valid.</p> 1336 1337 <p><a name="selmul" id="selmul"><strong><code>SELECT MULTIPLE</code> 1338 and PHP</strong></a></p> 1339 1340 <p>The SELECT MULTIPLE tag in an HTML construct allows users to 1341 select multiple items from a list. These items are then passed to 1342 the action handler for the form. The problem is that they are all 1343 passed with the same widget name. ie.</p> 1344 <pre> 1345 <SELECT NAME="var" MULTIPLE> 1346</pre> 1347 1348 <p>Each selected option will arrive at the action handler as:</p> 1349 1350 <p>var=option1<br> 1351 var=option2<br> 1352 var=option3</p> 1353 1354 <p>Each option will overwrite the contents of the previous $var 1355 variable. The solution is to use PHP/FI's non-indexed array 1356 feature. The following should be used:</p> 1357 <pre> 1358 <SELECT NAME="var[]" MULTIPLE> 1359</pre> 1360 1361 <p>This tells PHP/FI to treat <em>var</em> as an array an each 1362 assignment of a value to var[] adds an item to the array. The 1363 first item becomes $var[0], the next $var[1], etc. The <a href= 1364 "#count">count()</a> function can be used to determine how many 1365 options were selected, and the <a href="#sort">sort()</a> 1366 function can be used to sort the option array if necessary.</p> 1367 <hr> 1368 <a name="imagecoord" id="imagecoord"><strong><code>IMAGE 1369 SUBMIT</code> and PHP</strong></a> 1370 1371 <p>When submitting a form, it is possible to use an image instead 1372 of the standard submit button with a tag like:</p> 1373 <pre> 1374 <input type=image src=image.gif name=sub> 1375</pre> 1376 1377 <p>When the user clicks somewhere on the image, the accompanying 1378 form will be transmitted to the server with two additional 1379 variables, <em>sub_x</em> and <em>sub_y</em>. These contain the 1380 coordinates of the user click within the image. The experienced 1381 may note that the actual variable names sent by the browser 1382 contains a period rather than an underscore, but PHP converts the 1383 period to an underscore automatically.</p> 1384 <hr> 1385 1386 <h2><a name="gd_support" id="gd_support">GD (a graphics library 1387 for GIF creation) Support in PHP</a></h2>PHP supports the GD 1388 library version 1.2 written by Thomas Boutell. There is no GD 1389 code in PHP itself. If you wish to use the GD support in PHP/FI, 1390 you must obtain the GD library from <a href= 1391 "http://www.boutell.com/gd/http/gd1.3.tar.gz">http://www.boutell.com/gd/http/gd1.3.tar.gz</a>, 1392 install it, and then re-install PHP. 1393 1394 <p>Not all of the GD features are supported by PHP. For a list of 1395 supported functions see the <a href="#funcs">Alphabetical List of 1396 Functions</a>. All the GD functions start with the word, 1397 <em>Image</em>.</p> 1398 1399 <p>More information on the GD package is available at: <a href= 1400 "http://www.boutell.com/gd/">http://www.boutell.com/gd/</a>.</p> 1401 1402 <p><em>GD 1.2 is copyright 1994, 1995 Quest Protein Database 1403 Center, Cold Springs Harbor Labs.</em></p> 1404 <hr> 1405 1406 <h2><a name="virtual_hosts" id="virtual_hosts">PHP/FI and Virtual 1407 Hosts</a></h2>PHP works fine on virtual host setups supported by 1408 some http daemons. The one problem that may occur on such a setup 1409 is related to an inconsistency in the way httpd sets the 1410 SCRIPT_NAME environment variable. Normally it is set to the path 1411 of the current CGI program in relation to the top-level ROOT_DIR 1412 on the httpd server. However, when a virtual domain is used, some 1413 httpd's do not correctly set the SCRIPT_NAME variable as the 1414 relative path from the virtual domain's top level directory as it 1415 should. If the ?config screen gives you an invalid URL error 1416 message, you know that this problem exists on your setup. You 1417 will need to edit the <em>php.h</em> file and set the 1418 VIRTUAL_PATH #define to the path to your <em>php.cgi</em> binary 1419 relative to your top-level directory. 1420 <hr> 1421 1422 <h2><a name="upload" id="upload">File Upload Support</a></h2> 1423 1424 <p>PHP/FI will automatically detect a file upload from a browser 1425 which supports the form-based file upload features as proposed by 1426 <a href="mailto:nebel@xsoft.sd.xerox.com">E. Nebel</a> and 1427 <a href="mailto:masinter@parc.xerox.com">L. Masinter</a> from 1428 Xerox and described in <a href= 1429 "ftp://ds.internic.net/rfc/rfc1867.txt">RFC 1867</a>.</p> 1430 1431 <p>A file upload screen can be built by creating a special form 1432 which looks something like this:</p> 1433 1434 <blockquote> 1435 <pre> 1436 <FORM ENCTYPE="multipart/form-data" ACTION="_URL_" METHOD=POST><br> 1437 <INPUT TYPE="hidden" name="MAX_FILE_SIZE" value="1000"><br> 1438 Send this file: <INPUT NAME="userfile" TYPE="file"><br> 1439 <INPUT TYPE="submit" VALUE="Send File"><br> 1440 </FORM> 1441 </pre> 1442 </blockquote> 1443 1444 <p>The _URL_ should point to a php html file. The MAX_FILE_SIZE 1445 hidden field must precede the file input field and its value is 1446 the maximum filesize accepted. The value is in bytes. In this 1447 destination file, the following variables will be defined upon a 1448 successful upload:</p> 1449 1450 <dl> 1451 <dt><strong>$userfile</strong></dt> 1452 1453 <dd> 1454 <p>The temporary filename in which the uploaded file was 1455 stored on the server machine.</p> 1456 </dd> 1457 1458 <dt><strong>$userfile_name</strong></dt> 1459 1460 <dd> 1461 <p>The original name of the file on the sender's system.</p> 1462 </dd> 1463 1464 <dt><strong>$userfile_size</strong></dt> 1465 1466 <dd> 1467 <p>The size of the uploaded file in bytes.</p> 1468 </dd> 1469 1470 <dt><strong>$userfile_type</strong></dt> 1471 1472 <dd> 1473 <p>The mime type of the file if the browser provided this 1474 information. An example would be "image/gif".</p> 1475 </dd> 1476 </dl> 1477 1478 <p>The <em><strong>$userfile</strong></em> basename of the above 1479 variables will match the NAME field in the upload form.</p> 1480 1481 <p>Files will by default be stored in the server's default 1482 temporary directory. This can be changed by setting the 1483 environment variable TMPDIR in the environment in which PHP/FI 1484 runs. Setting it using a PutEnv() call from within a PHP/FI 1485 script will not work though. Alternatively, you may hard-code in 1486 a temporary directory by editing <em>php.h</em> and defining the 1487 <strong>UPLOAD_TMPDIR</strong> variable.</p> 1488 1489 <p>The PHP/FI script which receives the uploaded file should 1490 implement whatever logic is necessary for determining what should 1491 be done with the uploaded file. You can for example use the 1492 $file_size variable to throw away any files that are either too 1493 small or too big. You could use the $file_type variable to throw 1494 away any files that didn't match a certain type criteria. 1495 Whatever the logic, you should either delete the file from the 1496 temporary directory or move it elsewhere.</p> 1497 1498 <p>Please note that the CERN httpd seems to strip off everything 1499 starting at the first whitespace in the content-type mime header 1500 it gets from the client. As long as this is the case, CERN httpd 1501 will not support the file upload feature.</p> 1502 <hr> 1503 1504 <h2><a name="cookies" id="cookies">Cookie Support</a></h2> 1505 1506 <p>PHP/FI transparently supports HTTP cookies as defined by 1507 <a href= 1508 "http://www.netscape.com/newsref/std/cookie_spec.html">Netscape's 1509 Spec</a>. Cookies are a mechanism for storing data in the remote 1510 browser and thus tracking or identifying return users. You can 1511 set cookies using the <a href="#setcookie">SetCookie()</a> 1512 function. Cookies are part of the HTTP header, so the SetCookie() 1513 function must be called before any output is sent to the browser. 1514 This is the same restriction as for the Header() function.</p> 1515 1516 <p>Any cookies sent to you from the client will automatically be 1517 turned into a PHP/FI variable just like GET and POST method 1518 data.</p> 1519 1520 <p>If you wish to assign multiple values to a single cookie, just 1521 add <b>[]</b> to the cookie name. For example:</p> 1522 <pre> 1523 SetCookie("MyCookie[]","Rasmus Lerdorf", time()+3600); 1524</pre>Note that a cookie will replace a previous cookie by the same 1525name in your browser unless the path or domain is different. So, 1526for a shopping cart application you may want to keep a counter and 1527pass this along. ie. 1528 <pre> 1529 1530 $Count++; 1531 SetCookie("Count",$Count, time()+3600); 1532 SetCookie("Cart[$Count]",$item, time()+3600); 1533</pre> 1534 <hr> 1535 1536 <h2><a name="msql_support" id="msql_support">mSQL 1537 Support</a></h2> 1538 1539 <p>mSQL stands for mini-SQL and is a small and simple SQL 1540 database engine written by David Hughes. It is available from 1541 <a href= 1542 "ftp://ftp.bond.edu.au/pub/Minerva/msql">ftp://ftp.bond.edu.au/pub/Minerva/msql</a></p> 1543 1544 <p>PHP/FI supports has a rich set of mSQL support functions:</p> 1545 1546 <dl> 1547 <dt><a href="#msql">msql()</a></dt> 1548 1549 <dt><a href="#msql_close">msql_Close()</a></dt> 1550 1551 <dt><a href="#msql_connect">msql_Connect()</a></dt> 1552 1553 <dt><a href="#msql_createdb">msql_CreateDB()</a></dt> 1554 1555 <dt><a href="#msql_dbname">msql_dbName()</a></dt> 1556 1557 <dt><a href="#msql_dropdb">msql_DropDB()</a></dt> 1558 1559 <dt><a href="#msql_fieldflags">msql_FieldFlags()</a></dt> 1560 1561 <dt><a href="#msql_fieldlen">msql_FieldLen()</a></dt> 1562 1563 <dt><a href="#msql_fieldname">msql_FieldName()</a></dt> 1564 1565 <dt><a href="#msql_fieldtype">msql_FieldType()</a></dt> 1566 1567 <dt><a href="#msql_freeresult">msql_FreeResult()</a></dt> 1568 1569 <dt><a href="#msql_listdbs">msql_ListDBs()</a></dt> 1570 1571 <dt><a href="#msql_listfields">msql_Listfields()</a></dt> 1572 1573 <dt><a href="#msql_listtables">msql_ListTables()</a></dt> 1574 1575 <dt><a href="#msql_numfields">msql_NumFields()</a></dt> 1576 1577 <dt><a href="#msql_numrows">msql_NumRows()</a></dt> 1578 1579 <dt><a href="#msql_regcase">msql_RegCase()</a></dt> 1580 1581 <dt><a href="#msql_result">msql_Result()</a></dt> 1582 1583 <dt><a href="#msql_tablename">msql_TableName()</a></dt> 1584 </dl> 1585 1586 <p>In addition to these functions, PHP/FI can also be compiled to 1587 automatically escape any forward single quote ( ' ) characters 1588 found in GET or POST data. If the MAGIC_QUOTES variable is 1589 defined in the <em>php.h</em> file then these quotes will be 1590 automatically escaped making it easier to pass form data directly 1591 to msql queries.</p> 1592 <hr> 1593 1594 <h2><a name="pg95_support" id= 1595 "pg95_support">Postgres95/PostgreSQL Support</a></h2> 1596 1597 <p>Postgres95/PostgreSQL is a powerful public domain database 1598 that implements a significant subset of the SQL language. It 1599 supports many datatypes and commands that are not available in 1600 mSQL. More information about Postgres and the software itself can 1601 be found at this URL: <a href= 1602 "http://www.postgreSQL.org/">http://www.postgreSQL.org/</a>.</p> 1603 1604 <p>The following PHP functions are available for Postgres95:</p> 1605 1606 <dl> 1607 <dt><a href="#pg_connect">pg_Connect()</a></dt> 1608 1609 <dt><a href="#pg_close">pg_Close()</a></dt> 1610 1611 <dt><a href="#pg_host">pg_Host()</a></dt> 1612 1613 <dt><a href="#pg_port">pg_Port()</a></dt> 1614 1615 <dt><a href="#pg_options">pg_Options()</a></dt> 1616 1617 <dt><a href="#pg_tty">pg_tty()</a></dt> 1618 1619 <dt><a href="#pg_dbname">pg_DBname()</a></dt> 1620 1621 <dt><a href="#pg_exec">pg_Exec()</a></dt> 1622 1623 <dt><a href="#pg_result">pg_Result()</a></dt> 1624 1625 <dt><a href="#pg_freeresult">pg_FreeResult()</a></dt> 1626 1627 <dt><a href="#pg_getlastoid">pg_GetLastOid()</a></dt> 1628 1629 <dt><a href="#pg_numrows">pg_NumRows()</a></dt> 1630 1631 <dt><a href="#pg_numfields">pg_NumFields()</a></dt> 1632 1633 <dt><a href="#pg_fieldnum">pg_FieldNum()</a></dt> 1634 1635 <dt><a href="#pg_fieldname">pg_FieldName()</a></dt> 1636 1637 <dt><a href="#pg_fieldtype">pg_FieldType()</a></dt> 1638 1639 <dt><a href="#pg_fieldsize">pg_FieldSize()</a></dt> 1640 1641 <dt><a href="#pg_fieldprtlen">pg_FieldPrtLen()</a></dt> 1642 1643 <dt><a href="#pg_errorMessage">pg_errorMessage()</a></dt> 1644 </dl> 1645 1646 <p><strong>Note:</strong> Binary cursors are not supported.</p> 1647 1648 <p>In addition to these functions, PHP/FI can also be compiled to 1649 automatically escape any forward single quote ( ' ) and double 1650 quote ( " ) characters found in GET or POST data. If the 1651 MAGIC_QUOTES variable is defined in the <em>php.h</em> file then 1652 these quotes will be automatically escaped making it easier to 1653 pass form data directly to Postgres queries.</p> 1654 1655 <p>Here is a sample script that connects to Postgres database on 1656 localhost called 'mydb' and retrieves the names and ages of 1657 people in a table:</p> 1658 <pre> 1659<? 1660 $conn = pg_Connect("localhost", "5432", "", "", "mydb"); 1661 if (!$conn) { 1662 echo "An error occured.\n"; 1663 exit; 1664 } 1665 1666 $result = pg_Exec($conn, "select * from table1"); 1667 if (!$result) { 1668 echo "An error occured.\n"; 1669 exit; 1670 } 1671 1672 $num = pg_NumRows($result); 1673 $i = 0; 1674 1675 while ($i < $num) { 1676 echo "name: "; 1677 echo pg_Result($result, $i, "name"); 1678 echo " age: "; 1679 echo pg_Result($result, $i, "age"); 1680 echo "<BR>"; 1681 $i++; 1682 } 1683 1684 pg_FreeResult($result); 1685 pg_Close($conn); 1686> 1687</pre> 1688 <hr> 1689 1690 <h2><a name="mysql_support" id="mysql_support">mysql 1691 Support</a></h2> 1692 1693 <p>mysql is an clone of the mSQL package. You can get a copy from 1694 <a href="http://www.tcx.se/">http://www.tcx.se/</a></p> 1695 1696 <p>PHP/FI supports has a rich set of mysql support functions:</p> 1697 1698 <dl> 1699 <dt><a href="#mysql">mysql()</a></dt> 1700 1701 <dt><a href="#mysql_close">mysql_Close()</a></dt> 1702 1703 <dt><a href="#mysql_connect">mysql_Connect()</a></dt> 1704 1705 <dt><a href="#mysql_createdb">mysql_CreateDB()</a></dt> 1706 1707 <dt><a href="#mysql_dbname">mysql_dbName()</a></dt> 1708 1709 <dt><a href="#mysql_dropdb">mysql_DropDB()</a></dt> 1710 1711 <dt><a href="#mysql_fieldflags">mysql_FieldFlags()</a></dt> 1712 1713 <dt><a href="#mysql_fieldlen">mysql_FieldLen()</a></dt> 1714 1715 <dt><a href="#mysql_fieldname">mysql_FieldName()</a></dt> 1716 1717 <dt><a href="#mysql_fieldtype">mysql_FieldType()</a></dt> 1718 1719 <dt><a href="#mysql_freeresult">mysql_FreeResult()</a></dt> 1720 1721 <dt><a href="#mysql_listdbs">mysql_ListDBs()</a></dt> 1722 1723 <dt><a href="#mysql_listfields">mysql_Listfields()</a></dt> 1724 1725 <dt><a href="#mysql_listtables">mysql_ListTables()</a></dt> 1726 1727 <dt><a href="#mysql_numfields">mysql_NumFields()</a></dt> 1728 1729 <dt><a href="#mysql_numrows">mysql_NumRows()</a></dt> 1730 1731 <dt><a href="#mysql_result">mysql_Result()</a></dt> 1732 1733 <dt><a href="#mysql_tablename">mysql_TableName()</a></dt> 1734 </dl> 1735 1736 <p>In addition to these functions, PHP/FI can also be compiled to 1737 automatically escape any forward single quote ( ' ) characters 1738 found in GET or POST data. If the MAGIC_QUOTES variable is 1739 defined in the <em>php.h</em> file then these quotes will be 1740 automatically escaped making it easier to pass form data directly 1741 to mysql queries.</p> 1742 <hr> 1743 1744 <h2><a name="solid_support" id="solid_support">Solid 1745 Support</a></h2> 1746 1747 <p>The Solid server is a high-volume SQL server. It supports the 1748 ANSI SQL2, ODBC, SAG CLI and X/Open SQL standards. More 1749 information about the Solid server is available at <a href= 1750 "http://www.solidtech.com/">www.solidtech.com</a>. The Solid 1751 interface to PHP was developed by <a href= 1752 "http://solid.digiface.nl/">DigiFace Internet Services</a>.</p> 1753 1754 <p>The following PHP functions are available for the Solid 1755 Server:</p> 1756 1757 <dl> 1758 <dt><a href="#solid_connect">Solid_Connect()</a></dt> 1759 1760 <dt><a href="#solid_close">Solid_Close()</a></dt> 1761 1762 <dt><a href="#solid_exec">Solid_Exec()</a></dt> 1763 1764 <dt><a href="#solid_result">Solid_Result()</a></dt> 1765 1766 <dt><a href="#solid_freeresult">Solid_FreeResult()</a></dt> 1767 1768 <dt><a href="#solid_numrows">Solid_NumRows()</a></dt> 1769 1770 <dt><a href="#solid_numfields">Solid_NumFields()</a></dt> 1771 1772 <dt><a href="#solid_fieldnum">Solid_FieldNum()</a></dt> 1773 1774 <dt><a href="#solid_fieldname">Solid_FieldName()</a></dt> 1775 </dl> 1776 1777 <p>In addition to these functions, PHP/FI can also be compiled to 1778 automatically escape any forward single quote ( ' ) characters 1779 found in GET or POST data. If the MAGIC_QUOTES variable is 1780 defined in the <em>php.h</em> file then these quotes will be 1781 automatically escaped making it easier to pass form data directly 1782 to Solid queries.</p> 1783 1784 <p>Here is the same script that was shown in the Postgres 1785 section, adapted for the Solid server.</p> 1786 <pre> 1787<? 1788 $conn = Solid_Connect("", "username", "password"); 1789 if (!$conn) { 1790 echo "An error occured.\n"; 1791 exit; 1792 } 1793 1794 $result = Solid_Exec($conn, "select * from table1"); 1795 if (!$result) { 1796 echo "An error occured.\n"; 1797 exit; 1798 } 1799 1800 while (Solid_FetchRow($result)) { 1801 echo "name: "; 1802 echo Solid_Result($result, "name"); 1803 echo " age: "; 1804 echo Solid_Result($result, "age"); 1805 echo "<BR>"; 1806 } 1807 1808 Solid_FreeResult($result); 1809 Solid_Close($conn); 1810> 1811</pre> 1812 <hr> 1813 1814 <h2><a name="sybase_support" id="sybase_support">Sybase 1815 Support</a></h2>The supporting functions uses Sybase DB library 1816 API calls. Therefore you must have sybase API libraries and 1817 headers files installed in your system in order to compile PHP/FI 1818 with sybase support. 1819 1820 <p>The following PHP/FI functions are available for Sybase.</p> 1821 1822 <dl> 1823 <dt><a href= 1824 "#sybsql_checkconnect">SybSQL_CheckConnect()</a></dt> 1825 1826 <dt><a href="#sybsql_connect">SybSQL_Connect()</a></dt> 1827 1828 <dt><a href="#sybsql_DBuse">SybSQL_DBuse()</a></dt> 1829 1830 <dt><a href="#sybsql_Exit">SybSQL_Exit()</a></dt> 1831 1832 <dt><a href="#sybsql_fieldname">SybSQL_Fieldname()</a></dt> 1833 1834 <dt><a href="#sybsql_getfield">SybSQL_GetField()</a></dt> 1835 1836 <dt><a href="#sybsql_isrow">SybSQL_IsRow()</a></dt> 1837 1838 <dt><a href="#sybsql_nextrow">SybSQL_NextRow()</a></dt> 1839 1840 <dt><a href="#sybsql_numfields">SybSQL_NumFields()</a></dt> 1841 1842 <dt><a href="#sybsql_numrows">SybSQL_NumRows()</a></dt> 1843 1844 <dt><a href="#sybsql_query">SybSQL_Query()</a></dt> 1845 1846 <dt><a href="#sybsql_result">SybSQL_Result()</a></dt> 1847 1848 <dt><a href="#sybsql_result_all">SybSQL_Result_All()</a></dt> 1849 1850 <dt><a href="#sybsql_seek">SybSQL_Seek()</a></dt> 1851 </dl> 1852 1853 <p>For a complete example, see the example following the <a href= 1854 "#sybsql_result">sybSQL_Result()</a> function.</p> 1855 <hr> 1856 1857 <h2><a name="oracle_support" id="oracle_support">Oracle 1858 Support</a></h2>The PHP/FI interface to Oracle uses the Oracle 1859 Call Interface (OCI). You need the OCI libraries on your system 1860 to compile PHP/FI with Oracle support. 1861 1862 <p>The following PHP/FI functions are available for Oracle:</p> 1863 1864 <dl> 1865 <dt><a href="#ora_bind">Ora_Bind()</a></dt> 1866 1867 <dt><a href="#ora_close">Ora_Close()</a></dt> 1868 1869 <dt><a href="#ora_commit">Ora_Commit()</a></dt> 1870 1871 <dt><a href="#ora_commitoff">Ora_CommitOff()</a></dt> 1872 1873 <dt><a href="#ora_commiton">Ora_CommitOn()</a></dt> 1874 1875 <dt><a href="#ora_exec">Ora_Exec()</a></dt> 1876 1877 <dt><a href="#ora_fetch">Ora_Fetch()</a></dt> 1878 1879 <dt><a href="#ora_getcolumn">Ora_GetColumn()</a></dt> 1880 1881 <dt><a href="#ora_logoff">Ora_Logoff()</a></dt> 1882 1883 <dt><a href="#ora_logon">Ora_Logon()</a></dt> 1884 1885 <dt><a href="#ora_open">Ora_Open()</a></dt> 1886 1887 <dt><a href="#ora_parse">Ora_Parse()</a></dt> 1888 1889 <dt><a href="#ora_rollback">Ora_Rollback()</a></dt> 1890 </dl> 1891 1892 <p>An example PHP/FI Oracle application:</p> 1893 <pre> 1894<? 1895PutEnv("ORACLE_HOME=path_to_your_oracle_home" 1896PutEnv("ORACLE_SID=database" 1897 1898/* Establish a connection between PHP and Oracle. */ 1899$conn = Ora_Logon("username" "password" 1900 1901if ($conn < 0) { 1902 echo("Could not connect to Oracle.\n" 1903 exit; 1904} 1905 1906/* Open a cursor in Oracle. */ 1907$cursor = Ora_Open($conn); 1908 1909if ($cursor < 0) { 1910 echo("Could not open a cursor.\n" 1911 Ora_Logoff($conn); 1912 exit; 1913} 1914 1915/* Turn off autocommit. */ 1916Ora_CommitOff($conn); 1917 1918/* This is the SQL query. */ 1919$query = "SELECT * FROM some_table" 1920 1921if (Ora_Parse($cursor, $query) < 0) { 1922 echo("Parse failed!\n" 1923 Ora_Logoff($conn); 1924 exit; 1925} 1926 1927/* Execute the SQL statement associated with $cursor and 1928 prepare storage for select-list items. */ 1929$ncols = Ora_Exec($cursor); 1930 1931echo "lt;P>\n" 1932echo "lt;TABLE BORDER=1 CELLSPACING=0>\n" 1933 1934/* Retrieve all rows from the database one after another. */ 1935while (Ora_Fetch($cursor) == 1) { 1936 $i = 0; 1937 echo "lt;TR>\n" 1938 while ($i < $ncols) { 1939 /* Get data for a single column of currently fetched row. */ 1940 $col = Ora_GetColumn($cursor, $i); 1941 echo("lt;TD>$col</TD>\n" 1942 $i++; 1943 } 1944 echo("lt;/TR>\n" 1945} 1946 1947echo "</TABLE>\n"; 1948 1949/* Close the Oracle connection. */ 1950Ora_Close($cursor); 1951 1952/* Disconnect the logon data area. */ 1953Ora_Logoff($conn); 1954> 1955</pre> 1956 <hr> 1957 1958 <h2><a name="illustra_support" id="illustra_support">Informix 1959 Illustra Support</a></h2> 1960 1961 <p>Illustra is a commercial database sold by Informix. It has 1962 several features that are not fully supported by this interface 1963 (yet). The main claim to fame for Illustra is that it is an 1964 object-relational database capable of being extended in an 1965 object-orientated fashion. For example, it is possible to have an 1966 Image as a base type within the database. More information can be 1967 obtained from <a href="http://www.illustra.com/">The illustra 1968 home page</a>.</p> 1969 1970 <p>The following PHP functions are available for Illustra:</p> 1971 1972 <dl> 1973 <dt><a href="#mi_connect">mi_Connect()</a></dt> 1974 1975 <dt><a href="#mi_close">mi_Close()</a></dt> 1976 1977 <dt><a href="#mi_dbname">mi_DBname()</a></dt> 1978 1979 <dt><a href="#mi_exec">mi_Exec()</a></dt> 1980 1981 <dt><a href="#mi_result">mi_Result()</a></dt> 1982 1983 <dt><a href="#mi_numrows">mi_NumRows()</a></dt> 1984 1985 <dt><a href="#mi_numfields">mi_NumFields()</a></dt> 1986 1987 <dt><a href="#mi_fieldnum">mi_FieldNum()</a></dt> 1988 1989 <dt><a href="#mi_fieldname">mi_FieldName()</a></dt> 1990 </dl> 1991 1992 <p><strong>Note:</strong> Type operations are not yet 1993 supported.</p> 1994 1995 <p>Here is a sample script that connects to the illustra database 1996 on localhost called 'mydb' and retrieves the names and ages of 1997 people in a table:</p> 1998 <pre> 1999<? 2000 $conn = mi_Connect("mydb", "username", "password"); 2001 if ($conn<0) { 2002 echo "An error occured on connection.\n"; 2003 exit; 2004 } 2005 2006 $result = mi_Exec($conn, "select * from table1"); 2007 if ($result < 0) { 2008 echo "An error occured.\n"; 2009 exit; 2010 } 2011 2012 $num = mi_NumRows($result); 2013 $i = 0; 2014 2015 while ($i < $num) { 2016 echo "name: "; 2017 echo mi_Result($result, $i, "name"); 2018 echo " age: "; 2019 echo mi_Result($result, $i, "age"); 2020 echo "<BR>"; 2021 $i++; 2022 } 2023 2024 mi_Close($conn); 2025> 2026</pre> 2027 <hr> 2028 2029 <h2><a name="adabas_support" id="adabas_support">Adabas 2030 Support</a></h2> 2031 2032 <p>Adabas D is an advanced RDBMS that is available on many 2033 platforms. A special version, the so called Personal Edition is 2034 available for Linux and Win32 at no cost. It is resticted to 5 2035 simulataneous users and 100 MB of data. For more information on 2036 Adabas D refer to <a href= 2037 "http://www.softwareag.com">http://www.softwareag.com</a>.</p> 2038 2039 <p>The following PHP functions are available for accessing Adabas 2040 databases:</p> 2041 2042 <dl> 2043 <dt><a href="#ada_connect">Ada_Connect()</a></dt> 2044 2045 <dt><a href="#ada_close">Ada_Close()</a></dt> 2046 2047 <dt><a href="#ada_exec">Ada_Exec()</a></dt> 2048 2049 <dt><a href="#ada_result">Ada_Result()</a></dt> 2050 2051 <dt><a href="#ada_resultall">Ada_ResultAll()</a></dt> 2052 2053 <dt><a href="#ada_freeresult">Ada_FreeResult()</a></dt> 2054 2055 <dt><a href="#ada_numrows">Ada_NumRows()</a></dt> 2056 2057 <dt><a href="#ada_numfields">Ada_NumFields()</a></dt> 2058 2059 <dt><a href="#ada_numrows">Ada_NumRows()</a></dt> 2060 2061 <dt><a href="#ada_numfields">Ada_NumFields()</a></dt> 2062 2063 <dt><a href="#ada_fieldnum">Ada_FieldNum()</a></dt> 2064 2065 <dt><a href="#ada_fieldname">Ada_FieldName()</a></dt> 2066 2067 <dt><a href="#ada_fieldtype">Ada_FieldType()</a></dt> 2068 </dl>Here is the same script that was shown in the Postgres and 2069 Solid sections, adapted for Adabas D. 2070 <pre> 2071<? 2072 $conn = Ada_Connect("node:db", "username", "password"); 2073 if (!$conn) { 2074 echo "An error occured.\n"; 2075 exit; 2076 } 2077 2078 $result = Ada_Exec($conn, "select * from table1"); 2079 if (!$result) { 2080 echo "An error occured.\n"; 2081 exit; 2082 } 2083 2084 while (Ada_FetchRow($result)) { 2085 echo "name: "; 2086 echo Ada_Result($result, "name"); 2087 echo " age: "; 2088 echo Ada_Result($result, "age"); 2089 echo "<BR>"; 2090 } 2091 2092 Ada_FreeResult($result); 2093 Ada_Close($conn); 2094> 2095</pre> 2096 <hr> 2097 2098 <h2><a name="regexp" id="regexp">Regular Expressions</a></h2> 2099 2100 <p>Regular expressions are used for complex string manipulation 2101 in PHP/FI. The script interface to the regular expression support 2102 is through the following functions: <a href="#ereg">EReg()</a>, 2103 <a href="#eregi">ERegi()</a>, <a href= 2104 "#ereg_replace">EReg_Replace()</a>, <a href= 2105 "#eregi_replace">ERegi_Replace()</a>, <a href= 2106 "#reg_match">Reg_Match()</a>, <a href= 2107 "#reg_replace">Reg_Replace()</a>, and <a href= 2108 "#reg_search">Reg_Search()</a>. The first argument to all three 2109 functions is a regular expression string. The EReg functions use 2110 the Posix Extended regular expressions as defined by POSIX 2111 1003.2, while the Reg functions implement Basic regular 2112 expressions. For a complete description of regular expressions 2113 see your regex(7) man page. If you do not have this page, the 2114 regex(7) man page written by Henry Spencer can be found in the 2115 src/regex directory in the PHP/FI distribution. Ask your system 2116 administrator to install this man page for you.</p> 2117 2118 <p>Some examples of regular expressions and what they do:</p> 2119 2120 <blockquote> 2121 <dl> 2122 <dt><code>ereg("abc",$string);</code></dt> 2123 2124 <dd>Returns true if "abc" is found anywhere in $string.</dd> 2125 2126 <dt><code>ereg("^abc",$string);</code></dt> 2127 2128 <dd>Returns true if "abc" is found at the beginning of 2129 $string.</dd> 2130 2131 <dt><code>ereg("abc$",$string);</code></dt> 2132 2133 <dd>Returns true if "abc" is found at the end of 2134 $string.</dd> 2135 2136 <dt> 2137 <code>eregi("(ozilla.[23]|MSIE.3)",$HTTP_USER_AGENT);</code></dt> 2138 2139 <dd>Returns true if client browser is Netscape 2, 3 or MSIE 2140 3.</dd> 2141 2142 <dt><code>ereg("([[:alnum:]]+) ([[:alnum:]]+) 2143 ([[:alnum:]]+)",$string,$regs);</code><br></dt> 2144 2145 <dd>Places three space separated words into $regs[1], 2146 $regs[2] and $regs[3].</dd> 2147 2148 <dt><code>ereg_replace("^","<BR>",$string)</code></dt> 2149 2150 <dd>Put a <BR> tag at the beginning of $string.</dd> 2151 2152 <dt><code>ereg_replace("$","<BR>",$string)</code></dt> 2153 2154 <dd>Put a <BR> tag at the end of $string.</dd> 2155 2156 <dt><code>ereg_replace(10,"",$string);</code></dt> 2157 2158 <dd>Get rid of any linefeed characters in $string.</dd> 2159 2160 <dt><code>ereg_replace(13,"<BR>",$string);</code></dt> 2161 2162 <dd>Replace all carriage returns with a <BR> tag in 2163 $string.</dd> 2164 </dl> 2165 </blockquote> 2166 <hr> 2167 2168 <h2><a name="escapes" id="escapes">Escape Characters</a></h2> 2169 2170 <p>The following escape sequences are supported in most places 2171 where a quoted string argument is used:</p> 2172 2173 <blockquote> 2174 <pre> 2175 \a --> bell 2176 \b --> backspace 2177 \n --> linefeed 2178 \r --> carriage return 2179 \t --> tab 2180 \nnn --> octal char 2181 \xXX --> hex char 2182</pre> 2183 </blockquote> 2184 <hr> 2185 2186 <h2><a name="octal" id="octal">Octal Notation of Unix file 2187 permissions</a></h2> 2188 2189 <p>A couple of functions in the PHP/FI script language epxect 2190 octal arguments to denote Unix-style permission parameters. In 2191 this octal notation 3 bits are used to represent the values 0-7. 2192 Each bit of the three represents a specific permission. Octal is 2193 traditionally noted in some contexts by a leading 0, such as 2194 0755. You do not need to use this leading 0 in PHP since the 2195 functions that expect octal parameters are will simplyassume that 2196 the parameter is octal. Using the leading 0 is however good 2197 practise to remind yourself that you are no longer dealing with a 2198 base 10 value.</p> 2199 2200 <p><b>Bit Description</b></p> 2201 <pre> 2202 xxx 2203 ^^^ 2204 ||+----1 bit (execute permission) 2205 |+-----2 bit (write permission) 2206 +------4 bit (read permission) 2207</pre>These three bits are repeated three times for owner, group, 2208and world. Thus 0755 means: 2209 <pre> 2210 owner: r,w,x 2211 group: r, ,x 2212 world: r, ,x 2213</pre>Note that the execute bit on a directory means 'access', not 2214'execute'. There are also the extended bits in the fourth octal 2215nibble, like 0?755: 2216 <pre> 2217 4: suid bit (set userid) 2218 2: sgid bit (set group id) 2219 1: sticky bit (on a directory, only the owner can delete a file) 2220</pre> 2221 <hr> 2222 2223 <h2><a name="script" id="script">PHP/FI Script Language</a></h2> 2224 2225 <p>The PHP script language is similar in syntax to the C language 2226 in many ways. It supports variables, arrays, function calls, 2227 different variable types and most things you might need to write 2228 complex cgi programs.</p> 2229 2230 <p>Each PHP/FI function is described in the following section and 2231 can be quickly found by simply appending #function_name to the 2232 url for this document since each function description has been 2233 tagged with its name.</p> 2234 2235 <h3><a name="syntax" id="syntax">Syntax</a></h3> 2236 2237 <p>Each PHP instruction starts with <strong><?</strong> and 2238 ends with a <strong>></strong>. Or, instructions may be 2239 grouped inside a single <strong><? ></strong> pair and 2240 separated by <strong>;</strong> characters.</p> 2241 2242 <p>Variables are supported and are indicated by preceding the 2243 variable name with a <strong>$</strong>. So, for example, to set 2244 a variable to 5 and then display this variable, the following is 2245 valid:</p> 2246 <pre> 2247 <?$a = 5> 2248 <?echo $a> 2249</pre> 2250 2251 <p>This is the same as writing:</p> 2252 <pre> 2253 <? $a = 5; echo $a > 2254</pre> 2255 2256 <p>Or even:</p> 2257 <pre> 2258 <? 2259 $a = 5; 2260 echo $a; 2261 > 2262</pre> 2263 2264 <p>Extra white space characters such as spaces, tabs and 2265 new-lines are ignored. This fact should be used to format the PHP 2266 script blocks to make them easier to read. Case is relevant in 2267 variable names, but not in function calls. In the functional 2268 overview later on in this documentation, case is only used to 2269 make the function names easier to read. In the actual script 2270 language you can use any case you wish.</p> 2271 2272 <p>Comments are supported. A comment is written just like 2273 comments in the C language. <strong>/*</strong> starts a comment 2274 and <strong>*/</strong> ends a comment. Comments can be placed 2275 anywhere within the <strong><? ... ></strong> block.</p> 2276 <hr> 2277 2278 <h3><a name="vars" id="vars">Variables</a></h3> 2279 2280 <p>Three types of variables are supported. <strong>Long 2281 integer</strong>, <strong>Double precision floating 2282 point</strong> and <strong>character strings</strong>. They are 2283 automatically detected. For example:</p> 2284 <pre> 2285 <?$a = 5> 2286</pre> 2287 2288 <p>causes $a to become a variable of type INTEGER.</p> 2289 <pre> 2290 <?$a = 5.0> 2291</pre> 2292 2293 <p>causes $a to become a variable of type DOUBLE.</p> 2294 <pre> 2295 <?$a = "5"> 2296</pre> 2297 2298 <p>causes $a to become a variable of type STRING.</p> 2299 2300 <p>The type of the variable is not generally important. Every 2301 variable regardless of its type is converted to all three types 2302 internally and the various functions will try to use the correct 2303 type. There are only a few functions affected by the type of the 2304 variable.</p> 2305 2306 <p>All three variable types may also be treated as arrays by 2307 appending <strong>[value]</strong> to their names. Unlike C, 2308 these are actually associative arrays similar to those used in 2309 Perl. The following would be valid:</p> 2310 <pre> 2311 <? 2312 $a[0] = 5; 2313 $a["hello"] = 6; 2314 echo $a[0]; 2315 echo $a["hello"]; 2316 > 2317</pre> 2318 2319 <p>Note that if a variable is used both as an array and as a 2320 normal variable, the normal variable is synonymous with the index 2321 "0" entry in the array. ie.</p> 2322 <pre> 2323 $a = 1; 2324</pre> 2325 2326 <p>Is the same as writing:</p> 2327 <pre> 2328 $a[0] = 1; 2329</pre> 2330 2331 <p>PHP/FI also supports non-indexed arrays. A non-indexed array 2332 will generate its own index as items are added to it. For 2333 example:</p> 2334 <pre> 2335 $a[] = "Hello"; 2336 $a[] = "There"; 2337</pre> 2338 2339 <p>The first item inserted into a non-indexed array always gets 2340 assigned index 0, the second index 1, etc. Therefore the above 2341 items may be printed out with:</p> 2342 <pre> 2343 echo $a[0]; 2344 echo $a[1]; 2345 2346</pre> 2347 2348 <p>Arrays can be copied by a simple assignment. If $b is an 2349 array, then all the values can be copied to a new array named $a 2350 with:</p> 2351 <pre> 2352 $a = $b; 2353</pre> 2354 2355 <p>Please not that if PHP does not force you to define variables 2356 before using them. If in the above statement, $b was undefined, 2357 then $a would be set to an empty string ("").</p> 2358 2359 <p>The [] notation is also used to indicate that arrays are to be 2360 appended. If $a and $b are both arrays, then $b can be appended 2361 to $a by:</p> 2362 <pre> 2363 $a[] = $b; 2364</pre> 2365 2366 <p>In the above, there will be a difference between associative 2367 arrays and normal numbered arrays. Numbered arrays will be 2368 renumbered such that all elements from $b will come after the 2369 original elements from $a. While with associative arrays, 2370 elements in $b will be merged with elements in $a. Any elements 2371 (items with the same index name) which already exist in $a will 2372 be overwritten by $b elements.</p> 2373 2374 <p>You can use the <a href="#count">count()</a> function to 2375 determine the number of items in any array.</p> 2376 2377 <p>Also inherent to the language is the fact that the type of the 2378 variable determines how certain basic operations will be carried 2379 out. For example:</p> 2380 <pre> 2381 $a = $b + $c; 2382</pre> 2383 2384 <p>can do a couple of different things. If $b is a number, the 2385 numerical value of $c is added to $b and the sum is stored in $a. 2386 In this case the type of $c is irrelevant. The operation is 2387 guided by the type of the first variable. If $b is a string, then 2388 the string value of $c is appended to $b and the resultant string 2389 is placed in $a. This also leads to some caveats. You should read 2390 the section on <a href="#overload">overloaded operators</a> to 2391 get a better understanding of how to deal with them.</p> 2392 <hr> 2393 2394 <h3><a name="assoc" id="assoc">Associative Arrays</a></h3> 2395 2396 <p>The previous section introduced associative arrays. An 2397 associative array is an array in which the index need not be a 2398 numerically sequential value. The array index can be any number 2399 or string. PHP/FI provides a set of functions to manipulate these 2400 associative arrays. These include, <a href="#next">Next()</a>, 2401 <a href="#prev">Prev()</a>,<a href="#reset">Reset()</a>,<a href= 2402 "#end">End()</a>, and <a href="#key">Key()</a>.</p> 2403 <hr> 2404 2405 <h3><a name="varvars" id="varvars">Variable Variables</a></h3> 2406 2407 <p>Sometimes it is convenient to be able to have variable 2408 variable names. That is, a variable name which can be set and 2409 used dynamically. A normal variable is set with a statement such 2410 as:</p> 2411 <pre> 2412 $a = "hello"; 2413</pre> 2414 2415 <p>A variable variable takes the value of a variable and treats 2416 that as the name of a variable. In the above example, 2417 <strong>hello</strong>, can be used as the name of a variable by 2418 using two dollar signs. ie.</p> 2419 <pre> 2420 $$a = "world"; 2421</pre> 2422 2423 <p>At this point two variables have been defined and stored in 2424 the PHP/FI symbol tree:</p> 2425 <pre> 2426 Variable Name Variable Content 2427 <em>a</em> <em>hello</em> 2428 <em>hello</em> <em>world</em> 2429</pre> 2430 2431 <p>Therefore, this statement:</p> 2432 <pre> 2433 echo "$a $$a"; 2434</pre> 2435 2436 <p>produces the exact same output as:</p> 2437 <pre> 2438 echo "$a $hello"; 2439</pre> 2440 2441 <p>ie. they both produce: <strong>hello world</strong></p> 2442 <hr> 2443 2444 <h3><a name="lang" id="lang">Language Constructs</a></h3> 2445 2446 <p>As far as language constructs are concerned, the PHP language 2447 is quite simple. The following commands are used to guide the 2448 control flow through a file:</p> 2449 2450 <ul> 2451 <li>if (condition)</li> 2452 2453 <li>else</li> 2454 2455 <li>elseif (condition)</li> 2456 2457 <li>endif</li> 2458 2459 <li>switch(expression)</li> 2460 2461 <li>case expression</li> 2462 2463 <li>default</li> 2464 2465 <li>break</li> 2466 2467 <li>endswitch</li> 2468 2469 <li>while</li> 2470 2471 <li>endwhile</li> 2472 2473 <li>include</li> 2474 2475 <li>exit</li> 2476 </ul> 2477 2478 <p>The syntax of conditions are similar to that of the C 2479 language. <strong>==</strong> tests for equality. 2480 <strong>!=</strong> means not equal. Also supported are: 2481 <strong>></strong>, <strong><</strong>, 2482 <strong>>=</strong>, <strong><=</strong>. Conditional AND 2483 is <strong>&&</strong>, conditional OR is 2484 <strong>||</strong>.</p> 2485 2486 <p>Examples:</p> 2487 <pre> 2488 <? 2489 if($a==5 && $b!=0 ); 2490 $c = 100 + $a / $b; 2491 endif; 2492 > 2493</pre> 2494 2495 <p>The above may also be written in standard C syntax:<br> 2496 In this case, there is no need for a semicolon after the closing 2497 curly brace.</p> 2498 <pre> 2499 <? 2500 if($a==5 && $b!=0) { 2501 $c = 100 + $a / $b; 2502 } 2503 > 2504</pre> 2505 2506 <p>There is no difference between the two syntaxes. I personally 2507 like to use endif, endswitch and endwhile so I explicitly know 2508 which construct I am ending. However, these ending constructs can 2509 always be replaced with a closing curly brace.</p> 2510 2511 <p>It is important to note that the flow of the language is not 2512 dependent on the organization of the script blocks within the 2513 code. You can start an if expression in one block and have the 2514 end of the expression in another. For example:</p> 2515 <pre> 2516 <?if($a==5 && $b!=0)> 2517 <b>Normal html text</b> 2518 <?endif> 2519</pre> 2520 2521 <p>In this example it is easy to see why it is sometimes more 2522 desirable to use the <code>endif</code> keyword as opposed to a 2523 closing brace. The above is much more readable than the 2524 following:</p> 2525 <pre> 2526 <?if($a==5 && $b!=0) {> 2527 <b>Normal html text</b> 2528 <? } > 2529</pre> 2530 2531 <p>Both version are valid and they will do exactly the same 2532 thing.</p> 2533 <hr> 2534 2535 <h3><a name="user_funcs" id="user_funcs">User-Defined 2536 Functions</a></h3> 2537 2538 <p>You may define a function within a PHP script with the 2539 following syntax:</p> 2540 <pre> 2541 <? 2542 Function Test ( 2543 echo "This is a test\n"; 2544 ); 2545 > 2546</pre> 2547 2548 <p>This function can now be called from anywhere in the script as 2549 long as the call comes after the function definition. A sample 2550 call might be:</p> 2551 <pre> 2552 <? 2553 Test(); 2554 > 2555</pre> 2556 2557 <p>User defined functions like this act exactly like PHP's 2558 internal functions in that you can pass arguments to them and 2559 have them return a value. Here is the syntax for a function 2560 definition of a function which takes 3 arguments and returns the 2561 sum of these arguments:</p> 2562 <pre> 2563 <? 2564 Function Sum $a,$b,$c ( 2565 return($a+$b+$c); 2566 ); 2567 2568 echo Sum($a,$b,$c); 2569 > 2570</pre> 2571 2572 <p>The <em>return</em> statement is used to return a value from 2573 the function. Only a single value can be returned using this 2574 mechanism, however, if more values need to be communicated back 2575 and forth between the main code and functions, global variables 2576 can be used. This brings us to the section on the scope of 2577 variables.</p> 2578 <hr> 2579 2580 <h3><a name="scope" id="scope">Scope of Variables</a></h3> 2581 2582 <p>The scope of a variable is the context within which it is 2583 defined. For the most part all PHP/FI variables only have a 2584 single scope. However, within user-defined functions a local 2585 function scope is introduced. Any variable used inside a function 2586 is by default limited to the local function scope. For 2587 example:</p> 2588 <pre> 2589 $a=1; /* global scope */ 2590 Function Test ( 2591 echo $a; /* reference to local scope variable */ 2592 ); 2593 Test(); 2594</pre> 2595 2596 <p>This script will not produce any output because the 2597 <em>echo</em> statement refers to a local version of the 2598 <em>$a</em> variable, and it has not been assigned a value within 2599 this scope. You may notice that this is a little bit different 2600 from the C language in that global variables in C are 2601 automatically available to functions unless specifically 2602 overridden by a local definition. This can cause some problems in 2603 that people may inadvertently change a global variable. In PHP/FI 2604 global variables must be declared global inside a function if 2605 they are going to be used in that function. An example:</p> 2606 <pre> 2607 $a=1; 2608 $b=2; 2609 Function Sum $first,$second ( 2610 global $a,$b; 2611 2612 $b = $a + $b; 2613 ); 2614 Sum(); 2615 echo $b; 2616</pre> 2617 2618 <p>The above script will output "3". By declaring $a and $b 2619 global within the function, all references to either variable 2620 will refer to the global version. There is no limit to the number 2621 of global variables that can be manipulated by a function. 2622 However, the variable must exist in the global scope prior to the 2623 function being called. You cannot create new global variables 2624 from within a function.</p> 2625 2626 <p>Another important feature of variable scoping is the 2627 <em>static</em> variable. A static variable exists only in a 2628 local function scope, but it does not lose its value when program 2629 execution leaves this scope. Consider the following example:</p> 2630 <pre> 2631 Function Test ( 2632 $a=0; 2633 echo $a; 2634 $a++; 2635 ); 2636</pre> 2637 2638 <p>This function is quite useless since every time it is called 2639 it sets $a to 0 and prints "0". The $a++ which increments the 2640 variable serves no purpose since as soon as the function exits 2641 the $a variable disappears. To make a useful counting function 2642 which will not lose track of the current count, the $a variable 2643 is declared static:</p> 2644 <pre> 2645 Function Test ( 2646 static $a=0; 2647 echo $a; 2648 $a++; 2649 ); 2650</pre> 2651 2652 <p>Now, every time the Test() function is called it will print 2653 the value of $a and increment it.</p> 2654 2655 <p>Static variables are also essential when functions are called 2656 recursively. A recursive function is one which calls itself. Care 2657 must be taken when writing a recursive function because it is 2658 possible to make it recurse indefinitely. You must make sure you 2659 have an adequate way of terminating the recursion. The following 2660 simple function recursively counts to 10:</p> 2661 <pre> 2662 Function Test ( 2663 static $count=0; 2664 2665 $count++; 2666 echo $count; 2667 if($count < 10) { 2668 Test(); 2669 } 2670 ); 2671</pre> 2672 <hr> 2673 2674 <h3><a name="math" id="math">Mathematical Expressions</a></h3> 2675 2676 <p>PHP supports full mathematical operations anywhere an 2677 expression is expected. Order of operations are taken into 2678 account. The following are the valid operators:</p> 2679 <pre> 2680 <? $a = 2 + 1 > <em>Addition</em> 2681 <? $a = 2 - 1 > <em>Subtraction</em> 2682 <? $a = 2 * 1 > <em>Multiplication</em> 2683 <? $a = 2 / 1 > <em>Division</em> 2684 <? $a = 2 % 1 > <em>Modulus</em> 2685 <? $a = 2 ^ 1 > <em>Bit-wise Exclusive OR</em> 2686</pre> 2687 2688 <p>Both bracketing and order of operations is supported, so the 2689 following is valid:</p> 2690 <pre> 2691 <?$a = (2+1)*3+6/3> 2692</pre> 2693 2694 <p>The C-like incremental operators <code>+=</code> and <code>-=</code> 2695 are supported. ie.</p> 2696 <pre> 2697 <? $a += $b> 2698</pre> 2699 2700 <p>This is equivalent to:</p> 2701 <pre> 2702 <? $a = $a + $b> 2703</pre> 2704 2705 <p>The C-like bit-wise operators <code>&=</code>, <code>|=</code> and 2706 <code>^=</code> are supported. ie.</p> 2707 <pre> 2708 <? $a &= 4> 2709</pre>This is equivalent to: 2710 <pre> 2711 <? $a = $a & 4> 2712</pre> 2713 <hr> 2714 2715 <h3><a name="while" id="while">While Loops</a></h3> 2716 2717 <p>You can loop within a PHP script by using the <em>while(); 2718 endwhile;</em> construct.</p> 2719 <pre> 2720 <? 2721 $a=0; 2722 while($a<100) { 2723 $a++; 2724 echo $list[$a]; 2725 } 2726 > 2727</pre> 2728 2729 <p>The above example shows the use of a while loop to display the 2730 contents of an array. <strong>WARNING</strong> although the PHP 2731 language supports incremental operators such as 2732 <strong>++</strong> and <strong>-<!>-</strong> to increment 2733 and decrement a variable, they are not treated exactly like they 2734 would be in the C language. The variable is incremented right 2735 away. There is no concept of incrementing the variable before or 2736 after the operation as there is in C.</p> 2737 2738 <p>As explained in the <a href="#lang">Language Constructs</a> 2739 section above, the same can be obtained with <em>while(); 2740 endwhile;</em>.</p> 2741 <hr> 2742 2743 <h3><a name="switch" id="switch">Switch Construct</a></h3> 2744 2745 <p>PHP supports a switch construct very similar to the C 2746 equivalent.</p> 2747 <pre> 2748 <? 2749 $a=0; 2750 switch($a) { 2751 case 1; 2752 echo "a is 1"; 2753 break; 2754 case "hello"; 2755 echo "a is hello"; 2756 break; 2757 default; 2758 echo "a is unknown"; 2759 break; 2760 } 2761 > 2762</pre> 2763 2764 <p>The above is an example of a switch construct. It is similar 2765 to a series of if/elseif/else constructs but easier to read. The 2766 only difference between the PHP switch construct and that of the 2767 C language is that semi-colons are used to terminate every line. 2768 There are no colons.</p> 2769 2770 <p>As explained in the <a href="#lang">Language Constructs</a> 2771 section above, the same can be obtained with <em>switch(); 2772 endswitch;</em>.</p> 2773 2774 <p>All of these constructs can of course be nested and used 2775 inside each other just like C. The various files in the 2776 <em>examples</em> directory of the PHP distribution should 2777 provide a good starting point for learning the language.</p> 2778 <hr> 2779 2780 <h3><a name="secure" id="secure">Secure Variables - Defeating GET 2781 method hacks</a></h3> 2782 2783 <p>A previous section talked about GET and POST method data and 2784 variables. If you think about it, you may be able to envision a 2785 security issue. For example, if on a web page I have obtained 2786 some data from a database and I pass this data along in a 2787 variable called "data" in a POST method form. In the ensuing page 2788 I can access this variable and do something with it. However, if 2789 someone accessed this second page directly and put a 2790 "?data=something" right in the URL thereby doing a GET method 2791 variable set, they have effectively circumvented the original 2792 POST method form.</p> 2793 2794 <p>PHP provides a <em>SecureVar()</em> function which is used to 2795 mark variables names as being secure variables. These secure 2796 variables can only be set directly in a PHP script, or they can 2797 come from a POST method form. They cannot be set using the GET 2798 method variable definition mechanism. From our above scenario, if 2799 we placed the line:</p> 2800 <pre> 2801 <?SecureVar("data")> 2802</pre> 2803 2804 <p>Near the beginning of our second page, then the GET method 2805 trick would not work. The "data" variable would appear to be 2806 empty unless it came directly from the POST method form on the 2807 first page.</p> 2808 2809 <p>The <em>SecureVar()</em> actually takes a regular expression 2810 as its argument, so you can mark patterns of variable names that 2811 should be treated in this secure manner. For example,</p> 2812 <pre> 2813 <?SecureVar(".*data.*")> 2814</pre> 2815 2816 <p>Would mark any variable with the word "data" anywhere in their 2817 name as being secure.</p> 2818 2819 <p>Please note that POST-method forms are not intrinsically 2820 secure. People can emulate the posting of any data to a form by 2821 simply telnetting to the HTTP port on your system. You need to 2822 take appropriate security measures to stop people from doing this 2823 if in fact security is a concern.</p> 2824 <hr> 2825 2826 <h3><a name="overload" id="overload">Overloaded Operators and 2827 dealing with variable types</a></h3>An overloaded operator is an 2828 operator like '+' for example which can do different things based 2829 on the types of the expressions it is asked to operate on. 2830 2831 <p>The problem is that PHP understands 3 variable types. Integer, 2832 Double and String. When a variable is first assigned, PHP 2833 automatically figures out the variable type.</p> 2834 2835 <p>ie.</p> 2836 <pre> 2837 $a = 1; Type would be integer 2838 $b = 1.5; Type would be double 2839 $c = "1"; Type would be string 2840</pre> 2841 2842 <p>Now, what happens when you do something like:</p> 2843 <pre> 2844 $d = $a + $c; 2845</pre> 2846 2847 <p>The parser looks at the first part of the arithmetic 2848 expression and uses that to type the result and thus also the 2849 nature of the arithmetic that is to be done. In the above case 2850 since $a is an integer, $d will be an integer and an integer 2851 addition is done giving the result:</p> 2852 <pre> 2853 $d = 2 Type is integer 2854</pre> 2855 2856 <p>Therefore:</p> 2857 <pre> 2858 $d = $c + $a 2859</pre> 2860 2861 <p>Results in:</p> 2862 <pre> 2863 $d = "11" Type is string 2864</pre> 2865 2866 <p>The above makes sense to me, and once you understand it, it is 2867 probably workable. However, when more complex expressions are 2868 used it can get extremely confusing.</p> 2869 2870 <p>The solution is a simple type casting mechanism. In reality 2871 all variables are automatically converted to all 3 types, and an 2872 internal flag just marks what type the variable actually is. So, 2873 when I say:</p> 2874 <pre> 2875 $a = 1; 2876</pre> 2877 2878 <p>Internally in the symbol table I store 3 versions.</p> 2879 <pre> 2880 Integer: 1 <-- flag 2881 Double : 1.0 2882 String : "1" 2883</pre> 2884 2885 <p>The <em>SetType()</em> function can move this flag indicating 2886 the type of the variable.</p> 2887 <pre> 2888 SetType($a,"double"); 2889</pre> 2890 2891 <p>This would force $a to be treated as a double from then 2892 on.</p> 2893 2894 <p>The <em>GetType()</em> function returns the type. 2895 <code>GetType($a)</code> would return "double" in this case.</p> 2896 2897 <p>Functions also exist to return the 3 various types without 2898 moving the type flag.</p> 2899 <pre> 2900 IntVal($a) returns 1 2901 DoubleVal($a) returns 1.0 2902 StrVal($a) returns "1" 2903</pre> 2904 2905 <p>This doesn't change the overloaded operator nature of the PHP 2906 variables, but it does give you some tools to better deal with 2907 them. PHP is not not a full-fledged Perl look-alike. It has to be 2908 small and fast. Perl deals with the overloaded operator pitfall 2909 by forcing something like the '+' operator to only work on 2910 numbers. If you want to add strings, you must use the '.' 2911 operator. Once you start having separate operators for each type 2912 you start making the language much more complex. ie. you can't 2913 use '==' for stings, you now would use 'eq'. I don't see the 2914 point, especially for something like PHP where most of the 2915 scripts will be rather simple and in most cases written by 2916 non-programmers who want a language with a basic logical syntax 2917 that doesn't have too high a learning curve.</p> 2918 <hr> 2919 2920 <h3><a name="quiet" id="quiet">Suppressing Errors from function 2921 calls</a></h3> 2922 2923 <p>It may be desirable in certain circumstances to ignore fatal 2924 errors which may be reported by specific PHP functions. For 2925 example, you may want to ignore errors from a dbmopen() call and 2926 simply check the return value of the call without having error 2927 messages appear on the web screen. This can be done by putting 2928 the "@" character in front of the function call. ie.</p> 2929 <pre> 2930 $err_code = @dbmopen($filename,"w"); 2931</pre> 2932 2933 <p>The actual error message that would have been printed can be 2934 checked by looking at the PHP internal variable, 2935 <strong>$phperrmsg</strong>.</p> 2936 2937 <p>A more general approach to suppress error message printing is 2938 to use the <a href="#seterrorreporting">SetErrorReporting()</a> 2939 function. With this function error printing can be disabled for 2940 entire blocks of code by preceding the block with a call 2941 like:</p> 2942 <pre> 2943 SetErrorReporting(0); 2944</pre> 2945 2946 <p>This turns off all errors. They can then be re-enabled later 2947 with:</p> 2948 <pre> 2949 SetErrorReporting(1); 2950</pre> 2951 <hr> 2952 2953 <h3><a name="funcs" id="funcs">Internal 2954 Functions</a></h3><a href="function"></a> 2955 2956 <p>PHP has a number of built-in functions. Functions are called 2957 in the same manner as they are called in the C language. Some 2958 take one or more arguments, and some return values which can then 2959 be assigned to a variable or used as an argument to another 2960 function. For example:</p> 2961 <pre> 2962 <?$t=time()> 2963</pre> 2964 2965 <p>This assigns the return value of the <em>time()</em> function 2966 to the <em>t</em> variable.</p> 2967 2968 <h3>Alphabetical List of Functions</h3> 2969 2970 <dl> 2971 <dt><a name="abs" id="abs"><span class="big">Abs(arg)</span></a></dt> 2972 2973 <dd> 2974 <p>Abs returns the absolute value of arg.</p> 2975 </dd> 2976 2977 <dt><a name="ada_close" id="ada_close"><span class="big">Ada_Close(connection_id)</span></a></dt> 2978 2979 <dd> 2980 <p>Ada_Close will close down the connection to the Adabas 2981 server associated with the given connection identifier.</p> 2982 2983 <p>This function is only available if Adabas support has been 2984 enabled in PHP.</p> 2985 </dd> 2986 2987 <dt><a name="ada_connect" id="ada_connect"><span class="big">$connection = Ada_Connect(data source name, username, 2988 password)</span></a></dt> 2989 2990 <dd> 2991 <p>Ada_Connect opens a connection to a Adabas server. Each of 2992 the arguments should be a quoted string. The first parameter 2993 (data source name) is a string in the form 2994 "servername:databasename". The servername (but not the colon) 2995 can be omitted if you want to access a local database. This 2996 function returns a connection_id. This identifier is needed 2997 by other Adabas functions. You can have multiple connections 2998 open at once. This function will return <strong>0</strong> on 2999 error.</p> 3000 3001 <p>This function is only available if Adabas support has been 3002 enabled in PHP.</p> 3003 </dd> 3004 3005 <dt><a name="ada_exec" id="ada_exec"><span class="big">$result = 3006 Ada_Exec(connection_id, query_string)</span></a></dt> 3007 3008 <dd> 3009 <p>Ada_Exec will send an SQL statement to the Adabas server 3010 specified by the connection_id. The connection_id must be a 3011 valid identifier that was returned by Ada_Connect or the 3012 special value <strong>0</strong>. If connection_id is 0, 3013 ada_exec tries to establish or to use a connection with the 3014 parameters given with the <a href="#directives">configuration 3015 directives</a> <em>phpAdaDefDB, phpAdaUser</em> and 3016 <em>phpAdaPW</em>.<br> 3017 The return value of this function is an identifier to be used 3018 to access the results by other Adabas functions. This 3019 function will return <strong>0</strong> on error. It will 3020 return <strong>1</strong> when the command executed correctly 3021 but is not expected to return data (insert or update 3022 commands, for example). Note that selects which return no 3023 data will still return a valid result greater than 1.</p> 3024 3025 <p>This function is only available if Adabas support has been 3026 enabled in PHP.</p> 3027 </dd> 3028 3029 <dt><a name="ada_fetchrow" id="ada_fetchrow"><span class="big">Ada_FetchRow(result_id [,row_number])</span></a></dt> 3030 3031 <dd> 3032 <p>Ada_FetchRow fetches a row of the data that was returned 3033 by Ada_Exec. After Ada_FetchRow is called, the fields of that 3034 row can be access with Ada_Result. If no rownumber is given, 3035 Ada_FetchRow will try to fetch the next row in the result 3036 set. Every time Ada_FetchRow is called a new row can be 3037 accessed by Ada_Result. If Ada_FetchRow was succesful (there 3038 was a row), <strong>1</strong> is returned, if there are no 3039 more rows, Ada_FetchRow will return <strong>0</strong>. The 3040 return value of Ada_FetchRow can be used as the condition of 3041 a while loop. Calls to Ada_FetchRow() with and without 3042 rownumber can be mixed. To step through the result more than 3043 once, you can call Ada_FetchRow() with rownumber 1 and then 3044 continue with Ada_FetchRow() without rownumber to review the 3045 result.</p> 3046 3047 <p>This function is only available if Adabas support has been 3048 enabled in PHP.</p> 3049 </dd> 3050 3051 <dt><a name="ada_fieldname" id="ada_fieldname"><span class="big">Ada_FieldName(result_id, field_number)</span></a></dt> 3052 3053 <dd> 3054 <p>Ada_FieldName will return the name of the field occupying 3055 the given column number in the given Adabas result 3056 identifier. Field numbering starts from 0.</p> 3057 3058 <p>This function is only available if Adabas support has been 3059 enabled in PHP.</p> 3060 </dd> 3061 3062 <dt><a name="ada_fieldnum" id="ada_fieldnum"><span class="big">Ada_FieldNum(result_id, field_name)</span></a></dt> 3063 3064 <dd> 3065 <p>Ada_FieldNum will return the number of the column slot 3066 that corresponds to the named field in the given Adabas 3067 result identifier. Field numbering starts at 0. This function 3068 will return <strong>-1</strong> on error.</p> 3069 3070 <p>This function is only available if Adabas support has been 3071 enabled in PHP.</p> 3072 </dd> 3073 3074 <dt><a name="ada_fieldtype" id="ada_fieldtype"><span class="big">Ada_FieldType(result_id, 3075 field_name|field_number)</span></a></dt> 3076 3077 <dd> 3078 <p>Ada_FieldType will return the SQL type of the field 3079 referecend by name or number in the given Adabas result 3080 identifier. Note: Field numbering starts from 0.</p> 3081 3082 <p>This function is only available if Adabas support has been 3083 enabled in PHP.</p> 3084 </dd> 3085 3086 <dt><a name="ada_freeresult" id="ada_freeresult"><span class="big">Ada_FreeResult(result_id)</span></a></dt> 3087 3088 <dd> 3089 <p>Ada_FreeResult only needs to be called if you are worried 3090 about using too much memory while your script is running. All 3091 result memory will automatically be freed when the script is 3092 finished. But, if you are sure you are not going to need the 3093 result data anymore in a script, you may call Ada_FreeResult 3094 with the result identifier as an argument and the associated 3095 result memory will be freed.</p> 3096 3097 <p>This function is only available if Adabas support has been 3098 enabled in PHP.</p> 3099 </dd> 3100 3101 <dt><a name="ada_numfields" id="ada_numfields"><span class="big">Ada_NumFields(result_id)</span></a></dt> 3102 3103 <dd> 3104 <p>Ada_NumFields will return the number of fields (columns) 3105 in a Adabas result. The argument is a valid result identifier 3106 returned by Ada_Exec. This function will return 3107 <strong>-1</strong> on error.</p> 3108 3109 <p>This function is only available if Adabas support has been 3110 enabled in PHP.</p> 3111 </dd> 3112 3113 <dt><a name="ada_numrows" id="ada_numrows"><span class="big">Ada_NumRows(result_id)</span></a></dt> 3114 3115 <dd> 3116 <p>Ada_NumRows will return the number of rows in a Adabas 3117 result. The argument is a valid result identifier returned by 3118 Ada_Exec. This function will return <strong>-1</strong> on 3119 error. For INSERT, UPDATE, DELETE statements Ada_NumRows() 3120 returns the number of rows affected. For a SELECT clause this 3121 is the number of rows available.</p> 3122 3123 <p>This function is only available if Adabas support has been 3124 enabled in PHP.</p> 3125 </dd> 3126 3127 <dt><a name="ada_result" id="ada_result"><span class="big">Ada_Result(result_id, field name | index)</span></a></dt> 3128 3129 <dd> 3130 <p>Ada_Result will return values from a result identifier 3131 produced by Ada_Exec. The field name specify what cell in the 3132 row to return. Instead of naming the field, you may use the 3133 field index as an unquoted number. Field indices start from 3134 0. If the requested field is of code type BYTE (binary) or is 3135 longer than 4096 bytes, the contents is sent directly to the 3136 client. Hint: [VAR]CHAR BYTE fields can be returned into a 3137 php variable by using the HEX() db function; e. g. SELECT 3138 HEX(SYSKEY) SYSKEY FROM MYTABLE.</p> 3139 3140 <p>This function is only available if Adabas support has been 3141 enabled in PHP.</p> 3142 </dd> 3143 3144 <dt><a name="ada_resultall" id="ada_resultall"><span class="big">Ada_ResultAll(result_id [,format])</span></a></dt> 3145 3146 <dd> 3147 <p>Ada_ResultAll will print all rows from a result identifier 3148 produced by Ada_Exec. The result is printed in HTML table 3149 format. With the optional formatstring additional overall 3150 table formatting can be done (e. g. bgcolor= will set 3151 background color, >caption> </caption to set 3152 caption). Note: The contents of "format" will be inserted 3153 into the HTML table tag like this <table format 3154 >...</p> 3155 3156 <p>This function is only available if Adabas support has been 3157 enabled in PHP.</p> 3158 </dd> 3159 3160 <dt><a name="addslashes" id="addslashes"><span class="big">AddSlashes(arg)</span></a></dt> 3161 3162 <dd> 3163 <p>Escapes any $ \ or ' (if MAGIC_QUOTES is set) with a 3164 backslash. See also <a href= 3165 "#stripslashes">StripSlashes()</a>.</p> 3166 </dd> 3167 3168 <dt><a name="asort" id="asort"><span class="big">ASort(array)</span></a></dt> 3169 3170 <dd> 3171 <p>Sort is used to sort a PHP associative array in ascending 3172 order. Use ARSort() for descending order. Unlike the <a href= 3173 "#sort">Sort()</a> function, ASort() maintains index-value 3174 pairings. It understands the three variable types and will 3175 sort alphabetically if the array contains strings, and 3176 numerically if the array contains numbers. In the case of an 3177 array which contains a mixture of types, the first type in 3178 the array will specify the sort method. Note that if you are 3179 going to sort a non-associative array, you should use the 3180 <a href="#sort">Sort()</a> function.</p> 3181 </dd> 3182 3183 <dt><a name="bindec" id="bindec"><span class="big">BinDec(binary_string)</span></a></dt> 3184 3185 <dd> 3186 <p>BinDec returns the decimal equivalent of the binary number 3187 represented by the binary_string argument. The largest number 3188 that can be converted is 31 bits long or 4294967295 in 3189 decimal. See also the <a href="#decbin">DecBin()</a> 3190 function.</p> 3191 </dd> 3192 3193 <dt><a name="ceil" id="ceil"><span class="big">Ceil(value)</span></a></dt> 3194 3195 <dd> 3196 <p>Ceil() rounds a floating point value up to the next 3197 integer. The return value is of type double (floating point) 3198 such that it can be used properly in complex equations. To 3199 get an integer type back, use: <code>$new = 3200 IntVal(Ceil($value));</code><br> 3201 See also <a href="#floor">Floor()</a>.</p> 3202 </dd> 3203 3204 <dt><a name="chdir" id="chdir"><span class="big">ChDir(dir)</span></a></dt> 3205 3206 <dd> 3207 <p>ChDir changes the current working directory to the 3208 directory specified in the argument.</p> 3209 </dd> 3210 3211 <dt><a name="chgrp" id="chgrp"><span class="big">ChGrp(file,group)</span></a></dt> 3212 3213 <dd> 3214 <p>ChGrp changes the group id of the specified file.</p> 3215 </dd> 3216 3217 <dt><a name="chmod" id="chmod"><span class="big">ChMod(file,perms)</span></a></dt> 3218 3219 <dd> 3220 <p>ChMod changes the file permissions of the specified file. 3221 The <em>perms</em> parameter must be specified in <a href= 3222 "#octal">octal</a> notation. eg. ChMod($filename,0755)</p> 3223 </dd> 3224 3225 <dt><a name="chown" id="chown"><span class="big">ChOwn(file,owner)</span></a></dt> 3226 3227 <dd> 3228 <p>ChOwn changes the specified file to be owned by the 3229 specified owner. Note that this will only work if the PHP/FI 3230 binary is running as root (which is not generally a good 3231 idea).</p> 3232 </dd> 3233 3234 <dt><a name="chop" id="chop"><span class="big">Chop(string)</span></a></dt> 3235 3236 <dd> 3237 <p>Chop removes all trailing whitespaces including new-lines, 3238 tabs and spaces and returns the new string.</p> 3239 </dd> 3240 3241 <dt><a name="chr" id="chr"><span class="big">Chr(arg)</span></a></dt> 3242 3243 <dd> 3244 <p>Chr returns the ASCII character represented by the integer 3245 argument.</p> 3246 </dd> 3247 3248 <dt><a name="clearstack" id="clearstack"><span class="big">ClearStack()</span></a></dt> 3249 3250 <dd> 3251 <p>The ClearStack() function is a hack/workaround for a 3252 deficiency in the PHP parser. This dificiency is that PHP 3253 only has a single expression stack. When inside a 3254 user-defined function this expression stack is never cleared 3255 because its contents may be needed within a complex 3256 expression in the context from which the user-defined 3257 function was called. This means that if you have a while loop 3258 with a lot of iterations inside a user-defined function, you 3259 may be chewing up a lot of stack space. You may even be 3260 hitting the max data space limit. You can put a call to 3261 ClearStack() inside your while loop to prevent this memory 3262 consumption, but the trade-off is that you cannot use your 3263 function within any sort of context. ie. you have to assign 3264 the output of the function to a temporary variable and then 3265 use this temporary variable in whatever context you need.</p> 3266 </dd> 3267 3268 <dt><a name="clearstatcache" id="clearstatcache"><span class="big"> 3269 ClearStatCache()</span></a></dt> 3270 3271 <dd> 3272 <p>The stat() system call is normally an expensive operation 3273 on most operating systems. In order to make sure that 3274 repeated calls to the various File* functions like <a href= 3275 "#fileperms">FilePerms()</a>, <a href= 3276 "#fileinode">FileInode()</a>, etc. the result of the last 3277 stat() call is always cached. If one of the File* functions 3278 is called again with the same argument, the cached stat() 3279 result will be used. In order to force a new stat() system 3280 call this ClearStatCache() function may be called to clear 3281 the cached stat() result.</p> 3282 </dd> 3283 3284 <dt><a name="closedir" id="closedir"><span class="big"> 3285 closeDir()</span></a></dt> 3286 3287 <dd> 3288 <p>closeDir closes a directory opened using the <a href= 3289 "#opendir">openDir</a> function.</p> 3290 </dd> 3291 3292 <dt><a name="closelog" id="closelog"><span class="big"> 3293 CloseLog()</span></a></dt> 3294 3295 <dd> 3296 <p>CloseLog() closes the descriptor Syslog() uses to write to 3297 the system logger. See the closelog(3) UNIX man page for more 3298 details. See also <a href="#syslog">Syslog()</a>, <a href= 3299 "#openlog">OpenLog()</a> and <a href= 3300 "#initsyslog">InitSyslog()</a>.</p> 3301 </dd> 3302 3303 <dt><a name="cos" id="cos"><span class="big"> 3304 Cos(arg)</span></a></dt> 3305 3306 <dd> 3307 <p>Cos returns the cosine of arg in radians. See also 3308 <a href="#sin">Sin()</a> and <a href="#tan">Tan()</a></p> 3309 </dd> 3310 3311 <dt><a name="count" id="count"><span class="big"> 3312 Count(array)</span></a></dt> 3313 3314 <dd> 3315 <p>Count returns the number of items in an array variable. If 3316 the variable is not an array, the return value will be 1 3317 (because a normal variable is similar to an array with only 3318 one item). If the variable is not defined, the return value 3319 will be 0.</p> 3320 </dd> 3321 3322 <dt><a name="crypt" id="crypt"><span class="big"> 3323 Crypt(string,[salt])</span></a></dt> 3324 3325 <dd> 3326 <p>Crypt will encrypt a string using the standard Unix DES 3327 encryption method. Arguments are a string to be encrypted and 3328 an optional two-character salt string to base the encryption 3329 on. See the Unix man page for your crypt function for more 3330 information. If you do not have a crypt function on your Unix 3331 system, you can use Michael Glad's public domain UFC-Crypt 3332 package which was developed in Denmark and hence not 3333 restricted by US export laws as long as you ftp it from an 3334 non-US site.</p> 3335 </dd> 3336 3337 <dt><a name="date" id="date"><span class="big"> 3338 Date(format,time)</span></a></dt> 3339 3340 <dd> 3341 <p>The Date function is used to display times and dates in 3342 various ways. The function takes a format string and a time 3343 as arguments. If the time argument is left off, the current 3344 time and date will be used. The time argument is specified as 3345 an integer in number of seconds since the Unix Epoch on Jan.1 3346 1970. The format string is used to indicate which date/time 3347 components should be displayed and how they should be 3348 formatted. The following characters are recognized within the 3349 format string. Any unrecognized character is printed 3350 verbosely:</p> 3351 3352 <ul> 3353 <li><code>Y - Year eg. 1995</code></li> 3354 3355 <li><code>y - Year eg. 95</code></li> 3356 3357 <li><code>M - Month eg. Oct</code></li> 3358 3359 <li><code>m - Month eg. 10</code></li> 3360 3361 <li><code>F - Month eg. October</code></li> 3362 3363 <li><code>D - Day eg. Fri</code></li> 3364 3365 <li><code>l - Day eg. Friday</code></li> 3366 3367 <li><code>d - Day eg. 27</code></li> 3368 3369 <li><code>z - Day of the year eg. 299</code></li> 3370 3371 <li><code>H - Hours in 24 hour format eg. 13</code></li> 3372 3373 <li><code>h - Hours in 12 hour format eg. 1</code></li> 3374 3375 <li><code>i - Minutes eg. 5</code></li> 3376 3377 <li><code>s - Seconds eg. 40</code></li> 3378 3379 <li><code>U - Seconds since epoch eg. 814807830</code></li> 3380 3381 <li><code>A - AM/PM</code></li> 3382 3383 <li><code>a - am/pm</code></li> 3384 </ul> 3385 3386 <p>See also the <a href="#mktime">MkTime()</a> function.</p> 3387 </dd> 3388 3389 <dt><a name="dblist" id="dblist"><span class="big"> 3390 dbList()</span></a></dt> 3391 3392 <dd> 3393 <p>dbList outputs information about the db support compiled 3394 into PHP.</p> 3395 </dd> 3396 3397 <dt><a name="dbmclose" id="dbmclose"><span class="big"> 3398 dbmClose(filename)</span></a></dt> 3399 3400 <dd> 3401 <p>dbmClose simply closes the specified dbm file. It will 3402 also unlock any lock files, so it is important to close any 3403 dbm files that have been opened.</p> 3404 </dd> 3405 3406 <dt><a name="dbmdelete" id="dbmdelete"><span class="big"> 3407 dbmDelete(filename,key)</span></a></dt> 3408 3409 <dd> 3410 <p>dbmDelete will delete the key/content pair specified by 3411 the given key argument.</p> 3412 </dd> 3413 3414 <dt><a name="dbmexists" id="dbmexists"><span class="big"> 3415 dbmExists(filename,key)</span></a></dt> 3416 3417 <dd> 3418 <p>dbmExists will return 1 if the key exists and 0 3419 otherwise.</p> 3420 </dd> 3421 3422 <dt><a name="dbmfetch" id="dbmfetch"><span class="big"> 3423 dbmFetch(filename,key)</span></a></dt> 3424 3425 <dd> 3426 <p>dbmFetch will return the content string associated with 3427 the given key.</p> 3428 </dd> 3429 3430 <dt><a name="dbmfirstkey" id="dbmfirstkey"><span class="big"> 3431 dbmFirstKey(filename)</span></a></dt> 3432 3433 <dd> 3434 <p>dbmFirstKey returns the first key in the dbm file. Note 3435 that no particular order is guaranteed since the order 3436 depends on hash table values calculated within the dbm 3437 implementation. You may use the <a href="#sort">Sort</a> 3438 function to sort arrays of data from the dbm file if 3439 necessary.</p> 3440 </dd> 3441 3442 <dt><a name="dbminsert" id="dbminsert"><span class="big"> 3443 dbmInsert(filename,key,content)</span></a></dt> 3444 3445 <dd> 3446 <p>dbmInsert inserts a new key/content data pair into a dbm 3447 file. If the key already exists, the insert will fail.</p> 3448 </dd> 3449 3450 <dt><a name="dbmnextkey" id="dbmnextkey"><span class="big"> 3451 dbmNextKey(filename,key)</span></a></dt> 3452 3453 <dd> 3454 <p>dbmNextKey returns the next key after the specified key. 3455 By calling <strong>dbmfirstkey()</strong> followed by 3456 successive calls to <strong>dbmnextkey()</strong> it is 3457 possible to visit every key/content pair in the dbm file.</p> 3458 </dd> 3459 3460 <dt><a name="dbmopen" id="dbmopen"><span class="big"> 3461 dbmOpen(filename,mode)</span></a></dt> 3462 3463 <dd> 3464 <p>dbmOpen() opens a dbm file. The first argument is the 3465 full-path filename of the dbm file to be opened and the 3466 second is the file open mode which is one of <b>"r"</b>, 3467 <b>"n"</b> or <b>"w"</b> for read, new (implies write) and 3468 write respectively. If ndbm support is used, ndbm will 3469 actually create <em>filename.dir</em> and 3470 <em>filename.pag</em> files. gdbm only uses one file, as does 3471 the internal flat ascii file support, and Berkeley's libdb 3472 create a <em>filename.db</em> file. Note that PHP does its 3473 own file locking in addition to any file locking that may be 3474 done by the dbm library itself. PHP does not delete the 3475 <em>.lck</em> files it creates. It uses these files simply as 3476 fixed inodes on which to do the file locking. For more 3477 information on dbm files, see your Unix man pages, or obtain 3478 GNU's gdbm from <a href= 3479 "ftp://prep.ai.mit.edu/pub/gnu">ftp://prep.ai.mit.edu/pub/gnu</a>.</p> 3480 </dd> 3481 3482 <dt><a name="dbmreplace" id="dbmreplace"><span class="big"> 3483 dbmReplace(filename,key,content)</span></a></dt> 3484 3485 <dd> 3486 <p>dbmReplace is similar to the <strong>dbminsert()</strong> 3487 function, the only difference being that if the key already 3488 exists, the old content string will be replaced with the 3489 new.</p> 3490 </dd> 3491 3492 <dt><a name="decbin" id="decbin"><span class="big"> 3493 DecBin(number)</span></a></dt> 3494 3495 <dd> 3496 <p>DecBin returns a string containing a binary representation 3497 of the given number argument. The largest number that can be 3498 converted is 31 bits long or 4294967295 in decimal. See also 3499 the <a href="#bindec">BinDec()</a> function.</p> 3500 </dd> 3501 3502 <dt><a name="dechex" id="dechex"><span class="big"> 3503 DecHex(number)</span></a></dt> 3504 3505 <dd> 3506 <p>DecHex converts a decimal number to a hexadecimal string. 3507 See also the <a href="#hexdec">HexDec()</a> function.</p> 3508 </dd> 3509 3510 <dt><a name="decoct" id="decoct"><span class="big"> 3511 DecOct(number)</span></a></dt> 3512 3513 <dd> 3514 <p>DecOct converts a decimal number to an octal number. See 3515 also <a href="#octdec">OctDec()</a>.</p> 3516 </dd> 3517 3518 <dt><a name="doubleval" id="doubleval"><span class="big"> 3519 doubleval(variable)</span></a></dt> 3520 3521 <dd> 3522 <p>doubleval returns the double (floating point) value of the 3523 variable. See also the <a href="#strval">strval()</a> and 3524 <a href="#intval">intval()</a> functions.</p> 3525 </dd> 3526 3527 <dt><a name="echo" id="echo"><span class="big">Echo 3528 [format_string] expression [, expression 3529 [,...]]</span></a></dt> 3530 3531 <dd> 3532 <p>Echo is not a function. ie. you do not put brackets around 3533 the arguments to it. It is used to display results of PHP 3534 functions or PHP variables. See the <a href="#escapes">Escape 3535 Character Section</a> for a list of special characters 3536 supported. The format_string is optional and if not present, 3537 no output formatting will be done. The format string is 3538 similar to the format string of the C <em>printf</em> 3539 function. See the man page for <em>printf</em> for more 3540 details. Up to 5 expressions can be printed with a single 3541 echo command. If you try to print more you will get a parser 3542 error. Note that the types of the expressions are not 3543 relevant. The expressions are automagically converted to the 3544 appropriate types as specified by the format string if one is 3545 present. If you want to format something and assign the 3546 formatted string to a variable instead of displaying it, use 3547 the <a href="#sprintf">sprintf()</a> function.</p> 3548 3549 <p>The following conversions are supported,</p> 3550 3551 <blockquote> 3552 <dl> 3553 <dt>%d %i</dt> 3554 3555 <dd>Print a signed decimal number.</dd> 3556 3557 <dt>%o</dt> 3558 3559 <dd>Print an octal number.</dd> 3560 3561 <dt>%u</dt> 3562 3563 <dd>Print an unsigned decimal number.</dd> 3564 3565 <dt>%x %X</dt> 3566 3567 <dd>Print a hexadecimal number.</dd> 3568 3569 <dt>%f</dt> 3570 3571 <dd>Print a floating-point number.</dd> 3572 3573 <dt>%e %E</dt> 3574 3575 <dd>Print a floating-point number in scientific 3576 notation.</dd> 3577 3578 <dt>%g %G</dt> 3579 3580 <dd>Print a floating-point number in scientific notation 3581 or normal notation, as appropriate.</dd> 3582 3583 <dt>%c</dt> 3584 3585 <dd>Print a single character.</dd> 3586 3587 <dt>%s</dt> 3588 3589 <dd>Print a string of characters.</dd> 3590 3591 <dt>%%</dt> 3592 3593 <dd>Print a literal percent-sign.</dd> 3594 </dl> 3595 3596 <p>The following flags are accepted.</p> 3597 3598 <dl> 3599 <dt>'-'</dt> 3600 3601 <dd>Left-justify the output within the field-width.</dd> 3602 3603 <dt>'+'</dt> 3604 3605 <dd>Ensure that all integers are signed (with a 3606 plus/minus sign).</dd> 3607 3608 <dt>' '</dt> 3609 3610 <dd>Similar to '+', but uses a space instead of a 3611 plus-sign.</dd> 3612 3613 <dt>'#'</dt> 3614 3615 <dd>Print prefixes in front of hex and octal numbers 3616 designating them as such.</dd> 3617 3618 <dt>'''</dt> 3619 3620 <dd>Separate the digits into groups (usually 3621 comma-separated groups of three).</dd> 3622 3623 <dt>'0'</dt> 3624 3625 <dd>Pad the field-width with zeros.</dd> 3626 </dl> 3627 3628 <p>All of these flags are dependent upon whether or not 3629 your C library's printf function supports them (the ''', 3630 for example, is a GNU extension).</p> 3631 3632 <p>Most conversions will accept a field width and a 3633 precision, as shown in the <code>demo_echo.html</code> file in 3634 the directory /examples. It is not necessary to specify any 3635 type modifiers, and, in fact, PHP will complain if the type 3636 modifier does not make sense (which is almost always the 3637 case). PHP will complain about (and refuse to accept) 3638 anything that it does not recognize. Any extra arguments 3639 given that are not required by the format-string are 3640 ignored.</p> 3641 </blockquote> 3642 </dd> 3643 3644 <dt><a name="end" id="end"><span class="big"> 3645 End(variable)</span></a></dt> 3646 3647 <dd> 3648 <p>End moves the internal array pointer for the given 3649 variable to the last item of the array and returns the value 3650 of this item. This is useful for traversing an associative 3651 array in reverse order. See also <a href="#reset">Reset()</a> 3652 and <a href="#prev">Prev()</a>. The following example would 3653 traverse an associative array in reverse order:</p> 3654 <pre> 3655 <? 3656 Reset($array); 3657 $first_key = key($array); 3658 End($array); 3659 $k = key($array); 3660 while($k != $first_key); 3661 echo $array[$k]; 3662 prev($array); 3663 $k = key($array); 3664 endwhile; 3665 echo $array[$k]; 3666 > 3667</pre> 3668 </dd> 3669 3670 <dt><a name="ereg" id="ereg"><span class="big"> 3671 ereg(expr,arg[,regs])</span></a></dt> 3672 3673 <dd> 3674 <p>ereg returns non-zero if the regular expression is matched 3675 in the argument string. For example, the condition, 3676 <code><?if (ereg("^This.*", "This is an example 3677 string")></code> would be true since the "^This.*" 3678 expression says to match the word <strong>This</strong> at 3679 the beginning of the string and then match any characters 3680 afterwards. If the <em>regs</em> argument is present, then 3681 match registers are filled into positions 0-10 in the array 3682 named by the <em>regs</em> argument. Register 0 will always 3683 contain the full matched string. For more information on 3684 regular expressions, see the <a href="#regexp">regular 3685 expression section</a> of this document.</p> 3686 </dd> 3687 3688 <dt><a name="eregi" id="eregi"><span class="big"> 3689 eregi(expr,arg[,regs])</span></a></dt> 3690 3691 <dd> 3692 <p>eregi is identical to the <a href="#ereg">ereg()</a> 3693 function except for the fact that the regular expression is 3694 applied such that upper/lower case is ignored.</p> 3695 </dd> 3696 3697 <dt><a name="ereg_replace" id="ereg_replace"><span class="big"> 3698 ereg_replace(expr,replace,arg)</span></a></dt> 3699 3700 <dd> 3701 <p>ereg_Replace scans the entire argument string and replaces 3702 any portions of the string matched by the given expression 3703 with the replacement string. For example, in the string, 3704 <code>"This is an example string"</code> we could very easily 3705 replace every space with a dash with the command: 3706 <strong>ereg_replace(" ","-","This is an example 3707 string")</strong>.For more information on regular 3708 expressions, see the <a href="#regexp">regular expression 3709 section</a> of this document.</p> 3710 </dd> 3711 3712 <dt><a name="eregi_replace" id="eregi_replace"><span class="big"> 3713 eregi_replace(expr,replace,arg)</span></a></dt> 3714 3715 <dd> 3716 <p>eregi_replace is identical to the <a href= 3717 "#ereg_replace">ereg_replace()</a> function except for the 3718 fact that the regular expression is applied such that 3719 upper/lower case is ignored.</p> 3720 </dd> 3721 3722 <dt><a name="escapeshellcmd" id="escapeshellcmd"><span class="big"> 3723 EscapeShellCmd(string)</span></a></dt> 3724 3725 <dd> 3726 <p>EscapeShellCmd escapes any characters in a string that 3727 might be used to trick a shell command into executing 3728 arbitrary commands. This function should be used to make sure 3729 that any data coming from user input is escaped before this 3730 data is passed to the <a href="#exec">Exec()</a> or <a href= 3731 "#system">System()</a> functions. A standard use would 3732 be:</p> 3733 <pre> 3734 <?system(EscapeShellCmd($cmd))> 3735</pre> 3736 </dd> 3737 3738 <dt><a name="eval" id="eval"><span class="big"> 3739 Eval(string)</span></a></dt> 3740 3741 <dd> 3742 <p>Eval takes the contents of the string argument and treats 3743 it like a mini PHP/FI script. It will execute it as a 3744 separate PHP/FI script. Any variables set or accessed from 3745 inside the eval will be from the global reference frame in 3746 the current context of the eval statement in the script. 3747 Variable substitution is done on the string arguments, so if 3748 variables are to be used in the string expression they should 3749 be escaped. Some examples:</p> 3750 <pre> 3751 $a = "echo phpversion();"; 3752 eval($a); 3753 3754 eval("echo phpversion();"); 3755 3756 eval("\$a=1; echo \$a;"); 3757</pre> 3758 </dd> 3759 3760 <dt><a name="exec" id="exec"><span class="big"> 3761 Exec(command_string [, array 3762 [,return_var]])</span></a></dt> 3763 3764 <dd> 3765 <p>Exec executes the given unix command, however it does not 3766 output anything. It simply returns the last line from the 3767 result of the command. If you need to execute a command and 3768 have all the data from the command passed directly back 3769 without any interference, use the <a href= 3770 "#passthru">PassThru()</a> function. If the array argument is 3771 present, then the specified array will be filled with every 3772 line of output from the unix command starting at the end of 3773 the array. Make sure you <a href="#unset">UnSet</a> the array 3774 before the call if your array already contains elements and 3775 you want to start filling it at array element 0. If the 3776 return_var argument is present along with the array argument, 3777 then the return status of the executed unix command will be 3778 written to this variable. Note that if you are going to allow 3779 data coming from user input to be passed to this Exec 3780 function, then you should be using the <a href= 3781 "#escpapeshellcmd">EscapeShellCmd()</a> function to make sure 3782 that users cannot trick the system into executing arbitrary 3783 commands. See also the <a href="#system">system()</a> 3784 function.</p> 3785 </dd> 3786 3787 <dt><a name="exit" id="exit"><span class="big"> 3788 Exit</span></a></dt> 3789 3790 <dd> 3791 <p>The Exit command is used to terminate parsing right away 3792 as soon as this tag is parsed.</p> 3793 </dd> 3794 3795 <dt><a name="exp" id="exp"><span class="big"> 3796 Exp(arg)</span></a></dt> 3797 3798 <dd> 3799 <p>Exp returns e raised to the power of arg. See also 3800 <a href="#pow">pow()</a></p> 3801 </dd> 3802 3803 <dt><a name="fclose" id="fclose"><span class="big"> 3804 fclose($fd)</span></a></dt> 3805 3806 <dd> 3807 <p>fclose() closes a file opened by <a href= 3808 "#fopen">fopen()</a>. The argument is a file pointer index as 3809 returned by the fopen() call.</p> 3810 </dd> 3811 3812 <dt><a name="feof" id="feof"><span class="big"> 3813 feof($fd)</span></a></dt> 3814 3815 <dd> 3816 <p>Feof returns true if the file referred to by the file 3817 pointer index argument has hit end-of-file.</p> 3818 </dd> 3819 3820 <dt><a name="fgets" id="fgets"><span class="big"> 3821 fgets($fd,bytes)</span></a></dt> 3822 3823 <dd> 3824 <p>fgets() reads a line from a file opened by <a href= 3825 "#fopen">fopen()</a>. Arguments are a file pointer index as 3826 returned by fopen() and the max number of bytes to read. 3827 Reading ends when max number of bytes have been read, or on 3828 an end of line. This is similar to the C fgets() call. See 3829 also <a href="#fputs">fputs()</a>.</p> 3830 </dd> 3831 3832 <dt><a name="fgetss" id="fgetss"><span class="big"> 3833 fgetss($fd,bytes)</span></a></dt> 3834 3835 <dd> 3836 <p>Identical to the fgets() function, except this one tries 3837 to strip off any HTML tags or PHP/FI script tags as it is 3838 reading the file.</p> 3839 </dd> 3840 3841 <dt><a name="file" id="file"><span class="big">$array = 3842 File(filename)</span></a></dt> 3843 3844 <dd> 3845 <p>File reads the entire file and returns an array with each 3846 array element containing a line of the file starting with 3847 array index <strong>0</strong>.</p> 3848 </dd> 3849 3850 <dt><a name="fileatime" id="fileatime"><span class="big"> 3851 fileAtime(filename)</span></a></dt> 3852 3853 <dd> 3854 <p>fileAtime returns the time of last data access. If the 3855 file does not exist, or if it for some other reason could not 3856 be accessed, this function returns -1. If repeated calls to 3857 fileAtime and the rest ofthe file* functions are to be made 3858 and the file being accessed might change or disappear, the 3859 <a href="#clearstatcache">ClearStatCache()</a> should be 3860 called before the call to the file* function.</p> 3861 </dd> 3862 3863 <dt><a name="filectime" id="filectime"><span class="big"> 3864 fileCtime(filename)</span></a></dt> 3865 3866 <dd> 3867 <p>fileCtime returns the time of last status change. If the 3868 file does not exist, or if it for some other reason could not 3869 be accessed, this function returns -1. If repeated calls to 3870 fileCtime and the rest ofthe file* functions are to be made 3871 and the file being accessed might change or disappear, the 3872 <a href="#clearstatcache">ClearStatCache()</a> should be 3873 called before the call to the file* function.</p> 3874 </dd> 3875 3876 <dt><a name="filegroup" id="filegroup"><span class="big"> 3877 fileGroup(filename)</span></a></dt> 3878 3879 <dd> 3880 <p>fileGroup returns the group id of the owner of the file. 3881 If the file does not exist, or if it for some other reason 3882 could not be accessed, this function returns -1. If repeated 3883 calls to fileGroup and the rest ofthe file* functions are to 3884 be made and the file being accessed might change or 3885 disappear, the <a href="#clearstatcache">ClearStatCache()</a> 3886 should be called before the call to the file* function.</p> 3887 </dd> 3888 3889 <dt><a name="fileinode" id="fileinode"><span class="big"> 3890 fileInode(filename)</span></a></dt> 3891 3892 <dd> 3893 <p>fileInode returns the file's inode. If the file does not 3894 exist, or if it for some other reason could not be accessed, 3895 this function returns -1. If repeated calls to fileInode and 3896 the rest ofthe file* functions are to be made and the file 3897 being accessed might change or disappear, the <a href= 3898 "#clearstatcache">ClearStatCache()</a> should be called 3899 before the call to the file* function.</p> 3900 </dd> 3901 3902 <dt><a name="filemtime" id="filemtime"><span class="big"> 3903 fileMtime(filename)</span></a></dt> 3904 3905 <dd> 3906 <p>fileMtime returns the time of last data modification. If 3907 the file does not exist, or if it for some other reason could 3908 not be accessed, this function returns -1. If repeated calls 3909 to fileMtime and the rest ofthe file* functions are to be 3910 made and the file being accessed might change or disappear, 3911 the <a href="#clearstatcache">ClearStatCache()</a> should be 3912 called before the call to the file* function.</p> 3913 </dd> 3914 3915 <dt><a name="fileowner" id="fileowner"><span class="big"> 3916 fileOwner(filename)</span></a></dt> 3917 3918 <dd> 3919 <p>fileOwner returns the uid of the owner of the file. If the 3920 file does not exist, or if it for some other reason could not 3921 be accessed, this function returns -1. If repeated calls to 3922 fileOwner and the rest ofthe file* functions are to be made 3923 and the file being accessed might change or disappear, the 3924 <a href="#clearstatcache">ClearStatCache()</a> should be 3925 called before the call to the file* function.</p> 3926 </dd> 3927 3928 <dt><a name="fileperms" id="fileperms"><span class="big"> 3929 filePerms(filename)</span></a></dt> 3930 3931 <dd> 3932 <p>filePerms returns the permission bits of the file. This is 3933 the <em>st_mode</em> field of the Unix C stat structure. If 3934 the file does not exist, or if it for some other reason could 3935 not be accessed, this function returns -1. If repeated calls 3936 to filePerms and the rest ofthe file* functions are to be 3937 made and the file being accessed might change or disappear, 3938 the <a href="#clearstatcache">ClearStatCache()</a> should be 3939 called before the call to the file* function.</p> 3940 </dd> 3941 3942 <dt><a name="filesize" id="filesize"><span class="big"> 3943 fileSize(filename)</span></a></dt> 3944 3945 <dd> 3946 <p>fileSize returns the size of the file in bytes. If the 3947 file does not exist, or if it for some other reason could not 3948 be accessed, this function returns -1. If repeated calls to 3949 fileSize and the rest ofthe file* functions are to be made 3950 and the file being accessed might change or disappear, the 3951 <a href="#clearstatcache">ClearStatCache()</a> should be 3952 called before the call to the file* function.</p> 3953 </dd> 3954 3955 <dt><a name="filetype" id="filetype"><span class="big"> 3956 fileType(filename)</span></a></dt> 3957 3958 <dd> 3959 <p>fileType returns the type of the file. The return values 3960 are one of: "dir", "file","fifo","char", "block", or "link". 3961 These are for, directory, regular file, fifo special, 3962 character special, block special and symbolic link, 3963 respectively.</p> 3964 </dd> 3965 3966 <dt><a name="floor" id="floor"><span class="big"> 3967 Floor(value)</span></a></dt> 3968 3969 <dd> 3970 <p>Floor() rounds a floating point value down to the previous 3971 integer. The return value is of type double (floating point) 3972 such that it can be used properly in complex equations. To 3973 get an integer type back, use: <code>$new = 3974 IntVal(Floor($value));</code><br> 3975 See also <a href="#ceil">Ceil()</a>.</p> 3976 </dd> 3977 3978 <dt><a name="flush" id="flush"><span class="big"> 3979 Flush()</span></a></dt> 3980 3981 <dd> 3982 <p>The Flush() function is used to Flush the output buffer. 3983 For the Apache module, it flushes Apache's output buffer, and 3984 for the CGI version it simply flushes stdout. When running as 3985 a CGI under Apache, the server will buffer the CGI script's 3986 output, so this Flush() function won't help much there. Look 3987 at running your script as an nph- script if you are running 3988 the CGI version of PHP under the Apache web server. Or, 3989 alternatively, run the Apache module version of PHP.</p> 3990 </dd> 3991 3992 <dt><a name="fopen" id="fopen"><span class="big">$fp = 3993 fopen(filename,mode)</span></a></dt> 3994 3995 <dd> 3996 <p>fopen() opens a file and returns a file pointer index. If 3997 the file could not be opened the function returns -1. It is 3998 similar to the C fopen() call. The filename argument is the 3999 relative or absolute path to the file to be opened, and the 4000 mode argument is one of, "r", "r+", "w", "w+", "a", "a+". See 4001 the Unix man page on the fopen() call for more information. 4002 See also the <a href="#popen">popen()</a> function 4003 description. See also the <a href="#fclose">fclose()</a> 4004 function description.</p> 4005 4006 <p>Example:</p> 4007 <pre> 4008 $fp = fopen("/home/rasmus/file.txt","r"); 4009</pre> 4010 </dd> 4011 4012 <dt><a name="fputs" id="fputs"><span class="big"> 4013 fputs(fp,string)</span></a></dt> 4014 4015 <dd> 4016 <p>fputs() writes a line to a file opened by <a href= 4017 "#fopen">fopen()</a>. Arguments are a file pointer index as 4018 returned by fopen() and the string to write. Note that the 4019 string argument may contain the special escape characters, 4020 <strong>\n</strong>, <strong>\r</strong> and 4021 <strong>\t</strong> to output newlines, carriage returns and 4022 tabs respectively. See also <a href="#fgets">fgets()</a>.</p> 4023 </dd> 4024 4025 <dt><a name="fpassthru" id="fpassthru"><span class="big"> 4026 FPassThru(fp)</span></a></dt> 4027 4028 <dd> 4029 <p>FPassThru() outputs all remaining data on <i>fp</i> 4030 directly. It is different from <a href= 4031 "#readfile">ReadFile()</a> in that it can also handle files 4032 opened with <a href="#fsockopen">fsockopen()</a>. It differs 4033 from <a href="#passthru">PassThru()</a> in that it does not 4034 handle commands, but opened files. FPassThru() returns the 4035 number of bytes read and written.</p> 4036 </dd> 4037 4038 <dt><a name="fseek" id="fseek"><span class="big"> 4039 fseek(fp,pos)</span></a></dt> 4040 4041 <dd> 4042 <p>fseek() positions a file pointer identified by the $fd 4043 argument which is the return value of the <a href= 4044 "#fopen">fopen()</a> call. The file pointer is positioned at 4045 the beginning of the file plus the offset specified by the 4046 <strong>pos</strong> argument. See also <a href= 4047 "#ftell">ftell()</a> and <a href="#rewind">rewind()</a>.</p> 4048 </dd> 4049 4050 <dt><a name="fsockopen" id="fsockopen"><span class="big">fp = 4051 fsockopen(hostname,port)</span></a></dt> 4052 4053 <dd> 4054 <p>fsockopen() opens a socket connection and returns a file 4055 pointer index. This file pointer index can be used by 4056 <a href="#fgets">fgets</a>, <a href="#fputs">fputs</a> and 4057 <a href="#fclose">fclose</a>. Arguments are a hostname and a 4058 port number. Return values are: -3 if the socket couldn't be 4059 created, -4 if the dns lookup on the hostname failed, -5 if 4060 the connection was refused or it timed out, -6 if the actual 4061 fdopen() call failed or -7 if the setvbuf() call failed. If 4062 the port number is 0, then the hostname argument will be 4063 treated as a filename of a Unix domain socket if your 4064 operating system support Unix domain sockets.</p> 4065 </dd> 4066 4067 <dt><a name="ftell" id="ftell"><span class="big">pos = 4068 ftell(fp)</span></a></dt> 4069 4070 <dd> 4071 <p>ftell() returns the position of a file pointer identified 4072 by the fp argument which is the return value of the <a href= 4073 "#fopen">fopen()</a> call. The position can later be used as 4074 an argument to fseek(). See also <a href="#fseek">fseek()</a> 4075 and <a href="#rewind">rewind()</a>.</p> 4076 </dd> 4077 4078 <dt><a name="getaccdir" id="getaccdir"><span class="big"> 4079 getAccDir()</span></a></dt> 4080 4081 <dd> 4082 <p>getAccDir returns the directory where PHP access 4083 configuration files are kept. The access configuration 4084 filenames come from the numerical user id of the user whose 4085 access configurations they represent.</p> 4086 </dd> 4087 4088 <dt><a name="getenv" id="getenv"><span class="big"> 4089 GetEnv(string)</span></a></dt> 4090 4091 <dd> 4092 <p>GetEnv returns the value of the environment value 4093 specified by <em>string</em>. Normally this function is not 4094 used because environment variables are available to PHP/FI 4095 directly. If a reference is made to a variable which is not 4096 found in the internal symbol table, then the environment 4097 space is automatically searched. GetEnv should be used when 4098 it is necessary to ensure that an environment variable has 4099 not been overwritten by normal PHP/FI variable. Security 4100 mechanisms that rely on http server-defined variables like 4101 REMOTE_ADDR and REMOTE_HOST should load these variables using 4102 GetEnv as opposed to referencing them directly as 4103 $REMOTE_ADDR to avoid someone making up a fake form and 4104 posting the data to your server and thereby bypassing 4105 whatever security mechanism you might have.</p> 4106 </dd> 4107 4108 <dt><a name="gethostbyname" id="gethostbyname"><span class="big"> 4109 getHostByName(domain_name)</span></a></dt> 4110 4111 <dd> 4112 <p>getHostByName converts the given domain name into an IP 4113 address in nnn.nnn.nnn.nnn format.</p> 4114 </dd> 4115 4116 <dt><a name="gethostbyaddr" id="gethostbyaddr"><span class="big"> 4117 getHostByAddr(ip_address)</span></a></dt> 4118 4119 <dd> 4120 <p>getHostByAddr converts the given IP address in 4121 nnn.nnn.nnn.nnn format into a fully qualified domain 4122 name.</p> 4123 </dd> 4124 4125 <dt><a name="getimagesize" id="getimagesize"><span class="big"> 4126 GetImageSize(filename)</span></a></dt> 4127 4128 <dd> 4129 <p>The GetImageSize() function takes either a full path 4130 filename, or a relative path relative to the location of the 4131 calling script. It returns a 3 element array consisting of 4132 width, height and type. Width and height are in pixels, and a 4133 type of 1 means GIF, a 2 indicates a JPG file and a 3 4134 indicates a PNG file. Other file types are not supported. The 4135 fourth element in the returned array is a string containing, 4136 "width=x height=y" that is suitable for using directly in an 4137 IMG tag. It is important to note that the GD image library is 4138 not needed to use this function. An example follows:</p> 4139 <pre> 4140 <? 4141 $result = GetImageSize("img/flag.jpg"); 4142 > 4143 <IMG SRC="img/flag.jpg" ?echo $result[3]> > 4144</pre> 4145 </dd> 4146 4147 <dt><a name="getlastaccess" id="getlastaccess"><span class="big"> 4148 getLastAccess()</span></a></dt> 4149 4150 <dd> 4151 <p>getLastAccess returns the date and time in unix time 4152 format of the last time the current page was access. This 4153 value can be passed to the <a href="#date">Date()</a> 4154 function for formatting.<br> 4155 This function is only available if PHP was compiled with 4156 Access Logging enabled.</p> 4157 </dd> 4158 4159 <dt><a name="getlastbrowser" id="getlastbrowser"><span class="big"> 4160 getLastbrowser()</span></a></dt> 4161 4162 <dd> 4163 <p>getLastBrowser returns the identification string of 4164 browser the last user to access the current page used.<br> 4165 This function is only available if PHP was compiled with 4166 Access Logging enabled.</p> 4167 </dd> 4168 4169 <dt><a name="getlastemail" id="getlastemail"><span class="big"> 4170 getLastEmail()</span></a></dt> 4171 4172 <dd> 4173 <p>getLastEmail returns the E-Mail address of the last user 4174 to access the current page.<br> 4175 This function is only available if PHP was compiled with 4176 Access Logging enabled.</p> 4177 </dd> 4178 4179 <dt><a name="getlasthost" id="getlasthost"><span class="big"> 4180 getLastHost()</span></a></dt> 4181 4182 <dd> 4183 <p>getLastHost returns the hostname of the last user to 4184 access the current page.<br> 4185 This function is only available if PHP was compiled with 4186 Access Logging enabled.</p> 4187 </dd> 4188 4189 <dt><a name="getlastmod" id="getlastmod"><span class="big"> 4190 getLastMod()</span></a></dt> 4191 4192 <dd> 4193 <p>getLastMod returns the date and time in unix time format 4194 of the last time the current page was modified. This value 4195 can be passed to the <a href="#date">Date()</a> function for 4196 formatting.<br> 4197 This function is only available if PHP was compiled with 4198 Access Logging enabled.</p> 4199 </dd> 4200 4201 <dt><a name="getlastref" id="getlastref"><span class="big"> 4202 getLastref()</span></a></dt> 4203 4204 <dd> 4205 <p>getLastRef returns the URL of the referring document of 4206 the last user to access the current page.<br> 4207 This function is only available if PHP was compiled with 4208 Access Logging enabled.</p> 4209 </dd> 4210 4211 <dt><a name="getlogdir" id="getlogdir"><span class="big"> 4212 getLogDir()</span></a></dt> 4213 4214 <dd> 4215 <p>getLogDir returns the top-level directory under which PHP 4216 log files can be found. The actual log files are in 4217 directories under this directory. Each subdirectory is the 4218 numerical user id of the user to whom the log files belong. 4219 Then within each directory a series of dbm log files are 4220 found, each with the numerical inode of the file they 4221 represent as the primary component of the filename.</p> 4222 </dd> 4223 4224 <dt><a name="getmyinode" id="getmyinode"><span class="big"> 4225 getMyInode()</span></a></dt> 4226 4227 <dd> 4228 <p>getMyInode returns the numerical inode of the current HTML 4229 file.</p> 4230 </dd> 4231 4232 <dt><a name="getmypid" id="getmypid"><span class="big"> 4233 getMyPid()</span></a></dt> 4234 4235 <dd> 4236 <p>getMyPid() returns the current process id of the PHP 4237 parsing process.</p> 4238 </dd> 4239 4240 <dt><a name="getmyuid" id="getmyuid"><span class="big"> 4241 getMyUid()</span></a></dt> 4242 4243 <dd> 4244 <p>getMyUid returns the numerical user id of the owner of the 4245 current HTML file.</p> 4246 </dd> 4247 4248 <dt><a name="getrandmax" id="getrandmax"><span class="big"> 4249 getRandMax()</span></a></dt> 4250 4251 <dd> 4252 <p>getRandMax returns the maximum random number the <a href= 4253 "#rand">Rand</a> function will return. If the value returned 4254 does not seem to be accurate, have a look in the php.h source 4255 file in the PHP distribution for more information.</p> 4256 </dd> 4257 4258 <dt><a name="getstartlogging" id="getstartlogging"><span class="big"> 4259 getStartLogging()</span></a></dt> 4260 4261 <dd> 4262 <p>getStartLogging returns the time and date in Unix time 4263 format when logging commenced on the current page. This is 4264 more accurate when mSQL-based logging is used since a 4265 timestamp is kept in each log file. For dbm-logging the time 4266 returned is the time the user's log directory was 4267 created.</p> 4268 </dd> 4269 4270 <dt><a name="gettoday" id="gettoday"><span class="big"> 4271 getToday()</span></a></dt> 4272 4273 <dd> 4274 <p>getToday returns the total number of hits the current page 4275 has had since 12 midnight local time.<br> 4276 This function is only available if PHP was compiled with 4277 Access Logging enabled.</p> 4278 </dd> 4279 4280 <dt><a name="gettotal" id="gettotal"><span class="big"> 4281 getTotal()</span></a></dt> 4282 4283 <dd> 4284 <p>getTotal returns the total number of hits the current page 4285 has had since access logging was started on the page.<br> 4286 This function is only available if PHP was compiled with 4287 Access Logging enabled.</p> 4288 </dd> 4289 4290 <dt><a name="gettype" id="gettype"><span class="big"> 4291 GetType(variable)</span></a></dt> 4292 4293 <dd> 4294 <p>GetType returns the type of the variable. The return value 4295 is a string and it is one of, "integer", "double" or 4296 "string". See also the <a href="#settype">SetType()</a> 4297 function</p> 4298 </dd> 4299 4300 <dt><a name="gmdate" id="gmdate"><span class="big"> 4301 gmDate(format,time)</span></a></dt> 4302 4303 <dd> 4304 <p>gmDate is identical to the <a href="#date">Date</a> 4305 function except for the fact that it uses Greenwich Mean Time 4306 instead of the current local time.</p> 4307 </dd> 4308 4309 <dt><a name="header" id="header"><span class="big"> 4310 Header(header_string)</span></a></dt> 4311 4312 <dd> 4313 <p>The Header command is used at the top of an HTML file to 4314 send raw HTTP header strings. See the <a href= 4315 "http://www.w3.org/Protocols/rfc2068/rfc2068">HTTP 4316 Specification</a> for more information on raw http headers. 4317 Remember that the Header() command must be used before any 4318 actual output is sent either by normal HTML tags or by PHP 4319 echo commands.<br> 4320 Usage examples can be found in the <a href="#http_auth">HTTP 4321 Authentication</a> section.</p> 4322 </dd> 4323 4324 <dt><a name="hexdec" id="hexdec"><span class="big"> 4325 HexDec(hex_string)</span></a></dt> 4326 4327 <dd> 4328 <p>HexDec converts a hexadecimal string to a decimal number. 4329 See also the <a href="#dechex">DecHex()</a> function.</p> 4330 </dd> 4331 4332 <dt><a name="htmlspecialchars" id= 4333 "htmlspecialchars"><span class="big">HtmlSpecialChars(string)</span></a></dt> 4334 4335 <dd> 4336 <p>HtmlSpecialChars converts any characters with ascii codes 4337 in the string argument between 160 and 255 inclusive to their 4338 corresponding HTML Entity names. The function returns the 4339 converted string. The <b><</b>, <b>></b>, <b>&</b> 4340 and <b>"</b> are also converted.</p> 4341 </dd> 4342 4343 <dt><a name="imagearc" id="imagearc"><span class="big"> 4344 ImageArc(im, cx, cy, w, h, s, e, col)</span></a></dt> 4345 4346 <dd> 4347 <p>ImageArc draws a partial ellipse centered at cx,cy (top 4348 left is 0,0) in the image represented by <a href= 4349 "#imagecreate">im</a>. w and h specifies the ellipse's width 4350 and height respectively while the start and end points are 4351 specified in degrees indicated by the s and e 4352 arguments.<br> 4353 This function is only available if GD support has been 4354 enabled in PHP.</p> 4355 </dd> 4356 4357 <dt><a name="imagechar" id="imagechar"><span class="big"> 4358 ImageChar(im, size, x, y, c, col)</span></a></dt> 4359 4360 <dd> 4361 <p>ImageChar draws the character c in the image identified by 4362 <a href="#imagecreate">im</a> at coordinates x,y (top left is 4363 0,0) in colour col. The size argument can be 1, 2, 3, 4 or 5 4364 indicating the size of the font to be used. 1 is the smallest 4365 and 5 is the largest.<br> 4366 This function is only available if GD support has been 4367 enabled in PHP.</p> 4368 </dd> 4369 4370 <dt><a name="imagecharup" id="imagecharup"><span class="big"> 4371 ImageCharUp(im, size, x, y, c, col)</span></a></dt> 4372 4373 <dd> 4374 <p>ImageCharUp draws the character c vertically in the image 4375 identified by <a href="#imagecreate">im</a> at coordinates 4376 x,y (top left is 0,0) in colour col. The size argument can be 4377 1, 2, 3, 4 or 5 indicating the size of the font to be used. 1 4378 is the smallest and 5 is the largest.<br> 4379 This function is only available if GD support has been 4380 enabled in PHP.</p> 4381 </dd> 4382 4383 <dt><a name="imagecolorallocate" id= 4384 "imagecolorallocate"><span class="big">col = 4385 ImageColorAllocate(im, red, green, blue)</span></a></dt> 4386 4387 <dd> 4388 <p>ImageColorAllocate returns a colour identifier 4389 representing the colour composed of the given RGB components. 4390 The im argument is the return from the <a href= 4391 "#imagecreate">ImageCreate</a> function. ImageColorAllocate 4392 must be called to create each colour that is to be used in 4393 the image represented by im.<br> 4394 This function is only available if GD support has been 4395 enabled in PHP.</p> 4396 </dd> 4397 4398 <dt><a name="imagecolortransparent" id= 4399 "imagecolortransparent"><span class="big"> 4400 ImageColorTransparent(im, col)</span></a></dt> 4401 4402 <dd> 4403 <p>ImageColorTransparent sets the transparent colour in the 4404 im image to col. im is the image identifier returned by 4405 <a href="#imagecreate">ImageCreate</a> and col is the colour 4406 identifier returned by <a href= 4407 "#imagecolorallocate">ImageColorAllocate</a>. This function 4408 is only available if GD support has been enabled in PHP.</p> 4409 </dd> 4410 4411 <dt><a name="imagecopyresized" id= 4412 "imagecopyresized"><span class="big">ImageCopyResized(dst_im, 4413 src_im, dstX, dstY, srcX, srcY, dstW, dstH, srcW, srcH 4414 )</span></a></dt> 4415 4416 <dd> 4417 <p>ImageCopyResized copies a rectangular portion of one image 4418 to another image. <em>dst_im</em> is the destination image, 4419 <em>src_im</em> is the source image identifier. If the source 4420 and destination coordinates and width and heights differ, 4421 appropriate stretching or shrinking of the image fragment 4422 will be performed. The coordinates refer to the upper left 4423 corner. This function can be used to copy regions within the 4424 same image (if <em>dst_im</em> is the same as 4425 <em>src_im</em>) but if the regions overlap the results will 4426 be unpredictable.<br> 4427 This function is only available if GD support has been 4428 enabled in PHP.</p> 4429 </dd> 4430 4431 <dt><a name="imagecreate" id="imagecreate"><span class="big">im = 4432 ImageCreate(x_size, y_size)</span></a></dt> 4433 4434 <dd> 4435 <p>ImageCreate returns an image identifier representing a 4436 blank image of size x_size by y_size.<br> 4437 This function is only available if GD support has been 4438 enabled in PHP.</p> 4439 </dd> 4440 4441 <dt><a name="imagecreatefromgif" id= 4442 "imagecreatefromgif"><span class="big">im = 4443 ImageCreateFromGif(filename)</span></a></dt> 4444 4445 <dd> 4446 <p>ImageCreateFromGif returns an image identifier 4447 representing the image obtained from the given 4448 <em>filename</em>.<br> 4449 This function is only available if GD support has been 4450 enabled in PHP.</p> 4451 </dd> 4452 4453 <dt><a name="imagedestroy" id="imagedestroy"><span class="big"> 4454 ImageDestroy(im)</span></a></dt> 4455 4456 <dd> 4457 <p>ImageDestroy frees any memory associated with image im. im 4458 is the image identifier returned by the <a href= 4459 "#imagecreate">ImageCreate</a> function. This function is 4460 only available if GD support has been enabled in PHP.</p> 4461 </dd> 4462 4463 <dt><a name="imagefill" id="imagefill"><span class="big"> 4464 ImageFill(im, x, y, col)</span></a></dt> 4465 4466 <dd> 4467 <p>ImageFill performs a flood fill starting at coordinate x,y 4468 (top left is 0,0) with colour col in image im.<br> 4469 This function is only available if GD support has been 4470 enabled in PHP.</p> 4471 </dd> 4472 4473 <dt><a name="imagefilledpolygon" id= 4474 "imagefilledpolygon"><span class="big">ImageFilledPolygon(im, 4475 points, num_points, col)</span></a></dt> 4476 4477 <dd> 4478 <p>ImageFilledPolygon creates a filled polygon in image 4479 <a href="#imagecreate">im</a>. points is a PHP array 4480 containing the polygon's vertices. ie. points[0] = x0, 4481 points[1] = y0, points[2] = x1, points[3] = y1, etc. 4482 num_points is the total number of vertices.<br> 4483 This function is only available if GD support has been 4484 enabled in PHP.</p> 4485 </dd> 4486 4487 <dt><a name="imagefilledrectangle" id= 4488 "imagefilledrectangle"><span class="big">ImageFilledRectangle(im, 4489 x1, y1, x2, y2, col)</span></a></dt> 4490 4491 <dd> 4492 <p>ImageFilledRectangle creates a filled rectangle of colour 4493 col in image im starting at upper left coordinate x1,y1 and 4494 ending at bottom right coordinate x2,y2. 0,0 is the top left 4495 corner of the image.<br> 4496 This function is only available if GD support has been 4497 enabled in PHP.</p> 4498 </dd> 4499 4500 <dt><a name="imagefilltoborder" id= 4501 "imagefilltoborder"><span class="big">ImageFillToBorder(im, x, y, 4502 border, col)</span></a></dt> 4503 4504 <dd> 4505 <p>ImageFillToBorder performs a flood fill whose border 4506 colour is defined by border. The starting point for the fill 4507 is x,y (top left is 0,0) and the region is filled with colour 4508 col.<br> 4509 This function is only available if GD support has been 4510 enabled in PHP.</p> 4511 </dd> 4512 4513 <dt><a name="imagegif" id="imagegif"><span class="big"> 4514 ImageGif(im [,filename])</span></a></dt> 4515 4516 <dd> 4517 <p>ImageGif creates the GIF file in filename from the image 4518 im. The im argument is the return from the <a href= 4519 "#imagecreate">ImageCreate</a> function. The filename 4520 argument is optional, and if left off, the raw image stream 4521 will be returned directly. By sending an <em>image/gif</em> 4522 content-type using the <a href="#header">Header()</a> 4523 function, you can create a PHP/FI script which returns GIF 4524 images directly using this function.<br> 4525 This function is only available if GD support has been 4526 enabled in PHP.</p> 4527 </dd> 4528 4529 <dt><a name="imageinterlace" id="imageinterlace"><span class="big"> 4530 ImageInterlace(im, interlace)</span></a></dt> 4531 4532 <dd> 4533 <p>ImageInterlace turns the interlace bit on or off. If 4534 interlace is 1 the im image will be interlaced, and if 4535 interlace is 0 the interlace bit is turned off. This 4536 functions is only available if GD support has been enabled in 4537 PHP.</p> 4538 </dd> 4539 4540 <dt><a name="imageline" id="imageline"><span class="big"> 4541 ImageLine(im, x1, y1, x2, y2, col)</span></a></dt> 4542 4543 <dd> 4544 <p>ImageLine draws a line from x1,y1 to x2,y2 (top left is 4545 0,0) in image <a href="#imagecreate">im</a> of colour 4546 <a href="#imagecolorallocate">col</a>.<br> 4547 This function is only available if GD support has been 4548 enabled in PHP.</p> 4549 </dd> 4550 4551 <dt><a name="imagepolygon" id="imagepolygon"><span class="big"> 4552 ImagePolygon(im, points, num_points, col)</span></a></dt> 4553 4554 <dd> 4555 <p>ImagePolygon creates a polygon in image <a href= 4556 "#imagecreate">im</a>. points is a PHP array containing the 4557 polygon's vertices. ie. points[0] = x0, points[1] = y0, 4558 points[2] = x1, points[3] = y1, etc. num_points is the total 4559 number of vertices.<br> 4560 This function is only available if GD support has been 4561 enabled in PHP.</p> 4562 </dd> 4563 4564 <dt><a name="imagerectangle" id="imagerectangle"><span class="big"> 4565 ImageRectangle(im, x1, y1, x2, y2, col)</span></a></dt> 4566 4567 <dd> 4568 <p>ImageRectangle creates a rectangle of colour col in image 4569 im starting at upper left coordinate x1,y1 and ending at 4570 bottom right coordinate x2,y2. 0,0 is the top left corner of 4571 the image.<br> 4572 This function is only available if GD support has been 4573 enabled in PHP.</p> 4574 </dd> 4575 4576 <dt><a name="imagesetpixel" id="imagesetpixel"><span class="big"> 4577 ImageSetPixel(im, x, y, col)</span></a></dt> 4578 4579 <dd> 4580 <p>ImageSetPixel draws a pixel at x,y (top left is 0,0) in 4581 image <a href="#imagecreate">im</a> of colour <a href= 4582 "#imagecolorallocate">col</a>.<br> 4583 This function is only available if GD support has been 4584 enabled in PHP.</p> 4585 </dd> 4586 4587 <dt><a name="imagestring" id="imagestring"><span class="big"> 4588 ImageString(im, size, x, y, s, col)</span></a></dt> 4589 4590 <dd> 4591 <p>ImageString draws the string s in the image identified by 4592 <a href="#imagecreate">im</a> at coordinates x,y (top left is 4593 0,0) in colour col. The size argument can be 1, 2, 3, 4 or 5 4594 indicating the size of the font to be used. 1 is the smallest 4595 and 5 is the largest.<br> 4596 This function is only available if GD support has been 4597 enabled in PHP.</p> 4598 </dd> 4599 4600 <dt><a name="imagestringup" id="imagestringup"><span class="big"> 4601 ImageStringUp(im, size, x, y, s, col)</span></a></dt> 4602 4603 <dd> 4604 <p>ImageStringUp draws the string s vertically in the image 4605 identified by <a href="#imagecreate">im</a> at coordinates 4606 x,y (top left is 0,0) in colour col. The size argument can be 4607 1, 2, 3, 4 or 5 indicating the size of the font to be used. 1 4608 is the smallest and 5 is the largest.<br> 4609 This function is only available if GD support has been 4610 enabled in PHP.</p> 4611 </dd> 4612 4613 <dt><a name="imagesx" id="imagesx"><span class="big"> 4614 ImageSX(im)</span></a></dt> 4615 4616 <dd> 4617 <p>ImageSX returns the width of the image identified by 4618 <em>im</em>.</p> 4619 </dd> 4620 4621 <dt><a name="imagesy" id="imagesy"><span class="big"> 4622 ImageSY(im)</span></a></dt> 4623 4624 <dd> 4625 <p>ImageSY returns the height of the image identified by 4626 <em>im</em>.</p> 4627 </dd> 4628 4629 <dt><a name="include" id="include"><span class="big"> 4630 Include(filename)</span></a></dt> 4631 4632 <dd> 4633 <p>The Include command can be used to insert other files into 4634 the current html file. This is extremely handy for headers 4635 and footers which may need to be included in hundreds of HTML 4636 files. By using an include command you then only need to 4637 modify the header or footer file in one place when it needs 4638 to be changed. Since full PHP parsing is done on the included 4639 file, you can also use the include command to include common 4640 PHP scripts you may have written. Sort of like having a 4641 primitive shared library of scripts you can call from your 4642 HTML file. You can place such common library files in one 4643 directory and set PHP's include path and not have to refer to 4644 the files with pathnames. For Apache module users this can be 4645 configured with the <strong>phpIncludePath</strong> 4646 directive, for CGI users with the PHP_INCLUDE_PATH 4647 environment variable. This path is colon-separated just like 4648 <code>$PATH</code> is in your UNIX shell. eg.</p> 4649 <pre> 4650 <?include("/path/filename.txt")> 4651</pre> 4652 </dd> 4653 4654 <dt><a name="initsyslog" id="initsyslog"><span class="big"> 4655 InitSyslog()</span></a></dt> 4656 4657 <dd> 4658 <p>InitSyslog() defines some PHP variables that you need when 4659 using OpenLog() and Syslog(). These variables are not defined 4660 by default for efficiency reasons. The variables are named in 4661 the same way as in the <syslog.h> C include file (such 4662 as $LOG_LOCAL0). See your syslog(3) UNIX manual page for more 4663 details. See also <a href="#initsyslog">InitSyslog()</a>, 4664 <a href="#syslog">Syslog()</a> and <a href= 4665 "#closelog">CloseLog()</a>.</p> 4666 </dd> 4667 4668 <dt><a name="intval" id="intval"><span class="big"> 4669 intval(variable)</span></a></dt> 4670 4671 <dd> 4672 <p>intval returns the long integer value of the variable. See 4673 also the <a href="#strval">strval()</a> and <a href= 4674 "#doubleval">doubleval()</a> functions.</p> 4675 </dd> 4676 4677 <dt><a name="isset" id="isset"><span class="big"> 4678 IsSet(variable)</span></a></dt> 4679 4680 <dd> 4681 <p>The IsSet function returns 1 if the given variable is 4682 defined, and 0 if it isn't.</p> 4683 </dd> 4684 4685 <dt><a name="key" id="key"><span class="big"> 4686 Key(variable)</span></a></dt> 4687 4688 <dd> 4689 <p>Key returns the key of the current array item. The current 4690 item is determined by the position of the array pointer for 4691 the given variable. This array pointer may be manipulated 4692 with the <a href="#reset">Reset()</a>, <a href= 4693 "#end">End()</a>, <a href="#next">Next()</a>, and <a href= 4694 "#prev">Prev()</a> functions. This function is mainly used 4695 for determining the key value for an item in an associative 4696 array, although it will work for normal array as well.</p> 4697 </dd> 4698 4699 <dt><a name="link" id="link"><span class="big"> 4700 Link(target,link)</span></a></dt> 4701 4702 <dd> 4703 <p>Link() creates a hard link. See the <a href= 4704 "#symlink">Symlink()</a> function for creating symbolic links 4705 (soft) links. See also <a href="#readlink">ReadLink</a> and 4706 <a href="#LinkInfo">LinkInfo</a> functions.</p> 4707 </dd> 4708 4709 <dt><a name="linkinfo" id="linkinfo"><span class="big"> 4710 LinkInfo(path)</span></a></dt> 4711 4712 <dd> 4713 <p>LinkInfo returns the st_dev field of the UNIX C stat 4714 structure returned by the lstat system call. This function is 4715 used to verify if a link (pointed to by path) really exists 4716 (using the same method as the S_ISLNK macro defined in 4717 stat.h). Returns -1 in case of error.</p> 4718 </dd> 4719 4720 <dt><a name="log" id="log"><span class="big"> 4721 Log(arg)</span></a></dt> 4722 4723 <dd> 4724 <p>Log returns the natural logarithm of arg.</p> 4725 </dd> 4726 4727 <dt><a name="log10" id="log10"><span class="big"> 4728 Log10(arg)</span></a></dt> 4729 4730 <dd> 4731 <p>Log10 returns the base-10 logarithm of arg.</p> 4732 </dd> 4733 4734 <dt><a name="logas" id="logas"><span class="big"> 4735 LogAs(filename)</span></a></dt> 4736 4737 <dd> 4738 <p>The LogAs() function will treat the hit on the current 4739 page as if it as actually received on the argument 4740 filename.</p> 4741 </dd> 4742 4743 <dt><a name="mail" id="mail"><span class="big"> 4744 Mail(to,subject,message[,headers])</span></a></dt> 4745 4746 <dd> 4747 <p>Mail automatically mails the message specified in the 4748 message argument to the receiver specified in the to 4749 argument. Multiple recipients can be specified by spaces 4750 between them in the to argument.</p> 4751 4752 <p>eg.</p> 4753 <pre> 4754 mail("rasmus@lerdorf.on.ca", 4755 "My Subject", 4756 "Line 1\nLine 2\nLine 3"); 4757</pre>If a fourth string argument is passed, this string is 4758inserted at the end of the header, example: 4759 <pre> 4760 mail("ssb@guardian.no", "the subject", $message, 4761 "X-Mailer: PHP/FI " + phpversion()); 4762</pre> 4763 </dd> 4764 4765 <dt><a name="max" id="max"><span class="big"> 4766 Max(array)</span></a></dt> 4767 4768 <dd> 4769 <p>Max returns the maximum value of a PHP array. ie. it will 4770 search through the entire array looking for the max element. 4771 If it is an array of strings, the returned string is the 4772 string which would be alphabetically last in the array if it 4773 were sorted.</p> 4774 </dd> 4775 4776 <dt><a name="md5" id="md5"><span class="big"> 4777 Md5(message)</span></a></dt> 4778 4779 <dd> 4780 <p>Md5 returns the MD5 hash of a string value.</p> 4781 </dd> 4782 4783 <dt><a name="mi_close" id="mi_close"><span class="big"> 4784 mi_Close(connection_id)</span></a></dt> 4785 4786 <dd> 4787 <p>mi_Close will close down the connection to an Illustra 4788 database associated with the given connection identifier.</p> 4789 4790 <p>This function is only available if Illustra support has 4791 been enabled in PHP.</p> 4792 </dd> 4793 4794 <dt><a name="mi_connect" id="mi_connect"><span class="big"> 4795 $connection = mi_Connect(database, username, 4796 password)</span></a></dt> 4797 4798 <dd> 4799 <p>mi_Connect opens a connection to an Illustra database. 4800 Each of the arguments should be a quoted string. This 4801 function returns a connection_id. This identifier is needed 4802 by other Illustra functions. You can have multiple 4803 connections open at once. The host to connect to is governed 4804 by the MI_PARAMS file on the machine running the PHP 4805 executable. No support as yet for remote invocation This 4806 function will return <strong>-1</strong> on error.</p> 4807 4808 <p>This function is only available if Illustra support has 4809 been enabled in PHP.</p> 4810 </dd> 4811 4812 <dt><a name="mi_dbname" id="mi_dbname"><span class="big"> 4813 mi_DBname(connection_id)</span></a></dt> 4814 4815 <dd> 4816 <p>mi_DBname will return the name of the database that the 4817 given Illustra connection identifier is connected to.</p> 4818 4819 <p>This function is only available if Illustra support has 4820 been enabled in PHP.</p> 4821 </dd> 4822 4823 <dt><a name="mi_exec" id="mi_exec"><span class="big">$result = 4824 mi_Exec(connection_id, query_string)</span></a></dt> 4825 4826 <dd> 4827 <p>mi_Exec will send an SQL statement to the Illustra 4828 database specified by the connection_id. The connection_id 4829 must be a valid identifier that was returned by mi_Connect. 4830 The return value of this function is an identifier to be used 4831 to access the results from other Illustra functions. This 4832 function will return <strong>-1</strong> on error.</p> 4833 4834 <p>This function is only available if Illustra support has 4835 been enabled in PHP.</p> 4836 </dd> 4837 4838 <dt><a name="mi_fieldname" id="mi_fieldname"><span class="big"> 4839 mi_FieldName(connection_id, result_id, 4840 field_number)</span></a></dt> 4841 4842 <dd> 4843 <p>mi_FieldName will return the name of the field occupying 4844 the given column number with the given Illustra result and 4845 connection identifiers. Field numbering starts from 0.</p> 4846 4847 <p>This function will return <strong>-1</strong> on 4848 error.</p> 4849 4850 <p>This function is only available if Illustra support has 4851 been enabled in PHP.</p> 4852 </dd> 4853 4854 <dt><a name="mi_fieldnum" id="mi_fieldnum"><span class="big"> 4855 mi_FieldNum(connection_id, result_id, 4856 field_name)</span></a></dt> 4857 4858 <dd> 4859 <p>mi_FieldNum will return the number of the column slot that 4860 corresponds to the named field in the given Illustra result 4861 identifier. Field numbering starts at 0. This function will 4862 return <strong>-1</strong> on error.</p> 4863 4864 <p>This function is only available if Illustra support has 4865 been enabled in PHP.</p> 4866 </dd> 4867 4868 <dt><a name="mi_numfields" id="mi_numfields"><span class="big"> 4869 mi_NumFields(connection_id, result_id)</span></a></dt> 4870 4871 <dd> 4872 <p>mi_NumFields will return the number of fields (columns) in 4873 an Illustra result. The argument is a valid result identifier 4874 returned by mi_Exec. This function will return 4875 <strong>-1</strong> on error.</p> 4876 4877 <p>This function is only available if Illustra support has 4878 been enabled in PHP.</p> 4879 </dd> 4880 4881 <dt><a name="mi_numrows" id="mi_numrows"><span class="big"> 4882 mi_NumRows(connection_id, result_id)</span></a></dt> 4883 4884 <dd> 4885 <p>mi_NumRows will return the number of rows in an Illustra 4886 result. The argument is a valid result identifier returned by 4887 mi_Exec. This function will return <strong>-1</strong> on 4888 error.</p> 4889 4890 <p>This function is only available if Illustra support has 4891 been enabled in PHP.</p> 4892 </dd> 4893 4894 <dt><a name="mi_result" id="mi_result"><span class="big"> 4895 mi_Result(connection_id, result_id, row_number, field 4896 name/index)</span></a></dt> 4897 4898 <dd> 4899 <p>mi_Result will return values from a result identifier 4900 produced by mi_Exec. The row_number and field name specify 4901 what cell in the table of results to return. Row numbering 4902 starts from 0. Instead of naming the field, you may use the 4903 field index as an unquoted number. Field indices start from 4904 0.</p> 4905 4906 <p>All values returned from the database are in String form, 4907 since no type-detection is available at the present.</p> 4908 4909 <p>This function is only available if Illustra support has 4910 been enabled in PHP.</p> 4911 </dd> 4912 4913 <dt><a name="microtime" id="microtime"><span class="big"> 4914 Microtime()</span></a></dt> 4915 4916 <dd> 4917 <p>Microtime() returns a string "msec sec" where sec is 4918 number of seconds since 00:00 GMT, Jan 1, 1970, and msec is 4919 the microseconds part (as fraction of seconds). Ex 4920 "0.87633900 825010464".<br> 4921 This function is only available on operating systems that 4922 support the gettimeofday() system call.</p> 4923 </dd> 4924 4925 <dt><a name="min" id="min"><span class="big"> 4926 Min(array)</span></a></dt> 4927 4928 <dd> 4929 <p>Min returns the minimum value of a PHP array. ie. it will 4930 search through the entire array looking for the min element. 4931 If it is an array of strings, the returned string is the 4932 string which would be alphabetically first in the array if it 4933 were sorted.</p> 4934 </dd> 4935 4936 <dt><a name="mkdir" id="mkdir"><span class="big"> 4937 MkDir(dir,mode)</span></a></dt> 4938 4939 <dd> 4940 <p>MkDir creates a directory. The <em>mode</em> parameter 4941 must be given in <a href="#octal">octal</a> notation. eg. 4942 MkDir("DirName",0755);</p> 4943 </dd> 4944 4945 <dt><a name="mktime" id="mktime"><span class="big"> 4946 MkTime(hour,min,sec,mon,day,year)</span></a></dt> 4947 4948 <dd> 4949 <p>MkTime returns a time in Unix timestamp (long integer) 4950 format which corresponds to the date and time specified by 4951 the arguments. Arguments may be left out in which case the 4952 given component is set to the current value according to the 4953 current local time and date. These left out arguments may 4954 only be left out from right to left. ie. 4955 <code>MkTime(hour,min,sec)</code> is valid, but 4956 <code>MkTime(mon,day,year)</code> is not valid. Note that this 4957 function can be very handy as a tool for doing both date 4958 arithmetic and date validation. You can feed it invalid 4959 parameters, such as a month greater than 12, or a day greater 4960 than 31 and it will figure out the right date anyway. It will 4961 also generate an error message if any of the parameters are 4962 outside the normal values. Use the <a href= 4963 "#seterrorreporting">SetErrorReporting(0)</a> function to 4964 turn this error reporting off before calling the function and 4965 you may then check the $phperrmsg for any errors that may 4966 have occurred.</p> 4967 4968 <p>eg.</p> 4969 <pre> 4970 SetErrorReporting(0); 4971 $a = MkTime(0,0,0,13,1,1997); 4972 SetErrorReporting(1); 4973 echo $phperrmsg; 4974</pre> 4975 </dd> 4976 4977 <dt><a name="msql" id="msql"><span class="big">$result = 4978 msql($database,$query)</span></a></dt> 4979 4980 <dd> 4981 <p>msql sends an mSQL query. Arguments are the database name 4982 and the query string. ie. <strong><code><?msql("MyDatabase" 4983 , "select * from table")></code></strong>. The return value 4984 from this function is a result identifier to be used to 4985 access the results from the other msql_ functions. A result 4986 identifier is a positive integer. The function returns 4987 <strong>0</strong> when no result identifier is created. This 4988 is the case with any queries that do not return anything, 4989 such as <em>create</em>, <em>update</em>, <em>drop</em>, 4990 <em>insert</em> and <em>delete</em>. The function will return 4991 <strong>-1</strong> if an error occurs. A string describing 4992 the error will be placed in $phperrmsg, and unless the 4993 function was called as <strong>@msql()</strong> then this 4994 error string will also be printed out. For mSQL 2.0, the 4995 $result variable will contain the number of rows affected by 4996 the SQL command performed. If you want your application to be 4997 portable to mSQL 1.0, do not rely on this.<br> 4998 This function is only available if mSQL support has been 4999 enabled in PHP.</p> 5000 </dd> 5001 5002 <dt><a name="msql_close" id="msql_close"><span class="big"> 5003 msql_close()</span></a></dt> 5004 5005 <dd> 5006 <p>msql_Close closes the socket connection to the msql 5007 daemon, if an open connection exists. Note, since only one 5008 concurrent mSQL session can be open at any one time, this 5009 function does not take an argument.</p> 5010 </dd> 5011 5012 <dt><a name="msql_connect" id="msql_connect"><span class="big"> 5013 msql_connect($hostname)</span></a></dt> 5014 5015 <dd> 5016 <p>msql_Connect specifies the host name or IP on which the 5017 mSQL database engine resides. This is equivalent to the 5018 msqlConnect() function in the mSQL C API. The one difference 5019 between this function and the C API equivalent is that if the 5020 function isn't called, a connection to the local host is made 5021 by default on the first call to the msql() function. And, 5022 there is no need for an msql_close function since only one 5023 connection may be active at any one time. If a second call to 5024 msql_connect() is made in a file, then the connection to the 5025 first host is automatically closed. To explicitly connect to 5026 the msql daemon on the local host, use: 5027 <strong><code><?msql_connect("localhost")></code></strong><br> 5028 5029 This function is only available if mSQL support has been 5030 enabled in PHP.</p> 5031 </dd> 5032 5033 <dt><a name="msql_createdb" id="msql_createdb"><span class="big"> 5034 msql_CreateDB($database)</span></a></dt> 5035 5036 <dd> 5037 <p>msql_CreateDB creates the given database.<br> 5038 This function is only available if mSQL support has been 5039 enabled in PHP.</p> 5040 </dd> 5041 5042 <dt><a name="msql_dbname" id="msql_dbname"><span class="big"> 5043 msql_dbName($result,$i)</span></a></dt> 5044 5045 <dd> 5046 <p>msql_dbName returns the database name stored in position 5047 <em>$i</em> of the result pointer returned from the <a href= 5048 "#msql_listdbs">msql_ListDbs()</a> function. The <a href= 5049 "#msql_numrows">msql_NumRows()</a> function can be used to 5050 determine how many database names are available.<br> 5051 This function is only available if mSQL support has been 5052 enabled in PHP.</p> 5053 </dd> 5054 5055 <dt><a name="msql_dropdb" id="msql_dropdb"><span class="big"> 5056 msql_DropDB($database)</span></a></dt> 5057 5058 <dd> 5059 <p>msql_DropDB deletes the given mSQL database. Use this with 5060 caution as all data in the database will be lost.<br> 5061 This function is only available if mSQL support has been 5062 enabled in PHP.</p> 5063 </dd> 5064 5065 <dt><a name="msql_fieldflags" id="msql_fieldflags"><span class="big"> 5066 msql_FieldFlags($result,$i)</span></a></dt> 5067 5068 <dd> 5069 <p>msql_FieldFlags returns the field flags of the specified 5070 field. Currently this is either, "not null", "primary key", a 5071 combination of the two or "" (an empty string).<br> 5072 This function is only available if mSQL support has been 5073 enabled in PHP.</p> 5074 </dd> 5075 5076 <dt><a name="msql_fieldlen" id="msql_fieldlen"><span class="big"> 5077 msql_FieldLen($result,$i)</span></a></dt> 5078 5079 <dd> 5080 <p>msql_FieldLen returns the length of the specified 5081 field.<br> 5082 This function is only available if mSQL support has been 5083 enabled in PHP.</p> 5084 </dd> 5085 5086 <dt><a name="msql_fieldname" id="msql_fieldname"><span class="big"> 5087 msql_FieldName($result,$i)</span></a></dt> 5088 5089 <dd> 5090 <p>msql_FieldName returns the name of the specified field. 5091 Arguments to the function is the result identifier and the 5092 field index. ie. <code>msql_FieldName($result,2);</code> will 5093 return the name of the second field in the result associated 5094 with the result identifier.<br> 5095 This function is only available if mSQL support has been 5096 enabled in PHP.</p> 5097 </dd> 5098 5099 <dt><a name="msql_fieldtype" id="msql_fieldtype"><span class="big"> 5100 msql_FieldType($result,$i)</span></a></dt> 5101 5102 <dd> 5103 <p>msql_FieldType is similar to the msql_FieldName() 5104 function. The arguments are identical, but the field type is 5105 returned. This will be one of "int", "char" or "real".<br> 5106 This function is only available if mSQL support has been 5107 enabled in PHP.</p> 5108 </dd> 5109 5110 <dt><a name="msql_freeresult" id="msql_freeresult"><span class="big"> 5111 msql_FreeResult($result)</span></a></dt> 5112 5113 <dd> 5114 <p>msql_FreeResult only needs to be called if you are worried 5115 about using too much memory while your script is running. All 5116 result memory will automatically be freed when the script is 5117 finished. But, if you are sure you are not going to need the 5118 result data anymore in a script, you may call msql_freeresult 5119 with the result identifier as an argument and the associated 5120 result memory will be freed.<br> 5121 This function is only available if mSQL support has been 5122 enabled in PHP.</p> 5123 </dd> 5124 5125 <dt><a name="msql_listdbs" id="msql_listdbs"><span class="big"> 5126 $result = msql_ListDBs()</span></a></dt> 5127 5128 <dd> 5129 <p>msql_ListDBs will return a result pointer containing the 5130 databases available from the current mSQL daemon. Use the 5131 <a href="#msql_dbname">msql_dbName()</a> function to traverse 5132 this result pointer.<br> 5133 This function is only available if mSQL support has been 5134 enabled in PHP.</p> 5135 </dd> 5136 5137 <dt><a name="msql_listfields" id="msql_listfields"><span class="big"> 5138 $result = 5139 msql_Listfields($database,$tablename)</span></a></dt> 5140 5141 <dd> 5142 <p>msql_listfields retrieves information about the the given 5143 tablename. Arguments are the database name and the table 5144 name. A result pointer is returned which can be used with 5145 msql_fieldflags, msql_fieldlen, msql_fieldname, 5146 msql_fieldtype. A result identifier is a positive integer. 5147 The function returns -1 if a error occurs. A string 5148 describing the error will be placed in $phperrmsg, and unless 5149 the function was called as @msql() then this error string 5150 will also be printed out.<br> 5151 This function is only available if mSQL support has been 5152 enabled in PHP.</p> 5153 </dd> 5154 5155 <dt><a name="msql_listtables" id="msql_listtables"><span class="big"> 5156 $result = msql_ListTables($database)</span></a></dt> 5157 5158 <dd> 5159 <p>msql_ListTables takes a database name and result pointer 5160 much like the <a href="#msql">msql()</a> function. The 5161 <a href="#msql_tablename">msql_TableName()</a> function 5162 should be used to extract the actual table names from the 5163 result pointer.<br> 5164 This function is only available if mSQL support has been 5165 enabled in PHP.</p> 5166 </dd> 5167 5168 <dt><a name="msql_numfields" id="msql_numfields"><span class="big"> 5169 msql_NumFields($result)</span></a></dt> 5170 5171 <dd> 5172 <p>msql_NumFields returns the number of fields in a result. 5173 The argument is the result identifier returned by the msql() 5174 function.<br> 5175 This function is only available if mSQL support has been 5176 enabled in PHP.</p> 5177 </dd> 5178 5179 <dt><a name="msql_numrows" id="msql_numrows"><span class="big"> 5180 msql_NumRows($result)</span></a></dt> 5181 5182 <dd> 5183 <p>msql_NumRows simply returns the number of rows in a 5184 result. The argument is the result identifier returned by the 5185 msql() function.<br> 5186 This function is only available if mSQL support has been 5187 enabled in PHP.</p> 5188 </dd> 5189 5190 <dt><a name="msql_regcase" id="msql_regcase"><span class="big"> 5191 msql_RegCase(string)</span></a></dt> 5192 5193 <dd> 5194 <p>msql_RegCase takes a string argument and converts it to 5195 the regular expression needed to send to mSQL in order to get 5196 a case insensitive match. This turns a string like "abc" into 5197 "[Aa][Bb][Cc]".<br> 5198 This function is only available if mSQL support has been 5199 enabled in PHP.</p> 5200 </dd> 5201 5202 <dt><a name="msql_result" id="msql_result"><span class="big"> 5203 msql_Result($result,$i,field)</span></a></dt> 5204 5205 <dd> 5206 <p>msql_Result displays a field from a returned record. 5207 Arguments are the result identifier returned by the msql() 5208 function, an integer which is the index of the record to be 5209 viewed and a field name. The field argument supports the 5210 "table.field" syntax for handling results from a join. This 5211 function is perhaps best illustrated with a complete 5212 example:</p> 5213 <pre> 5214 <? 5215 $name = "bob"; 5216 $result = msql($database,"select * from table where firstname='$name'"); 5217 $num = msql_numrows($result); 5218 echo "$num records found!<p>"; 5219 $i=0; 5220 while($i<$num); 5221 echo msql_result($result,$i,"fullname"); 5222 echo "<br>"; 5223 echo msql_result($result,$i,"address"); 5224 echo "<br>"; 5225 $i++; 5226 endwhile; 5227 > 5228</pre> 5229 5230 <p>The above script connects to the mSQL engine on the local 5231 machine, sets the <em>name</em> variable to <em>bob</em> and 5232 sends a query which asks for all the fields from a table 5233 where the <em>firstname</em> field is set to <em>bob</em>. It 5234 then displays the number of records it found after which it 5235 loops through each of the found records and displays the 5236 <em>fullname</em> and <em>address</em> fields for each 5237 record. As you can see, it would be trivial to add HTML 5238 markup tags around the printed fields to format the results 5239 in a table or in whatever manner is desired. Note that there 5240 is no msql_connect() call. msql_connect need only be called 5241 if a connection to a remote database is desired.</p> 5242 5243 <p>This function is only available if mSQL support has been 5244 enabled in PHP.</p> 5245 </dd> 5246 5247 <dt><a name="msql_tablename" id="msql_tablename"><span class="big"> 5248 msql_TableName($result,$i)</span></a></dt> 5249 5250 <dd> 5251 <p>msql_TableName takes a result pointer returned by the 5252 <a href="#msql_listtables">msql_ListTables()</a> function as 5253 well as an integer index and returns the name of a table. The 5254 <a href="#msql_numrows">msql_NumRows()</a> function may be 5255 used to determine the number of tables in the result pointer. 5256 An example would be:</p> 5257 <pre> 5258 <? 5259 $result = msql_listtables("dbname"); 5260 $i=0; 5261 while($i < msql_numrows($result)); 5262 $tb_names[$i]=msql_tablename($result, $i); 5263 echo $tb_names[$i]; 5264 echo "<BR>"; 5265 $i++; 5266 endwhile; 5267 > 5268</pre><br> 5269 This function is only available if mSQL support has been 5270 enabled in PHP. 5271 </dd> 5272 5273 <dt><a name="mysql" id="mysql"><span class="big">$result = 5274 mysql($database,$query)</span></a></dt> 5275 5276 <dd> 5277 <p>mysql sends a mysql query. Arguments are the database name 5278 and the query string. ie. <strong><code><?mysql("MyDatabase" 5279 , "select * from table")></code></strong>. The return value 5280 from this function is a result identifier to be used to 5281 access the results from the other mysql_ functions. A result 5282 identifier is a positive integer. The function returns 5283 <strong>0</strong> when no result identifier is created. This 5284 is the case with any queries that do not return anything, 5285 such as <em>create</em>, <em>update</em>, <em>drop</em>, 5286 <em>insert</em> and <em>delete</em>. The function will return 5287 <strong>-1</strong> if an error occurs. A string describing 5288 the error will be placed in $phperrmsg, and unless the 5289 function was called as <strong>@mysql()</strong> then this 5290 error string will also be printed out.<br> 5291 This function is only available if mysql support has been 5292 enabled in PHP.</p> 5293 </dd> 5294 5295 <dt><a name="mysql_affected_rows" id= 5296 "mysql_affected_rows"><span class="big"> 5297 mysql_affected_rows()</span></a></dt> 5298 5299 <dd> 5300 <p>mysql_affected_rows() returns number of rows affected by 5301 the last INSERT, UPDATE or DELETE query.</p> 5302 </dd> 5303 5304 <dt><a name="mysql_close" id="mysql_close"><span class="big"> 5305 mysql_close()</span></a></dt> 5306 5307 <dd> 5308 <p>mysql_Close closes the socket connection to the mysql 5309 daemon, if an open connection exists.</p> 5310 </dd> 5311 5312 <dt><a name="mysql_connect" id="mysql_connect"><span class="big"> 5313 mysql_connect($hostname [,username 5314 [,password]])</span></a></dt> 5315 5316 <dd> 5317 <p>mysql_Connect specifies the host name or IP on which the 5318 mysql database engine resides. This is equivalent to the 5319 mysqlConnect() function in the mysql C API. The one 5320 difference between this function and the C API equivalent is 5321 that if the function isn't called, a connection to the local 5322 host is made by default on the first call to the mysql() 5323 function. And, there is no need for an mysql_close function 5324 since only one connection may be active at any one time. If a 5325 second call to mysql_connect() is made in a file, then the 5326 connection to the first host is automatically closed.</p> 5327 5328 <p>An optional username and password may be provided. Note 5329 that when PHP is compiled to run in <a href="#safemode">SAFE 5330 MODE</a> then the username must either be the same as the 5331 owner of the file being processed, or the owner of the httpd 5332 process (usually nobody). Any other username will fail.</p> 5333 5334 <p>To explicitly connect to the mysql daemon on the local 5335 host, use: 5336 <strong><code><?mysql_connect("localhost")></code></strong><br> 5337 5338 This function is only available if mysql support has been 5339 enabled in PHP.</p> 5340 </dd> 5341 5342 <dt><a name="mysql_createdb" id="mysql_createdb"><span class="big"> 5343 mysql_CreateDB($database)</span></a></dt> 5344 5345 <dd> 5346 <p>mysql_CreateDB creates the given database.<br> 5347 This function is only available if mysql support has been 5348 enabled in PHP.</p> 5349 </dd> 5350 5351 <dt><a name="mysql_dbname" id="mysql_dbname"><span class="big"> 5352 mysql_dbName($result,$i)</span></a></dt> 5353 5354 <dd> 5355 <p>mysql_dbName returns the database name stored in position 5356 <em>$i</em> of the result pointer returned from the <a href= 5357 "#mysql_listdbs">mysql_ListDbs()</a> function. The <a href= 5358 "#mysql_numrows">mysql_NumRows()</a> function can be used to 5359 determine how many database names are available.<br> 5360 This function is only available if mysql support has been 5361 enabled in PHP.</p> 5362 </dd> 5363 5364 <dt><a name="mysql_dropdb" id="mysql_dropdb"><span class="big"> 5365 mysql_DropDB($database)</span></a></dt> 5366 5367 <dd> 5368 <p>mysql_DropDB deletes the given mysql database. Use this 5369 with caution as all data in the database will be lost.<br> 5370 This function is only available if mysql support has been 5371 enabled in PHP.</p> 5372 </dd> 5373 5374 <dt><a name="mysql_fieldflags" id= 5375 "mysql_fieldflags"><span class="big">mysql_FieldFlags($result,$i)</span></a></dt> 5376 5377 <dd> 5378 <p>mysql_FieldFlags returns the field flags of the specified 5379 field. Currently this is either, "not null", "primary key", a 5380 combination of the two or "" (an empty string).<br> 5381 This function is only available if mysql support has been 5382 enabled in PHP.</p> 5383 </dd> 5384 5385 <dt><a name="mysql_fieldlen" id="mysql_fieldlen"><span class="big"> 5386 mysql_FieldLen($result,$i)</span></a></dt> 5387 5388 <dd> 5389 <p>mysql_FieldLen returns the length of the specified 5390 field.<br> 5391 This function is only available if mysql support has been 5392 enabled in PHP.</p> 5393 </dd> 5394 5395 <dt><a name="mysql_fieldname" id="mysql_fieldname"><span class="big"> 5396 mysql_FieldName($result,$i)</span></a></dt> 5397 5398 <dd> 5399 <p>mysql_FieldName returns the name of the specified field. 5400 Arguments to the function is the result identifier and the 5401 field index. ie. <code>mysql_FieldName($result,2);</code> will 5402 return the name of the second field in the result associated 5403 with the result identifier.<br> 5404 This function is only available if mysql support has been 5405 enabled in PHP.</p> 5406 </dd> 5407 5408 <dt><a name="mysql_fieldtype" id="mysql_fieldtype"><span class="big"> 5409 mysql_FieldType($result,$i)</span></a></dt> 5410 5411 <dd> 5412 <p>mysql_FieldType is similar to the mysql_FieldName() 5413 function. The arguments are identical, but the field type is 5414 returned. This will be one of "int", "char" or "real".<br> 5415 This function is only available if mysql support has been 5416 enabled in PHP.</p> 5417 </dd> 5418 5419 <dt><a name="mysql_freeresult" id= 5420 "mysql_freeresult"><span class="big">mysql_FreeResult($result)</span></a></dt> 5421 5422 <dd> 5423 <p>mysql_FreeResult only needs to be called if you are 5424 worried about using too much memory while your script is 5425 running. All result memory will automatically be freed when 5426 the script is finished. But, if you are sure you are not 5427 going to need the result data anymore in a script, you may 5428 call mysql_freeresult with the result identifier as an 5429 argument and the associated result memory will be 5430 freed.<br> 5431 This function is only available if mysql support has been 5432 enabled in PHP.</p> 5433 </dd> 5434 5435 <dt><a name="mysql_insert_id" id="mysql_insert_id"><span class="big"> 5436 mysql_insert_id()</span></a></dt> 5437 5438 <dd> 5439 <p>mysql_insert_id() returns the ID generated for an 5440 AUTO_INCREMENT field. This function takes no arguments. It 5441 will return the auto-generated ID returned by the last INSERT 5442 query performed.</p> 5443 </dd> 5444 5445 <dt><a name="mysql_listdbs" id="mysql_listdbs"><span class="big"> 5446 $result = mysql_ListDBs()</span></a></dt> 5447 5448 <dd> 5449 <p>mysql_ListDBs will return a result pointer containing the 5450 databases available from the current mysql daemon. Use the 5451 <a href="#mysql_dbname">mysql_dbName()</a> function to 5452 traverse this result pointer.<br> 5453 This function is only available if mysql support has been 5454 enabled in PHP.</p> 5455 </dd> 5456 5457 <dt><a name="mysql_listfields" id= 5458 "mysql_listfields"><span class="big">$result = 5459 mysql_Listfields($database,$tablename)</span></a></dt> 5460 5461 <dd> 5462 <p>mysql_listfields retrieves information about the the given 5463 tablename. Arguments are the database name and the table 5464 name. A result pointer is returned which can be used with 5465 mysql_fieldflags, mysql_fieldlen, mysql_fieldname, 5466 mysql_fieldtype. A result identifier is a positive integer. 5467 The function returns -1 if a error occurs. A string 5468 describing the error will be placed in $phperrmsg, and unless 5469 the function was called as @mysql() then this error string 5470 will also be printed out.<br> 5471 This function is only available if mysql support has been 5472 enabled in PHP.</p> 5473 </dd> 5474 5475 <dt><a name="mysql_listtables" id= 5476 "mysql_listtables"><span class="big">$result = 5477 mysql_ListTables($database)</span></a></dt> 5478 5479 <dd> 5480 <p>mysql_ListTables takes a database name and result pointer 5481 much like the <a href="#mysql">mysql()</a> function. The 5482 <a href="#mysql_tablename">mysql_TableName()</a> function 5483 should be used to extract the actual table names from the 5484 result pointer.<br> 5485 This function is only available if mysql support has been 5486 enabled in PHP.</p> 5487 </dd> 5488 5489 <dt><a name="mysql_numfields" id="mysql_numfields"><span class="big"> 5490 mysql_NumFields($result)</span></a></dt> 5491 5492 <dd> 5493 <p>mysql_NumFields returns the number of fields in a result. 5494 The argument is the result identifier returned by the mysql() 5495 function.<br> 5496 This function is only available if mysql support has been 5497 enabled in PHP.</p> 5498 </dd> 5499 5500 <dt><a name="mysql_numrows" id="mysql_numrows"><span class="big"> 5501 mysql_NumRows($result)</span></a></dt> 5502 5503 <dd> 5504 <p>mysql_NumRows simply returns the number of rows in a 5505 result. The argument is the result identifier returned by the 5506 mysql() function.<br> 5507 This function is only available if mysql support has been 5508 enabled in PHP.</p> 5509 </dd> 5510 5511 <dt><a name="mysql_result" id="mysql_result"><span class="big"> 5512 mysql_Result($result,$i,field)</span></a></dt> 5513 5514 <dd> 5515 <p>mysql_Result displays a field from a returned record. 5516 Arguments are the result identifier returned by the mysql() 5517 function, an integer which is the index of the record to be 5518 viewed and a field name. The field argument supports the 5519 "table.field" syntax for handling results from a join. One 5520 difference between mSQL 1.0 and mysql is that mysql supports 5521 functions that can act on the result data. These functions 5522 can be applied in this function. This function is perhaps 5523 best illustrated with a complete example:</p> 5524 <pre> 5525 <? 5526 $name = "bob"; 5527 $result = mysql($database,"select * from table where firstname='$name'"); 5528 $num = mysql_numrows($result); 5529 echo "$num records found!<p>"; 5530 $i=0; 5531 while($i<$num); 5532 echo mysql_result($result,$i,"lcase(fullname)"); 5533 echo "<br>"; 5534 echo mysql_result($result,$i,"address"); 5535 echo "<br>"; 5536 $i++; 5537 endwhile; 5538 > 5539</pre> 5540 5541 <p>The above script connects to the mysql engine on the local 5542 machine, sets the <em>name</em> variable to <em>bob</em> and 5543 sends a query which asks for all the fields from a table 5544 where the <em>firstname</em> field is set to <em>bob</em>. It 5545 then displays the number of records it found after which it 5546 loops through each of the found records and displays the 5547 <em>fullname</em> and <em>address</em> fields for each 5548 record. The lcase() call in the result function changes the 5549 returned string to lower case. For a complete set of 5550 functions that can be applied to the result data, see your 5551 mysql documentation. As you can see, it would be trivial to 5552 add HTML markup tags around the printed fields to format the 5553 results in a table or in whatever manner is desired. Note 5554 that there is no mysql_connect() call. mysql_connect need 5555 only be called if a connection to a remote database is 5556 desired.</p> 5557 5558 <p>This function is only available if mysql support has been 5559 enabled in PHP.</p> 5560 </dd> 5561 5562 <dt><a name="mysql_tablename" id="mysql_tablename"><span class="big"> 5563 mysql_TableName($result,$i)</span></a></dt> 5564 5565 <dd> 5566 <p>mysql_TableName takes a result pointer returned by the 5567 <a href="#mysql_listtables">mysql_ListTables()</a> function 5568 as well as an integer index and returns the name of a table. 5569 The <a href="#mysql_numrows">mysql_NumRows()</a> function may 5570 be used to determine the number of tables in the result 5571 pointer. An example would be:</p> 5572 <pre> 5573 <? 5574 $result = mysql_listtables("dbname"); 5575 $i=0; 5576 while($i < mysql_numrows($result)); 5577 $tb_names[$i]=mysql_tablename($result, $i); 5578 echo $tb_names[$i]; 5579 echo "<BR>"; 5580 $i++; 5581 endwhile; 5582 > 5583</pre><br> 5584 This function is only available if mysql support has been 5585 enabled in PHP. 5586 </dd> 5587 5588 <dt><a name="next" id="next"><span class="big"> 5589 Next(variable)</span></a></dt> 5590 5591 <dd> 5592 <p>Next moves the internal array pointer to the next item in 5593 the array. This happens automatically when an array is 5594 accessed using the non-indexed method ($array[]). The 5595 function returns the value of the new item. This function can 5596 be used to move the pointer forward without having to access 5597 the array explicitly. One use would be to traverse an 5598 associative array and only printing out the keys of the array 5599 and not the actual contents.</p> 5600 <pre> 5601 <? 5602 Reset($array); 5603 $i=0; 5604 while($i < count($array)); 5605 echo key($array); 5606 next($array); 5607 $i++; 5608 endwhile; 5609 > 5610</pre> 5611 </dd> 5612 5613 <dt><a name="octdec" id="octdec"><span class="big"> 5614 OctDec(octal_number)</span></a></dt> 5615 5616 <dd> 5617 <p>OctDec converts an octal number to a decimal number. See 5618 also <a href="#decoct">DecOct()</a>.</p> 5619 </dd> 5620 5621 <dt><a name="opendir" id="opendir"><span class="big"> 5622 openDir(directory)</span></a></dt> 5623 5624 <dd> 5625 <p>openDir opens the specified directory and places an 5626 internal pointer to the beginning of the directory. Directory 5627 entries are read using the <a href="#readdir">readDir</a> 5628 function, and an opened directory should be closed with the 5629 <a href="#closedir">closeDir</a> function.</p> 5630 </dd> 5631 5632 <dt><a name="openlog" id="openlog"><span class="big"> 5633 OpenLog(ident,options,facility)</span></a></dt> 5634 5635 <dd> 5636 <p>OpenLog() initializes the system for further Syslog() 5637 calls. See the openlog(3) UNIX man page for more details. See 5638 also <a href="#initsyslog">InitSyslog()</a>, <a href= 5639 "#syslog">Syslog()</a> and <a href= 5640 "#closelog">CloseLog()</a>.</p> 5641 </dd> 5642 5643 <dt><a name="ora_bind" id="ora_bind"><span class="big"> 5644 Ora_Bind(cursor_ind, php_variable_name, sql_variable_name, 5645 size)</span></a><br></dt> 5646 5647 <dd>Ora_Bind() performs binding of PHP variables with Oracle 5648 ones.<br> 5649 <br> 5650 Function parameters are:<br></dd> 5651 5652 <dd> 5653 <var>cursor_id</var> - oracle cursor id for _parsed_ SQL 5654 query or PL/SQL block;<br> 5655 <var>php_variable_name</var> - variable name in PHP script 5656 without leading '$'<br> 5657 <var>sql_variable_name</var> - variable name in SQL with 5658 leading colon<br> 5659 <var>size</var> - maximal number of bytes to be taken into 5660 account at binding<br> 5661 <br> 5662 <b>Notes:</b><br> 5663 1) PHP variable <b>SHOULD</b> be initialised with at least 5664 <b>size</b> bytes length string even it is return-only 5665 variable.<br> 5666 2) Ora_Bind() <b>SHOULD</b> be used after Ora_Parse and 5667 before Ora_Exec. In case of re-parsing the SQL sentence, all 5668 used variables have to be re-bound.<br> 5669 <br> 5670 Ora_Bind() returns 0 upon success, -1 upon failure.<br> 5671 5672 <p>There is an example of Ora_Bind() usage:</p> 5673 <pre> 5674 5675 /* This is the PHP variable to be bound */ 5676 $rc = "12345"; 5677 5678 /* This is the SQL query. */ 5679 $query = "SELECT * FROM my_table where my_index = :indiana"; 5680 5681 ........ 5682 5683 if (Ora_Parse($cursor, $query) < 0) { 5684 echo("Parse failed!\n" 5685 Ora_Logoff($conn); 5686 exit; 5687 } 5688 5689 if (Ora_Bind($cursor, "rc", ":indiana", strlen($rc)) < 0) { 5690 echo("Binding failed!\n" 5691 Ora_Logoff($conn); 5692 exit; 5693 } 5694 5695 /* Execute the SQL statement associated with $cursor and 5696 prepare storage for select-list items. */ 5697 $ncols = Ora_Exec($cursor); 5698 5699 ...... 5700 5701</pre> 5702 </dd> 5703 5704 <dt><a name="ora_close" id="ora_close"><span class="big"> 5705 Ora_Close(conn_ind)</span></a></dt> 5706 5707 <dd>Ora_Close() closes the Oracle connection identified by 5708 <var>conn_ind</var>. Returns 0 upon success, -1 upon 5709 failure.</dd> 5710 5711 <dt><a name="ora_commit" id="ora_commit"><span class="big"> 5712 Ora_Commit(conn_ind)</span></a></dt> 5713 5714 <dd>Commits the current transaction on <var>conn_ind</var>. The 5715 current transaction starts from the <a href= 5716 "#ora_logon">Ora_Logon()</a> call or from the last Ora_Commit() 5717 or <a href="#ora_rollback">Ora_Rollback()</a>, and lasts until 5718 an Ora_Commit(), <a href="#ora_rollback">Ora_Rollback()</a> or 5719 <a href="#ora_logoff">Ora_Logoff()</a> call is issued. 5720 Ora_Commit() returns -1 (and an error message) upon 5721 failure.</dd> 5722 5723 <dt><a name="ora_commitoff" id="ora_commitoff"><span class="big"> 5724 Ora_CommitOff(conn_ind)</span></a></dt> 5725 5726 <dd>Ora_CommitOff() turns off autocommit (automatic commit of 5727 every SQL data manipulation statement) on the Oracle connection 5728 <var>conn_ind</var>.</dd> 5729 5730 <dt><a name="ora_commiton" id="ora_commiton"><span class="big"> 5731 Ora_CommitOn(conn_ind)</span></a></dt> 5732 5733 <dd>Ora_CommitOff() turns on autocommit (automatic commit of 5734 every SQL data manipulation statement) on the Oracle connection 5735 <var>conn_ind</var>.</dd> 5736 5737 <dt><a name="ora_exec" id="ora_exec"><span class="big"> 5738 Ora_Exec(cursor_ind)</span></a></dt> 5739 5740 <dd>Ora_Exec() executes the SQL statement associated with 5741 <var>cursor_ind</var> and prepares storage for select-list 5742 items. The return value is the number of columns for selects, 5743 or -1 on error.</dd> 5744 5745 <dt><a name="ora_fetch" id="ora_fetch"><span class="big"> 5746 Ora_Fetch(cursor_ind)</span></a></dt> 5747 5748 <dd>Ora_Fetch() retrieves a row from the database. Returns 1 if 5749 a column was retrieved, 0 if there are no more columns to 5750 retrieve or -1 on error.</dd> 5751 5752 <dt><a name="ora_getcolumn" id="ora_getcolumn"><span class="big"> 5753 Ora_GetColumn(cursor_ind, column)</span></a></dt> 5754 5755 <dd>Ora_GetColumn() fetches data for a single column in a 5756 returned row. <a href="ora_fetch">Ora_Fetch()</a> must have 5757 been called prior to Ora_GetColumn().</dd> 5758 5759 <dt><a name="ora_logoff" id="ora_logoff"><span class="big"> 5760 Ora_Logoff(conn_ind)</span></a></dt> 5761 5762 <dd>Ora_Logoff() disconnects the logon data area belonging to 5763 <var>conn_ind</var> and frees used Oracle resources.</dd> 5764 5765 <dt><a name="ora_logon" id="ora_logon"><span class="big"> 5766 Ora_Logon(userid, password)</span></a></dt> 5767 5768 <dd>Ora_Logon() establishes a connection between PHP and an 5769 Oracle database with the given user id and password. Returns 0 5770 on success and -1 on failure.</dd> 5771 5772 <dt><a name="ora_open" id="ora_open"><span class="big"> 5773 Ora_Open(conn_ind)</span></a></dt> 5774 5775 <dd>Ora_Open() opens a cursor in Oracle that maintains state 5776 information about the processing of a SQL statement. Returns a 5777 cursor index or -1 on error.</dd> 5778 5779 <dt><a name="ora_parse" id="ora_parse"><span class="big"> 5780 Ora_Parse(cursor_ind, sql_statement [, 5781 defer])</span></a></dt> 5782 5783 <dd>Ora_Parse() parses a SQL statement or PL/SQL block and 5784 associates it with a cursor. An optional third argument can be 5785 set to 1 to defer the parse. Returns 0 on success or -1 on 5786 error.</dd> 5787 5788 <dt><a name="ora_rollback" id="ora_rollback"><span class="big"> 5789 Ora_Rollback(cursor_ind)</span></a></dt> 5790 5791 <dd>Ora_Rollback() rolls back the current transaction. See 5792 <a href="#ora_commit">Ora_Commit()</a> for a definition of the 5793 current transaction.</dd> 5794 5795 <dt><a name="ord" id="ord"><span class="big"> 5796 Ord(arg)</span></a></dt> 5797 5798 <dd> 5799 <p>Ord returns the ASCII value of the first character of 5800 arg.</p> 5801 </dd> 5802 5803 <dt><a name="parse_str" id="parse_str"><span class="big"> 5804 Parse_Str(arg)</span></a></dt> 5805 5806 <dd> 5807 <p>Parse_str takes a string identical to a regular URL 5808 encoded string and extracts variables and their values.<br> 5809 ex.</p> 5810 <pre> 5811 <? parse_str("a[]=hello+world&a[]=second+variable"); 5812 echo $a[],"<br>"; 5813 echo $a[],"<br>"; 5814 > 5815 5816produces 5817 5818hello world 5819second variable 5820</pre> 5821 </dd> 5822 5823 <dt><a name="passthru" id="passthru"><span class="big"> 5824 PassThru(command_string [,return_var])</span></a></dt> 5825 5826 <dd> 5827 <p>The PassThru() function is similar to the <a href= 5828 "#exec">Exec()</a> function in that it executes a Unix 5829 command. If the return_var argument is present, the return 5830 status of the Unix command will be placed here. This command 5831 should be used in place of Exec or System when the output 5832 from the Unix command is binary data which needs to be passed 5833 directly back to the browser. A common use for this is to 5834 execute something like the pbmplus utilities that can output 5835 an image stream directly. By setting the content-type to 5836 <em>image/gif</em> and then calling a pbmplus program to 5837 output a gif, you can create PHP/FI scripts that output 5838 images directly.</p> 5839 </dd> 5840 5841 <dt><a name="pclose" id="pclose"><span class="big"> 5842 pclose(fp)</span></a></dt> 5843 5844 <dd> 5845 <p>Pclose closes a pipe opened using the <a href= 5846 "#popen">popen()</a> function.</p> 5847 </dd> 5848 5849 <dt><a name="pg_close" id="pg_close"><span class="big"> 5850 pg_Close(connection_id)</span></a></dt> 5851 5852 <dd> 5853 <p>pg_Close will close down the connection to a Postgres 5854 database associated with the given connection identifier.</p> 5855 5856 <p>This function is only available if Postgres support has 5857 been enabled in PHP.</p> 5858 </dd> 5859 5860 <dt><a name="pg_connect" id="pg_connect"><span class="big"> 5861 $connection = pg_Connect(host, port, options, tty, 5862 dbname)</span></a></dt> 5863 5864 <dd> 5865 <p>pg_Connect opens a connection to a Postgres database. Each 5866 of the arguments should be a quoted string, including the 5867 port number. The options and tty arguments are optional and 5868 can be empty strings. This function returns a connection_id. 5869 This identifier is needed by other Postgres functions. You 5870 can have multiple connections open at once. This function 5871 will return <strong>0</strong> on error.</p> 5872 5873 <p>This function is only available if Postgres support has 5874 been enabled in PHP.</p> 5875 </dd> 5876 5877 <dt><a name="pg_dbname" id="pg_dbname"><span class="big"> 5878 pg_DBname(connection_id)</span></a></dt> 5879 5880 <dd> 5881 <p>pg_DBname will return the name of the database that the 5882 given Postgres connection identifier is connected to.</p> 5883 5884 <p>This function is only available if Postgres support has 5885 been enabled in PHP.</p> 5886 </dd> 5887 5888 <dt><a name="pg_errorMessage" id="pg_errorMessage"><span class="big"> 5889 pg_ErrorMessage(connection_id)</span></a></dt> 5890 5891 <dd> 5892 <p>If an error occured on the last database action for which 5893 a valid connection exists, this function will return a string 5894 containing the error message generated by the back-end 5895 server.</p> 5896 5897 <p>This function is only available if Postgres support has 5898 been enabled in PHP.</p> 5899 </dd> 5900 5901 <dt><a name="pg_exec" id="pg_exec"><span class="big">$result = 5902 pg_Exec(connection_id, query_string)</span></a></dt> 5903 5904 <dd> 5905 <p>pg_Exec will send an SQL statement to the Postgres 5906 database specified by the connection_id. The connection_id 5907 must be a valid identifier that was returned by pg_Connect. 5908 The return value of this function is an identifier to be used 5909 to access the results from other Postgres functions. This 5910 function will return <strong>0</strong> on error. It will 5911 return <strong>1</strong> when the command executed correctly 5912 but are not expected to returned data (insert or update 5913 commands, for example). Note that selects which return no 5914 data will still return a valid result greater than 1.</p> 5915 5916 <p>This function is only available if Postgres support has 5917 been enabled in PHP.</p> 5918 </dd> 5919 5920 <dt><a name="pg_fieldname" id="pg_fieldname"><span class="big"> 5921 pg_FieldName(result_id, field_number)</span></a></dt> 5922 5923 <dd> 5924 <p>pg_FieldName will return the name of the field occupying 5925 the given column number in the given Postgres result 5926 identifier. Field numbering starts from 0.</p> 5927 5928 <p>This function is only available if Postgres support has 5929 been enabled in PHP.</p> 5930 </dd> 5931 5932 <dt><a name="pg_fieldprtlen" id="pg_fieldprtlen"><span class="big"> 5933 pg_FieldPrtLen(result_id, row_number, 5934 field_name)</span></a></dt> 5935 5936 <dd> 5937 <p>pg_FieldPrtLen will return the actual printed length 5938 (number of characters) of a specific value in a Postgres 5939 result. Row numbering starts at 0. This function will return 5940 <strong>-1</strong> on an error.</p> 5941 5942 <p>This function is only available if Postgres support has 5943 been enabled in PHP.</p> 5944 </dd> 5945 5946 <dt><a name="pg_fieldnum" id="pg_fieldnum"><span class="big"> 5947 pg_FieldNum(result_id, field_name)</span></a></dt> 5948 5949 <dd> 5950 <p>pg_FieldNum will return the number of the column slot that 5951 corresponds to the named field in the given Postgres result 5952 identifier. Field numbering starts at 0. This function will 5953 return <strong>-1</strong> on error.</p> 5954 5955 <p>This function is only available if Postgres support has 5956 been enabled in PHP.</p> 5957 </dd> 5958 5959 <dt><a name="pg_fieldsize" id="pg_fieldsize"><span class="big"> 5960 pg_FieldSize(result_id, field_name)</span></a></dt> 5961 5962 <dd> 5963 <p>pg_FieldSize will return the internal storage size (in 5964 bytes) of the named field in the given Postgres result. A 5965 field size of 0 indicates a variable length field. This 5966 function will return <strong>-1</strong> on error.</p> 5967 5968 <p>This function is only available if Postgres support has 5969 been enabled in PHP.</p> 5970 </dd> 5971 5972 <dt><a name="pg_fieldtype" id="pg_fieldtype"><span class="big"> 5973 pg_FieldType(result_id, field_number)</span></a></dt> 5974 5975 <dd> 5976 <p>pg_FieldType will return a string containing the type name 5977 of the given field in the given Postgres result identifier. 5978 Field numbering starts at 0.</p> 5979 5980 <p>This function is only available if Postgres support has 5981 been enabled in PHP.</p> 5982 </dd> 5983 5984 <dt><a name="pg_freeresult" id="pg_freeresult"><span class="big"> 5985 pg_FreeResult(result_id)</span></a></dt> 5986 5987 <dd> 5988 <p>pg_FreeResult only needs to be called if you are worried 5989 about using too much memory while your script is running. All 5990 result memory will automatically be freed when the script is 5991 finished. But, if you are sure you are not going to need the 5992 result data anymore in a script, you may call pg_freeresult 5993 with the result identifier as an argument and the associated 5994 result memory will be freed.</p> 5995 5996 <p>This function is only available if Postgres support has 5997 been enabled in PHP.</p> 5998 </dd> 5999 6000 <dt><a name="pg_getlastoid" id="pg_getlastoid"><span class="big"> 6001 pg_GetLastOid()</span></a></dt> 6002 6003 <dd> 6004 <p>pg_GetLastOid can be used to retrieve the Oid assigned to 6005 an inserted tuple if the last command sent via pg_Exec was an 6006 SQL Insert. This function will return a positive integer if 6007 there was a valid Oid. It will return <strong>-1</strong> if 6008 an error occured or the last command sent via pg_Exec was not 6009 an Insert.</p> 6010 6011 <p>This function is only available if Postgres support has 6012 been enabled in PHP.</p> 6013 </dd> 6014 6015 <dt><a name="pg_host" id="pg_host"><span class="big"> 6016 pg_Host(connection_id)</span></a></dt> 6017 6018 <dd> 6019 <p>pg_Host will return the host name the the given Postgres 6020 connection identifier is connected to.</p> 6021 6022 <p>This function is only available if Postgres support has 6023 been enabled in PHP.</p> 6024 </dd> 6025 6026 <dt><a name="pg_numfields" id="pg_numfields"><span class="big"> 6027 pg_NumFields(result_id)</span></a></dt> 6028 6029 <dd> 6030 <p>pg_NumFields will return the number of fields (columns) in 6031 a Postgres result. The argument is a valid result identifier 6032 returned by pg_Exec. This function will return 6033 <strong>-1</strong> on error.</p> 6034 6035 <p>This function is only available if Postgres support has 6036 been enabled in PHP.</p> 6037 </dd> 6038 6039 <dt><a name="pg_numrows" id="pg_numrows"><span class="big"> 6040 pg_NumRows(result_id)</span></a></dt> 6041 6042 <dd> 6043 <p>pg_NumRows will return the number of rows in a Postgres 6044 result. The argument is a valid result identifier returned by 6045 pg_Exec. This function will return <strong>-1</strong> on 6046 error.</p> 6047 6048 <p>This function is only available if Postgres support has 6049 been enabled in PHP.</p> 6050 </dd> 6051 6052 <dt><a name="pg_options" id="pg_options"><span class="big"> 6053 pg_Options(connection_id)</span></a></dt> 6054 6055 <dd> 6056 <p>pg_Options will return a string containing the options 6057 specified on the given Postgres connection identifier.</p> 6058 6059 <p>This function is only available if Postgres support has 6060 been enabled in PHP.</p> 6061 </dd> 6062 6063 <dt><a name="pg_port" id="pg_port"><span class="big"> 6064 pg_Port(connection_id)</span></a></dt> 6065 6066 <dd> 6067 <p>pg_Port will return the port number that the given 6068 Postgres connection identifier is connected to.</p> 6069 6070 <p>This function is only available if Postgres support has 6071 been enabled in PHP.</p> 6072 </dd> 6073 6074 <dt><a name="pg_result" id="pg_result"><span class="big"> 6075 pg_Result(result_id, row_number, field 6076 name/index)</span></a></dt> 6077 6078 <dd> 6079 <p>pg_Result will return values from a result identifier 6080 produced by pg_Exec. The row_number and field name specify 6081 what cell in the table of results to return. Row numbering 6082 starts from 0. Instead of naming the field, you may use the 6083 field index as an unquoted number. Field indices start from 6084 0.</p> 6085 6086 <p>Postgres has many built in types and only the basic ones 6087 are directly supported here. All forms of integer, boolean 6088 and oid types are returned as integer values. All forms of 6089 float, and real types are returned as double values. All 6090 other types, including arrays are returned as strings 6091 formatted in the same default Postgres manner that you would 6092 see in the 'monitor' or 'psql' programs.</p> 6093 6094 <p>Support for returning PHP arrays of numerical and string 6095 data from a Postgres result is planned for a later date.</p> 6096 6097 <p>This function is only available if Postgres support has 6098 been enabled in PHP.</p> 6099 </dd> 6100 6101 <dt><a name="pg_tty" id="pg_tty"><span class="big"> 6102 pg_tty(connection_id)</span></a></dt> 6103 6104 <dd> 6105 <p>pg_tty will return the tty name that server side debugging 6106 output is sent to on the given Postgres connection 6107 identifier.</p> 6108 6109 <p>This function is only available if Postgres support has 6110 been enabled in PHP.</p> 6111 </dd> 6112 6113 <dt><a name="phpinfo" id="phpinfo"><span class="big"> 6114 phpInfo()</span></a></dt> 6115 6116 <dd> 6117 <p>phpInfo prints the same page you get when adding "?info" 6118 to a PHP/FI parsed URL or when you run the php.cgi binary by 6119 itself. It is especially useful for debugging scripts in the 6120 Apache module version since it displays a number of useful 6121 internal data.</p> 6122 </dd> 6123 6124 <dt><a name="phpversion" id="phpversion"><span class="big"> 6125 phpVersion()</span></a></dt> 6126 6127 <dd> 6128 <p>phpVersion returns the version number of PHP/FI currently 6129 running.</p> 6130 </dd> 6131 6132 <dt><a name="popen" id="popen"><span class="big">fp = 6133 popen(command,mode)</span></a></dt> 6134 6135 <dd> 6136 <p>Popen opens a pipe to a command and returns a file pointer 6137 index. This file pointer index can be used by <a href= 6138 "#fgets">fgets</a>, <a href="#fputs">fputs</a> and <a href= 6139 "#fclose">fclose</a>. Arguments are the command to run and 6140 the mode. The mode can be either "r" for read or "w" for 6141 write. See the UNIX C library popen man page for more 6142 details. Any file opened with popen() should be closed using 6143 the <a href="#pclose">pclose()</a> function.</p> 6144 </dd> 6145 6146 <dt><a name="pos" id="pos"><span class="big"> 6147 pos(var)</span></a></dt> 6148 6149 <dd> 6150 <p>The Pos() function returns the numerical position of an 6151 array element within that array. This is not very useful for 6152 normal arrays, but for associative arrays it can be 6153 handy.</p> 6154 </dd> 6155 6156 <dt><a name="pow" id="pow"><span class="big"> 6157 pow(x,y)</span></a></dt> 6158 6159 <dd> 6160 <p>Evaluates x raised to the power of y. See also <a href= 6161 "#exp">Exp()</a></p> 6162 </dd> 6163 6164 <dt><a name="prev" id="prev"><span class="big"> 6165 Prev(variable)</span></a></dt> 6166 6167 <dd> 6168 <p>Prev moves the internal array pointer for the given 6169 variable to the previous item in the array. If already at the 6170 beginning of the list, the pointer will point to the first 6171 item. The function returns the value of the new item. This 6172 function is useful for traversing an associative array in 6173 reverse order. See the example in the <a href= 6174 "#end">End()</a> definition. Also see <a href= 6175 "#next">Next()</a>.</p> 6176 </dd> 6177 6178 <dt><a name="putenv" id="putenv"><span class="big"> 6179 PutEnv(string)</span></a></dt> 6180 6181 <dd> 6182 <p>PutEnv puts the given string in the environment. Not 6183 extremely useful since the local environment variables are 6184 wiped out when PHP is done with a page, but in some cases it 6185 is useful if other things called from within a PHP script 6186 checks environment variables. For example, if you want to run 6187 multiple mSQL daemon processes, you will need to use PutEnv 6188 to switch back and forth between the different sockets.</p> 6189 </dd> 6190 6191 <dt><a name="quotemeta" id="quotemeta"><span class="big"> 6192 QuoteMeta(arg)</span></a></dt> 6193 6194 <dd> 6195 <p>QuoteMeta returns a string composed of arg with any 6196 regular expression special characters escaped with a 6197 backslash.</p> 6198 </dd> 6199 6200 <dt><a name="rand" id="rand"><span class="big"> 6201 Rand()</span></a></dt> 6202 6203 <dd> 6204 <p>Rand returns a random number between 0 and RANDMAX. 6205 <b>Remember</b> to seed your random number generator with a 6206 call to <a href="#srand">srand()</a> before calling rand(). 6207 You only need to seed the random number generator once. 6208 RANDMAX can be determined with the <a href= 6209 "#getrandmax">getRandMax</a> function. Normally a specific 6210 range is chosen by simply using the modulus operator on the 6211 result.</p> 6212 </dd> 6213 6214 <dt><a name="readdir" id="readdir"><span class="big"> 6215 readDir()</span></a></dt> 6216 6217 <dd> 6218 <p>readDir reads the next entry from the currently open 6219 directory structure. Once an entry is read, the pointer is 6220 advanced to the next entry in the directory and the next call 6221 to this function will return the next entry in the directory. 6222 Use the <a href="#opendir">openDir</a> function to open a 6223 directory before calling this function.</p> 6224 </dd> 6225 6226 <dt><a name="readfile" id="readfile"><span class="big"> 6227 ReadFile(filename)</span></a></dt> 6228 6229 <dd> 6230 <p>$size = ReadFile(Filename) - Reads the file filename and 6231 simply outputs it directly. It returns the number of bytes 6232 actually read. It is different from the File() command in 6233 that it does not store the file in memory, and it is safe for 6234 use on binary files. This function is generally used where 6235 one might otherwise do a PassThru("cat filename"). Using 6236 ReadFile is more efficient.</p> 6237 </dd> 6238 6239 <dt><a name="readlink" id="readlink"><span class="big"> 6240 ReadLink(path)</span></a></dt> 6241 6242 <dd>ReadLink does the same as the readlink C function and 6243 returns the contents of the symbolic link path or -1 in case of 6244 error. See also <a href="#linkinfo">LinkInfo</a>.</dd> 6245 6246 <dt><a name="reg_match" id="reg_match"><span class="big"> 6247 reg_Match(expr,arg[,regs])</span></a></dt> 6248 6249 <dd> 6250 <p><b>This function has been replaced by the <a href= 6251 "#ereg">ereg()</a> function. It is however still available 6252 for backwards compatibility.</b><br> 6253 reg_Match returns non-zero if the regular expression is 6254 matched in the argument string. For example, the condition, 6255 <code><?if (reg_match("^This.*", "This is an example 6256 string")></code> would be true since the "^This.*" 6257 expression says to match the word <strong>This</strong> at 6258 the beginning of the string and then match any characters 6259 afterwards. If the <em>regs</em> argument is present, then 6260 match registers are filled into positions 0-10 in the array 6261 named by the <em>regs</em> argument. Register 0 will always 6262 contain the full matched string. For more information on 6263 regular expressions, see the <a href="#regexp">regular 6264 expression section</a> of this document.</p> 6265 </dd> 6266 6267 <dt><a name="reg_replace" id="reg_replace"><span class="big"> 6268 reg_replace(expr,replace,arg)</span></a></dt> 6269 6270 <dd> 6271 <p><b>This function has been replaced by the <a href= 6272 "#ereg_replace">ereg_replace()</a> function. It is however 6273 still available for backwards compatibility.</b><br> 6274 reg_Replace scans the entire argument string and replaces any 6275 portions of the string matched by the given expression with 6276 the replacement string. For example, in the string, <code>"This 6277 is an example string"</code> we could very easily replace every 6278 space with a dash with the command: <strong>reg_replace(" 6279 ","-","This is an example string")</strong>.For more 6280 information on regular expressions, see the <a href= 6281 "#regexp">regular expression section</a> of this 6282 document.</p> 6283 </dd> 6284 6285 <dt><a name="reg_search" id="reg_search"><span class="big"> 6286 reg_Search(expr,arg[,regs])</span></a></dt> 6287 6288 <dd> 6289 <p><b>This function has been replaced by the <a href= 6290 "#ereg">ereg()</a> function. It is however still available 6291 for backwards compatibility.</b><br> 6292 reg_Search will scan the entire argument string for any 6293 matches to the given regular expression. If a match is found, 6294 it will return the portion of the string starting at where 6295 the match occurred. If no match is found a zero-length string 6296 is returned. If the <em>regs</em> argument is present, then 6297 match registers are filled into positions 0-10 in the array 6298 named by the <em>regs</em> argument. Register 0 will always 6299 be assigned the full matched string. For more information on 6300 regular expressions, see the <a href="#regexp">regular 6301 expression section</a> of this document.</p> 6302 </dd> 6303 6304 <dt><a name="rename" id="rename"><span class="big"> 6305 Rename(old,new)</span></a></dt> 6306 6307 <dd> 6308 <p>Rename filename old to new. Similar to the Unix C rename() 6309 function.</p> 6310 </dd> 6311 6312 <dt><a name="reset" id="reset"><span class="big"> 6313 Reset(variable)</span></a></dt> 6314 6315 <dd> 6316 <p>Reset moves the internal array pointer for the given array 6317 variable to the first item of the array and returns the value 6318 of this item. This is useful for traversing associative and 6319 non-indexed arrays. See also <a href="#end">End()</a> and 6320 <a href="#next">Next()</a>. The following example traverses 6321 an associative array:</p> 6322 <pre> 6323 <? 6324 Reset($array); 6325 $i=0; 6326 while($i < count($array)); 6327 echo $array[]; /* pointer automatically moves ahead one */ 6328 $i++; 6329 endwhile; 6330 > 6331</pre> 6332 </dd> 6333 6334 <dt><a name="return" id="return"><span class="big"> 6335 return(value)</span></a></dt> 6336 6337 <dd> 6338 <p>Return exits the current function call and returns the 6339 specified value back to the caller. See the section on 6340 <a href="#user_funcs">User-Defined Functions</a> for more 6341 information.</p> 6342 </dd> 6343 6344 <dt><a name="rewind" id="rewind"><span class="big"> 6345 rewind($fd)</span></a></dt> 6346 6347 <dd> 6348 <p>rewind() resets a file pointer identified by the $fd 6349 argument which is the return value of the <a href= 6350 "#fopen">fopen()</a> call. The file pointer is positioned at 6351 the beginning of the file. See also <a href= 6352 "#ftell">ftell()</a> and <a href="#fseek">fseek()</a>.</p> 6353 </dd> 6354 6355 <dt><a name="rewinddir" id="rewinddir"><span class="big"> 6356 rewindDir()</span></a></dt> 6357 6358 <dd> 6359 <p>rewindDir moves the current directory pointer back to the 6360 beginning of the directory. Use the <a href= 6361 "#opendir">openDir</a> function to open a directory before 6362 calling this function.</p> 6363 </dd> 6364 6365 <dt><a name="rmdir" id="rmdir"><span class="big"> 6366 RmDir(dir)</span></a></dt> 6367 6368 <dd> 6369 <p>RmDir() removes the given directory. See the <a href= 6370 "#unlink">Unlink()</a> function for removing regular 6371 files.</p> 6372 </dd> 6373 6374 <dt><a name="setcookie" id="setcookie"><span class="big"> 6375 SetCookie(name,value,expire,path,domain,secure)</span></a></dt> 6376 6377 <dd> 6378 <p>SetCookie() defines a cookie to be sent along with the 6379 rest of the header information. All the arguments except the 6380 name argument are optional. If only the name argument is 6381 present, the cookie by that name will be deleted from the 6382 remote client. You may also replace any argument with an 6383 empty string (<b>""</b>) in order to skip that argument. The 6384 expire and secure arguments are integers and cannot be 6385 skipped with an empty string. Use a zero (<b>0</b>) instead. 6386 The expire argument is a regular Unix time integer as 6387 returned by the <a href="#time">time()</a> or <a href= 6388 "#mktime">mktime()</a> functions. Some examples follow:</p> 6389 <pre> 6390 SetCookie("TestCookie","Test Value"); 6391 SetCookie("TestCookie",$value,time()+3600); /* expire in 1 hour */ 6392 SetCookie("TestCookie",$value,time()+3600,"/~rasmus/",".utoronto.ca",1); 6393</pre> 6394 6395 <p>Note that the value portion of the cookie will 6396 automatically be urlencoded when you send the cookie, and 6397 when it is received, it is automatically decoded and assigned 6398 to a variable by the same name as the cookie name. ie. to see 6399 the contents of our test cookie in a script, simply do:</p> 6400 <pre> 6401 echo $TestCookie; 6402</pre> 6403 </dd> 6404 6405 <dt><a name="seterrorreporting" id= 6406 "seterrorreporting"><span class="big"> 6407 SetErrorReporting(arg)</span></a></dt> 6408 6409 <dd> 6410 <p>SetErrorReporting sets the current error reporting state 6411 to the value of <em>arg</em>. If non-zero, errors will be 6412 printed, and if 0 they won't be. The function returns the 6413 previous error reporting state. This is a more general way of 6414 disabling error reporting than by preceding individual 6415 functions with a '@' character. See the section on <a href= 6416 "#quiet">Suppressing Errors from function calls</a> for more 6417 information.</p> 6418 </dd> 6419 6420 <dt><a name="setlogging" id="setlogging"><span class="big"> 6421 SetLogging(arg)</span></a></dt> 6422 6423 <dd> 6424 <p>SetLogging() either enables or disables the logging of 6425 access statistics for a page. If <em>arg</em> is non-zero, 6426 logging will be enabled, if zero, disabled.</p> 6427 </dd> 6428 6429 <dt><a name="setshowinfo" id="setshowinfo"><span class="big"> 6430 SetShowInfo(arg)</span></a></dt> 6431 6432 <dd> 6433 <p>SetShowInfo() either enables or disables the information 6434 footer at the bottom of all pages loaded through PHP. If 6435 <em>arg</em> is non-zero, the footers will be enabled, if 6436 zero, disabled.</p> 6437 </dd> 6438 6439 <dt><a name="settype" id="settype"><span class="big"> 6440 SetType(variable,type)</span></a></dt> 6441 6442 <dd> 6443 <p>SetType sets the type of a variable. The type argument is 6444 one of, "integer", "double" or "string". See also the 6445 <a href="#gettype">GetType()</a> function.</p> 6446 </dd> 6447 6448 <dt><a name="shl" id="shl"><span class="big"> 6449 shl(n,b)</span></a></dt> 6450 6451 <dd> 6452 <p>Shift the value <b>n</b> left <b>b</b> bits.</p> 6453 </dd> 6454 6455 <dt><a name="shr" id="shr"><span class="big"> 6456 shr(n,b)</span></a></dt> 6457 6458 <dd> 6459 <p>Shift the value <b>n</b> right <b>b</b> bits.</p> 6460 </dd> 6461 6462 <dt><a name="sin" id="sin"><span class="big"> 6463 Sin(arg)</span></a></dt> 6464 6465 <dd> 6466 <p>Sin returns the sine of arg in radians. See also <a href= 6467 "#cos">Cos()</a> and <a href="#tan">Tan()</a></p> 6468 </dd> 6469 6470 <dt><a name="sleep" id="sleep"><span class="big"> 6471 Sleep(secs)</span></a></dt> 6472 6473 <dd> 6474 <p>Sleep will delay for secs seconds. Similar to the Unix C 6475 sleep() function. See also the <a href="#usleep">USleep()</a> 6476 function.</p> 6477 </dd> 6478 6479 <dt><a name="solid_close" id="solid_close"><span class="big"> 6480 Solid_Close(connection_id)</span></a></dt> 6481 6482 <dd> 6483 <p>Solid_Close will close down the connection to the Solid 6484 server associated with the given connection identifier.</p> 6485 6486 <p>This function is only available if Solid support has been 6487 enabled in PHP.</p> 6488 </dd> 6489 6490 <dt><a name="solid_connect" id="solid_connect"><span class="big"> 6491 $connection = Solid_Connect(data source name, username, 6492 password)</span></a></dt> 6493 6494 <dd> 6495 <p>Solid_Connect opens a connection to a Solid server. Each 6496 of the arguments should be a quoted string. The first 6497 parameter (data source name) can be an empty string, 6498 resulting in a connection to the default server on the 6499 localhost. This function returns a connection_id. This 6500 identifier is needed by other Solid functions. You can have 6501 multiple connections open at once. This function will return 6502 <strong>0</strong> on error.</p> 6503 6504 <p>This function is only available if Solid support has been 6505 enabled in PHP.</p> 6506 </dd> 6507 6508 <dt><a name="solid_exec" id="solid_exec"><span class="big"> 6509 $result = Solid_Exec(connection_id, 6510 query_string)</span></a></dt> 6511 6512 <dd> 6513 <p>Solid_Exec will send an SQL statement to the Solid server 6514 specified by the connection_id. The connection_id must be a 6515 valid identifier that was returned by Solid_Connect. The 6516 return value of this function is an identifier to be used to 6517 access the results by other Solid functions. This function 6518 will return <strong>0</strong> on error. It will return 6519 <strong>1</strong> when the command executed correctly but 6520 are not expected to returned data (insert or update commands, 6521 for example). Note that selects which return no data will 6522 still return a valid result greater than 1.</p> 6523 6524 <p>This function is only available if Solid support has been 6525 enabled in PHP.</p> 6526 </dd> 6527 6528 <dt><a name="solid_fetchrow" id="solid_fetchrow"><span class="big"> 6529 Solid_FetchRow(result_id)</span></a></dt> 6530 6531 <dd> 6532 <p>Solid_FetchRow fetches a row of the data that was returned 6533 by Solid_Exec. After Solid_FetchRow is called, the fields of 6534 that row can be access with Solid_Result. Every time 6535 Solid_FetchRow is called a new row can be accessed by 6536 Solid_Result. If Solid_FetchRow was succesful (there was a 6537 new row), <strong>1</strong> is returned, if there are no 6538 more rows, Solid_FetchRow will return <strong>0</strong>. The 6539 return value of Solid_FetchRow can be used as the condition 6540 of a while loop.</p> 6541 6542 <p>This function is only available if Solid support has been 6543 enabled in PHP.</p> 6544 </dd> 6545 6546 <dt><a name="solid_fieldname" id="solid_fieldname"><span class="big"> 6547 Solid_FieldName(result_id, field_number)</span></a></dt> 6548 6549 <dd> 6550 <p>Solid_FieldName will return the name of the field 6551 occupying the given column number in the given Solid result 6552 identifier. Field numbering starts from 0.</p> 6553 6554 <p>This function is only available if Solid support has been 6555 enabled in PHP.</p> 6556 </dd> 6557 6558 <dt><a name="solid_fieldnum" id="solid_fieldnum"><span class="big"> 6559 Solid_FieldNum(result_id, field_name)</span></a></dt> 6560 6561 <dd> 6562 <p>Solid_FieldNum will return the number of the column slot 6563 that corresponds to the named field in the given Solid result 6564 identifier. Field numbering starts at 0. This function will 6565 return <strong>-1</strong> on error.</p> 6566 6567 <p>This function is only available if Solid support has been 6568 enabled in PHP.</p> 6569 </dd> 6570 6571 <dt><a name="solid_freeresult" id= 6572 "solid_freeresult"><span class="big">Solid_FreeResult(result_id)</span></a></dt> 6573 6574 <dd> 6575 <p>Solid_FreeResult only needs to be called if you are 6576 worried about using too much memory while your script is 6577 running. All result memory will automatically be freed when 6578 the script is finished. But, if you are sure you are not 6579 going to need the result data anymore in a script, you may 6580 call Solid_FreeResult with the result identifier as an 6581 argument and the associated result memory will be freed.</p> 6582 6583 <p>This function is only available if Solid support has been 6584 enabled in PHP.</p> 6585 </dd> 6586 6587 <dt><a name="solid_numfields" id="solid_numfields"><span class="big"> 6588 Solid_NumFields(result_id)</span></a></dt> 6589 6590 <dd> 6591 <p>Solid_NumFields will return the number of fields (columns) 6592 in a Solid result. The argument is a valid result identifier 6593 returned by Solid_Exec. This function will return 6594 <strong>-1</strong> on error.</p> 6595 6596 <p>This function is only available if Solid support has been 6597 enabled in PHP.</p> 6598 </dd> 6599 6600 <dt><a name="solid_numrows" id="solid_numrows"><span class="big"> 6601 Solid_NumRows(result_id)</span></a></dt> 6602 6603 <dd> 6604 <p>Solid_NumRows will return the number of rows in a Solid 6605 result. The argument is a valid result identifier returned by 6606 Solid_Exec. This function will return <strong>-1</strong> on 6607 error. <b>Large Caveat:</b> The SOLID SQL server uses ODBC as 6608 it's primary (and only) interface. SolidNumRows() uses 6609 SQLRowCount at the low-level to get the number of rows. 6610 SQLRowCount follows the age-old Microsoft tradition of 6611 unnecessary limitations, strange exceptions and other odd 6612 things. This means that the function will only return the 6613 number of rows affected by an INSERT, UPDATE or a DELETE 6614 clause. No SELECT! As a workaround you can try the count() 6615 statement of SQL or a while-loop that counts the number of 6616 rows. If you need Solid_NumRows() to figure out how many 6617 records to read after a SELECT clause, try checking the 6618 return value from <a href= 6619 "#solid_fetchrow">Solid_FetchRow()</a> instead. So instead 6620 of:</p> 6621 <pre> 6622 $num = Solid_NumRows(); 6623 $i=0; 6624 while ($i < $num) { 6625 /* print results... */ 6626 $i++; 6627 } 6628</pre> 6629 6630 <p>you might try:</p> 6631 <pre> 6632 while(Solid_FetchRow($result)) { 6633 /* print results... */ 6634 } 6635</pre> 6636 6637 <p>This function is only available if Solid support has been 6638 enabled in PHP.</p> 6639 </dd> 6640 6641 <dt><a name="solid_result" id="solid_result"><span class="big"> 6642 Solid_Result(result_id, field name/index)</span></a></dt> 6643 6644 <dd> 6645 <p>Solid_Result will return values from a result identifier 6646 produced by Solid_Exec. The field name specify what cell in 6647 the row to return. Instead of naming the field, you may use 6648 the field index as an unquoted number. Field indices start 6649 from 0.</p> 6650 6651 <p>This function is only available if Solid support has been 6652 enabled in PHP.</p> 6653 </dd> 6654 6655 <dt><a name="sort" id="sort"><span class="big"> 6656 Sort(array)</span></a></dt> 6657 6658 <dd> 6659 <p>Sort is used to sort a PHP array in ascending order. To 6660 sort in descending order, use the RSort() function. It 6661 understands the three variable types and will sort 6662 alphabetically if the array contains strings, and numerically 6663 if the array contains numbers. In the case of an array which 6664 contains a mixture of types, the first type in the array will 6665 specify the sort method. Note that if you are going to sort 6666 an associative array, you should use the <a href= 6667 "#asort">ASort()</a> function.</p> 6668 </dd> 6669 6670 <dt><a name="soundex" id="soundex"><span class="big"> 6671 Soundex(string)</span></a></dt> 6672 6673 <dd> 6674 <p>This function takes a string argument and returns the 6675 soundex key for the string. Soundex keys have the property 6676 that words pronounced similarly produce the same soundex key, 6677 and can thus be used to simplify searches in databases where 6678 you know the pronunciation but not the spelling. This soundex 6679 function returns a string 4 characters long, starting with a 6680 letter.<br> 6681 This particular soundex function is one described by Donald 6682 Knuth in "The Art Of Computer Programming, vol. 3: Sorting 6683 And Searching", Addison-Wesley (1973), pp. 391-392.<br> 6684 Example:</p> 6685 <pre> 6686 Euler and Ellery map to E460 6687 Gauss and Ghosh map to G200 6688 Hilbert and Heilbronn map to H416 6689 Knuth and Kant map to K530 6690 Lloyd and Ladd map to L300 6691 Lukasiewicz and Lissajous map to L222 6692 6693</pre> 6694 </dd> 6695 6696 <dt><a name="sprintf" id="sprintf"><span class="big"> 6697 Sprintf(format,arg [,arg,arg,arg,arg])</span></a></dt> 6698 6699 <dd> 6700 <p>Sprintf returns the string created by the formatted output 6701 defined by the format argument and arg. It is similar to the 6702 formatted version of the <a href="#echo">echo</a> command, 6703 except this just returns the string while echo displays it. 6704 It is also similar to the C function by the same name. The 6705 difference being that this version does not accept more than 6706 5 <em>arg</em> arguments. If you need to format more than 5 6707 arguments into a single string, simply call sprintf() 6708 multiple times for each group of arguments. Note that the 6709 type of the argument doesn't affect the output. The argument 6710 type is automagically converted to match the type specified 6711 in the format string.</p> 6712 </dd> 6713 6714 <dt><a name="sqrt" id="sqrt"><span class="big"> 6715 Sqrt(arg)</span></a></dt> 6716 6717 <dd> 6718 <p>Sqrt returns the square root of arg.</p> 6719 </dd> 6720 6721 <dt><a name="srand" id="srand"><span class="big"> 6722 Srand(integer)</span></a></dt> 6723 6724 <dd> 6725 <p>Srand seeds the random number generator. This function 6726 takes any integer as an argument. One choice for a seed value 6727 is to use the <strong>date</strong> function to give you the 6728 current number of seconds past the minute. Note that this 6729 function <b>does not return a value</b>! This function simply 6730 seeds the random number generator for subsequent calls to the 6731 <a href="#rand">rand()</a> function. eg.</p> 6732 <pre> 6733 <?srand(date("s"))> 6734</pre> 6735 </dd> 6736 6737 <dt><a name="strchr" id="strchr"><span class="big"> 6738 strchr(string,arg)</span></a></dt> 6739 6740 <dd> 6741 <p>strchr and <a href="#strstr">strstr</a> are actually 6742 identical functions. They can be used interchangeably and 6743 both are included for completeness sake. They will return the 6744 portion of the string argument starting at the point where 6745 the given sub-string is found. For example, in the string, 6746 "This is an example string" above, the call: <code><?echo 6747 strchr($string,"an ")></code> would return the string: 6748 <code>"an example string"</code>.</p> 6749 </dd> 6750 6751 <dt><a name="strtr" id="strtr"><span class="big"> 6752 strtr(input,set1,set2)</span></a></dt> 6753 6754 <dd>strtr() translates each character of "string" that is in 6755 "set1" to the corresponding character in "set2". Characters not 6756 in set1 are passed through unchanged. When a character appears 6757 more than once in "set1" and the corresponding characters in 6758 "set2" are not all the same, only the final one is used. When 6759 one of "set1" or "set2" is longer, longer "set?" is truncated 6760 to length of shorter "set?".</dd> 6761 6762 <dt><a name="stripslashes" id="stripslashes"><span class="big"> 6763 StripSlashes(arg)</span></a></dt> 6764 6765 <dd> 6766 <p>StripSlashes unescapes the string argument. See also 6767 <a href="#addslashes">AddSlashes()</a>.</p> 6768 </dd> 6769 6770 <dt><a name="strlen" id="strlen"><span class="big"> 6771 strlen(string)</span></a></dt> 6772 6773 <dd> 6774 <p>strlen returns the length of the string.</p> 6775 </dd> 6776 6777 <dt><a name="strrchr" id="strrchr"><span class="big"> 6778 strrchr(string,arg)</span></a></dt> 6779 6780 <dd> 6781 <p>strrchr will search for a single character starting at the 6782 end of the argument string and working its way backwards. It 6783 returns the string starting with the search character if the 6784 character was found and an empty string if it wasn't.</p> 6785 </dd> 6786 6787 <dt><a name="strstr" id="strstr"><span class="big"> 6788 strstr(string,arg)</span></a></dt> 6789 6790 <dd> 6791 <p>strstr and <a href="#strchr">strchr</a> are actually 6792 identical functions. They can be used interchangeably and 6793 both are included for completeness sake. They will return the 6794 portion of the string argument starting at the point where 6795 the given sub-string is found. For example, in the string, 6796 "This is an example string" above, the call: <code><?echo 6797 strstr($string,"an ")></code> would return the string: 6798 <code>"an example string"</code>.</p> 6799 </dd> 6800 6801 <dt><a name="strtok" id="strtok"><span class="big"> 6802 strtok(string,arg)</span></a></dt> 6803 6804 <dd> 6805 <p>strtok is used to tokenize a string. That is, if you have 6806 a string like <strong>"This is an example string"</strong> 6807 you could tokenize this string into its individual words by 6808 using the space character as the token. You would use the 6809 following script code:</p> 6810 <pre> 6811 <? 6812 $string = "This is an example string"; 6813 $tok = strtok($string," "); 6814 while($tok); 6815 echo "Word=$tok<br>"; 6816 $tok = strtok(" "); 6817 endwhile; 6818 > 6819</pre> 6820 6821 <p>Note that only the first call to strtok uses the string 6822 argument. Every subsequent call to strtok only needs the 6823 token to use, as it keeps track of where it is in the current 6824 string. To start over, or to tokenize a new string you simply 6825 call strtok with the string argument again to initialize it. 6826 Note that you may put multiple tokens in the <i>arg</i> 6827 parameter. The string will be tokenized when any one of the 6828 characters in the argument are found.</p> 6829 </dd> 6830 6831 <dt><a name="strtolower" id="strtolower"><span class="big"> 6832 strtolower(string)</span></a></dt> 6833 6834 <dd> 6835 <p>strtolower converts the string argument to all lower case 6836 characters.</p> 6837 </dd> 6838 6839 <dt><a name="strtoupper" id="strtoupper"><span class="big"> 6840 strtoupper(string)</span></a></dt> 6841 6842 <dd> 6843 <p>strtoupper converts the string argument to all upper case 6844 characters.</p> 6845 </dd> 6846 6847 <dt><a name="strval" id="strval"><span class="big"> 6848 strval(variable)</span></a></dt> 6849 6850 <dd> 6851 <p>strval returns the string value of the variable. See also 6852 the <a href="#intval">intval()</a> and <a href= 6853 "#doubleval">doubleval()</a> functions.</p> 6854 </dd> 6855 6856 <dt><a name="substr" id="substr"><span class="big">substr(string, 6857 start, length)</span></a></dt> 6858 6859 <dd> 6860 <p>substr returns a part of the given string. The start 6861 position is given by the start argument. The first position 6862 in a string is position 0. And the length argument specifies 6863 the number of characters to return from the start 6864 position.</p> 6865 </dd> 6866 6867 <dt><a name="sybsql_checkconnect" id= 6868 "sybsql_checkconnect"><span class="big"> 6869 sybSQL_CheckConnect()</span></a></dt> 6870 6871 <dd> 6872 <p>This function returns 1 if the connection to the database 6873 has been established and 0 otherwise.</p> 6874 </dd> 6875 6876 <dt><a name="sybsql_dbuse" id="sybsql_dbuse"><span class="big"> 6877 sybSQL_DBuse(database)</span></a></dt> 6878 6879 <dd> 6880 <p>This function issues a Sybase Transact-SQL <b>use</b> 6881 command for the specified database. The only argument to the 6882 function is the name of the database to use. Example: 6883 <code>sybsql_dbuse("pubs2");</code></p> 6884 6885 <p>The function returns 1 on success and 0 on failure.</p> 6886 </dd> 6887 6888 <dt><a name="sybsql_connect" id="sybsql_connect"><span class="big"> 6889 sybSQL_Connect()</span></a></dt> 6890 6891 <dd> 6892 <p>This function opens a network connection to the sybase 6893 server. This function depends on several environment 6894 variables which must be set by the caller before calling this 6895 function.</p> 6896 6897 <p>The environment variables are:</p> 6898 6899 <p><b>DSQUERY</b> - the alias of the sybase server as defined 6900 in the sybase interface file.<br> 6901 <b>DBUSER</b> - connect to the sybase server as this 6902 user.<br> 6903 <b>DBPW</b> - password of the user.</p> 6904 6905 <p>These variables can be set in several ways. If php/fi is 6906 running as a CGI program, then a shell wrapper can be used to 6907 set these variables or you can set these variables directly 6908 in the HTML page using the builtin PHP/FI function 6909 <b><a href="#putenv">putenv()</a></b>. Instead of using the 6910 values directly in <b><a href="#putenv">putenv()</a></b>, the 6911 values can be obtained from form input. The variables can be 6912 defined in a file and included in the html files with PHP/FI 6913 <code><a href="#include">include</a></code> statement.</p> 6914 6915 <p>The function returns 1 on success and 0 on failure.</p> 6916 </dd> 6917 6918 <dt><a name="sybsql_exit" id="sybsql_exit"><span class="big"> 6919 sybSQL_Exit()</span></a></dt> 6920 6921 <dd> 6922 <p>This function forces a Sybase connection to be shut down. 6923 If not called, the connection will automatically be closed 6924 when the PHP page has been fully parsed, so calling this 6925 function is optional.</p> 6926 </dd> 6927 6928 <dt><a name="sybsql_fieldname" id= 6929 "sybsql_fieldname"><span class="big">sybSQL_Fieldname(index)</span></a></dt> 6930 6931 <dd> 6932 <p>This function returns the field name of a regular result 6933 column. The argument to the function is the field index. 6934 Example: <code>sybsql_fieldname(0);</code>. NOTE: the field 6935 index starts at 0.</p> 6936 6937 <p>If the the result column does not have any name, the 6938 function returns an empty string ("").</p> 6939 </dd> 6940 6941 <dt><a name="sybsql_getfield" id="sybsql_getfield"><span class="big"> 6942 sybSQL_GetField(field)</span></a></dt> 6943 6944 <dd> 6945 <p>This function gets the value of a specific column of the 6946 current result row. The only argument to the function is the 6947 string specifying the field. Example: 6948 <code>$value=sybsql_getfield("@10");</code> <b>NOTE</b>: 6949 <a href="#sybsql_nextrow">sybsql_nextrow()</a> must be called 6950 before calling this function. sybsql_nextrow() must be called 6951 if the row pointer needs to be incremented, because this 6952 function only reads the current row in the row buffer.</p> 6953 6954 <p>If the specified column has a value, the function returns 6955 the value as a string otherwise the function returns an empty 6956 string ("").</p> 6957 </dd> 6958 6959 <dt><a name="sybsql_isrow" id="sybsql_isrow"><span class="big"> 6960 sybSQL_IsRow()</span></a></dt> 6961 6962 <dd> 6963 <p>This function indicates if the current SQL command 6964 returned any rows.</p> 6965 6966 <p>The function returns 1 if the SQL command returned any 6967 rows and 0 if the command didn't return any rows.</p> 6968 </dd> 6969 6970 <dt><a name="sybsql_nextrow" id="sybsql_nextrow"><span class="big"> 6971 sybSQL_NextRow()</span></a></dt> 6972 6973 <dd> 6974 <p>This function increments the row pointer to the next 6975 result row.</p> 6976 6977 <p>The function returns 1 as long as there are rows left to 6978 read. If there are no more rows left to read or in case of 6979 error the function returns 0.</p> 6980 </dd> 6981 6982 <dt><a name="sybsql_numfields" id= 6983 "sybsql_numfields"><span class="big">sybSQL_NumFields()</span></a></dt> 6984 6985 <dd> 6986 <p>This function returns the number of fields in a current 6987 result row.</p> 6988 6989 <p>The function returns the number of rows in the current 6990 result row. If there are no fields, the function returns 6991 0.</p> 6992 </dd> 6993 6994 <dt><a name="sybsql_numrows" id="sybsql_numrows"><span class="big"> 6995 sybSQL_NumRows()</span></a></dt> 6996 6997 <dd> 6998 <p>This function returns the number of rows in the current 6999 result buffer. <b>NOTE:</b> when this function is called, it 7000 will seek to the first row right away, then it will call 7001 dbnextrow() until there are no more rows and increment a 7002 internal counter to calculate the number of rows in the 7003 result buffer. Then it points back to the very first row. 7004 Therefore, after calling this function row counter always 7005 points to the very first row. It's ugly but I don't know any 7006 other way at this time.</p> 7007 7008 <p>If there are no rows in the result buffer, the function 7009 will return 0.</p> 7010 </dd> 7011 7012 <dt><a name="sybsql_query" id="sybsql_query"><span class="big"> 7013 sybSQL_Query()</span></a></dt> 7014 7015 <dd> 7016 <p>This function submits a Sybase SQL query request to the 7017 server. The only argument to the function is the query 7018 string. Example: <code>$rc=sybsql_query("select * from 7019 authors");</code></p> 7020 7021 <p>The function returns 1, if the query is passed 7022 successfully and returns 0 if the request fails.</p> 7023 </dd> 7024 7025 <dt><a name="sybsql_result" id="sybsql_result"><span class="big"> 7026 sybSQL_Result(string)</span></a></dt> 7027 7028 <dd> 7029 <p>This function prints specific fields of the current result 7030 row. The only argument to the function is a string which 7031 holds information about the fields to be printed. A field is 7032 specified with a @ followed by a number. For example, @0 7033 means first row, @10 means 11th row. Note that the field 7034 number starts at 0. The function is perhaps best illustrated 7035 with a complete example:</p> 7036 <pre> 7037<? 7038 /* 7039 ** assuming all the necessary variables for 7040 ** connection is already set. please note, NO error checking is 7041 ** done. You should always check return code of a function. 7042 */ 7043 7044 /* connect */ 7045 $rc=sybsql_connect(); 7046 7047 /* use the pub2 database */ 7048 $rc=sybsql_dbuse("pubs2"); 7049 7050 /* send the SQL request */ 7051 $rc=sybsql_query("select * from authors"); 7052 $i=0; 7053 7054 /* find the no of rows returned */ 7055 $nrows=sybsql_numrows(); 7056 7057 /* start table */ 7058 echo "<table border>\n"; 7059 /* 7060 ** print only first and 2nd field 7061 */ 7062 while($i<$nrows) { 7063 sybsql_result("<tr><td>@0</td>@1</td></tr>\n"); 7064 $i++; 7065 } 7066 /* end table */ 7067 echo "</table>\n"; 7068> 7069</pre> 7070 7071 <p>The above example uses HTML table to format the output. Of 7072 course, any other valid HTML tags can be used.</p> 7073 </dd> 7074 7075 <dt><a name="sybsql_result_all" id= 7076 "sybsql_result_all"><span class="big"> 7077 sybSQL_Result_All()</span></a></dt> 7078 7079 <dd> 7080 <p>This function prints all rows in the current result 7081 buffer. The result is printed in a hard coded HTML table 7082 format. Note that this function should not be called inside a 7083 loop. The function will print the name of the columns if 7084 there are any column headings in the output.</p> 7085 </dd> 7086 7087 <dt><a name="sybsql_seek" id="sybsql_seek"><span class="big"> 7088 sybSQL_Seek(row)</span></a></dt> 7089 7090 <dd> 7091 <p>This function sets the requested row number as the current 7092 row in the row buffer. The only argument to the function is 7093 the row number. Example: <code>$rc=sybsql_seek(10);</code> 7094 Note, row number starts at 0.</p> 7095 7096 <p>The function returns 1 if the seek succeeds and 0 if the 7097 seek fails. When all of the rows in the current result buffer 7098 have been visited, the row pointer points to the last row. If 7099 it is needed to go backward and visit some more rows, this 7100 function can be used for this purpose.</p> 7101 </dd> 7102 7103 <dt><a name="symlink" id="symlink"><span class="big"> 7104 Symlink(target,link)</span></a></dt> 7105 7106 <dd> 7107 <p>Symlink() creates a symbolic link. See the <a href= 7108 "#link">Link()</a> function to create hard links.</p> 7109 </dd> 7110 7111 <dt><a name="syslog" id="syslog"><span class="big"> 7112 Syslog(level,message)</span></a></dt> 7113 7114 <dd> 7115 <p>Syslog() logs messages to the system using UNIX's 7116 syslog(3) feature. See your UNIX man page for more details. 7117 See also <a href="#initsyslog">InitSyslog()</a>, <a href= 7118 "#openlog">OpenLog()</a> and <a href= 7119 "#closelog">CloseLog()</a>.</p> 7120 </dd> 7121 7122 <dt><a name="system" id="system"><span class="big"> 7123 System(command_string [,return_var])</span></a></dt> 7124 7125 <dd> 7126 <p>System is just like the C <em>system()</em> command in 7127 that it executes the given unix command and outputs the 7128 result. If a variable is provided as the second argument, 7129 then the return status code of the executed unix command will 7130 be written to this variable. Note, that if you are going to 7131 allow data coming from user input to be passed to this System 7132 function, then you should be using the <a href= 7133 "#escapeshellcmd">EscapeShellCmd()</a> function to make sure 7134 that users cannot trick the system into executing arbitrary 7135 commands. The System() call also automatically flushes the 7136 Apache output buffer after each line of output if PHP is 7137 running as an Apache module. If you need to execute a command 7138 and have all the data from the command passed directly back 7139 without any interference, use the <a href= 7140 "#passthru">PassThru()</a> function. See also the <a href= 7141 "#exec">Exec</a> function.</p> 7142 </dd> 7143 7144 <dt><a name="tan" id="tan"><span class="big"> 7145 Tan(arg)</span></a></dt> 7146 7147 <dd> 7148 <p>Sin returns the tangent of arg in radians. See also 7149 <a href="#sin">Sin()</a> and <a href="#cos">Cos()</a></p> 7150 </dd> 7151 7152 <dt><a name="tempnam" id="tempnam"><span class="big"> 7153 TempNam(path, prefix)</span></a></dt> 7154 7155 <dd> 7156 <p>TempNam returns a unique filename located in the directory 7157 indicated by path with filename prefix given by prefix. It is 7158 identical to the Unix C tempnam() function.</p> 7159 </dd> 7160 7161 <dt><a name="time" id="time"><span class="big"> 7162 Time()</span></a></dt> 7163 7164 <dd> 7165 <p>Time simply returns the current local time in seconds 7166 since Unix epoch (00:00:00 Jan. 1 1970). It is equivalent to 7167 calling <a href="#date">Date("U")</a>. If you need better 7168 than per-second granularity, use the <a href= 7169 "#microtime">Microtime</a> function.</p> 7170 </dd> 7171 7172 <dt><a name="umask" id="umask"><span class="big"> 7173 Umask([mask])</span></a></dt> 7174 7175 <dd> 7176 <p>Umask(<i>mask</i>) sets PHP's umask to <i>mask</i> & 7177 0777 and returns the old umask. If PHP/FI is an Apache 7178 module, Apache's old umask is restored when PHP/FI has 7179 finished. <i>mask</i> must be specified in <a href= 7180 "#octal">octal</a> notation, like for <a href= 7181 "#chmod">ChMod()</a>. Umask() without arguments simply 7182 returns the current umask.</p> 7183 </dd> 7184 7185 <dt><a name="uniqid" id="uniqid"><span class="big"> 7186 UniqId()</span></a></dt> 7187 7188 <dd> 7189 <p>UniqId returns a prefixed unique identifier based on 7190 current time in microseconds. The prefix can be useful for 7191 instance if you generate identifiers simultaneously on 7192 several hosts that might happen to generate the identifier at 7193 the same microsecond. The prefix can be up to 114 characters 7194 long.</p> 7195 </dd> 7196 7197 <dt><a name="unlink" id="unlink"><span class="big"> 7198 Unlink(filename)</span></a></dt> 7199 7200 <dd> 7201 <p>Unlink deletes the given filename. Similar to the Unix C 7202 unlink() function. See the <a href="#rmdir">RmDir()</a> 7203 function for removing directories.</p> 7204 </dd> 7205 7206 <dt><a name="unset" id="unset"><span class="big"> 7207 UnSet($var)</span></a></dt> 7208 7209 <dd> 7210 <p>UnSet undefines the given variable. In the case of an 7211 array, the entire array is cleared. Individual array elements 7212 may also be unset.</p> 7213 </dd> 7214 7215 <dt><a name="urldecode" id="urldecode"><span class="big"> 7216 UrlDecode(arg)</span></a></dt> 7217 7218 <dd> 7219 <p>UrlDecode decodes a string encoded with the <a href= 7220 "#urlencode">UrlEncode</a> function. In typical use, it is 7221 not necessary to decode URL Encoded strings because these are 7222 automatically decoded when strings are passed between pages. 7223 However, for completeness sake, this function has been 7224 included.</p> 7225 </dd> 7226 7227 <dt><a name="urlencode" id="urlencode"><span class="big"> 7228 UrlEncode(arg)</span></a></dt> 7229 7230 <dd> 7231 <p>UrlEncode encodes any characters from arg which are not 7232 one of "a-zA-Z0-9_-." by replacing them with %xx where xx is 7233 their ASCII value in hexadecimal. The encoded string is 7234 returned.</p> 7235 </dd> 7236 7237 <dt><a name="usleep" id="usleep"><span class="big"> 7238 USleep(microsecs)</span></a></dt> 7239 7240 <dd> 7241 <p>Sleep will delay for the given number of microseconds. 7242 Similar to the Unix C usleep() function. See also the 7243 <a href="#sleep">Sleep()</a> function.</p> 7244 </dd> 7245 7246 <dt><a name="virtual" id="virtual"><span class="big"> 7247 Virtual(filename)</span></a></dt> 7248 7249 <dd> 7250 <p>Virtual is an Apache-specific function which is equivalent 7251 to <!--#include virtual...--> in mod_include. It 7252 performs an Apache sub-request. It is useful for including 7253 CGI scripts or .shtml files, or anything else that you would 7254 parse through Apache (for .phtml files, you'd probably want 7255 to use <?Include>.</p> 7256 </dd> 7257 </dl> 7258 <hr> 7259 7260 <h2><a name="addfunc" id="addfunc">Adding your own internal 7261 functions to PHP/FI</a></h2>It may well be that the set of 7262 functions provided by PHP/FI does not include a particular 7263 function that you may need. By carefully following the steps 7264 described below, it is possible for you to add your own functions 7265 to PHP/FI. 7266 7267 <p>Before you start hacking away at the internals of PHP/FI you 7268 need to grab a copy of the latest version of Bison. Bison is 7269 GNU's implementation of YACC (Yet Another Compiler Compiler). The 7270 YACC that came with your operating system may or may not be good 7271 enough, but just to make sure, go grab Bison. You can find it at 7272 <a href= 7273 "ftp://prep.ai.mit.edu/pub/gnu">ftp://prep.ai.mit.edu/pub/gnu</a>.</p> 7274 7275 <p>You should also have a look at the Makefile and turn on 7276 debugging. Simply uncomment the <strong>DEBUG</strong> line in 7277 the Makefile. The output file of debug information is specified 7278 by <strong>DEBUG_FILE</strong> in <em>php.h</em>. It is by 7279 default set to <em>/tmp/php.err</em>. You can change this to suit 7280 your needs.</p> 7281 7282 <p>A final thing you might want to keep in mind is that php runs 7283 as the same user id as httpd on your system, unless of course you 7284 are running it with the setuid bit set, and this httpd user does 7285 not generally have write access to the various directories. This 7286 means that if you do something that causes php to core dump, you 7287 will not get a core file. The easy way around this is to make the 7288 directory where you keep your test .html files writable to all. 7289 PHP changes its current directory to the directory of the .html 7290 file it is reading and will thus dump its core there if it 7291 can.</p> 7292 7293 <p>In the following steps we will use the <em>Time()</em> 7294 function to illustrate how to add a function.</p> 7295 7296 <dl> 7297 <dt><strong>Step 1 - Defining the grammar of your 7298 Function</strong></dt> 7299 7300 <dd> 7301 <p>If your function takes 0 to 6 arguments, there are 7302 predefined grammars available. You can skip this step.</p> 7303 7304 <p>The grammar of your function is defined in the 7305 <em>parse.raw</em> file. The first thing to add is a token. A 7306 token is an upper case keyword which is usually the same as 7307 your function name. All the tokens are defined near the top 7308 of the parse.raw file. The order doesn't matter. Then you 7309 need to build your actual YACC grammar rule. Look at the 7310 existing rules and find a function that is similar to the one 7311 you are adding. Keep in mind that most normal functions are 7312 standard functions that read their arguments from the 7313 expression stack. Your function will most likely fall into 7314 this group in which case you won't need to touch the 7315 <em>parse.raw</em> file.</p> 7316 </dd> 7317 7318 <dt><strong>Step 2 - Adding your function to the lexical 7319 analyzer hash table</strong></dt> 7320 7321 <dd> 7322 <p>To do this, edit <em>lex.c</em> and find the hash table 7323 near the top of the file. Look for the line, <code>static 7324 cmd_table_t cmd_table[22][30] = {</code>, which defines the 7325 beginning of the hash table. The <code>[22][30]</code> defines 7326 the size of the 2 dimensional array which holds the hash 7327 table. The 22 is one greater than the maximum function name 7328 length and the 30 refers to the maximum number of functions 7329 in any one hash list. If you exceed either of these limits, 7330 simply increase them right here.</p> 7331 7332 <p>This hash table would probably rate as the absolute 7333 simplest hash table in the entire world. The hash value is 7334 the length of the string of the function name to be hashed. 7335 So, for our <em>Time()</em> example, we need to add an entry 7336 for hash value 4. Therefore we add the following line to the 7337 hash list for 4:</p> 7338 <pre> 7339 { "time",INTFUNC0,UnixTime }, 7340</pre> 7341 7342 <p>This entry maps a string to the INTFUNC0 token. You can 7343 look up the grammar for the INTFUNC0 token in 7344 <em>parse.raw</em> and you will see that it is a generic 7345 grammar for an internal function call with 0 arguments. The 7346 string, in quotes above, is the actual string that you will 7347 be using in the .html files to call your function. Keep in 7348 mind that PHP/FI function names are <strong>not</strong> case 7349 sensitive. And the final <b>UnixTime</b> element is the 7350 actual function to be called.</p> 7351 </dd> 7352 7353 <dt><strong>Step 3 - Write your actual Function</strong></dt> 7354 7355 <dd> 7356 <p>You can actually write your function in any language you 7357 like, as long as it is callable through the normal C function 7358 call convention and you have a way of creating either an 7359 object file or a library file compatible with the linker on 7360 your system. In general, we will assume that you are writing 7361 your function in C. All the functions that come with PHP/FI 7362 have been written in C. The Time() function, or UnixTime() as 7363 it is called internally in PHP can be found in 7364 <em>date.c</em> and looks like this:</p> 7365 <pre> 7366void UnixTime(void) { 7367 char temp[32]; 7368 7369 sprintf(temp,"%ld",(long)time(NULL)); 7370 Push(temp,LNUMBER); 7371} 7372</pre> 7373 7374 <p>Note that the function is void. This indicates that it 7375 doesn't return anything. This may seem confusing to you 7376 because obviously the function needs to somehow return the 7377 time. The time is returned, but not as the return value of 7378 the function. It is pushed onto what is called an expression 7379 stack. The expression stack is simply a stack of strings and 7380 an associated type. PHP/FI understands only 3 basic variable 7381 types: STRING, LNUMBER and DNUMBER. STRING is a character 7382 string, LNUMBER is a long integer and DNUMBER is a double, or 7383 floating point, value. In this Time() example, the value to 7384 be returned is the time expressed in Unix format (number of 7385 seconds since Jan.1 1970) and is thus an integer. The 7386 expression stack only accepts strings, so we sprintf the long 7387 integer into a string and push it onto the stack indicating 7388 that it is actually a long integer with the line: 7389 <code>Push(temp,LNUMBER);</code></p> 7390 </dd> 7391 7392 <dt><strong>Step 4 - Add your function prototype to 7393 php.h</strong></dt> 7394 7395 <dd> 7396 <p>In the bottom half of the <em>php.h</em> file you will 7397 find a complete list of prototypes of all the functions in 7398 php. They are grouped by the files in which they appear. 7399 Simply add your prototype to an appropriate place in this 7400 file. For our Time() example the following line is added:</p> 7401 <pre> 7402void UnixTime(void); 7403</pre> 7404 </dd> 7405 7406 <dt><strong>Step 5 - Compile</strong></dt> 7407 7408 <dd> 7409 <p>You have to remember to re-make the parser whenever you 7410 make a change to the <em>parse.raw</em> file. Type: 7411 <strong>make parser</strong> to do this. You must have at 7412 least version 1.25 of Bison in order to make the PHP parser. 7413 Then do a normal compile by typing: <strong>make</strong> 7414 once that is done.</p> 7415 </dd> 7416 7417 <dt><strong>Step 6 - Send me your additions!</strong></dt> 7418 7419 <dd> 7420 <p>If you would like your functions added to the next release 7421 of PHP/FI, send them to me. The best way is probably to make 7422 a context-sensitive diff. To do that, you need a copy of a 7423 clean unmodified distribution. Simply do a, <strong>diff 7424 -c</strong> on the files you have changed comparing them to 7425 the original files. Please don't send me a diff of the 7426 changes in <em>parse.c</em> since that file is automatically 7427 generated. Send me the diff from <em>parse.raw</em> 7428 instead.</p> 7429 </dd> 7430 </dl> 7431 7432 <p>The Time() example illustrated the steps involved in adding a 7433 function. Chances are that the function you wish to add is quite 7434 a bit more complex than this example. You will probably want to 7435 be able to pass arguments to your function and have it manipulate 7436 these arguments in some manner. You may even want to have it 7437 callable in different ways. These concepts will be illustrated by 7438 the PHP/FI crypt() function. See also the section entitled 7439 <a href="#hacknotes">Notes for Code Hacks</a> for some more 7440 technical details about writing code for PHP/FI.</p> 7441 7442 <p>The Crypt() Grammar in <em>parse.raw</em>:</p> 7443 <pre> 7444%token CRYPT 7445 . 7446 . 7447 . 7448 | CRYPT '(' expr ',' expr ')' 7449 { 7450 if(GetCurrentState(NULL) || inCase || inElseIf) Crypt(1); 7451 } 7452 | CRYPT '(' expr ')' 7453 { 7454 if(GetCurrentState(NULL) || inCase || inElseIf) Crypt(0); 7455 } 7456</pre> 7457 7458 <p>Here it is shown how to define a grammar which lets you call a 7459 function with either 1 or 2 arguments. You could write different 7460 functions to handle the two cases, or simply send a mode 7461 parameter as is done here to indicate the mode in which the 7462 function is called. Note that in this case you cannot use one of 7463 the pre-defined INTFUNCn grammars since your function can take a 7464 variable number of arguments.</p> 7465 7466 <p>The other aspect that is shown is how to actually represent 7467 function arguments. In most cases you will want to use the 7468 <strong>expr</strong> identifier. This identifier means that the 7469 argument is an expression. An expression can be a literal value, 7470 a function call or a combination of many expressions. See 7471 parse.raw for the complete yacc grammar definition for 7472 expressions for more details.</p> 7473 7474 <p>The Hash Table entry in <em>lex.c</em>:</p> 7475 <pre> 7476 { "crypt",CRYPT,NULL }, 7477</pre> 7478 7479 <p>Notice that the last item is a NULL in this case since the 7480 function call is handled in <em>parse.raw</em> directly. If you 7481 used an INTFUNCn grammar, then you would put the name of your 7482 function in place of this NULL. The actual Crypt() function in 7483 <em>crypt.c</em>:</p> 7484 <pre> 7485/* 7486 * If mode is non-zero, a salt is expected. 7487 * If mode is zero, a pseudo-random salt will be selected. 7488 */ 7489void Crypt(int mode) { 7490#if HAVE_CRYPT 7491 Stack *s; 7492 char salt[8]; 7493 char *enc; 7494 7495 salt[0] = '\0'; 7496 if(mode) { 7497 s = Pop(); 7498 if(!s) { 7499 Error("Stack error in crypt"); 7500 return; 7501 } 7502 if(s->strval) strncpy(salt,s->strval,2); 7503 } 7504 s = Pop(); 7505 if(!s) { 7506 Error("Stack error in crypt"); 7507 return; 7508 } 7509 if(!salt[0]) { 7510 salt[0] = 'A' + (time(NULL) % 26); 7511 salt[1] = 'a' + (time(NULL) % 26); 7512 salt[2] = '\0'; 7513 } 7514 enc = (char *)crypt(s->strval,salt); 7515#if DEBUG 7516 Debug("Crypt returned [%s]\n",enc); 7517#endif 7518 Push(enc,STRING); 7519 7520#else 7521 Error("No crypt support compiled into this version"); 7522#endif 7523} 7524</pre> 7525 7526 <p>The most important aspect of this function is the <strong>s = 7527 Pop()</strong> call. The arguments to the function must be popped 7528 off the expression stack one by one. When you write a function 7529 which takes multiple arguments, remember that a stack is a 7530 LAST-IN, FIRST-OUT data structure. This means that you will be 7531 popping your arguments off the stack in reverse order. The last 7532 argument is popped off first. In the above example we check to 7533 see if we are in the 2 argument mode. If we are, we pop the 7534 argument off the stack and save it. Then we pop the next argument 7535 off the stack. Pop() returns a pointer to a Stack structure (s). 7536 The Stack structure looks like this (from <em>php.h</em>):</p> 7537 <pre> 7538/* Expression Stack */ 7539typedef struct Stack { 7540 short type; 7541 unsigned char *strval; 7542 long intval; 7543 double douval; 7544 VarTree *var; 7545 struct Stack *next; 7546} Stack; 7547</pre> 7548 7549 <p>The <em>type</em> will generally be one of STRING, LNUMBER or 7550 DNUMBER. The <em>strval</em>, <em>intval</em>, and 7551 <em>douval</em> components are the string, integer and double 7552 representations of the value respectively. If the expression is 7553 actually a defined variable, the <em>var</em> component contains 7554 a pointer to the variable structure which defines this 7555 variable.</p> 7556 7557 <p>In our Crypt() function we are only interested in the string 7558 value of the argument, so we use <em>s->strval</em>. Many 7559 PHP/FI functions can do different things depending on the type of 7560 the variable simply by checking <em>s->type</em> and using 7561 <em>s->strval</em>, <em>s->intval</em> and/or 7562 <em>s->douval</em> appropriately.</p> 7563 7564 <p>After calling the <strong>real</strong> crypt() function and 7565 getting the encrypted string, our Crypt() function calls 7566 <em>Push(enc,STRING);</em> to push the return value onto the 7567 expression stack. It should be noted that the expression stack is 7568 cleared after each PHP/FI line, so if you push expressions onto 7569 this stack that are never popped by anything, it won't 7570 matter.</p> 7571 7572 <p>The <em>Debug()</em> call in the Crypt() example shows how to 7573 add debugging output to your function. Debug() is a varags 7574 (variable argument list) function just like printf.</p> 7575 <hr> 7576 7577 <h2><a name="hacknotes" id="hacknotes">Notes for 7578 Code-Hacks</a></h2> 7579 7580 <p>Memory management within PHP/FI is a tricky thing. Since we 7581 can run as a server module, we have to be very careful about 7582 memory resources. Not only do we need to be reentrant, but we 7583 also need to be handle the fact that we can receive a timeout 7584 signal at any time at which point we drop out of the module. We 7585 get no warning, and we get no time to free any memory that we may 7586 have allocated. And this memory has to be freed, or the data 7587 space of the httpd process we are linked to could grow 7588 indefinitely. This also applies when PHP is running in CGI mode 7589 since it can be set up to run as a FastCGI persistent 7590 process.</p> 7591 7592 <p>The solution is to use sub-pools of memory. These pools are 7593 automatically cleared by Apache when a session is terminated, or 7594 in the case of a FastCGI persistent process, these pools are 7595 cleared in <em>main.c</em> every time the FastCGI wrapper loop 7596 executes. Three such pools are used at the moment. They are 7597 numbered 0,1 and 2. The sub-pool number is the first argument to 7598 the <em>emalloc</em> and <em>estrdup</em> functions.</p> 7599 7600 <dl> 7601 <dt><strong>Pool 0 - Session lifespan</strong></dt> 7602 7603 <dd>Any memory allocated from this pool will span the entire 7604 session. It is a good idea to keep the use of this pool as low 7605 as possible. For example, if someone makes a while loop that 7606 iterates 1000 times and within this while loop they call 7607 something which allocates memory from pool 0, then this memory 7608 will be allocated 1000 times. This is a quick way to use up all 7609 alloted data space.</dd> 7610 7611 <dt><strong>Pool 1 - Temporary storage (shortest 7612 lifespan)</strong></dt> 7613 7614 <dd>If a temporary work buffer is needed for something within a 7615 function, the memory for it must come from this pool. This pool 7616 is cleared on every call to yylex(). ie. the memory is lost 7617 just about as soon as you leave a function.</dd> 7618 7619 <dt><strong>Pool 2 - Expression space (medium 7620 lifespan)</strong></dt> 7621 7622 <dd>This pool exists for the duration of an expression. An 7623 expression in this context being a full PHP/FI command line. It 7624 will not get cleared within functions since the higher level 7625 expression which called the function has not been completed 7626 until the function returns. The ClearIt flag in the yylex() 7627 function indicates when it is safe to clear this pool.</dd> 7628 </dl> 7629 7630 <p>The use of sub-pools completely eliminates the need to 7631 explicitly free memory anywhere in the code, with the one 7632 exception being memory allocated using a regular malloc call by 7633 various libraries that could be linked into PHP. The gdbm library 7634 is one such example.</p> 7635 7636<?php site_footer(); ?> 7637
