glob.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.glob" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
 <refnamediv>
  <refname>glob</refname>
  <refpurpose>Find pathnames matching a pattern</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>glob</methodname>
   <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   The <function>glob</function> function searches for all the pathnames
   matching <parameter>pattern</parameter> according to the rules used by
   the libc glob() function, which is similar to the rules used by common
   shells.
  </para>
  <simpara>
   The behavior on Unix systems and macOS is determined by the system's
   implementation of glob(). On Windows, an implementation that conforms
   to the POSIX 1003.2 definition for glob() is used, and it includes
   an extension to handle the <literal>[!...]</literal> convention for
   negating a range.
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>pattern</parameter></term>
     <listitem>
      <para>
       The pattern. No tilde expansion or parameter substitution is done.
      </para>
      <para>
       Special characters:
       <itemizedlist>
        <listitem>
         <simpara>
          <literal>*</literal> - Matches zero or more characters.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <literal>?</literal> - Matches exactly one character (any character).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <literal>[...]</literal> - Matches one character from a group of
          characters. If the first character is <literal>!</literal>,
          matches any character not in the group.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <literal>{a,b,c}</literal> - Matches one string from a group of
          strings delimited by a comma when the <constant>GLOB_BRACE</constant>
          flag is used.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <literal>\</literal> - Escapes the following character,
          except when the <constant>GLOB_NOESCAPE</constant> flag is used.
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Any of the <constant>GLOB_<replaceable>*</replaceable></constant> constants.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an array containing the matched files/directories, an empty array
   if no file matched or &false; on error.
   Unless <literal>GLOB_NOSORT</literal> was used, the names will
   be sorted alphanumerically.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Convenient way how <function>glob</function> can replace
     <function>opendir</function> and friends.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
foreach (glob("*.txt") as $filename) {
    echo "$filename size " . filesize($filename) . "\n";
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
funclist.txt size 44686
funcsummary.txt size 267625
quickref.txt size 137820
]]>
    </screen>
   </example>
   <example>
    <title>
     Example with a more complex pattern
    </title>
    <programlisting role="php">
<![CDATA[
<?php
foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
    echo "$filename\n";
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
path/docs/mailinglist-rules.md
path/docs/README.md
path/docs/release-process.md
path/pear/install-pear.txt
path/Zend/README.md
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.no-remote;
  <note>
   <simpara>
    This function isn't available on some systems (e.g. old Sun OS).
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>opendir</function></member>
    <member><function>readdir</function></member>
    <member><function>closedir</function></member>
    <member><function>fnmatch</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
-->