begriffs open source - ai-pg/blob - full-docs/man3/SPI_returntuple.3

   1 '\" t
   2 .\"     Title: SPI_returntuple
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "SPI_RETURNTUPLE" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 SPI_returntuple \- prepare to return a tuple as a Datum
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 HeapTupleHeader SPI_returntuple(HeapTuple \fIrow\fR, TupleDesc \fIrowdesc\fR)
  36 .fi
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBSPI_returntuple\fR
  40 makes a copy of a row in the upper executor context, returning it in the form of a row type
  41 Datum\&. The returned pointer need only be converted to
  42 Datum
  43 via
  44 \fBPointerGetDatum\fR
  45 before returning\&.
  46 .PP
  47 This function can only be used while connected to SPI\&. Otherwise, it returns NULL and sets
  48 \fISPI_result\fR
  49 to
  50 SPI_ERROR_UNCONNECTED\&.
  51 .PP
  52 Note that this should be used for functions that are declared to return composite types\&. It is not used for triggers; use
  53 \fBSPI_copytuple\fR
  54 for returning a modified row in a trigger\&.
  55 .SH "ARGUMENTS"
  56 .PP
  57 HeapTuple \fIrow\fR
  58 .RS 4
  59 row to be copied
  60 .RE
  61 .PP
  62 TupleDesc \fIrowdesc\fR
  63 .RS 4
  64 descriptor for row (pass the same descriptor each time for most effective caching)
  65 .RE
  66 .SH "RETURN VALUE"
  67 .PP
  68 HeapTupleHeader
  69 pointing to copied row, or
  70 NULL
  71 on error (see
  72 \fISPI_result\fR
  73 for an error indication)