<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.ob-get-status" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>ob_get_status</refname>
  <refpurpose>Get status of output buffers</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>ob_get_status</methodname>
   <methodparam choice="opt"><type>bool</type><parameter>full_status</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>ob_get_status</function> returns status information on either
   the top level output buffer or all active output buffer levels if
   <parameter>full_status</parameter> is set to &true;.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>full_status</parameter></term>
     <listitem>
      <para>
       &true; to return all active output buffer levels. If &false; or not
       set, only the top level output buffer is returned.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   If <parameter>full_status</parameter> is omitted or &false; a simple array
   holding status information on the active output level is returned.
  </para>
  <para>
   If <parameter>full_status</parameter> is &true; an array
   with one element for each active output buffer level is returned.
   The output level is used as key of the top level array and each array
   element itself is another array holding status information
   on one active output level.
  </para>
  <para>
   An empty array is returned if output buffering is not turned on.
  </para>
  <para>
   <segmentedlist>
    <title><function>ob_get_status</function> return array elements</title>
    <segtitle>Key</segtitle><segtitle>Value</segtitle>
    <seglistitem>
     <seg>name</seg>
     <seg>
      Name of active output handler (see the return values of
      <function>ob_list_handlers</function> for details)
     </seg>
    </seglistitem>
    <seglistitem>
     <seg>type</seg>
     <seg>
      <literal>0</literal> (internal handler) or
      <literal>1</literal> (user supplied handler)
     </seg>
    </seglistitem>
    <seglistitem>
     <seg>flags</seg>
     <seg>
      Bitmask of flags set by <function>ob_start</function>,
      the type of output handler (see above)
      and the status of the buffering process
      (<link linkend="outcontrol.constants.flags-returned-by-handler">
       <constant>PHP_OUTPUT_HANDLER_<replaceable>*</replaceable></constant>
      </link> constants).
      If the handler successfully processed the buffer and did not return &false;,
      <constant>PHP_OUTPUT_HANDLER_STARTED</constant> and
      <constant>PHP_OUTPUT_HANDLER_PROCESSED</constant> will be set.
      If the handler failed while processing the buffer or returned &false;,
      <constant>PHP_OUTPUT_HANDLER_STARTED</constant> and
      <constant>PHP_OUTPUT_HANDLER_DISABLED</constant> will be set.
     </seg>
    </seglistitem>
    <seglistitem>
     <seg>level</seg>
     <seg>
      Output nesting level (zero based). Note that the value returned for the
      same level by <function>ob_get_level</function> is off by one.
      The first level is <literal>0</literal> for <function>ob_get_status</function>,
      and <literal>1</literal> for <function>ob_get_level</function>.
     </seg>
    </seglistitem>
    <seglistitem>
     <seg>chunk_size</seg>
     <seg>
      Chunk size in bytes. Set by <function>ob_start</function>
      or <link linkend="ini.output-buffering">output_buffering</link> is enabled
      and its value is set to a positive integer
     </seg>
    </seglistitem>
    <seglistitem>
     <seg>buffer_size</seg>
     <seg>
      Output buffer size in bytes
     </seg>
    </seglistitem>
    <seglistitem>
     <seg>buffer_used</seg>
     <seg>
      Size of data in output buffer in bytes
      (the same as the integer return value of <function>ob_get_length</function>)
     </seg>
    </seglistitem>
   </segmentedlist>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Array returned when <parameter>full_status</parameter> is &false;</title>
    <screen>
<![CDATA[
Array
(
    [name] => URL-Rewriter
    [type] => 0
    [flags] => 112
    [level] => 2
    [chunk_size] => 0
    [buffer_size] => 16384
    [buffer_used] => 1024
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Array returned when <parameter>full_status</parameter> is &true;</title>
    <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [name] => default output handler
            [type] => 0
            [flags] => 112
            [level] => 1
            [chunk_size] => 0
            [buffer_size] => 16384
            [buffer_used] => 2048
        )

    [1] => Array
        (
            [name] => URL-Rewriter
            [type] => 0
            [flags] => 112
            [level] => 2
            [chunk_size] => 0
            [buffer_size] => 16384
            [buffer_used] => 1024
        )

)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>ob_get_level</function></member>
    <member><function>ob_list_handlers</function></member>
    <member><function>ob_get_length</function></member>
    <member><function>ob_start</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
