[PHP-DEV] CVS update: php3/doc/functions From: cschneid (php-dev <email protected>)
Date: 11/23/98

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 <email protected>
For help: php-dev-help <email protected>