Home • Explore • Blog • CI
☰



postgresql
41th chunk of `doc/src/sgml/spi.sgml`
94e25546dcba321ca30111f5186678ace29c532f9cfc6cc20000000100000fa3
 <function>SPI_getnspname</function> returns a copy of the name of
   the namespace that the specified <structname>Relation</structname>
   belongs to. This is equivalent to the relation's schema. You should
   <function>pfree</function> the return value of this function when
   you are finished with it.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Relation <parameter>rel</parameter></literal></term>
    <listitem>
     <para>
      input relation
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   The name of the specified relation's namespace.
  </para>
 </refsect1>
</refentry>

<refentry id="spi-spi-result-code-string">
 <indexterm><primary>SPI_result_code_string</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_result_code_string</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_result_code_string</refname>
  <refpurpose>return error code as string</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
const char * SPI_result_code_string(int <parameter>code</parameter>);
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_result_code_string</function> returns a string representation
   of the result code returned by various SPI functions or stored
   in <varname>SPI_result</varname>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>int <parameter>code</parameter></literal></term>
    <listitem>
     <para>
      result code
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   A string representation of the result code.
  </para>
 </refsect1>
</refentry>

 </sect1>

 <sect1 id="spi-memory">
  <title>Memory Management</title>

  <para>
    <indexterm>
     <primary>memory context</primary>
     <secondary>in SPI</secondary>
    </indexterm>
   <productname>PostgreSQL</productname> allocates memory within
   <firstterm>memory contexts</firstterm>, which provide a convenient method of
   managing allocations made in many different places that need to
   live for differing amounts of time.  Destroying a context releases
   all the memory that was allocated in it.  Thus, it is not necessary
   to keep track of individual objects to avoid memory leaks; instead
   only a relatively small number of contexts have to be managed.
   <function>palloc</function> and related functions allocate memory
   from the <quote>current</quote> context.
  </para>

  <para>
   <function>SPI_connect</function> creates a new memory context and
   makes it current.  <function>SPI_finish</function> restores the
   previous current memory context and destroys the context created by
   <function>SPI_connect</function>.  These actions ensure that
   transient memory allocations made inside your C function are
   reclaimed at C function exit, avoiding memory leakage.
  </para>

  <para>
   However, if your C function needs to return an object in allocated
   memory (such as a value of a pass-by-reference data type), you
   cannot allocate that memory using <function>palloc</function>, at
   least not while you are connected to SPI.  If you try, the object
   will be deallocated by <function>SPI_finish</function>, and your
   C function will not work reliably.  To solve this problem, use
   <function>SPI_palloc</function> to allocate memory for your return
   object.  <function>SPI_palloc</function> allocates memory in the
   <quote>upper executor context</quote>, that is, the memory context
   that was current when <function>SPI_connect</function> was called,
   which is precisely the right context for a value returned from your
   C function.  Several of the other utility functions described in
   this section also return objects created in the upper executor context.
Title: SPI_result_code_string Function and Memory Management in SPI
Summary
This section describes the `SPI_result_code_string` function, which converts an SPI result code to a human-readable string, and discusses memory management within SPI. SPI functions manage memory using memory contexts. `SPI_connect` creates a new memory context, while `SPI_finish` destroys it and restores the previous context. To return allocated memory from a C function, `SPI_palloc` should be used to allocate memory in the 'upper executor context' to avoid premature deallocation by `SPI_finish`.