overloaded functions must be different from the C names of all
    other functions, either internal or dynamically loaded.  If this
    rule is violated, the behavior is not portable.  You might get a
    run-time linker error, or one of the functions will get called
    (usually the internal one).  The alternative form of the
    <literal>AS</literal> clause for the SQL <command>CREATE
    FUNCTION</command> command decouples the SQL function name from
    the function name in the C source code.  For instance:
<programlisting>
CREATE FUNCTION test(int) RETURNS int
    AS '<replaceable>filename</replaceable>', 'test_1arg'
    LANGUAGE C;
CREATE FUNCTION test(int, int) RETURNS int
    AS '<replaceable>filename</replaceable>', 'test_2arg'
    LANGUAGE C;
</programlisting>
    The names of the C functions here reflect one of many possible conventions.
   </para>
  </sect1>

  <sect1 id="xfunc-volatility">
   <title>Function Volatility Categories</title>

   <indexterm zone="xfunc-volatility">
    <primary>volatility</primary>
    <secondary>functions</secondary>
   </indexterm>
   <indexterm zone="xfunc-volatility">
    <primary>VOLATILE</primary>
   </indexterm>
   <indexterm zone="xfunc-volatility">
    <primary>STABLE</primary>
   </indexterm>
   <indexterm zone="xfunc-volatility">
    <primary>IMMUTABLE</primary>
   </indexterm>

   <para>
    Every function has a <firstterm>volatility</firstterm> classification, with
    the possibilities being <literal>VOLATILE</literal>, <literal>STABLE</literal>, or
    <literal>IMMUTABLE</literal>.  <literal>VOLATILE</literal> is the default if the
    <link linkend="sql-createfunction"><command>CREATE FUNCTION</command></link>
    command does not specify a category.  The volatility category is a
    promise to the optimizer about the behavior of the function:

   <itemizedlist>
    <listitem>
     <para>
      A <literal>VOLATILE</literal> function can do anything, including modifying
      the database.  It can return different results on successive calls with
      the same arguments.  The optimizer makes no assumptions about the
      behavior of such functions.  A query using a volatile function will
      re-evaluate the function at every row where its value is needed.
     </para>
    </listitem>
    <listitem>
     <para>
      A <literal>STABLE</literal> function cannot modify the database and is
      guaranteed to return the same results given the same arguments
      for all rows within a single statement. This category allows the
      optimizer to optimize multiple calls of the function to a single
      call. In particular, it is safe to use an expression containing
      such a function in an index scan condition. (Since an index scan
      will evaluate the comparison value only once, not once at each
      row, it is not valid to use a <literal>VOLATILE</literal> function in an
      index scan condition.)
     </para>
    </listitem>
    <listitem>
     <para>
      An <literal>IMMUTABLE</literal> function cannot modify the database and is
      guaranteed to return the same results given the same arguments forever.
      This category allows the optimizer to pre-evaluate the function when
      a query calls it with constant arguments.  For example, a query like
      <literal>SELECT ... WHERE x = 2 + 2</literal> can be simplified on sight to
      <literal>SELECT ... WHERE x = 4</literal>, because the function underlying
      the integer addition operator is marked <literal>IMMUTABLE</literal>.
     </para>
    </listitem>
   </itemizedlist>
   </para>

   <para>
    For best optimization results, you should label your functions with the
    strictest volatility category that is valid for them.
   </para>

   <para>
    Any function with side-effects <emphasis>must</emphasis> be labeled
    <literal>VOLATILE</literal>, so that calls to it cannot be optimized away.
    Even a function with no side-effects needs to be labeled
    <literal>VOLATILE</literal> if its value