Home • Explore • Blog • CI
☰



postgresql
32th chunk of `doc/src/sgml/xfunc.sgml`
8d61a58812f3e21f813b9dc93fd4a6795bcf60130dd7d13b0000000100000fac
 directory of the shared library file (for instance the
     <productname>PostgreSQL</productname> tutorial directory, which
     contains the code for the examples used in this section).
     (Better style would be to use just <literal>'funcs'</literal> in the
     <literal>AS</literal> clause, after having added
     <replaceable>DIRECTORY</replaceable> to the search path.  In any
     case, we can omit the system-specific extension for a shared
     library, commonly <literal>.so</literal>.)
    </para>

    <para>
     Notice that we have specified the functions as <quote>strict</quote>,
     meaning that
     the system should automatically assume a null result if any input
     value is null.  By doing this, we avoid having to check for null inputs
     in the function code.  Without this, we'd have to check for null values
     explicitly, using <function>PG_ARGISNULL()</function>.
    </para>

    <para>
     The macro <function>PG_ARGISNULL(<replaceable>n</replaceable>)</function>
     allows a function to test whether each input is null.  (Of course, doing
     this is only necessary in functions not declared <quote>strict</quote>.)
     As with the
     <function>PG_GETARG_<replaceable>xxx</replaceable>()</function> macros,
     the input arguments are counted beginning at zero.  Note that one
     should refrain from executing
     <function>PG_GETARG_<replaceable>xxx</replaceable>()</function> until
     one has verified that the argument isn't null.
     To return a null result, execute <function>PG_RETURN_NULL()</function>;
     this works in both strict and nonstrict functions.
    </para>

    <para>
     At first glance, the version-1 coding conventions might appear
     to be just pointless obscurantism, compared to using
     plain <literal>C</literal> calling conventions.  They do however allow
     us to deal with <literal>NULL</literal>able arguments/return values,
     and <quote>toasted</quote> (compressed or out-of-line) values.
    </para>

    <para>
     Other options provided by the version-1 interface are two
     variants of the
     <function>PG_GETARG_<replaceable>xxx</replaceable>()</function>
     macros. The first of these,
     <function>PG_GETARG_<replaceable>xxx</replaceable>_COPY()</function>,
     guarantees to return a copy of the specified argument that is
     safe for writing into. (The normal macros will sometimes return a
     pointer to a value that is physically stored in a table, which
     must not be written to. Using the
     <function>PG_GETARG_<replaceable>xxx</replaceable>_COPY()</function>
     macros guarantees a writable result.)
    The second variant consists of the
    <function>PG_GETARG_<replaceable>xxx</replaceable>_SLICE()</function>
    macros which take three arguments. The first is the number of the
    function argument (as above). The second and third are the offset and
    length of the segment to be returned. Offsets are counted from
    zero, and a negative length requests that the remainder of the
    value be returned. These macros provide more efficient access to
    parts of large values in the case where they have storage type
    <quote>external</quote>. (The storage type of a column can be specified using
    <literal>ALTER TABLE <replaceable>tablename</replaceable> ALTER
    COLUMN <replaceable>colname</replaceable> SET STORAGE
    <replaceable>storagetype</replaceable></literal>. <replaceable>storagetype</replaceable> is one of
    <literal>plain</literal>, <literal>external</literal>, <literal>extended</literal>,
     or <literal>main</literal>.)
    </para>

    <para>
     Finally, the version-1 function call conventions make it possible
     to return set results (<xref linkend="xfunc-c-return-set"/>) and
     implement trigger functions (<xref linkend="triggers"/>) and
     procedural-language call handlers (<xref
     linkend="plhandler"/>).  For more details
     see <filename>src/backend/utils/fmgr/README</filename> in the
     source distribution.
Title: Handling Nulls, TOASTed Values, and Argument Copying in PostgreSQL C Functions
Summary
This section discusses handling NULL values in PostgreSQL C functions using `PG_ARGISNULL()` and `PG_RETURN_NULL()`. It explains how declaring a function as `STRICT` simplifies null handling. The passage also touches on the version-1 coding conventions and how they enable the system to deal with nullable arguments/return values and "toasted" (compressed or out-of-line) values. Finally, it introduces `PG_GETARG_<xxx>_COPY()` for obtaining writable copies of arguments and `PG_GETARG_<xxx>_SLICE()` for efficient access to parts of large values with external storage types. It mentions set results, trigger functions, and procedural-language call handlers.