CVS update: php3/doc/functions

Date: Monday November 23, 1998 @ 13:13 Author: cschneid Update of /repository/php3/doc/functions In directory asf:/u2/tmp/cvs-serv3598/doc/functions Modified Files: misc.sgml Log Message: Functions pack() and unpack() rewritten to be binary and buffer overrun safe and behave like the Perl functions for all implemented format codes. Index: php3/doc/functions/misc.sgml diff -c php3/doc/functions/misc.sgml:1.12 php3/doc/functions/misc.sgml:1.13 *** php3/doc/functions/misc.sgml:1.12 Sat Nov 21 18:08:01 1998 --- php3/doc/functions/misc.sgml Mon Nov 23 13:13:07 1998 *************** *** 120,125 **** --- 120,207 ---- </refsect1> </refentry> + <refentry id="function.pack"> + <refnamediv> + <refname>pack</refname> + <refpurpose>pack data into binary string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcdef>string <function>pack</function></funcdef> + <paramdef>string <parameter>format</parameter></paramdef> + <paramdef>mixed <parameter><optional>args</optional></parameter>...</paramdef> + </funcsynopsis> + <para> + Pack given arguments into binary string according to + <parameter>format</parameter>. Returns binary string containing data. + + <para> + The idea to this function was taken from Perl and all formatting + codes work the same as there. 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 + <itemizedlist> + <listitem><simpara>a NUL-padded string</simpara></listitem> + <listitem><simpara>A SPACE-padded string</simpara></listitem> + <listitem><simpara>h Hex string, low nibble first</simpara></listitem> + <listitem><simpara>H Hex string, high nibble first</simpara></listitem> + <listitem><simpara>c signed char</simpara></listitem> + <listitem><simpara>C unsigned char</simpara></listitem> + <listitem><simpara>s signed short (always 16 bit, machine byte order)</simpara></listitem> + <listitem><simpara>S unsigned short (always 16 bit, machine byte order)</simpara></listitem> + <listitem><simpara>n unsigned short (always 16 bit, big endian + byte order)</simpara></listitem> + <listitem><simpara>v unsigned short (always 16 bit, little + endian byte order)</simpara></listitem> + <listitem><simpara>i signed integer (machine dependant size and + byte order)</simpara></listitem> + <listitem><simpara>I unsigned integer (machine dependant size + and byte order)</simpara></listitem> + <listitem><simpara>l signed long (always 32 bit, machine byte order)</simpara></listitem> + <listitem><simpara>L unsigned long (always 32 bit, machine byte order)</simpara></listitem> + <listitem><simpara>N unsigned long (always 32 bit, big endian + byte order)</simpara></listitem> + <listitem><simpara>V unsigned long (always 32 bit, little endian + byte order)</simpara></listitem> + <listitem><simpara>f float (machine dependent size and representation)</simpara></listitem> + <listitem><simpara>d double (machine dependent size and representation)</simpara></listitem> + <listitem><simpara>x NUL byte</simpara></listitem> + <listitem><simpara>X Back up one byte</simpara></listitem> + <listitem><simpara>@ NUL-fill to absolute position</simpara></listitem> + </itemizedlist> + + <example> + <title>pack format string</title> + <programlisting role=php> + $binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66); + </programlisting> + <para> + The resulting binary string will be 6 bytes long and contain + the byte sequence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42. + </example> + + <para> + Note that the distinction between signed and unsigned values only + affects the function <function>unpack</function>, where as + function <function>pack</function> gives the same result for + signed and unsigned format codes. + + <para> + 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. + + </refsect1> + </refentry> + <refentry id="function.register-shutdown-function"> <refnamediv> <refname>register_shutdown_function</refname> *************** *** 202,207 **** --- 284,334 ---- of <parameter>seconds</parameter>. <simpara> See also <function>usleep</function>. + </refsect1> + </refentry> + + <refentry id="function.unpack"> + <refnamediv> + <refname>unpack</refname> + <refpurpose>unpack data from binary string</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcdef>array <function>unpack</function></funcdef> + <paramdef>string <parameter>format</parameter></paramdef> + <paramdef>string <parameter>data</parameter></paramdef> + </funcsynopsis> + <para> + Unpack from binary string into array according to + <parameter>format</parameter>. Returns array containing unpacked + elements of binary string. + + <para> + 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 /. + + <example> + <title>unpack format string</title> + <programlisting role=php> + $array = unpack("c2chars/nint", $binarydata); + </programlisting> + <para> + The resulting array will contain the entries "chars1", + "chars2" and "int". + </example> + + <para> + For an explanation of the format codes see also: + <function>pack</function> + + <para> + 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. + </refsect1> </refentry> -- 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