<entry><filename>postgres.h</filename></entry>
        </row>
        <row>
         <entry><type>xid</type></entry>
         <entry><type>TransactionId</type></entry>
         <entry><filename>postgres.h</filename></entry>
        </row>
       </tbody>
      </tgroup>
     </table>

    <para>
     Now that we've gone over all of the possible structures
     for base types, we can show some examples of real functions.
    </para>
   </sect2>

   <sect2 id="xfunc-c-v1-call-conv">
    <title>Version 1 Calling Conventions</title>

    <para>
     The version-1 calling convention relies on macros to suppress most
     of the complexity of passing arguments and results.  The C declaration
     of a version-1 function is always:
<programlisting>
Datum funcname(PG_FUNCTION_ARGS)
</programlisting>
     In addition, the macro call:
<programlisting>
PG_FUNCTION_INFO_V1(funcname);
</programlisting>
     must appear in the same source file.  (Conventionally, it's
     written just before the function itself.)  This macro call is not
     needed for <literal>internal</literal>-language functions, since
     <productname>PostgreSQL</productname> assumes that all internal functions
     use the version-1 convention.  It is, however, required for
     dynamically-loaded functions.
    </para>

    <para>
     In a version-1 function, each actual argument is fetched using a
     <function>PG_GETARG_<replaceable>xxx</replaceable>()</function>
     macro that corresponds to the argument's data type.  (In non-strict
     functions there needs to be a previous check about argument null-ness
     using <function>PG_ARGISNULL()</function>; see below.)
     The result is returned using a
     <function>PG_RETURN_<replaceable>xxx</replaceable>()</function>
     macro for the return type.
     <function>PG_GETARG_<replaceable>xxx</replaceable>()</function>
     takes as its argument the number of the function argument to
     fetch, where the count starts at 0.
     <function>PG_RETURN_<replaceable>xxx</replaceable>()</function>
     takes as its argument the actual value to return.
    </para>

    <para>
     To call another version-1 function, you can use
     <function>DirectFunctionCall<replaceable>n</replaceable>(func,
     arg1, ..., argn)</function>.  This is particularly useful when you want
     to call functions defined in the standard internal library, by using an
     interface similar to their SQL signature.
    </para>

    <para>
     These convenience functions and similar ones can be found
     in <filename>fmgr.h</filename>.
     The <function>DirectFunctionCall<replaceable>n</replaceable></function>
     family expect a C function name as their first argument.  There are also
     <function>OidFunctionCall<replaceable>n</replaceable></function> which
     take the OID of the target function, and some other variants.  All of
     these expect the function's arguments to be supplied
     as <type>Datum</type>s, and likewise they return <type>Datum</type>.
     Note that neither arguments nor result are allowed to be NULL when
     using these convenience functions.
    </para>

    <para>
     For example, to call the <function>starts_with(text, text)</function>
     function from C, you can search through the catalog and find out that
     its C implementation is the
     <function>Datum text_starts_with(PG_FUNCTION_ARGS)</function>
     function.  Typically you would
     use <literal>DirectFunctionCall2(text_starts_with, ...)</literal> to
     call such a function.  However, <function>starts_with(text,
     text)</function> requires collation information, so it will fail
     with <quote>could not determine which collation to use for string
     comparison</quote> if called that way.  Instead you must
     use <literal>DirectFunctionCall2Coll(text_starts_with, ...)</literal>
     and provide the desired collation, which typically is just passed
     through from <function>PG_GET_COLLATION()</function>, as shown in the