APIs must therefore be re-compiled for
each major release. The inclusion of <literal>PG_MODULE_MAGIC</literal>
(see <xref linkend="xfunc-c-dynload"/>) ensures that code compiled for
one major version will be rejected by other major versions.
</para>
</sect4>
<sect4 id="xfunc-guidance-abi-mninor-versions">
<title>Minor Versions</title>
<para>
<productname>PostgreSQL</productname> makes an effort to avoid server
ABI breaks in minor releases. In general, an extension compiled against
any minor release should work with any other minor release of the same
major version, past or future.
</para>
<para>
When a change <emphasis>is</emphasis> required,
<productname>PostgreSQL</productname> will choose the least invasive
change possible, for example by squeezing a new field into padding
space or appending it to the end of a struct. These sorts of changes
should not impact extensions unless they use very unusual code
patterns.
</para>
<para>
In rare cases, however, even such non-invasive changes may be
impractical or impossible. In such an event, the change will be
carefully managed, taking the requirements of extensions into account.
Such changes will also be documented in the release notes (<xref
linkend="release"/>).
</para>
<para>
Note, however, that many parts of the server are not designed or
maintained as publicly-consumable APIs (and that, in most cases, the
actual boundary is also not well-defined). If urgent needs arise,
changes in those parts will naturally be made with less consideration
for extension code than changes in well-defined and widely used
interfaces.
</para>
<para>
Also, in the absence of automated detection of such changes, this is
not a guarantee, but historically such breaking changes have been
extremely rare.
</para>
</sect4>
</sect3>
</sect2>
<sect2 id="xfunc-c-composite-type-args">
<title>Composite-Type Arguments</title>
<para>
Composite types do not have a fixed layout like C structures.
Instances of a composite type can contain null fields. In
addition, composite types that are part of an inheritance
hierarchy can have different fields than other members of the
same inheritance hierarchy. Therefore,
<productname>PostgreSQL</productname> provides a function
interface for accessing fields of composite types from C.
</para>
<para>
Suppose we want to write a function to answer the query:
<programlisting>
SELECT name, c_overpaid(emp, 1500) AS overpaid
FROM emp
WHERE name = 'Bill' OR name = 'Sam';
</programlisting>
Using the version-1 calling conventions, we can define
<function>c_overpaid</function> as:
<programlisting><![CDATA[
#include "postgres.h"
#include "executor/executor.h" /* for GetAttributeByName() */
PG_MODULE_MAGIC;
PG_FUNCTION_INFO_V1(c_overpaid);
Datum
c_overpaid(PG_FUNCTION_ARGS)
{
HeapTupleHeader t = PG_GETARG_HEAPTUPLEHEADER(0);
int32 limit = PG_GETARG_INT32(1);
bool isnull;
Datum salary;
salary = GetAttributeByName(t, "salary", &isnull);
if (isnull)
PG_RETURN_BOOL(false);
/* Alternatively, we might prefer to do PG_RETURN_NULL() for null salary. */
PG_RETURN_BOOL(DatumGetInt32(salary) > limit);
}
]]>
</programlisting>
</para>
<para>
<function>GetAttributeByName</function> is the
<productname>PostgreSQL</productname> system function that
returns attributes out of the specified row. It has
three arguments: the argument of type <type>HeapTupleHeader</type> passed
into
the function, the name of the desired attribute, and a
return parameter that tells whether the attribute
is null. <function>GetAttributeByName</function> returns