323 lines
14 KiB
C
323 lines
14 KiB
C
/*-------------------------------------------------------------------------
|
|
*
|
|
* fmgr.h
|
|
* Definitions for the Postgres function manager and function-call
|
|
* interface.
|
|
*
|
|
* This file must be included by all Postgres modules that either define
|
|
* or call fmgr-callable functions.
|
|
*
|
|
*
|
|
* Portions Copyright (c) 1996-2000, PostgreSQL, Inc
|
|
* Portions Copyright (c) 1994, Regents of the University of California
|
|
*
|
|
* $Id: fmgr.h,v 1.8 2000/07/12 02:37:25 tgl Exp $
|
|
*
|
|
*-------------------------------------------------------------------------
|
|
*/
|
|
#ifndef FMGR_H
|
|
#define FMGR_H
|
|
|
|
|
|
/*
|
|
* All functions that can be called directly by fmgr must have this signature.
|
|
* (Other functions can be called by using a handler that does have this
|
|
* signature.)
|
|
*/
|
|
|
|
typedef struct FunctionCallInfoData *FunctionCallInfo;
|
|
|
|
typedef Datum (*PGFunction) (FunctionCallInfo fcinfo);
|
|
|
|
/*
|
|
* This struct holds the system-catalog information that must be looked up
|
|
* before a function can be called through fmgr. If the same function is
|
|
* to be called multiple times, the lookup need be done only once and the
|
|
* info struct saved for re-use.
|
|
*/
|
|
typedef struct
|
|
{
|
|
PGFunction fn_addr; /* pointer to function or handler to be called */
|
|
Oid fn_oid; /* OID of function (NOT of handler, if any) */
|
|
short fn_nargs; /* 0..FUNC_MAX_ARGS, or -1 if variable arg count */
|
|
bool fn_strict; /* function is "strict" (NULL in => NULL out) */
|
|
void *fn_extra; /* extra space for use by handler */
|
|
} FmgrInfo;
|
|
|
|
/*
|
|
* This struct is the data actually passed to an fmgr-called function.
|
|
*/
|
|
typedef struct FunctionCallInfoData
|
|
{
|
|
FmgrInfo *flinfo; /* ptr to lookup info used for this call */
|
|
struct Node *context; /* pass info about context of call */
|
|
struct Node *resultinfo; /* pass or return extra info about result */
|
|
bool isnull; /* function must set true if result is NULL */
|
|
short nargs; /* # arguments actually passed */
|
|
Datum arg[FUNC_MAX_ARGS]; /* Arguments passed to function */
|
|
bool argnull[FUNC_MAX_ARGS]; /* T if arg[i] is actually NULL */
|
|
} FunctionCallInfoData;
|
|
|
|
/*
|
|
* This routine fills a FmgrInfo struct, given the OID
|
|
* of the function to be called.
|
|
*/
|
|
extern void fmgr_info(Oid functionId, FmgrInfo *finfo);
|
|
|
|
/*
|
|
* This macro invokes a function given a filled-in FunctionCallInfoData
|
|
* struct. The macro result is the returned Datum --- but note that
|
|
* caller must still check fcinfo->isnull! Also, if function is strict,
|
|
* it is caller's responsibility to verify that no null arguments are present
|
|
* before calling.
|
|
*/
|
|
#define FunctionCallInvoke(fcinfo) ((* (fcinfo)->flinfo->fn_addr) (fcinfo))
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
* Support macros to ease writing fmgr-compatible functions
|
|
*
|
|
* A C-coded fmgr-compatible function should be declared as
|
|
*
|
|
* Datum
|
|
* function_name(PG_FUNCTION_ARGS)
|
|
* {
|
|
* ...
|
|
* }
|
|
*
|
|
* It should access its arguments using appropriate PG_GETARG_xxx macros
|
|
* and should return its result using PG_RETURN_xxx.
|
|
*
|
|
*-------------------------------------------------------------------------
|
|
*/
|
|
|
|
/* Standard parameter list for fmgr-compatible functions */
|
|
#define PG_FUNCTION_ARGS FunctionCallInfo fcinfo
|
|
|
|
/*
|
|
* If function is not marked "proisstrict" in pg_proc, it must check for
|
|
* null arguments using this macro. Do not try to GETARG a null argument!
|
|
*/
|
|
#define PG_ARGISNULL(n) (fcinfo->argnull[n])
|
|
|
|
/*
|
|
* Support for fetching detoasted copies of toastable datatypes (all of
|
|
* which are varlena types). pg_detoast_datum() gives you either the input
|
|
* datum (if not toasted) or a detoasted copy allocated with palloc().
|
|
* pg_detoast_datum_copy() always gives you a palloc'd copy --- use it
|
|
* if you need a modifiable copy of the input. Caller is expected to have
|
|
* checked for null inputs first, if necessary.
|
|
*
|
|
* Note: it'd be nice if these could be macros, but I see no way to do that
|
|
* without evaluating the arguments multiple times, which is NOT acceptable.
|
|
*/
|
|
extern struct varlena * pg_detoast_datum(struct varlena * datum);
|
|
extern struct varlena * pg_detoast_datum_copy(struct varlena * datum);
|
|
|
|
#define PG_DETOAST_DATUM(datum) \
|
|
pg_detoast_datum((struct varlena *) DatumGetPointer(datum))
|
|
#define PG_DETOAST_DATUM_COPY(datum) \
|
|
pg_detoast_datum_copy((struct varlena *) DatumGetPointer(datum))
|
|
|
|
/*
|
|
* Support for cleaning up detoasted copies of inputs. This must only
|
|
* be used for pass-by-ref datatypes, and normally would only be used
|
|
* for toastable types. If the given pointer is different from the
|
|
* original argument, assume it's a palloc'd detoasted copy, and pfree it.
|
|
* NOTE: most functions on toastable types do not have to worry about this,
|
|
* but we currently require that support functions for indexes not leak
|
|
* memory.
|
|
*/
|
|
#define PG_FREE_IF_COPY(ptr,n) \
|
|
do { \
|
|
if ((Pointer) (ptr) != PG_GETARG_POINTER(n)) \
|
|
pfree(ptr); \
|
|
} while (0)
|
|
|
|
/* Macros for fetching arguments of standard types */
|
|
|
|
#define PG_GETARG_DATUM(n) (fcinfo->arg[n])
|
|
#define PG_GETARG_INT32(n) DatumGetInt32(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_UINT32(n) DatumGetUInt32(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_INT16(n) DatumGetInt16(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_UINT16(n) DatumGetUInt16(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_CHAR(n) DatumGetChar(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_BOOL(n) DatumGetBool(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_OID(n) DatumGetObjectId(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_POINTER(n) DatumGetPointer(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_CSTRING(n) DatumGetCString(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_NAME(n) DatumGetName(PG_GETARG_DATUM(n))
|
|
/* these macros hide the pass-by-reference-ness of the datatype: */
|
|
#define PG_GETARG_FLOAT4(n) DatumGetFloat4(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_FLOAT8(n) DatumGetFloat8(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_INT64(n) DatumGetInt64(PG_GETARG_DATUM(n))
|
|
/* use this if you want the raw, possibly-toasted input datum: */
|
|
#define PG_GETARG_RAW_VARLENA_P(n) ((struct varlena *) PG_GETARG_POINTER(n))
|
|
/* use this if you want the input datum de-toasted: */
|
|
#define PG_GETARG_VARLENA_P(n) PG_DETOAST_DATUM(PG_GETARG_DATUM(n))
|
|
/* DatumGetFoo macros for varlena types will typically look like this: */
|
|
#define DatumGetByteaP(X) ((bytea *) PG_DETOAST_DATUM(X))
|
|
#define DatumGetTextP(X) ((text *) PG_DETOAST_DATUM(X))
|
|
#define DatumGetBpCharP(X) ((BpChar *) PG_DETOAST_DATUM(X))
|
|
#define DatumGetVarCharP(X) ((VarChar *) PG_DETOAST_DATUM(X))
|
|
/* And we also offer variants that return an OK-to-write copy */
|
|
#define DatumGetByteaPCopy(X) ((bytea *) PG_DETOAST_DATUM_COPY(X))
|
|
#define DatumGetTextPCopy(X) ((text *) PG_DETOAST_DATUM_COPY(X))
|
|
#define DatumGetBpCharPCopy(X) ((BpChar *) PG_DETOAST_DATUM_COPY(X))
|
|
#define DatumGetVarCharPCopy(X) ((VarChar *) PG_DETOAST_DATUM_COPY(X))
|
|
/* GETARG macros for varlena types will typically look like this: */
|
|
#define PG_GETARG_BYTEA_P(n) DatumGetByteaP(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_TEXT_P(n) DatumGetTextP(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_BPCHAR_P(n) DatumGetBpCharP(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_VARCHAR_P(n) DatumGetVarCharP(PG_GETARG_DATUM(n))
|
|
/* And we also offer variants that return an OK-to-write copy */
|
|
#define PG_GETARG_BYTEA_P_COPY(n) DatumGetByteaPCopy(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_TEXT_P_COPY(n) DatumGetTextPCopy(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_BPCHAR_P_COPY(n) DatumGetBpCharPCopy(PG_GETARG_DATUM(n))
|
|
#define PG_GETARG_VARCHAR_P_COPY(n) DatumGetVarCharPCopy(PG_GETARG_DATUM(n))
|
|
|
|
/* To return a NULL do this: */
|
|
#define PG_RETURN_NULL() \
|
|
do { fcinfo->isnull = true; return (Datum) 0; } while (0)
|
|
|
|
/* A few internal functions return void (which is not the same as NULL!) */
|
|
#define PG_RETURN_VOID() return (Datum) 0
|
|
|
|
/* Macros for returning results of standard types */
|
|
|
|
#define PG_RETURN_INT32(x) return Int32GetDatum(x)
|
|
#define PG_RETURN_UINT32(x) return UInt32GetDatum(x)
|
|
#define PG_RETURN_INT16(x) return Int16GetDatum(x)
|
|
#define PG_RETURN_CHAR(x) return CharGetDatum(x)
|
|
#define PG_RETURN_BOOL(x) return BoolGetDatum(x)
|
|
#define PG_RETURN_OID(x) return ObjectIdGetDatum(x)
|
|
#define PG_RETURN_POINTER(x) return PointerGetDatum(x)
|
|
#define PG_RETURN_CSTRING(x) return CStringGetDatum(x)
|
|
#define PG_RETURN_NAME(x) return NameGetDatum(x)
|
|
/* these macros hide the pass-by-reference-ness of the datatype: */
|
|
#define PG_RETURN_FLOAT4(x) return Float4GetDatum(x)
|
|
#define PG_RETURN_FLOAT8(x) return Float8GetDatum(x)
|
|
#define PG_RETURN_INT64(x) return Int64GetDatum(x)
|
|
/* RETURN macros for other pass-by-ref types will typically look like this: */
|
|
#define PG_RETURN_BYTEA_P(x) PG_RETURN_POINTER(x)
|
|
#define PG_RETURN_TEXT_P(x) PG_RETURN_POINTER(x)
|
|
#define PG_RETURN_BPCHAR_P(x) PG_RETURN_POINTER(x)
|
|
#define PG_RETURN_VARCHAR_P(x) PG_RETURN_POINTER(x)
|
|
|
|
|
|
/*-------------------------------------------------------------------------
|
|
* Support routines and macros for callers of fmgr-compatible functions
|
|
*-------------------------------------------------------------------------
|
|
*/
|
|
|
|
/* These are for invocation of a specifically named function with a
|
|
* directly-computed parameter list. Note that neither arguments nor result
|
|
* are allowed to be NULL.
|
|
*/
|
|
extern Datum DirectFunctionCall1(PGFunction func, Datum arg1);
|
|
extern Datum DirectFunctionCall2(PGFunction func, Datum arg1, Datum arg2);
|
|
extern Datum DirectFunctionCall3(PGFunction func, Datum arg1, Datum arg2,
|
|
Datum arg3);
|
|
extern Datum DirectFunctionCall4(PGFunction func, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4);
|
|
extern Datum DirectFunctionCall5(PGFunction func, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5);
|
|
extern Datum DirectFunctionCall6(PGFunction func, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6);
|
|
extern Datum DirectFunctionCall7(PGFunction func, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7);
|
|
extern Datum DirectFunctionCall8(PGFunction func, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7, Datum arg8);
|
|
extern Datum DirectFunctionCall9(PGFunction func, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7, Datum arg8,
|
|
Datum arg9);
|
|
|
|
/* These are for invocation of a previously-looked-up function with a
|
|
* directly-computed parameter list. Note that neither arguments nor result
|
|
* are allowed to be NULL.
|
|
*/
|
|
extern Datum FunctionCall1(FmgrInfo *flinfo, Datum arg1);
|
|
extern Datum FunctionCall2(FmgrInfo *flinfo, Datum arg1, Datum arg2);
|
|
extern Datum FunctionCall3(FmgrInfo *flinfo, Datum arg1, Datum arg2,
|
|
Datum arg3);
|
|
extern Datum FunctionCall4(FmgrInfo *flinfo, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4);
|
|
extern Datum FunctionCall5(FmgrInfo *flinfo, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5);
|
|
extern Datum FunctionCall6(FmgrInfo *flinfo, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6);
|
|
extern Datum FunctionCall7(FmgrInfo *flinfo, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7);
|
|
extern Datum FunctionCall8(FmgrInfo *flinfo, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7, Datum arg8);
|
|
extern Datum FunctionCall9(FmgrInfo *flinfo, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7, Datum arg8,
|
|
Datum arg9);
|
|
|
|
/* These are for invocation of a function identified by OID with a
|
|
* directly-computed parameter list. Note that neither arguments nor result
|
|
* are allowed to be NULL. These are essentially FunctionLookup() followed
|
|
* by FunctionCallN(). If the same function is to be invoked repeatedly,
|
|
* do the FunctionLookup() once and then use FunctionCallN().
|
|
*/
|
|
extern Datum OidFunctionCall1(Oid functionId, Datum arg1);
|
|
extern Datum OidFunctionCall2(Oid functionId, Datum arg1, Datum arg2);
|
|
extern Datum OidFunctionCall3(Oid functionId, Datum arg1, Datum arg2,
|
|
Datum arg3);
|
|
extern Datum OidFunctionCall4(Oid functionId, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4);
|
|
extern Datum OidFunctionCall5(Oid functionId, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5);
|
|
extern Datum OidFunctionCall6(Oid functionId, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6);
|
|
extern Datum OidFunctionCall7(Oid functionId, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7);
|
|
extern Datum OidFunctionCall8(Oid functionId, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7, Datum arg8);
|
|
extern Datum OidFunctionCall9(Oid functionId, Datum arg1, Datum arg2,
|
|
Datum arg3, Datum arg4, Datum arg5,
|
|
Datum arg6, Datum arg7, Datum arg8,
|
|
Datum arg9);
|
|
|
|
|
|
/*
|
|
* Routines in fmgr.c
|
|
*/
|
|
extern Oid fmgr_internal_language(const char *proname);
|
|
|
|
/*
|
|
* Routines in dfmgr.c
|
|
*/
|
|
extern PGFunction fmgr_dynamic(Oid functionId);
|
|
extern PGFunction load_external_function(char *filename, char *funcname);
|
|
extern void load_file(char *filename);
|
|
|
|
|
|
/*
|
|
* !!! OLD INTERFACE !!!
|
|
*
|
|
* fmgr() is the only remaining vestige of the old-style caller support
|
|
* functions. It's no longer used anywhere in the Postgres distribution,
|
|
* but we should leave it around for a release or two to ease the transition
|
|
* for user-supplied C functions. OidFunctionCallN() replaces it for new
|
|
* code.
|
|
*/
|
|
|
|
/*
|
|
* DEPRECATED, DO NOT USE IN NEW CODE
|
|
*/
|
|
extern char *fmgr(Oid procedureId, ... );
|
|
|
|
#endif /* FMGR_H */
|