/usr/include/postgresql/9.3/server/funcapi.h is in postgresql-server-dev-9.3 9.3.4-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 | /*-------------------------------------------------------------------------
*
* funcapi.h
* Definitions for functions which return composite type and/or sets
*
* This file must be included by all Postgres modules that either define
* or call FUNCAPI-callable functions or macros.
*
*
* Copyright (c) 2002-2013, PostgreSQL Global Development Group
*
* src/include/funcapi.h
*
*-------------------------------------------------------------------------
*/
#ifndef FUNCAPI_H
#define FUNCAPI_H
#include "fmgr.h"
#include "access/tupdesc.h"
#include "executor/executor.h"
#include "executor/tuptable.h"
/*-------------------------------------------------------------------------
* Support to ease writing Functions returning composite types
*-------------------------------------------------------------------------
*
* This struct holds arrays of individual attribute information
* needed to create a tuple from raw C strings. It also requires
* a copy of the TupleDesc. The information carried here
* is derived from the TupleDesc, but it is stored here to
* avoid redundant cpu cycles on each call to an SRF.
*/
typedef struct AttInMetadata
{
/* full TupleDesc */
TupleDesc tupdesc;
/* array of attribute type input function finfo */
FmgrInfo *attinfuncs;
/* array of attribute type i/o parameter OIDs */
Oid *attioparams;
/* array of attribute typmod */
int32 *atttypmods;
} AttInMetadata;
/*-------------------------------------------------------------------------
* Support struct to ease writing Set Returning Functions (SRFs)
*-------------------------------------------------------------------------
*
* This struct holds function context for Set Returning Functions.
* Use fn_extra to hold a pointer to it across calls
*/
typedef struct FuncCallContext
{
/*
* Number of times we've been called before
*
* call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
* incremented for you every time SRF_RETURN_NEXT() is called.
*/
uint32 call_cntr;
/*
* OPTIONAL maximum number of calls
*
* max_calls is here for convenience only and setting it is optional. If
* not set, you must provide alternative means to know when the function
* is done.
*/
uint32 max_calls;
/*
* OPTIONAL pointer to result slot
*
* This is obsolete and only present for backwards compatibility, viz,
* user-defined SRFs that use the deprecated TupleDescGetSlot().
*/
TupleTableSlot *slot;
/*
* OPTIONAL pointer to miscellaneous user-provided context information
*
* user_fctx is for use as a pointer to your own struct to retain
* arbitrary context information between calls of your function.
*/
void *user_fctx;
/*
* OPTIONAL pointer to struct containing attribute type input metadata
*
* attinmeta is for use when returning tuples (i.e. composite data types)
* and is not used when returning base data types. It is only needed if
* you intend to use BuildTupleFromCStrings() to create the return tuple.
*/
AttInMetadata *attinmeta;
/*
* memory context used for structures that must live for multiple calls
*
* multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
* by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
* context for any memory that is to be reused across multiple calls of
* the SRF.
*/
MemoryContext multi_call_memory_ctx;
/*
* OPTIONAL pointer to struct containing tuple description
*
* tuple_desc is for use when returning tuples (i.e. composite data types)
* and is only needed if you are going to build the tuples with
* heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
* the TupleDesc pointer stored here should usually have been run through
* BlessTupleDesc() first.
*/
TupleDesc tuple_desc;
} FuncCallContext;
/*----------
* Support to ease writing functions returning composite types
*
* External declarations:
* get_call_result_type:
* Given a function's call info record, determine the kind of datatype
* it is supposed to return. If resultTypeId isn't NULL, *resultTypeId
* receives the actual datatype OID (this is mainly useful for scalar
* result types). If resultTupleDesc isn't NULL, *resultTupleDesc
* receives a pointer to a TupleDesc when the result is of a composite
* type, or NULL when it's a scalar result or the rowtype could not be
* determined. NB: the tupledesc should be copied if it is to be
* accessed over a long period.
* get_expr_result_type:
* Given an expression node, return the same info as for
* get_call_result_type. Note: the cases in which rowtypes cannot be
* determined are different from the cases for get_call_result_type.
* get_func_result_type:
* Given only a function's OID, return the same info as for
* get_call_result_type. Note: the cases in which rowtypes cannot be
* determined are different from the cases for get_call_result_type.
* Do *not* use this if you can use one of the others.
*----------
*/
/* Type categories for get_call_result_type and siblings */
typedef enum TypeFuncClass
{
TYPEFUNC_SCALAR, /* scalar result type */
TYPEFUNC_COMPOSITE, /* determinable rowtype result */
TYPEFUNC_RECORD, /* indeterminate rowtype result */
TYPEFUNC_OTHER /* bogus type, eg pseudotype */
} TypeFuncClass;
extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
Oid *resultTypeId,
TupleDesc *resultTupleDesc);
extern TypeFuncClass get_expr_result_type(Node *expr,
Oid *resultTypeId,
TupleDesc *resultTupleDesc);
extern TypeFuncClass get_func_result_type(Oid functionId,
Oid *resultTypeId,
TupleDesc *resultTupleDesc);
extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
char *argmodes,
Node *call_expr);
extern int get_func_arg_info(HeapTuple procTup,
Oid **p_argtypes, char ***p_argnames,
char **p_argmodes);
extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes,
char ***arg_names);
extern char *get_func_result_name(Oid functionId);
extern TupleDesc build_function_result_tupdesc_d(Datum proallargtypes,
Datum proargmodes,
Datum proargnames);
extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple);
/*----------
* Support to ease writing functions returning composite types
*
* External declarations:
* TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
* descriptor so that it can be used to return properly labeled tuples.
* You need to call this if you are going to use heap_form_tuple directly.
* TupleDescGetAttInMetadata does it for you, however, so no need to call
* it if you call TupleDescGetAttInMetadata.
* AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
* AttInMetadata struct based on the given TupleDesc. AttInMetadata can
* be used in conjunction with C strings to produce a properly formed
* tuple.
* HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
* build a HeapTuple given user data in C string form. values is an array
* of C strings, one for each attribute of the return tuple.
*
* Macro declarations:
* HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
*
* Obsolete routines and macros:
* TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
* TupleDesc based on a named relation.
* TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
* TupleDesc based on a type OID.
* TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Builds a
* TupleTableSlot, which is not needed anymore.
* TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
* given a tuple and a slot.
*----------
*/
#define HeapTupleGetDatum(_tuple) PointerGetDatum((_tuple)->t_data)
/* obsolete version of above */
#define TupleGetDatum(_slot, _tuple) PointerGetDatum((_tuple)->t_data)
extern TupleDesc RelationNameGetTupleDesc(const char *relname);
extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
/* from execTuples.c */
extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);
extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
extern TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc);
/*----------
* Support for Set Returning Functions (SRFs)
*
* The basic API for SRFs looks something like:
*
* Datum
* my_Set_Returning_Function(PG_FUNCTION_ARGS)
* {
* FuncCallContext *funcctx;
* Datum result;
* MemoryContext oldcontext;
* <user defined declarations>
*
* if (SRF_IS_FIRSTCALL())
* {
* funcctx = SRF_FIRSTCALL_INIT();
* // switch context when allocating stuff to be used in later calls
* oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
* <user defined code>
* <if returning composite>
* <build TupleDesc, and perhaps AttInMetaData>
* <endif returning composite>
* <user defined code>
* // return to original context when allocating transient memory
* MemoryContextSwitchTo(oldcontext);
* }
* <user defined code>
* funcctx = SRF_PERCALL_SETUP();
* <user defined code>
*
* if (funcctx->call_cntr < funcctx->max_calls)
* {
* <user defined code>
* <obtain result Datum>
* SRF_RETURN_NEXT(funcctx, result);
* }
* else
* SRF_RETURN_DONE(funcctx);
* }
*
*----------
*/
/* from funcapi.c */
extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);
extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS);
extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
#define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
#define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
#define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
#define SRF_RETURN_NEXT(_funcctx, _result) \
do { \
ReturnSetInfo *rsi; \
(_funcctx)->call_cntr++; \
rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
rsi->isDone = ExprMultipleResult; \
PG_RETURN_DATUM(_result); \
} while (0)
#define SRF_RETURN_DONE(_funcctx) \
do { \
ReturnSetInfo *rsi; \
end_MultiFuncCall(fcinfo, _funcctx); \
rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
rsi->isDone = ExprEndResult; \
PG_RETURN_NULL(); \
} while (0)
#endif /* FUNCAPI_H */
|