diff --git a/functions/misc.xml b/functions/misc.xml index d6da22f914..1eb6781ed9 100644 --- a/functions/misc.xml +++ b/functions/misc.xml @@ -5,13 +5,14 @@ These functions were placed here because none of the other - categories seemed to fit. + categories seemed to fit. + connection_aborted - Returns true if client disconnected + Returns true if client disconnected. Description @@ -20,8 +21,9 @@ void - Returns true if client disconnected. See the Connection Handling - description in the Features + Returns true if client disconnected. See the Connection Handling + description in the Features chapter for a complete explanation. @@ -30,7 +32,7 @@ connection_status - Returns connection status bitfield + Returns connection status bitfield. Description @@ -39,9 +41,10 @@ void - Returns the connection status bitfield. See the Connection - Handling description in the Features chapter for a complete - explanation. + Returns the connection status bitfield. See the Connection Handling + description in the Features + chapter for a complete explanation. @@ -49,7 +52,7 @@ connection_timeout - Return true if script timed out + Return true if script timed out. Description @@ -58,7 +61,8 @@ void - Returns true if script timed out. See the Connection Handling + Returns true if script timed out. See the Connection Handling description in the Features chapter for a complete explanation. @@ -67,104 +71,110 @@ - define - Defines a named constant. + define + Defines a named constant. - Description - - int define - string name - mixed value - int case_insensitive - - - - Defines a named constant, which is similar to a variable except: - - - - Constants do not have a dollar sign '$' before them; - - - - - Constants may be accessed anywhere without regard to variable - scoping rules; - - - - - Constants may not be redefined or undefined once they have - been set; and - - - - - Constants may only evaluate to scalar values. - - - - - - The name of the constant is given by name; - the value is given by value. - - - The optional third parameter - case_insensitive is also available. If the - value 1 is given, then the constant will be - defined case-insensitive. The default behaviour is - case-sensitive; i.e. CONSTANT and Constant represent different - values. - - - - Defining Constants - + Description + + int define + string name + mixed value + int + case_insensitive + + + + Defines a named constant, which is similar to a variable except: + + + + Constants do not have a dollar sign '$' before them; + + + + + Constants may be accessed anywhere without regard to variable + scoping rules; + + + + + Constants may not be redefined or undefined once they have + been set; and + + + + + Constants may only evaluate to scalar values. + + + + + + The name of the constant is given by name; + the value is given by value. + + + The optional third parameter + case_insensitive is also available. If the + value 1 is given, then the constant will be + defined case-insensitive. The default behaviour is + case-sensitive; i.e. CONSTANT and Constant represent different + values. + + + + Defining Constants + <?php -define("CONSTANT", "Hello world."); +define ("CONSTANT", "Hello world."); echo CONSTANT; // outputs "Hello world." ?> - - - - - define returns TRUE on success and FALSE if - an error occurs. - - - See also defined and the section on Constants. - + + + + + define returns TRUE on success and FALSE if + an error occurs. + + + See also defined and the section on Constants. + - defined - Checks whether a given named constant exists. + defined + + Checks whether a given named constant exists. + - Description - - int defined - string name - - - - Returns TRUE if the named constant given by - name has been defined, false otherwise. - - - See also define and the section on Constants. - + Description + + int defined + string name + + + Returns TRUE if the named constant given by + name has been defined, false otherwise. + + + See also define and the section on Constants. + die - Output a message and terminate the current script + + Output a message and terminate the current script. + Description @@ -174,25 +184,27 @@ echo CONSTANT; // outputs "Hello world." This language construct outputs a message and terminates parsing - of the script. It does not return. + of the script. It does not return. + die example - + <?php $filename = '/path/to/data-file'; -$file = fopen($filename, 'r') - or die "unable to open file ($filename)"; +$file = fopen ($filename, 'r') + or die "unable to open file ($filename)"; ?> - + + eval - Evaluate a string as PHP code + Evaluate a string as PHP code. Description @@ -200,55 +212,56 @@ $file = fopen($filename, 'r') void eval string code_str - eval evaluates the string given in code_str as PHP code. Among other things, this can be useful for storing code in a database text field for - later execution. - + later execution. + There are some factors to keep in mind when using eval. Remember that the string passed must be valid PHP code, including things like terminating statements with a semicolon so the parser doesn't die on the line after the eval, and properly escaping things in - code_str. - + code_str. + Also remember that variables given values under eval will retain these values in the main - script afterwards. - + script afterwards. + - eval() example - simple text merge - + + <function>Eval</function> example - simple text merge + + <?php $string = 'cup'; $name = 'coffee'; $str = 'This is a $string with my $name in it.<br>'; echo $str; -eval( "\$str = \"$str\";" ); +eval ("\$str = \"$str\";"); echo $str; ?> - - + + The above example will show: - + This is a $string with my $name in it. This is a cup with my coffee in it. - - + + exit - Terminate current script + Terminate current script. Description @@ -258,7 +271,8 @@ This is a cup with my coffee in it. This language construct terminates parsing of the script. It - does not return. + does not return. + @@ -274,57 +288,54 @@ This is a cup with my coffee in it. int arg_num - Returns the argument which is at the - arg_num'th offset into a user-defined - function's argument list. Function arguments are counted starting - from zero. func_get_arg will generate a - warning if called from outside of a function definition. + Returns the argument which is at the + arg_num'th offset into a user-defined + function's argument list. Function arguments are counted starting + from zero. func_get_arg will generate a + warning if called from outside of a function definition. - - - If arg_num is greater than the number of - arguments actually passed, a warning will be generated and - func_get_arg will return FALSE. - - - - - + + If arg_num is greater than the number of + arguments actually passed, a warning will be generated and + func_get_arg will return FALSE. + + + + <?php function foo() { - $numargs = func_num_args(); - echo "Number of arguments: $numargs<br>\n"; - if ( $numargs >= 2 ) { - echo "Second argument is: " . func_get_arg( 1 ) . "<br>\n"; - } + $numargs = func_num_args(); + echo "Number of arguments: $numargs<br>\n"; + if ($numargs >= 2) { + echo "Second argument is: " . func_get_arg (1) . "<br>\n"; + } } -foo( 1, 2, 3 ); +foo (1, 2, 3); ?> - - - - - - func_get_arg may be used in conjunction - with func_num_args and - func_get_args to allow user-defined - functions to accept variable-length argument lists. - - - - - This function was added in PHP 4. - - - + + + + + func_get_arg may be used in conjunction with + func_num_args and + func_get_args to allow user-defined + functions to accept variable-length argument lists. + + + + This function was added in PHP 4. + + func_get_args - Returns an array comprising a function's argument list. + + Returns an array comprising a function's argument list. + Description @@ -333,54 +344,52 @@ foo( 1, 2, 3 ); void - Returns an array in which each element is the corresponding - member of the current user-defined function's argument - list. func_get_args will generate a warning - if called from outside of a function definition. + Returns an array in which each element is the corresponding + member of the current user-defined function's argument + list. func_get_args will generate a warning + if called from outside of a function definition. - - + <?php function foo() { - $numargs = func_num_args(); - echo "Number of arguments: $numargs<br>\n"; - if ( $numargs >= 2 ) { - echo "Second argument is: " . func_get_arg( 1 ) . "<br>\n"; - } - $arg_list = func_get_args(); - for ( $i = 0; $i < $numargs; $i++ ) { - echo "Argument $i is: " . $arg_list[$i] . "<br>\n"; - } + $numargs = func_num_args(); + echo "Number of arguments: $numargs<br>\n"; + if ($numargs >= 2) { + echo "Second argument is: " . func_get_arg (1) . "<br>\n"; + } + $arg_list = func_get_args(); + for ($i = 0; $i < $numargs; $i++) { + echo "Argument $i is: " . $arg_list[$i] . "<br>\n"; + } } -foo( 1, 2, 3 ); +foo (1, 2, 3); ?> - - - - - - func_get_args may be used in conjunction - with func_num_args and - func_get_arg to allow user-defined functions - to accept variable-length argument lists. - - - - - This function was added in PHP 4. - - - + + + + + func_get_args may be used in conjunction + with func_num_args and + func_get_arg to allow user-defined functions + to accept variable-length argument lists. + + + + This function was added in PHP 4. + + func_num_args - Returns the number of arguments passed to the function. + + Returns the number of arguments passed to the function. + Description @@ -389,47 +398,45 @@ foo( 1, 2, 3 ); void - Returns the number of arguments passed into the current - user-defined function. func_num_args will - generate a warning if called from outside of a function - definition. + Returns the number of arguments passed into the current + user-defined function. func_num_args will + generate a warning if called from outside of a function + definition. - - - - + + + <?php function foo() { - $numargs = func_num_args(); - echo "Number of arguments: $numargs\n"; + $numargs = func_num_args(); + echo "Number of arguments: $numargs\n"; } -foo( 1, 2, 3 ); // Prints 'Number of arguments: 3' +foo (1, 2, 3); // Prints 'Number of arguments: 3' ?> - - - - - - func_num_args may be used in conjunction - with func_get_arg and - func_get_args to allow user-defined - functions to accept variable-length argument lists. - - - - - This function was added in PHP 4. - - - + + + + + func_num_args may be used in conjunction + with func_get_arg and + func_get_args to allow user-defined + functions to accept variable-length argument lists. + + + + This function was added in PHP 4. + + function_exists - Return true if the given function has been defined + + Return true if the given function has been defined. + Description @@ -438,77 +445,74 @@ foo( 1, 2, 3 ); // Prints 'Number of arguments: 3' string function_name - Checks the list of defined functions for function_name. - Returns true if the given function name was found, false otherwise. + Checks the list of defined functions for + function_name. Returns true if the given + function name was found, false otherwise. - - get_browser - Tells what the user's browser is capable of. + get_browser + + Tells what the user's browser is capable of. + - Description - - object get_browser - string user_agent - - - - get_browser attempts to determine the - capabilities of the user's browser. This is done by looking up - the browser's information in the - browscap.ini file. By default, the value of - $HTTP_USER_AGENT is used; however, you can alter this (i.e., look - up another browser's info) by passing the optional - user_agent parameter to - get_browser. - - - - The information is returned in an object, which will contain - various data elements representing, for instance, the browser's - major and minor version numbers and ID string; - true/false values for features such as frames, JavaScript, and - cookies; and so forth. - - - - While browscap.ini contains information on - many browsers, it relies on user updates to keep the database - current. The format of the file is fairly self-explanatory. - - - - The following example shows how one might list all available - information retrieved about the user's browser. - - - <function>get_browser</function> example - + Description + + object get_browser + string + user_agent + + + + get_browser attempts to determine the + capabilities of the user's browser. This is done by looking up + the browser's information in the + browscap.ini file. By default, the value of + $HTTP_USER_AGENT is used; however, you can alter this (i.e., look + up another browser's info) by passing the optional + user_agent parameter to + get_browser. + + + The information is returned in an object, which will contain + various data elements representing, for instance, the browser's + major and minor version numbers and ID string; true/false values + for features such as frames, JavaScript, and cookies; and so + forth. + + + While browscap.ini contains information on + many browsers, it relies on user updates to keep the database + current. The format of the file is fairly self-explanatory. + + + The following example shows how one might list all available + information retrieved about the user's browser. + + <function>Get_browser</function> example + <?php -function list_array( $array ) { - while ( list( $key, $value ) = each( $array ) ) { - $str .= "<b>$key:</b> $value<br>\n"; - } - return $str; +function list_array ($array) { + while (list ($key, $value) = each ($array)) { + $str .= "<b>$key:</b> $value<br>\n"; + } + return $str; } echo "$HTTP_USER_AGENT<hr>\n"; $browser = get_browser(); -echo list_array( (array) $browser ); +echo list_array ((array) $browser); ?> - - - - - - The output of the above script would look something like this: - - - + + + + + The output of the above script would look something like this: + + Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)<hr> <b>browser_name_pattern:</b> Mozilla/4\.5.*<br> <b>parent:</b> Netscape 4.0<br> @@ -529,40 +533,41 @@ Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)<hr> <b>crawler:</b> <br> <b>authenticodeupdate:</b> <br> <b>msn:</b> <br> - - - - In order for this to work, your browscap configuration file - setting must point to the correct location of the - browscap.ini file. - - - - For more information (including locations from which you may - obtain a browscap.ini file), check the PHP - FAQ at http://www.php.net/FAQ.html. - - - - - browscap support was added to PHP in version 3.0b2. - - - + + + In order for this to work, your browscap configuration file + setting must point to the correct location of the + browscap.ini file. + + + For more information (including locations from which you may + obtain a browscap.ini file), check the PHP + FAQ at http://www.php.net/FAQ.html. + + + + Browscap support was added to PHP in version 3.0b2. + + - ignore_user_abort - Set whether a client disconnect should abort script execution + + Set whether a client disconnect should abort script execution. + Description int ignore_user_abort - int setting + int + setting + This function sets whether a client disconnect should cause a @@ -578,8 +583,9 @@ Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)<hr> iptcparse - Parse a binary IPTC - http://www.xe.net/iptc/ block into single tags. + + Parse a binary IPTC &url.iptc; + block into single tags. @@ -592,14 +598,15 @@ Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)<hr> This function parses a binary IPTC block into its single tags. It returns an array using the tagmarker as an index and the value as the value. It returns false on error or if no IPTC data was - found. See GetImageSize for a sample. + found. See GetImageSize for a sample. + leak - Leak memory + Leak memory. Description @@ -608,122 +615,212 @@ Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)<hr> int bytes - Leak leaks the specified amount of memory. + Leak leaks the specified amount of memory. + This is useful when debugging the memory manager, which automatically - cleans up "leaked" memory when each request is completed. + cleans up "leaked" memory when each request is completed. + pack - pack data into binary string + Pack data into binary string. Description string pack string format - mixed args... + mixed + args ... + Pack given arguments into binary string according to - format. Returns binary string containing data. - + format. Returns binary string containing + data. + The idea to this function was taken from Perl and all formatting - codes work the same as there, however, there are some formatting codes that are missing - such as Perl's "u" format code. The format string consists of - format codes followed by an optional repeater argument. The - repeater argument can be either an integer value or * for - repeating to the end of the input data. For a, A, h, H the repeat - count specifies how many characters of one data argument are - taken, for @ it is the absolute position where to put the next - data, for everything else the repeat count specifies how many - data arguments are consumed and packed into the resulting binary - string. Currently implemented are + codes work the same as there, however, there are some formatting + codes that are missing such as Perl's "u" format code. The format + string consists of format codes followed by an optional repeater + argument. The repeater argument can be either an integer value or + * for repeating to the end of the input data. For a, A, h, H the + repeat count specifies how many characters of one data argument + are taken, for @ it is the absolute position where to put the + next data, for everything else the repeat count specifies how + many data arguments are consumed and packed into the resulting + binary string. Currently implemented are - a NUL-padded string - A SPACE-padded string - h Hex string, low nibble first - H Hex string, high nibble first - c signed char - C unsigned char - s signed short (always 16 bit, machine byte order) - S unsigned short (always 16 bit, machine byte order) - n unsigned short (always 16 bit, big endian - byte order) - v unsigned short (always 16 bit, little - endian byte order) - i signed integer (machine dependant size and - byte order) - I unsigned integer (machine dependant size - and byte order) - l signed long (always 32 bit, machine byte order) - L unsigned long (always 32 bit, machine byte order) - N unsigned long (always 32 bit, big endian - byte order) - V unsigned long (always 32 bit, little endian - byte order) - f float (machine dependent size and representation) - d double (machine dependent size and representation) - x NUL byte - X Back up one byte - @ NUL-fill to absolute position + + + a NUL-padded string + + + + + A SPACE-padded string + + + + + h Hex string, low nibble first + + + + + H Hex string, high nibble first + + + + + c signed char + + + + + C unsigned char + + + + + s signed short (always 16 bit, machine byte order) + + + + + S unsigned short (always 16 bit, machine byte order) + + + + + n unsigned short (always 16 bit, big endian byte order) + + + + + v unsigned short (always 16 bit, little endian byte order) + + + + + i signed integer (machine dependant size and byte order) + + + + + I unsigned integer (machine dependant size and byte order) + + + + + l signed long (always 32 bit, machine byte order) + + + + + L unsigned long (always 32 bit, machine byte order) + + + + + N unsigned long (always 32 bit, big endian byte order) + + + + + V unsigned long (always 32 bit, little endian byte order) + + + + + f float (machine dependent size and representation) + + + + + d double (machine dependent size and representation) + + + + + x NUL byte + + + + X Back up one byte + + + + @ NUL-fill to absolute position + + - pack format string -$binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66); - +$binarydata = pack ("nvc*", 0x1234, 0x5678, 65, 66); + The resulting binary string will be 6 bytes long and contain - the byte sequence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42. - - + the byte sequence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42. + + + Note that the distinction between signed and unsigned values only affects the function unpack, where as function pack gives the same result for - signed and unsigned format codes. - + signed and unsigned format codes. + Also note that PHP internally stores integral values as signed values of a machine dependant size. If you give it an unsigned - integral value too large to be stored that way it is converted to - a double which often yields an undesired result. - + integral value too large to be stored that way it is converted to + a double which often yields an undesired result. + - - register_shutdown_function - Register a function for execution on shutdown. - - - Description - - int register_shutdown_function - string func - - + + register_shutdown_function + + Register a function for execution on shutdown. + + + + Description + + int + register_shutdown_function + + string func + + Registers the function named by func to be executed when script processing is complete. - - Common Pitfalls: - - Since no output is allowed to the browser in this function, you will be - unable to debug it using statements such as print or echo. - - + + Common Pitfalls: + + + Since no output is allowed to the browser in this function, you + will be unable to debug it using statements such as print or + echo. + + + serialize - generates a storable representation of a value + + Generates a storable representation of a value. + Description @@ -734,45 +831,49 @@ $binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66); serialize returns a string containing a byte-stream representation of value that - can be stored anywhere. + can be stored anywhere. + This is useful for storing or passing PHP values around without - losing their type and structure. + losing their type and structure. + To make the serialized string into a PHP value again, use unserialize. serialize handles the types integer, double, string, array (multidimensional) and object (object properties will be serialized, but - methods are lost). + methods are lost). + - serialize example + <function>Serialize</function> example // $session_data contains a multi-dimensional array with session // information for the current user. We use serialize() to store // it in a database at the end of the request. -$conn = odbc_connect("webdb", "php", "chicken"); -$stmt = odbc_prepare($conn, - "UPDATE sessions SET data = ? WHERE id = ?"); -$sqldata = array(serialize($session_data), $PHP_AUTH_USER); -if (!odbc_execute($stmt, &$sqldata)) { +$conn = odbc_connect ("webdb", "php", "chicken"); +$stmt = odbc_prepare ($conn, + "UPDATE sessions SET data = ? WHERE id = ?"); +$sqldata = array (serialize($session_data), $PHP_AUTH_USER); +if (!odbc_execute ($stmt, &$sqldata)) { $stmt = odbc_prepare($conn, "INSERT INTO sessions (id, data) VALUES(?, ?)"); if (!odbc_execute($stmt, &$sqldata)) { /* Something went wrong. Bitch, whine and moan. */ } } - - + + + sleep - Delay execution + Delay execution. Description @@ -782,9 +883,11 @@ if (!odbc_execute($stmt, &$sqldata)) { The sleep function delays program execution for the given number - of seconds. + of seconds. + - See also usleep. + See also usleep. + @@ -798,12 +901,14 @@ if (!odbc_execute($stmt, &$sqldata)) { int uniqid string prefix - boolean lcg + boolean + lcg + uniqid returns a prefixed unique identifier - based on the current time in microseconds. The prefix can be useful - for instance if you generate identifiers simultaneously on + based on the current time in microseconds. The prefix can be + useful for instance if you generate identifiers simultaneously on several hosts that might happen to generate the identifier at the same microsecond. prefix can be up to 114 characters long. @@ -819,32 +924,34 @@ if (!odbc_execute($stmt, &$sqldata)) { will be 13 characters long. If lcg is true, it will be 23 characters. - - - - The lcg parameter is only available in - PHP 4 and PHP 3.0.13 and later. - - - + + + The lcg parameter is only available in + PHP 4 and PHP 3.0.13 and later. + + If you need a unique identifier or token and you intend to give out that token to the user via the network (i.e. session cookies), it is recommended that you use something along the lines of - -$token = md5(uniqid("")); // no random portion -$better_token = md5(uniqid(rand())); // better, difficult to guess - + + +$token = md5 (uniqid ("")); // no random portion +$better_token = md5 (uniqid (rand())); // better, difficult to guess + + + This will create a 32 character identifier (a 128 bit hex number) - that is extremely difficult to predict. + that is extremely difficult to predict. + unpack - unpack data from binary string + Unpack data from binary string. Description @@ -854,42 +961,45 @@ $better_token = md5(uniqid(rand())); // better, difficult to guess string data - Unpack from binary string into array according to - format. Returns array containing unpacked - elements of binary string. - + Unpack from binary string into array + according to format. Returns array + containing unpacked elements of binary string. + - Unpack works slightly different from Perl as the unpacked data is - stored in an associative array. To accomplish this you have to - name the different format codes and separate them by a slash /. - + Unpack works slightly different from Perl as + the unpacked data is stored in an associative array. To + accomplish this you have to name the different format codes and + separate them by a slash /. - unpack format string + <function>Unpack</function> format string -$array = unpack("c2chars/nint", $binarydata); - +$array = unpack ("c2chars/nint", $binarydata); + The resulting array will contain the entries "chars1", - "chars2" and "int". - - + "chars2" and "int". + + + For an explanation of the format codes see also: - pack - + pack + Note that PHP internally stores integral values as signed. If you unpack a large unsigned long and it is of the same size as PHP internally stored values the result will be a negative number - even though unsigned unpacking was specified. - + even though unsigned unpacking was specified. + unserialize - creates a PHP value from a stored representation + + Creates a PHP value from a stored representation. + Description @@ -904,38 +1014,40 @@ $array = unpack("c2chars/nint", $binarydata); be an integer, double, string, array or object. If an object was serialized, its methods are not preserved in the - returned value. + returned value. + - unserialize example + <function>Unserialize</function> example // Here, we use unserialize() to load session data from a database // into $session_data. This example complements the one described // with serialize. -$conn = odbc_connect("webdb", "php", "chicken"); -$stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?"); -$sqldata = array($PHP_AUTH_USER); -if (!odbc_execute($stmt, &$sqldata) || !odbc_fetch_into($stmt, &$tmp)) { +$conn = odbc_connect ("webdb", "php", "chicken"); +$stmt = odbc_prepare ($conn, "SELECT data FROM sessions WHERE id = ?"); +$sqldata = array ($PHP_AUTH_USER); +if (!odbc_execute ($stmt, &$sqldata) || !odbc_fetch_into ($stmt, &$tmp)) { // if the execute or fetch fails, initialize to empty array $session_data = array(); } else { // we should now have the serialized data in $tmp[0]. - $session_data = unserialize($tmp[0]); - if (!is_array($session_data)) { + $session_data = unserialize ($tmp[0]); + if (!is_array ($session_data)) { // something went wrong, initialize to empty array $session_data = array(); } } - - + + + usleep - Delay execution in microseconds + Delay execution in microseconds. Description @@ -944,14 +1056,17 @@ if (!odbc_execute($stmt, &$sqldata) || !odbc_fetch_into($stmt, &$tmp)) { int micro_seconds - The sleep function delays program execution for the given number - of micro_seconds. + The sleep function delays program execution + for the given number of micro_seconds. + - See also sleep. + See also sleep. + +