CVS update: php3/doc/functions

Date: Friday September 11, 1998 @ 9:34 Author: kk Update of /repository/php3/doc/functions In directory asf:/u2/tmp/cvs-serv9923/doc/functions Modified Files: array.sgml calendar.sgml datetime.sgml dbase.sgml dbm.sgml filesystem.sgml http.sgml imap.sgml strings.sgml var.sgml Log Message: Many errata from http://ca.php.net/manual/browse-errata.php3 incorporated into the documentation source. (Errata letters A-K). Index: php3/doc/functions/array.sgml diff -c php3/doc/functions/array.sgml:1.24 php3/doc/functions/array.sgml:1.25 *** php3/doc/functions/array.sgml:1.24 Mon Sep 7 06:52:34 1998 --- php3/doc/functions/array.sgml Fri Sep 11 09:34:39 1998 *************** *** 240,245 **** --- 240,254 ---- internal pointer points beyond the end of the elements list, <function>current</function> returns false. + <para> + <emphasis>Warning:</emphasis> if the array contains empty + elements (0 or "", the empty string) then this function + will return false for these elements as well. It is + undecideable if the current element is just a zero-value or + you have traversed beyond the end of the array. To properly + traverse an array, use the <function>each</function> + function. + <para> See also: <function>end</function>, <function>next</function>, Index: php3/doc/functions/calendar.sgml diff -c php3/doc/functions/calendar.sgml:1.3 php3/doc/functions/calendar.sgml:1.4 *** php3/doc/functions/calendar.sgml:1.3 Sun Mar 29 15:13:13 1998 --- php3/doc/functions/calendar.sgml Fri Sep 11 09:34:40 1998 *************** *** 5,10 **** --- 5,15 ---- <partintro> <para> + The calendar functions are only available if you have compiled the + calendar extension in dl/calendar. Read dl/README for instructions on + using it. + </para> + <para> The Calendar extension in PHP presents a series of functions to simplify converting between different calendar formats. The intermediary or standard it is based on is the Julian Day Count. Index: php3/doc/functions/datetime.sgml diff -c php3/doc/functions/datetime.sgml:1.16 php3/doc/functions/datetime.sgml:1.17 *** php3/doc/functions/datetime.sgml:1.16 Wed Sep 2 13:21:49 1998 --- php3/doc/functions/datetime.sgml Fri Sep 11 09:34:40 1998 *************** *** 83,88 **** --- 83,101 ---- print(date( "l dS of F Y h:i:s A" )); print("July 1, 2000 is on a " . date("l", mktime(0,0,0,7,1,2000))); </programlisting></example> + <para> + It is possible to use <function>date</function> and + <function>mktime</function> together to find dates in the + future or the past. + + <example> + <title><function>date</function> and <function>mktime</function> example</title> + <programlisting> + $tomorrow = mktime(0,0,0,date("m") ,date("d")+1,date("Y")); + $lastmonth = mktime(0,0,0,date("m")-1,date("d"), date("Y")); + $nextyear = mktime(0,0,0,date("m"), date("d", date("Y")+1); + </programlisting></example> + See also <function>gmdate</function> and <function>mktime</function>. </para> *************** *** 239,244 **** --- 252,264 ---- <paramdef>int <parameter>day</parameter></paramdef> <paramdef>int <parameter>year</parameter></paramdef> </funcsynopsis> + <para> + <emphasis>Warning:</emphasis> Note the strange order of + arguments, which differs from the order of arguments in + a regular UNIX mktime() call and which does not lend + itself well to leaving out parameters from right to left + (see below). It is a common error to mix these values up + in a script. <para> Returns the Unix timestamp corresponding to the arguments given. This timestamp is a long integer containing the number of Index: php3/doc/functions/dbase.sgml diff -c php3/doc/functions/dbase.sgml:1.4 php3/doc/functions/dbase.sgml:1.5 *** php3/doc/functions/dbase.sgml:1.4 Sun Mar 29 15:13:13 1998 --- php3/doc/functions/dbase.sgml Fri Sep 11 09:34:40 1998 *************** *** 7,13 **** These functions allow you to access records stored in dBase-format (dbf) databases. <simpara> ! There is no support for indexes or memo fields. </partintro> <refentry id="function.dbase-create"> --- 7,31 ---- These functions allow you to access records stored in dBase-format (dbf) databases. <simpara> ! There is no support for indexes or memo fields. There is no support ! for locking, too. Two concurrent webserver processes accessing the ! same dBase file will ruin your database. ! <simpara> ! Unlike SQL databases, dBase "databases" cannot change the database ! definition afterwards. Once the file is created, the database ! definition is fixed. There are no indexes that speed searching or ! otherwise organize your data. dBase files are simple sequential ! files of fixed length records. Records are appended to the end of ! the file and delete records are kept until you call ! <function>dbase_pack()</function>. ! <simpara> ! We recommend that you do not use dBase files as your production ! database. Choose any real SQL server instead; MySQL or Postgres ! are common choices with PHP. dBase support is here to allow you ! to import and export data to and from your web database, since the ! file format is commonly understood with Windows spreadsheets ! and organizers. Import and export of data is about all that ! dBase support is good for. </partintro> <refentry id="function.dbase-create"> *************** *** 62,67 **** --- 80,106 ---- <para> If the database is successfully created, a dbase_identifier is returned, otherwise false is returned. + + <example> + <title>Creating a dBase database file</title> + <programlisting> + // "database" name + $dbname = "/tmp/test.dbf"; + + // database "definition" + $def = + array( + array("date", "D"), + array("name", "C", 50), + array("age", "N", 3, 0), + array("email", "C", 128), + array("ismember", "L") + ); + + // creation + if (!dbase_create($dbname, $def)) + print "<strong>Error!</strong>"; + </programlisting></example> </refsect1> </refentry> *************** *** 173,179 **** </funcsynopsis> <para> Returns the data from <parameter>record</parameter> in an array. The ! array is indexed starting at 0, and includes an associative member named 'deleted' which is set to 1 if the record has been marked for deletion (see <function>dbase_delete_record</function>. <para> --- 212,218 ---- </funcsynopsis> <para> Returns the data from <parameter>record</parameter> in an array. The ! array is indexed starting at 1, and includes an associative member named 'deleted' which is set to 1 if the record has been marked for deletion (see <function>dbase_delete_record</function>. <para> *************** *** 195,201 **** </funcsynopsis> <para> Returns the number of fields (columns) in the specified ! database. </refsect1> </refentry> --- 234,250 ---- </funcsynopsis> <para> Returns the number of fields (columns) in the specified ! database. Field numbers are between 0 and dbase_numfields($db)-1, ! while record numbers are between 1 and dbase_numrecords($db). ! <example> ! <title>Using <function>dbase_numfields</function></title> ! <programlisting> ! $rec = dbase_get_record($db, $recno); ! $nf = dbase_numfields($db); ! for ($i=0; $i< $nf; $i++) { ! print $rec[$i]."<br>\n"; ! } ! </programlisting></example> </refsect1> </refentry> *************** *** 212,218 **** </funcsynopsis> <para> Returns the number of records (rows) in the specified ! database. </refsect1> </refentry> --- 261,268 ---- </funcsynopsis> <para> Returns the number of records (rows) in the specified ! database. Record numbers are between 1 and dbase_numrecords($db), ! while field numbers are between 0 and dbase_numfields($db)-1. </refsect1> </refentry> Index: php3/doc/functions/dbm.sgml diff -c php3/doc/functions/dbm.sgml:1.4 php3/doc/functions/dbm.sgml:1.5 *** php3/doc/functions/dbm.sgml:1.4 Tue Apr 28 22:11:47 1998 --- php3/doc/functions/dbm.sgml Fri Sep 11 09:34:40 1998 *************** *** 26,32 **** <para> The first argument is the full-path filename of the dbm file to be opened and the second is the file open mode which is one of "r", "n" or "w" for ! read, new (implies write) and write respectively. <para> Returns an identifer to be passed to the other dbm functions on success, or false on failure. --- 26,32 ---- <para> The first argument is the full-path filename of the dbm file to be opened and the second is the file open mode which is one of "r", "n" or "w" for ! read-only, new (implies read-write) and read-write respectively. <para> Returns an identifer to be passed to the other dbm functions on success, or false on failure. Index: php3/doc/functions/filesystem.sgml diff -c php3/doc/functions/filesystem.sgml:1.27 php3/doc/functions/filesystem.sgml:1.28 *** php3/doc/functions/filesystem.sgml:1.27 Mon Sep 7 07:55:36 1998 --- php3/doc/functions/filesystem.sgml Fri Sep 11 09:34:40 1998 *************** *** 689,702 **** If an error occurs, <function>fpassthru</function> returns false. <simpara> ! The file pointer must be valid, and must point to a file ! successfully opened by <function>fopen</function>, ! <function>popen</function>, or <function>fsockopen</function>. ! ! <simpara> ! The file is closed when <function>fpassthru</function> is done reading it (leaving <parameter>fp</parameter> useless). <simpara> See also <function>readfile</function>, <function>fopen</function>, --- 689,704 ---- If an error occurs, <function>fpassthru</function> returns false. <simpara> ! The file pointer must be valid, and must point to a file successfully ! opened by <function>fopen</function>, <function>popen</function>, or ! <function>fsockopen</function>. The file is closed when <function>fpassthru</function> is done reading it (leaving <parameter>fp</parameter> useless). + + <simpara> + If you just want to dump the contents of a file to stdout + you may want to use the <function>readfile</function>, which + saves you the <function>fopen</function> call. <simpara> See also <function>readfile</function>, <function>fopen</function>, Index: php3/doc/functions/http.sgml diff -c php3/doc/functions/http.sgml:1.8 php3/doc/functions/http.sgml:1.9 *** php3/doc/functions/http.sgml:1.8 Thu Jul 16 11:55:27 1998 --- php3/doc/functions/http.sgml Fri Sep 11 09:34:41 1998 *************** *** 24,35 **** <acronym>HTML</acronym> file to send raw <acronym>HTTP</acronym> header strings. See the <ulink url="&spec.http1.1;">HTTP 1.1 Specification</ulink> for more information on raw http headers. ! Remember that the <function>Header</function> function must be ! called before any actual output is sent either by normal HTML ! tags or from PHP. <para> <informalexample><programlisting role=php> Header("Location: http://www.php.net"); /* Redirect browser to PHP web site */ </programlisting></informalexample> </refsect1> </refentry> --- 24,52 ---- <acronym>HTML</acronym> file to send raw <acronym>HTTP</acronym> header strings. See the <ulink url="&spec.http1.1;">HTTP 1.1 Specification</ulink> for more information on raw http headers. ! <emphasis>Note:</emphasis> Remember that the ! <function>Header</function> function must be called before any actual ! output is sent either by normal HTML tags or from PHP. It is a very ! common error to read code with <function>include</function> or with ! auto_prepend and have spaces or empty lines in this code that force ! output before <function>header</function> is called. ! <para> <informalexample><programlisting role=php> Header("Location: http://www.php.net"); /* Redirect browser to PHP web site */ + exit; /* Make sure that code below does not get executed when we redirect. */ + </programlisting></informalexample> + + <para> + PHP scripts often generate dynamic HTML that must not be cached + by the client browser or any proxy caches between the server and the + client browser. Many proxies and clients can be forced to disable + caching with + <informalexample><programlisting role=php> + header("Expires: Mon, 26 Jul 1997 05:00:00 GMT"); // Date in the past + header("Last-Modified: " . gmdate("D, d M Y H:i:s") . "GMT"); // always modified + header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1 + header("Pragma: no-cache"); // HTTP/1.0 </programlisting></informalexample> </refsect1> </refentry> Index: php3/doc/functions/imap.sgml diff -c php3/doc/functions/imap.sgml:1.16 php3/doc/functions/imap.sgml:1.17 *** php3/doc/functions/imap.sgml:1.16 Fri Sep 4 14:50:16 1998 --- php3/doc/functions/imap.sgml Fri Sep 11 09:34:41 1998 *************** *** 2,7 **** --- 2,19 ---- <title>IMAP Functions</title> <titleabbrev>IMAP</titleabbrev> + <partintro> + <simpara> + To get these functions to work, you have to compile + PHP with --with-imap. That requires the c-client library + to be installed. Grab it from + ftp://ftp.cac.washington.edu/imap/imap-4.2.tar.Z and compile it. + Then copy c-client/c-client.a to /usr/local/lib or some + other directory on your link path and copy c-client/rfc822.h, + mail.h and linkage.h to /usr/local/include or some + other directory in your include path. + </partintro> + <refentry id="function.imap-append"> <refnamediv> <refname>imap_append</refname> *************** *** 383,388 **** --- 395,402 ---- <funcsynopsis> <funcdef>array <function>imap_listmailbox</function></funcdef> <paramdef>int <parameter>imap_stream</parameter></paramdef> + <paramdef>string <parameter>ref</parameter></paramdef> + <paramdef>string <parameter>pat</parameter></paramdef> </funcsynopsis> <para> Returns an array containing the names of the mailboxes. Index: php3/doc/functions/strings.sgml diff -c php3/doc/functions/strings.sgml:1.33 php3/doc/functions/strings.sgml:1.34 *** php3/doc/functions/strings.sgml:1.33 Thu Aug 20 00:12:45 1998 --- php3/doc/functions/strings.sgml Fri Sep 11 09:34:41 1998 *************** *** 24,30 **** Returns a string with backslashes before characters that need to be quoted in database queries etc. These characters are single quote (<literal>'</literal>), double quote ! (<literal>"</literal>), and backslash (<literal>\</literal>). <para> See also <function>stripslashes</function> and <function>quotemeta</function>. --- 24,31 ---- Returns a string with backslashes before characters that need to be quoted in database queries etc. These characters are single quote (<literal>'</literal>), double quote ! (<literal>"</literal>), backslash (<literal>\</literal>) ! and NUL (the null byte). <para> See also <function>stripslashes</function> and <function>quotemeta</function>. *************** *** 74,82 **** <title>chr() example</title> <programlisting> $str .= chr(27); /* add an escape character at the end of $str */ </programlisting></example> ! This function complements <function>ord</function>. </refsect1> </refentry> --- 75,88 ---- <title>chr() example</title> <programlisting> $str .= chr(27); /* add an escape character at the end of $str */ + + /* Often this is more useful */ + $str = sprintf("The string ends in escape: %c", 27); </programlisting></example> ! This function complements <function>ord</function>. See also ! <function>sprintf</function> with a format string of ! <literal>%c</literal>. </refsect1> </refentry> Index: php3/doc/functions/var.sgml diff -c php3/doc/functions/var.sgml:1.7 php3/doc/functions/var.sgml:1.8 *** php3/doc/functions/var.sgml:1.7 Fri May 15 16:59:06 1998 --- php3/doc/functions/var.sgml Fri Sep 11 09:34:41 1998 *************** *** 426,433 **** </funcsynopsis> <simpara> ! Returns true if <parameter>var</parameter> exists and has a ! value; false otherwise. <simpara> See also <function>empty</function>. --- 426,433 ---- </funcsynopsis> <simpara> ! Returns true if <parameter>var</parameter> exists; ! false otherwise. <simpara> See also <function>empty</function>. -- PHP Development Mailing List http://www.php.net/ To unsubscribe send an empty message to php-dev-unsubscribe@lists.php.net For help: php-dev-help@lists.php.net