granicus.if.org Git - postgresql/blob - src/include/fmgr.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * fmgr.h
   4  *        Definitions for the Postgres function manager and function-call
   5  *        interface.
   6  *
   7  * This file must be included by all Postgres modules that either define
   8  * or call fmgr-callable functions.
   9  *
  10  *
  11  * Portions Copyright (c) 1996-2001, PostgreSQL Global Development Group
  12  * Portions Copyright (c) 1994, Regents of the University of California
  13  *
  14  * $Id: fmgr.h,v 1.14 2001/05/17 17:44:18 petere Exp $
  15  *
  16  *-------------------------------------------------------------------------
  17  */
  18 #ifndef FMGR_H
  19 #define FMGR_H
  20
  21
  22 /*
  23  * All functions that can be called directly by fmgr must have this signature.
  24  * (Other functions can be called by using a handler that does have this
  25  * signature.)
  26  */
  27
  28 typedef struct FunctionCallInfoData *FunctionCallInfo;
  29
  30 typedef Datum (*PGFunction) (FunctionCallInfo fcinfo);
  31
  32 /*
  33  * This struct holds the system-catalog information that must be looked up
  34  * before a function can be called through fmgr.  If the same function is
  35  * to be called multiple times, the lookup need be done only once and the
  36  * info struct saved for re-use.
  37  */
  38 typedef struct
  39 {
  40         PGFunction      fn_addr;                /* pointer to function or handler to be
  41                                                                  * called */
  42         Oid                     fn_oid;                 /* OID of function (NOT of handler, if
  43                                                                  * any) */
  44         short           fn_nargs;               /* 0..FUNC_MAX_ARGS, or -1 if variable arg
  45                                                                  * count */
  46         bool            fn_strict;              /* function is "strict" (NULL in => NULL
  47                                                                  * out) */
  48         bool            fn_retset;              /* function returns a set (over multiple
  49                                                                  * calls) */
  50         void       *fn_extra;           /* extra space for use by handler */
  51         MemoryContext fn_mcxt;          /* memory context to store fn_extra in */
  52 } FmgrInfo;
  53
  54 /*
  55  * This struct is the data actually passed to an fmgr-called function.
  56  */
  57 typedef struct FunctionCallInfoData
  58 {
  59         FmgrInfo   *flinfo;                     /* ptr to lookup info used for this call */
  60         struct Node *context;           /* pass info about context of call */
  61         struct Node *resultinfo;        /* pass or return extra info about result */
  62         bool            isnull;                 /* function must set true if result is
  63                                                                  * NULL */
  64         short           nargs;                  /* # arguments actually passed */
  65         Datum           arg[FUNC_MAX_ARGS];             /* Arguments passed to function */
  66         bool            argnull[FUNC_MAX_ARGS]; /* T if arg[i] is actually NULL */
  67 } FunctionCallInfoData;
  68
  69 /*
  70  * This routine fills a FmgrInfo struct, given the OID
  71  * of the function to be called.
  72  */
  73 extern void fmgr_info(Oid functionId, FmgrInfo *finfo);
  74
  75 /*
  76  * This macro invokes a function given a filled-in FunctionCallInfoData
  77  * struct.      The macro result is the returned Datum --- but note that
  78  * caller must still check fcinfo->isnull!      Also, if function is strict,
  79  * it is caller's responsibility to verify that no null arguments are present
  80  * before calling.
  81  */
  82 #define FunctionCallInvoke(fcinfo)      ((* (fcinfo)->flinfo->fn_addr) (fcinfo))
  83
  84
  85 /*-------------------------------------------------------------------------
  86  *              Support macros to ease writing fmgr-compatible functions
  87  *
  88  * A C-coded fmgr-compatible function should be declared as
  89  *
  90  *              Datum
  91  *              function_name(PG_FUNCTION_ARGS)
  92  *              {
  93  *                      ...
  94  *              }
  95  *
  96  * It should access its arguments using appropriate PG_GETARG_xxx macros
  97  * and should return its result using PG_RETURN_xxx.
  98  *
  99  *-------------------------------------------------------------------------
 100  */
 101
 102 /* Standard parameter list for fmgr-compatible functions */
 103 #define PG_FUNCTION_ARGS        FunctionCallInfo fcinfo
 104
 105 /*
 106  * If function is not marked "proisstrict" in pg_proc, it must check for
 107  * null arguments using this macro.  Do not try to GETARG a null argument!
 108  */
 109 #define PG_ARGISNULL(n)  (fcinfo->argnull[n])
 110
 111 /*
 112  * Support for fetching detoasted copies of toastable datatypes (all of
 113  * which are varlena types).  pg_detoast_datum() gives you either the input
 114  * datum (if not toasted) or a detoasted copy allocated with palloc().
 115  * pg_detoast_datum_copy() always gives you a palloc'd copy --- use it
 116  * if you need a modifiable copy of the input.  Caller is expected to have
 117  * checked for null inputs first, if necessary.
 118  *
 119  * Note: it'd be nice if these could be macros, but I see no way to do that
 120  * without evaluating the arguments multiple times, which is NOT acceptable.
 121  */
 122 extern struct varlena *pg_detoast_datum(struct varlena * datum);
 123 extern struct varlena *pg_detoast_datum_copy(struct varlena * datum);
 124
 125 #define PG_DETOAST_DATUM(datum) \
 126         pg_detoast_datum((struct varlena *) DatumGetPointer(datum))
 127 #define PG_DETOAST_DATUM_COPY(datum) \
 128         pg_detoast_datum_copy((struct varlena *) DatumGetPointer(datum))
 129
 130 /*
 131  * Support for cleaning up detoasted copies of inputs.  This must only
 132  * be used for pass-by-ref datatypes, and normally would only be used
 133  * for toastable types.  If the given pointer is different from the
 134  * original argument, assume it's a palloc'd detoasted copy, and pfree it.
 135  * NOTE: most functions on toastable types do not have to worry about this,
 136  * but we currently require that support functions for indexes not leak
 137  * memory.
 138  */
 139 #define PG_FREE_IF_COPY(ptr,n) \
 140         do { \
 141                 if ((Pointer) (ptr) != PG_GETARG_POINTER(n)) \
 142                         pfree(ptr); \
 143         } while (0)
 144
 145 /* Macros for fetching arguments of standard types */
 146
 147 #define PG_GETARG_DATUM(n)       (fcinfo->arg[n])
 148 #define PG_GETARG_INT32(n)       DatumGetInt32(PG_GETARG_DATUM(n))
 149 #define PG_GETARG_UINT32(n)  DatumGetUInt32(PG_GETARG_DATUM(n))
 150 #define PG_GETARG_INT16(n)       DatumGetInt16(PG_GETARG_DATUM(n))
 151 #define PG_GETARG_UINT16(n)  DatumGetUInt16(PG_GETARG_DATUM(n))
 152 #define PG_GETARG_CHAR(n)        DatumGetChar(PG_GETARG_DATUM(n))
 153 #define PG_GETARG_BOOL(n)        DatumGetBool(PG_GETARG_DATUM(n))
 154 #define PG_GETARG_OID(n)         DatumGetObjectId(PG_GETARG_DATUM(n))
 155 #define PG_GETARG_POINTER(n) DatumGetPointer(PG_GETARG_DATUM(n))
 156 #define PG_GETARG_CSTRING(n) DatumGetCString(PG_GETARG_DATUM(n))
 157 #define PG_GETARG_NAME(n)        DatumGetName(PG_GETARG_DATUM(n))
 158 /* these macros hide the pass-by-reference-ness of the datatype: */
 159 #define PG_GETARG_FLOAT4(n)  DatumGetFloat4(PG_GETARG_DATUM(n))
 160 #define PG_GETARG_FLOAT8(n)  DatumGetFloat8(PG_GETARG_DATUM(n))
 161 #define PG_GETARG_INT64(n)       DatumGetInt64(PG_GETARG_DATUM(n))
 162 /* use this if you want the raw, possibly-toasted input datum: */
 163 #define PG_GETARG_RAW_VARLENA_P(n)      ((struct varlena *) PG_GETARG_POINTER(n))
 164 /* use this if you want the input datum de-toasted: */
 165 #define PG_GETARG_VARLENA_P(n) PG_DETOAST_DATUM(PG_GETARG_DATUM(n))
 166 /* DatumGetFoo macros for varlena types will typically look like this: */
 167 #define DatumGetByteaP(X)                       ((bytea *) PG_DETOAST_DATUM(X))
 168 #define DatumGetTextP(X)                        ((text *) PG_DETOAST_DATUM(X))
 169 #define DatumGetBpCharP(X)                      ((BpChar *) PG_DETOAST_DATUM(X))
 170 #define DatumGetVarCharP(X)                     ((VarChar *) PG_DETOAST_DATUM(X))
 171 /* And we also offer variants that return an OK-to-write copy */
 172 #define DatumGetByteaPCopy(X)           ((bytea *) PG_DETOAST_DATUM_COPY(X))
 173 #define DatumGetTextPCopy(X)            ((text *) PG_DETOAST_DATUM_COPY(X))
 174 #define DatumGetBpCharPCopy(X)          ((BpChar *) PG_DETOAST_DATUM_COPY(X))
 175 #define DatumGetVarCharPCopy(X)         ((VarChar *) PG_DETOAST_DATUM_COPY(X))
 176 /* GETARG macros for varlena types will typically look like this: */
 177 #define PG_GETARG_BYTEA_P(n)            DatumGetByteaP(PG_GETARG_DATUM(n))
 178 #define PG_GETARG_TEXT_P(n)                     DatumGetTextP(PG_GETARG_DATUM(n))
 179 #define PG_GETARG_BPCHAR_P(n)           DatumGetBpCharP(PG_GETARG_DATUM(n))
 180 #define PG_GETARG_VARCHAR_P(n)          DatumGetVarCharP(PG_GETARG_DATUM(n))
 181 /* And we also offer variants that return an OK-to-write copy */
 182 #define PG_GETARG_BYTEA_P_COPY(n)       DatumGetByteaPCopy(PG_GETARG_DATUM(n))
 183 #define PG_GETARG_TEXT_P_COPY(n)        DatumGetTextPCopy(PG_GETARG_DATUM(n))
 184 #define PG_GETARG_BPCHAR_P_COPY(n)      DatumGetBpCharPCopy(PG_GETARG_DATUM(n))
 185 #define PG_GETARG_VARCHAR_P_COPY(n) DatumGetVarCharPCopy(PG_GETARG_DATUM(n))
 186
 187 /* To return a NULL do this: */
 188 #define PG_RETURN_NULL()  \
 189         do { fcinfo->isnull = true; return (Datum) 0; } while (0)
 190
 191 /* A few internal functions return void (which is not the same as NULL!) */
 192 #define PG_RETURN_VOID()         return (Datum) 0
 193
 194 /* Macros for returning results of standard types */
 195
 196 #define PG_RETURN_DATUM(x)       return (x)
 197 #define PG_RETURN_INT32(x)       return Int32GetDatum(x)
 198 #define PG_RETURN_UINT32(x)  return UInt32GetDatum(x)
 199 #define PG_RETURN_INT16(x)       return Int16GetDatum(x)
 200 #define PG_RETURN_CHAR(x)        return CharGetDatum(x)
 201 #define PG_RETURN_BOOL(x)        return BoolGetDatum(x)
 202 #define PG_RETURN_OID(x)         return ObjectIdGetDatum(x)
 203 #define PG_RETURN_POINTER(x) return PointerGetDatum(x)
 204 #define PG_RETURN_CSTRING(x) return CStringGetDatum(x)
 205 #define PG_RETURN_NAME(x)        return NameGetDatum(x)
 206 /* these macros hide the pass-by-reference-ness of the datatype: */
 207 #define PG_RETURN_FLOAT4(x)  return Float4GetDatum(x)
 208 #define PG_RETURN_FLOAT8(x)  return Float8GetDatum(x)
 209 #define PG_RETURN_INT64(x)       return Int64GetDatum(x)
 210 /* RETURN macros for other pass-by-ref types will typically look like this: */
 211 #define PG_RETURN_BYTEA_P(x)   PG_RETURN_POINTER(x)
 212 #define PG_RETURN_TEXT_P(x)    PG_RETURN_POINTER(x)
 213 #define PG_RETURN_BPCHAR_P(x)  PG_RETURN_POINTER(x)
 214 #define PG_RETURN_VARCHAR_P(x) PG_RETURN_POINTER(x)
 215
 216
 217 /*-------------------------------------------------------------------------
 218  *              Support for detecting call convention of dynamically-loaded functions
 219  *
 220  * Dynamically loaded functions may use either the version-1 ("new style")
 221  * or version-0 ("old style") calling convention.  Version 1 is the call
 222  * convention defined in this header file; version 0 is the old "plain C"
 223  * convention.  A version-1 function must be accompanied by the macro call
 224  *
 225  *              PG_FUNCTION_INFO_V1(function_name);
 226  *
 227  * Note that internal functions do not need this decoration since they are
 228  * assumed to be version-1.
 229  *
 230  *-------------------------------------------------------------------------
 231  */
 232
 233 typedef struct
 234 {
 235         int                     api_version;    /* specifies call convention version
 236                                                                  * number */
 237         /* More fields may be added later, for version numbers > 1. */
 238 } Pg_finfo_record;
 239
 240 /* Expected signature of an info function */
 241 typedef Pg_finfo_record *(*PGFInfoFunction) (void);
 242
 243 /* Macro to build an info function associated with the given function name */
 244
 245 #define PG_FUNCTION_INFO_V1(funcname) \
 246 extern Pg_finfo_record * CppConcat(pg_finfo_,funcname) (void); \
 247 Pg_finfo_record * \
 248 CppConcat(pg_finfo_,funcname) (void) \
 249 { \
 250         static Pg_finfo_record my_finfo = { 1 }; \
 251         return &my_finfo; \
 252 }
 253
 254
 255 /*-------------------------------------------------------------------------
 256  *              Support routines and macros for callers of fmgr-compatible functions
 257  *-------------------------------------------------------------------------
 258  */
 259
 260 /* These are for invocation of a specifically named function with a
 261  * directly-computed parameter list.  Note that neither arguments nor result
 262  * are allowed to be NULL.
 263  */
 264 extern Datum DirectFunctionCall1(PGFunction func, Datum arg1);
 265 extern Datum DirectFunctionCall2(PGFunction func, Datum arg1, Datum arg2);
 266 extern Datum DirectFunctionCall3(PGFunction func, Datum arg1, Datum arg2,
 267                                         Datum arg3);
 268 extern Datum DirectFunctionCall4(PGFunction func, Datum arg1, Datum arg2,
 269                                         Datum arg3, Datum arg4);
 270 extern Datum DirectFunctionCall5(PGFunction func, Datum arg1, Datum arg2,
 271                                         Datum arg3, Datum arg4, Datum arg5);
 272 extern Datum DirectFunctionCall6(PGFunction func, Datum arg1, Datum arg2,
 273                                         Datum arg3, Datum arg4, Datum arg5,
 274                                         Datum arg6);
 275 extern Datum DirectFunctionCall7(PGFunction func, Datum arg1, Datum arg2,
 276                                         Datum arg3, Datum arg4, Datum arg5,
 277                                         Datum arg6, Datum arg7);
 278 extern Datum DirectFunctionCall8(PGFunction func, Datum arg1, Datum arg2,
 279                                         Datum arg3, Datum arg4, Datum arg5,
 280                                         Datum arg6, Datum arg7, Datum arg8);
 281 extern Datum DirectFunctionCall9(PGFunction func, Datum arg1, Datum arg2,
 282                                         Datum arg3, Datum arg4, Datum arg5,
 283                                         Datum arg6, Datum arg7, Datum arg8,
 284                                         Datum arg9);
 285
 286 /* These are for invocation of a previously-looked-up function with a
 287  * directly-computed parameter list.  Note that neither arguments nor result
 288  * are allowed to be NULL.
 289  */
 290 extern Datum FunctionCall1(FmgrInfo *flinfo, Datum arg1);
 291 extern Datum FunctionCall2(FmgrInfo *flinfo, Datum arg1, Datum arg2);
 292 extern Datum FunctionCall3(FmgrInfo *flinfo, Datum arg1, Datum arg2,
 293                           Datum arg3);
 294 extern Datum FunctionCall4(FmgrInfo *flinfo, Datum arg1, Datum arg2,
 295                           Datum arg3, Datum arg4);
 296 extern Datum FunctionCall5(FmgrInfo *flinfo, Datum arg1, Datum arg2,
 297                           Datum arg3, Datum arg4, Datum arg5);
 298 extern Datum FunctionCall6(FmgrInfo *flinfo, Datum arg1, Datum arg2,
 299                           Datum arg3, Datum arg4, Datum arg5,
 300                           Datum arg6);
 301 extern Datum FunctionCall7(FmgrInfo *flinfo, Datum arg1, Datum arg2,
 302                           Datum arg3, Datum arg4, Datum arg5,
 303                           Datum arg6, Datum arg7);
 304 extern Datum FunctionCall8(FmgrInfo *flinfo, Datum arg1, Datum arg2,
 305                           Datum arg3, Datum arg4, Datum arg5,
 306                           Datum arg6, Datum arg7, Datum arg8);
 307 extern Datum FunctionCall9(FmgrInfo *flinfo, Datum arg1, Datum arg2,
 308                           Datum arg3, Datum arg4, Datum arg5,
 309                           Datum arg6, Datum arg7, Datum arg8,
 310                           Datum arg9);
 311
 312 /* These are for invocation of a function identified by OID with a
 313  * directly-computed parameter list.  Note that neither arguments nor result
 314  * are allowed to be NULL.      These are essentially FunctionLookup() followed
 315  * by FunctionCallN().  If the same function is to be invoked repeatedly,
 316  * do the FunctionLookup() once and then use FunctionCallN().
 317  */
 318 extern Datum OidFunctionCall1(Oid functionId, Datum arg1);
 319 extern Datum OidFunctionCall2(Oid functionId, Datum arg1, Datum arg2);
 320 extern Datum OidFunctionCall3(Oid functionId, Datum arg1, Datum arg2,
 321                                  Datum arg3);
 322 extern Datum OidFunctionCall4(Oid functionId, Datum arg1, Datum arg2,
 323                                  Datum arg3, Datum arg4);
 324 extern Datum OidFunctionCall5(Oid functionId, Datum arg1, Datum arg2,
 325                                  Datum arg3, Datum arg4, Datum arg5);
 326 extern Datum OidFunctionCall6(Oid functionId, Datum arg1, Datum arg2,
 327                                  Datum arg3, Datum arg4, Datum arg5,
 328                                  Datum arg6);
 329 extern Datum OidFunctionCall7(Oid functionId, Datum arg1, Datum arg2,
 330                                  Datum arg3, Datum arg4, Datum arg5,
 331                                  Datum arg6, Datum arg7);
 332 extern Datum OidFunctionCall8(Oid functionId, Datum arg1, Datum arg2,
 333                                  Datum arg3, Datum arg4, Datum arg5,
 334                                  Datum arg6, Datum arg7, Datum arg8);
 335 extern Datum OidFunctionCall9(Oid functionId, Datum arg1, Datum arg2,
 336                                  Datum arg3, Datum arg4, Datum arg5,
 337                                  Datum arg6, Datum arg7, Datum arg8,
 338                                  Datum arg9);
 339
 340
 341 /*
 342  * Routines in fmgr.c
 343  */
 344 extern Pg_finfo_record *fetch_finfo_record(char *filename, char *funcname);
 345 extern Oid      fmgr_internal_function(const char *proname);
 346
 347 /*
 348  * Routines in dfmgr.c
 349  */
 350 extern PGFunction load_external_function(char *filename, char *funcname,
 351                                            bool signalNotFound);
 352 extern void load_file(char *filename);
 353 extern char * Dynamic_library_path;
 354
 355
 356 /*
 357  * !!! OLD INTERFACE !!!
 358  *
 359  * fmgr() is the only remaining vestige of the old-style caller support
 360  * functions.  It's no longer used anywhere in the Postgres distribution,
 361  * but we should leave it around for a release or two to ease the transition
 362  * for user-supplied C functions.  OidFunctionCallN() replaces it for new
 363  * code.
 364  */
 365
 366 /*
 367  * DEPRECATED, DO NOT USE IN NEW CODE
 368  */
 369 extern char *fmgr(Oid procedureId,...);
 370
 371 #endif   /* FMGR_H */