1 /*-------------------------------------------------------------------------
4 * Definitions for the Postgres function manager and function-call
7 * This file must be included by all Postgres modules that either define
8 * or call fmgr-callable functions.
11 * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
12 * Portions Copyright (c) 1994, Regents of the University of California
14 * $Id: fmgr.h,v 1.28 2003/06/24 23:14:46 momjian Exp $
16 *-------------------------------------------------------------------------
21 #include "nodes/nodes.h"
24 * All functions that can be called directly by fmgr must have this signature.
25 * (Other functions can be called by using a handler that does have this
29 typedef struct FunctionCallInfoData *FunctionCallInfo;
31 typedef Datum (*PGFunction) (FunctionCallInfo fcinfo);
34 * This struct holds the system-catalog information that must be looked up
35 * before a function can be called through fmgr. If the same function is
36 * to be called multiple times, the lookup need be done only once and the
37 * info struct saved for re-use.
39 typedef struct FmgrInfo
41 PGFunction fn_addr; /* pointer to function or handler to be
43 Oid fn_oid; /* OID of function (NOT of handler, if
45 short fn_nargs; /* 0..FUNC_MAX_ARGS, or -1 if variable arg
47 bool fn_strict; /* function is "strict" (NULL in => NULL
49 bool fn_retset; /* function returns a set */
50 void *fn_extra; /* extra space for use by handler */
51 MemoryContext fn_mcxt; /* memory context to store fn_extra in */
52 struct Node *fn_expr; /* expression parse tree for call, or NULL */
56 * This struct is the data actually passed to an fmgr-called function.
58 typedef struct FunctionCallInfoData
60 FmgrInfo *flinfo; /* ptr to lookup info used for this call */
61 struct Node *context; /* pass info about context of call */
62 struct Node *resultinfo; /* pass or return extra info about result */
63 bool isnull; /* function must set true if result is
65 short nargs; /* # arguments actually passed */
66 Datum arg[FUNC_MAX_ARGS]; /* Arguments passed to function */
67 bool argnull[FUNC_MAX_ARGS]; /* T if arg[i] is actually NULL */
68 } FunctionCallInfoData;
71 * This routine fills a FmgrInfo struct, given the OID
72 * of the function to be called.
74 extern void fmgr_info(Oid functionId, FmgrInfo *finfo);
77 * Same, when the FmgrInfo struct is in a memory context longer-lived than
78 * CurrentMemoryContext. The specified context will be set as fn_mcxt
79 * and used to hold all subsidiary data of finfo.
81 extern void fmgr_info_cxt(Oid functionId, FmgrInfo *finfo,
85 * Copy an FmgrInfo struct
87 extern void fmgr_info_copy(FmgrInfo *dstinfo, FmgrInfo *srcinfo,
88 MemoryContext destcxt);
91 * This macro invokes a function given a filled-in FunctionCallInfoData
92 * struct. The macro result is the returned Datum --- but note that
93 * caller must still check fcinfo->isnull! Also, if function is strict,
94 * it is caller's responsibility to verify that no null arguments are present
97 #define FunctionCallInvoke(fcinfo) ((* (fcinfo)->flinfo->fn_addr) (fcinfo))
100 /*-------------------------------------------------------------------------
101 * Support macros to ease writing fmgr-compatible functions
103 * A C-coded fmgr-compatible function should be declared as
106 * function_name(PG_FUNCTION_ARGS)
111 * It should access its arguments using appropriate PG_GETARG_xxx macros
112 * and should return its result using PG_RETURN_xxx.
114 *-------------------------------------------------------------------------
117 /* Standard parameter list for fmgr-compatible functions */
118 #define PG_FUNCTION_ARGS FunctionCallInfo fcinfo
121 * Get number of arguments passed to function.
123 #define PG_NARGS() (fcinfo->nargs)
126 * If function is not marked "proisstrict" in pg_proc, it must check for
127 * null arguments using this macro. Do not try to GETARG a null argument!
129 #define PG_ARGISNULL(n) (fcinfo->argnull[n])
132 * Support for fetching detoasted copies of toastable datatypes (all of
133 * which are varlena types). pg_detoast_datum() gives you either the input
134 * datum (if not toasted) or a detoasted copy allocated with palloc().
135 * pg_detoast_datum_copy() always gives you a palloc'd copy --- use it
136 * if you need a modifiable copy of the input. Caller is expected to have
137 * checked for null inputs first, if necessary.
139 * Note: it'd be nice if these could be macros, but I see no way to do that
140 * without evaluating the arguments multiple times, which is NOT acceptable.
142 extern struct varlena *pg_detoast_datum(struct varlena * datum);
143 extern struct varlena *pg_detoast_datum_copy(struct varlena * datum);
144 extern struct varlena *pg_detoast_datum_slice(struct varlena * datum,
145 int32 first, int32 count);
147 #define PG_DETOAST_DATUM(datum) \
148 pg_detoast_datum((struct varlena *) DatumGetPointer(datum))
149 #define PG_DETOAST_DATUM_COPY(datum) \
150 pg_detoast_datum_copy((struct varlena *) DatumGetPointer(datum))
151 #define PG_DETOAST_DATUM_SLICE(datum,f,c) \
152 pg_detoast_datum_slice((struct varlena *) DatumGetPointer(datum), \
153 (int32) f, (int32) c)
156 * Support for cleaning up detoasted copies of inputs. This must only
157 * be used for pass-by-ref datatypes, and normally would only be used
158 * for toastable types. If the given pointer is different from the
159 * original argument, assume it's a palloc'd detoasted copy, and pfree it.
160 * NOTE: most functions on toastable types do not have to worry about this,
161 * but we currently require that support functions for indexes not leak
164 #define PG_FREE_IF_COPY(ptr,n) \
166 if ((Pointer) (ptr) != PG_GETARG_POINTER(n)) \
170 /* Macros for fetching arguments of standard types */
172 #define PG_GETARG_DATUM(n) (fcinfo->arg[n])
173 #define PG_GETARG_INT32(n) DatumGetInt32(PG_GETARG_DATUM(n))
174 #define PG_GETARG_UINT32(n) DatumGetUInt32(PG_GETARG_DATUM(n))
175 #define PG_GETARG_INT16(n) DatumGetInt16(PG_GETARG_DATUM(n))
176 #define PG_GETARG_UINT16(n) DatumGetUInt16(PG_GETARG_DATUM(n))
177 #define PG_GETARG_CHAR(n) DatumGetChar(PG_GETARG_DATUM(n))
178 #define PG_GETARG_BOOL(n) DatumGetBool(PG_GETARG_DATUM(n))
179 #define PG_GETARG_OID(n) DatumGetObjectId(PG_GETARG_DATUM(n))
180 #define PG_GETARG_POINTER(n) DatumGetPointer(PG_GETARG_DATUM(n))
181 #define PG_GETARG_CSTRING(n) DatumGetCString(PG_GETARG_DATUM(n))
182 #define PG_GETARG_NAME(n) DatumGetName(PG_GETARG_DATUM(n))
183 /* these macros hide the pass-by-reference-ness of the datatype: */
184 #define PG_GETARG_FLOAT4(n) DatumGetFloat4(PG_GETARG_DATUM(n))
185 #define PG_GETARG_FLOAT8(n) DatumGetFloat8(PG_GETARG_DATUM(n))
186 #define PG_GETARG_INT64(n) DatumGetInt64(PG_GETARG_DATUM(n))
187 /* use this if you want the raw, possibly-toasted input datum: */
188 #define PG_GETARG_RAW_VARLENA_P(n) ((struct varlena *) PG_GETARG_POINTER(n))
189 /* use this if you want the input datum de-toasted: */
190 #define PG_GETARG_VARLENA_P(n) PG_DETOAST_DATUM(PG_GETARG_DATUM(n))
191 /* DatumGetFoo macros for varlena types will typically look like this: */
192 #define DatumGetByteaP(X) ((bytea *) PG_DETOAST_DATUM(X))
193 #define DatumGetTextP(X) ((text *) PG_DETOAST_DATUM(X))
194 #define DatumGetBpCharP(X) ((BpChar *) PG_DETOAST_DATUM(X))
195 #define DatumGetVarCharP(X) ((VarChar *) PG_DETOAST_DATUM(X))
196 /* And we also offer variants that return an OK-to-write copy */
197 #define DatumGetByteaPCopy(X) ((bytea *) PG_DETOAST_DATUM_COPY(X))
198 #define DatumGetTextPCopy(X) ((text *) PG_DETOAST_DATUM_COPY(X))
199 #define DatumGetBpCharPCopy(X) ((BpChar *) PG_DETOAST_DATUM_COPY(X))
200 #define DatumGetVarCharPCopy(X) ((VarChar *) PG_DETOAST_DATUM_COPY(X))
201 /* Variants which return n bytes starting at pos. m */
202 #define DatumGetByteaPSlice(X,m,n) ((bytea *) PG_DETOAST_DATUM_SLICE(X,m,n))
203 #define DatumGetTextPSlice(X,m,n) ((text *) PG_DETOAST_DATUM_SLICE(X,m,n))
204 #define DatumGetBpCharPSlice(X,m,n) ((BpChar *) PG_DETOAST_DATUM_SLICE(X,m,n))
205 #define DatumGetVarCharPSlice(X,m,n) ((VarChar *) PG_DETOAST_DATUM_SLICE(X,m,n))
206 /* GETARG macros for varlena types will typically look like this: */
207 #define PG_GETARG_BYTEA_P(n) DatumGetByteaP(PG_GETARG_DATUM(n))
208 #define PG_GETARG_TEXT_P(n) DatumGetTextP(PG_GETARG_DATUM(n))
209 #define PG_GETARG_BPCHAR_P(n) DatumGetBpCharP(PG_GETARG_DATUM(n))
210 #define PG_GETARG_VARCHAR_P(n) DatumGetVarCharP(PG_GETARG_DATUM(n))
211 /* And we also offer variants that return an OK-to-write copy */
212 #define PG_GETARG_BYTEA_P_COPY(n) DatumGetByteaPCopy(PG_GETARG_DATUM(n))
213 #define PG_GETARG_TEXT_P_COPY(n) DatumGetTextPCopy(PG_GETARG_DATUM(n))
214 #define PG_GETARG_BPCHAR_P_COPY(n) DatumGetBpCharPCopy(PG_GETARG_DATUM(n))
215 #define PG_GETARG_VARCHAR_P_COPY(n) DatumGetVarCharPCopy(PG_GETARG_DATUM(n))
216 /* And a b-byte slice from position a -also OK to write */
217 #define PG_GETARG_BYTEA_P_SLICE(n,a,b) DatumGetByteaPSlice(PG_GETARG_DATUM(n),a,b)
218 #define PG_GETARG_TEXT_P_SLICE(n,a,b) DatumGetTextPSlice(PG_GETARG_DATUM(n),a,b)
219 #define PG_GETARG_BPCHAR_P_SLICE(n,a,b) DatumGetBpCharPSlice(PG_GETARG_DATUM(n),a,b)
220 #define PG_GETARG_VARCHAR_P_SLICE(n,a,b) DatumGetVarCharPSlice(PG_GETARG_DATUM(n),a,b)
222 /* To return a NULL do this: */
223 #define PG_RETURN_NULL() \
224 do { fcinfo->isnull = true; return (Datum) 0; } while (0)
226 /* A few internal functions return void (which is not the same as NULL!) */
227 #define PG_RETURN_VOID() return (Datum) 0
229 /* Macros for returning results of standard types */
231 #define PG_RETURN_DATUM(x) return (x)
232 #define PG_RETURN_INT32(x) return Int32GetDatum(x)
233 #define PG_RETURN_UINT32(x) return UInt32GetDatum(x)
234 #define PG_RETURN_INT16(x) return Int16GetDatum(x)
235 #define PG_RETURN_CHAR(x) return CharGetDatum(x)
236 #define PG_RETURN_BOOL(x) return BoolGetDatum(x)
237 #define PG_RETURN_OID(x) return ObjectIdGetDatum(x)
238 #define PG_RETURN_POINTER(x) return PointerGetDatum(x)
239 #define PG_RETURN_CSTRING(x) return CStringGetDatum(x)
240 #define PG_RETURN_NAME(x) return NameGetDatum(x)
241 /* these macros hide the pass-by-reference-ness of the datatype: */
242 #define PG_RETURN_FLOAT4(x) return Float4GetDatum(x)
243 #define PG_RETURN_FLOAT8(x) return Float8GetDatum(x)
244 #define PG_RETURN_INT64(x) return Int64GetDatum(x)
245 /* RETURN macros for other pass-by-ref types will typically look like this: */
246 #define PG_RETURN_BYTEA_P(x) PG_RETURN_POINTER(x)
247 #define PG_RETURN_TEXT_P(x) PG_RETURN_POINTER(x)
248 #define PG_RETURN_BPCHAR_P(x) PG_RETURN_POINTER(x)
249 #define PG_RETURN_VARCHAR_P(x) PG_RETURN_POINTER(x)
252 /*-------------------------------------------------------------------------
253 * Support for detecting call convention of dynamically-loaded functions
255 * Dynamically loaded functions may use either the version-1 ("new style")
256 * or version-0 ("old style") calling convention. Version 1 is the call
257 * convention defined in this header file; version 0 is the old "plain C"
258 * convention. A version-1 function must be accompanied by the macro call
260 * PG_FUNCTION_INFO_V1(function_name);
262 * Note that internal functions do not need this decoration since they are
263 * assumed to be version-1.
265 *-------------------------------------------------------------------------
270 int api_version; /* specifies call convention version
272 /* More fields may be added later, for version numbers > 1. */
275 /* Expected signature of an info function */
276 typedef Pg_finfo_record *(*PGFInfoFunction) (void);
278 /* Macro to build an info function associated with the given function name */
280 #define PG_FUNCTION_INFO_V1(funcname) \
281 extern Pg_finfo_record * CppConcat(pg_finfo_,funcname) (void); \
283 CppConcat(pg_finfo_,funcname) (void) \
285 static Pg_finfo_record my_finfo = { 1 }; \
288 extern int no_such_variable
291 /*-------------------------------------------------------------------------
292 * Support routines and macros for callers of fmgr-compatible functions
293 *-------------------------------------------------------------------------
296 /* These are for invocation of a specifically named function with a
297 * directly-computed parameter list. Note that neither arguments nor result
298 * are allowed to be NULL.
300 extern Datum DirectFunctionCall1(PGFunction func, Datum arg1);
301 extern Datum DirectFunctionCall2(PGFunction func, Datum arg1, Datum arg2);
302 extern Datum DirectFunctionCall3(PGFunction func, Datum arg1, Datum arg2,
304 extern Datum DirectFunctionCall4(PGFunction func, Datum arg1, Datum arg2,
305 Datum arg3, Datum arg4);
306 extern Datum DirectFunctionCall5(PGFunction func, Datum arg1, Datum arg2,
307 Datum arg3, Datum arg4, Datum arg5);
308 extern Datum DirectFunctionCall6(PGFunction func, Datum arg1, Datum arg2,
309 Datum arg3, Datum arg4, Datum arg5,
311 extern Datum DirectFunctionCall7(PGFunction func, Datum arg1, Datum arg2,
312 Datum arg3, Datum arg4, Datum arg5,
313 Datum arg6, Datum arg7);
314 extern Datum DirectFunctionCall8(PGFunction func, Datum arg1, Datum arg2,
315 Datum arg3, Datum arg4, Datum arg5,
316 Datum arg6, Datum arg7, Datum arg8);
317 extern Datum DirectFunctionCall9(PGFunction func, Datum arg1, Datum arg2,
318 Datum arg3, Datum arg4, Datum arg5,
319 Datum arg6, Datum arg7, Datum arg8,
322 /* These are for invocation of a previously-looked-up function with a
323 * directly-computed parameter list. Note that neither arguments nor result
324 * are allowed to be NULL.
326 extern Datum FunctionCall1(FmgrInfo *flinfo, Datum arg1);
327 extern Datum FunctionCall2(FmgrInfo *flinfo, Datum arg1, Datum arg2);
328 extern Datum FunctionCall3(FmgrInfo *flinfo, Datum arg1, Datum arg2,
330 extern Datum FunctionCall4(FmgrInfo *flinfo, Datum arg1, Datum arg2,
331 Datum arg3, Datum arg4);
332 extern Datum FunctionCall5(FmgrInfo *flinfo, Datum arg1, Datum arg2,
333 Datum arg3, Datum arg4, Datum arg5);
334 extern Datum FunctionCall6(FmgrInfo *flinfo, Datum arg1, Datum arg2,
335 Datum arg3, Datum arg4, Datum arg5,
337 extern Datum FunctionCall7(FmgrInfo *flinfo, Datum arg1, Datum arg2,
338 Datum arg3, Datum arg4, Datum arg5,
339 Datum arg6, Datum arg7);
340 extern Datum FunctionCall8(FmgrInfo *flinfo, Datum arg1, Datum arg2,
341 Datum arg3, Datum arg4, Datum arg5,
342 Datum arg6, Datum arg7, Datum arg8);
343 extern Datum FunctionCall9(FmgrInfo *flinfo, Datum arg1, Datum arg2,
344 Datum arg3, Datum arg4, Datum arg5,
345 Datum arg6, Datum arg7, Datum arg8,
348 /* These are for invocation of a function identified by OID with a
349 * directly-computed parameter list. Note that neither arguments nor result
350 * are allowed to be NULL. These are essentially FunctionLookup() followed
351 * by FunctionCallN(). If the same function is to be invoked repeatedly,
352 * do the FunctionLookup() once and then use FunctionCallN().
354 extern Datum OidFunctionCall1(Oid functionId, Datum arg1);
355 extern Datum OidFunctionCall2(Oid functionId, Datum arg1, Datum arg2);
356 extern Datum OidFunctionCall3(Oid functionId, Datum arg1, Datum arg2,
358 extern Datum OidFunctionCall4(Oid functionId, Datum arg1, Datum arg2,
359 Datum arg3, Datum arg4);
360 extern Datum OidFunctionCall5(Oid functionId, Datum arg1, Datum arg2,
361 Datum arg3, Datum arg4, Datum arg5);
362 extern Datum OidFunctionCall6(Oid functionId, Datum arg1, Datum arg2,
363 Datum arg3, Datum arg4, Datum arg5,
365 extern Datum OidFunctionCall7(Oid functionId, Datum arg1, Datum arg2,
366 Datum arg3, Datum arg4, Datum arg5,
367 Datum arg6, Datum arg7);
368 extern Datum OidFunctionCall8(Oid functionId, Datum arg1, Datum arg2,
369 Datum arg3, Datum arg4, Datum arg5,
370 Datum arg6, Datum arg7, Datum arg8);
371 extern Datum OidFunctionCall9(Oid functionId, Datum arg1, Datum arg2,
372 Datum arg3, Datum arg4, Datum arg5,
373 Datum arg6, Datum arg7, Datum arg8,
379 extern Pg_finfo_record *fetch_finfo_record(void *filehandle, char *funcname);
380 extern Oid fmgr_internal_function(const char *proname);
381 extern Oid get_fn_expr_rettype(FunctionCallInfo fcinfo);
382 extern Oid get_fn_expr_argtype(FunctionCallInfo fcinfo, int argnum);
383 extern Oid get_fn_expr_functype(FunctionCallInfo fcinfo);
386 * Routines in dfmgr.c
388 extern char *Dynamic_library_path;
390 extern PGFunction load_external_function(char *filename, char *funcname,
391 bool signalNotFound, void **filehandle);
392 extern PGFunction lookup_external_function(void *filehandle, char *funcname);
393 extern void load_file(char *filename);
397 * !!! OLD INTERFACE !!!
399 * fmgr() is the only remaining vestige of the old-style caller support
400 * functions. It's no longer used anywhere in the Postgres distribution,
401 * but we should leave it around for a release or two to ease the transition
402 * for user-supplied C functions. OidFunctionCallN() replaces it for new
407 * DEPRECATED, DO NOT USE IN NEW CODE
409 extern char *fmgr(Oid procedureId,...);