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-2024, PostgreSQL Global Development Group
  12  * Portions Copyright (c) 1994, Regents of the University of California
  13  *
  14  * src/include/fmgr.h
  15  *
  16  *-------------------------------------------------------------------------
  17  */
  18 #ifndef FMGR_H
  19 #define FMGR_H
  20
  21 /* We don't want to include primnodes.h here, so make some stub references */
  22 typedef struct Node *fmNodePtr;
  23 typedef struct Aggref *fmAggrefPtr;
  24
  25 /* Likewise, avoid including execnodes.h here */
  26 typedef void (*fmExprContextCallbackFunction) (Datum arg);
  27
  28 /* Likewise, avoid including stringinfo.h here */
  29 typedef struct StringInfoData *fmStringInfo;
  30
  31
  32 /*
  33  * All functions that can be called directly by fmgr must have this signature.
  34  * (Other functions can be called by using a handler that does have this
  35  * signature.)
  36  */
  37
  38 typedef struct FunctionCallInfoBaseData *FunctionCallInfo;
  39
  40 typedef Datum (*PGFunction) (FunctionCallInfo fcinfo);
  41
  42 /*
  43  * This struct holds the system-catalog information that must be looked up
  44  * before a function can be called through fmgr.  If the same function is
  45  * to be called multiple times, the lookup need be done only once and the
  46  * info struct saved for re-use.
  47  *
  48  * Note that fn_expr really is parse-time-determined information about the
  49  * arguments, rather than about the function itself.  But it's convenient to
  50  * store it here rather than in FunctionCallInfoBaseData, where it might more
  51  * logically belong.
  52  *
  53  * fn_extra is available for use by the called function; all other fields
  54  * should be treated as read-only after the struct is created.
  55  */
  56 typedef struct FmgrInfo
  57 {
  58         PGFunction      fn_addr;                /* pointer to function or handler to be called */
  59         Oid                     fn_oid;                 /* OID of function (NOT of handler, if any) */
  60         short           fn_nargs;               /* number of input args (0..FUNC_MAX_ARGS) */
  61         bool            fn_strict;              /* function is "strict" (NULL in => NULL out) */
  62         bool            fn_retset;              /* function returns a set */
  63         unsigned char fn_stats;         /* collect stats if track_functions > this */
  64         void       *fn_extra;           /* extra space for use by handler */
  65         MemoryContext fn_mcxt;          /* memory context to store fn_extra in */
  66         fmNodePtr       fn_expr;                /* expression parse tree for call, or NULL */
  67 } FmgrInfo;
  68
  69 /*
  70  * This struct is the data actually passed to an fmgr-called function.
  71  *
  72  * The called function is expected to set isnull, and possibly resultinfo or
  73  * fields in whatever resultinfo points to.  It should not change any other
  74  * fields.  (In particular, scribbling on the argument arrays is a bad idea,
  75  * since some callers assume they can re-call with the same arguments.)
  76  *
  77  * Note that enough space for arguments needs to be provided, either by using
  78  * SizeForFunctionCallInfo() in dynamic allocations, or by using
  79  * LOCAL_FCINFO() for on-stack allocations.
  80  *
  81  * This struct is named *BaseData, rather than *Data, to break pre v12 code
  82  * that allocated FunctionCallInfoData itself, as it'd often silently break
  83  * old code due to no space for arguments being provided.
  84  */
  85 typedef struct FunctionCallInfoBaseData
  86 {
  87         FmgrInfo   *flinfo;                     /* ptr to lookup info used for this call */
  88         fmNodePtr       context;                /* pass info about context of call */
  89         fmNodePtr       resultinfo;             /* pass or return extra info about result */
  90         Oid                     fncollation;    /* collation for function to use */
  91 #define FIELDNO_FUNCTIONCALLINFODATA_ISNULL 4
  92         bool            isnull;                 /* function must set true if result is NULL */
  93         short           nargs;                  /* # arguments actually passed */
  94 #define FIELDNO_FUNCTIONCALLINFODATA_ARGS 6
  95         NullableDatum args[FLEXIBLE_ARRAY_MEMBER];
  96 } FunctionCallInfoBaseData;
  97
  98 /*
  99  * Space needed for a FunctionCallInfoBaseData struct with sufficient space
 100  * for `nargs` arguments.
 101  */
 102 #define SizeForFunctionCallInfo(nargs) \
 103         (offsetof(FunctionCallInfoBaseData, args) + \
 104          sizeof(NullableDatum) * (nargs))
 105
 106 /*
 107  * This macro ensures that `name` points to a stack-allocated
 108  * FunctionCallInfoBaseData struct with sufficient space for `nargs` arguments.
 109  */
 110 #define LOCAL_FCINFO(name, nargs) \
 111         /* use union with FunctionCallInfoBaseData to guarantee alignment */ \
 112         union \
 113         { \
 114                 FunctionCallInfoBaseData fcinfo; \
 115                 /* ensure enough space for nargs args is available */ \
 116                 char fcinfo_data[SizeForFunctionCallInfo(nargs)]; \
 117         } name##data; \
 118         FunctionCallInfo name = &name##data.fcinfo
 119
 120 /*
 121  * This routine fills a FmgrInfo struct, given the OID
 122  * of the function to be called.
 123  */
 124 extern void fmgr_info(Oid functionId, FmgrInfo *finfo);
 125
 126 /*
 127  * Same, when the FmgrInfo struct is in a memory context longer-lived than
 128  * CurrentMemoryContext.  The specified context will be set as fn_mcxt
 129  * and used to hold all subsidiary data of finfo.
 130  */
 131 extern void fmgr_info_cxt(Oid functionId, FmgrInfo *finfo,
 132                                                   MemoryContext mcxt);
 133
 134 /* Convenience macro for setting the fn_expr field */
 135 #define fmgr_info_set_expr(expr, finfo) \
 136         ((finfo)->fn_expr = (expr))
 137
 138 /*
 139  * Copy an FmgrInfo struct
 140  */
 141 extern void fmgr_info_copy(FmgrInfo *dstinfo, FmgrInfo *srcinfo,
 142                                                    MemoryContext destcxt);
 143
 144 extern void fmgr_symbol(Oid functionId, char **mod, char **fn);
 145
 146 /*
 147  * This macro initializes all the fields of a FunctionCallInfoBaseData except
 148  * for the args[] array.
 149  */
 150 #define InitFunctionCallInfoData(Fcinfo, Flinfo, Nargs, Collation, Context, Resultinfo) \
 151         do { \
 152                 (Fcinfo).flinfo = (Flinfo); \
 153                 (Fcinfo).context = (Context); \
 154                 (Fcinfo).resultinfo = (Resultinfo); \
 155                 (Fcinfo).fncollation = (Collation); \
 156                 (Fcinfo).isnull = false; \
 157                 (Fcinfo).nargs = (Nargs); \
 158         } while (0)
 159
 160 /*
 161  * This macro invokes a function given a filled-in FunctionCallInfoBaseData
 162  * struct.  The macro result is the returned Datum --- but note that
 163  * caller must still check fcinfo->isnull!      Also, if function is strict,
 164  * it is caller's responsibility to verify that no null arguments are present
 165  * before calling.
 166  *
 167  * Some code performs multiple calls without redoing InitFunctionCallInfoData,
 168  * possibly altering the argument values.  This is okay, but be sure to reset
 169  * the fcinfo->isnull flag before each call, since callees are permitted to
 170  * assume that starts out false.
 171  */
 172 #define FunctionCallInvoke(fcinfo)      ((* (fcinfo)->flinfo->fn_addr) (fcinfo))
 173
 174
 175 /*-------------------------------------------------------------------------
 176  *              Support macros to ease writing fmgr-compatible functions
 177  *
 178  * A C-coded fmgr-compatible function should be declared as
 179  *
 180  *              Datum
 181  *              function_name(PG_FUNCTION_ARGS)
 182  *              {
 183  *                      ...
 184  *              }
 185  *
 186  * It should access its arguments using appropriate PG_GETARG_xxx macros
 187  * and should return its result using PG_RETURN_xxx.
 188  *
 189  *-------------------------------------------------------------------------
 190  */
 191
 192 /* Standard parameter list for fmgr-compatible functions */
 193 #define PG_FUNCTION_ARGS        FunctionCallInfo fcinfo
 194
 195 /*
 196  * Get collation function should use.
 197  */
 198 #define PG_GET_COLLATION()      (fcinfo->fncollation)
 199
 200 /*
 201  * Get number of arguments passed to function.
 202  */
 203 #define PG_NARGS() (fcinfo->nargs)
 204
 205 /*
 206  * If function is not marked "proisstrict" in pg_proc, it must check for
 207  * null arguments using this macro.  Do not try to GETARG a null argument!
 208  */
 209 #define PG_ARGISNULL(n)  (fcinfo->args[n].isnull)
 210
 211 /*
 212  * Support for fetching detoasted copies of toastable datatypes (all of
 213  * which are varlena types).  pg_detoast_datum() gives you either the input
 214  * datum (if not toasted) or a detoasted copy allocated with palloc().
 215  * pg_detoast_datum_copy() always gives you a palloc'd copy --- use it
 216  * if you need a modifiable copy of the input.  Caller is expected to have
 217  * checked for null inputs first, if necessary.
 218  *
 219  * pg_detoast_datum_packed() will return packed (1-byte header) datums
 220  * unmodified.  It will still expand an externally toasted or compressed datum.
 221  * The resulting datum can be accessed using VARSIZE_ANY() and VARDATA_ANY()
 222  * (beware of multiple evaluations in those macros!)
 223  *
 224  * In consumers oblivious to data alignment, call PG_DETOAST_DATUM_PACKED(),
 225  * VARDATA_ANY(), VARSIZE_ANY() and VARSIZE_ANY_EXHDR().  Elsewhere, call
 226  * PG_DETOAST_DATUM(), VARDATA() and VARSIZE().  Directly fetching an int16,
 227  * int32 or wider field in the struct representing the datum layout requires
 228  * aligned data.  memcpy() is alignment-oblivious, as are most operations on
 229  * datatypes, such as text, whose layout struct contains only char fields.
 230  *
 231  * Note: it'd be nice if these could be macros, but I see no way to do that
 232  * without evaluating the arguments multiple times, which is NOT acceptable.
 233  */
 234 extern struct varlena *pg_detoast_datum(struct varlena *datum);
 235 extern struct varlena *pg_detoast_datum_copy(struct varlena *datum);
 236 extern struct varlena *pg_detoast_datum_slice(struct varlena *datum,
 237                                                                                           int32 first, int32 count);
 238 extern struct varlena *pg_detoast_datum_packed(struct varlena *datum);
 239
 240 #define PG_DETOAST_DATUM(datum) \
 241         pg_detoast_datum((struct varlena *) DatumGetPointer(datum))
 242 #define PG_DETOAST_DATUM_COPY(datum) \
 243         pg_detoast_datum_copy((struct varlena *) DatumGetPointer(datum))
 244 #define PG_DETOAST_DATUM_SLICE(datum,f,c) \
 245                 pg_detoast_datum_slice((struct varlena *) DatumGetPointer(datum), \
 246                 (int32) (f), (int32) (c))
 247 /* WARNING -- unaligned pointer */
 248 #define PG_DETOAST_DATUM_PACKED(datum) \
 249         pg_detoast_datum_packed((struct varlena *) DatumGetPointer(datum))
 250
 251 /*
 252  * Support for cleaning up detoasted copies of inputs.  This must only
 253  * be used for pass-by-ref datatypes, and normally would only be used
 254  * for toastable types.  If the given pointer is different from the
 255  * original argument, assume it's a palloc'd detoasted copy, and pfree it.
 256  * NOTE: most functions on toastable types do not have to worry about this,
 257  * but we currently require that support functions for indexes not leak
 258  * memory.
 259  */
 260 #define PG_FREE_IF_COPY(ptr,n) \
 261         do { \
 262                 if ((Pointer) (ptr) != PG_GETARG_POINTER(n)) \
 263                         pfree(ptr); \
 264         } while (0)
 265
 266 /* Macros for fetching arguments of standard types */
 267
 268 #define PG_GETARG_DATUM(n)       (fcinfo->args[n].value)
 269 #define PG_GETARG_INT32(n)       DatumGetInt32(PG_GETARG_DATUM(n))
 270 #define PG_GETARG_UINT32(n)  DatumGetUInt32(PG_GETARG_DATUM(n))
 271 #define PG_GETARG_INT16(n)       DatumGetInt16(PG_GETARG_DATUM(n))
 272 #define PG_GETARG_UINT16(n)  DatumGetUInt16(PG_GETARG_DATUM(n))
 273 #define PG_GETARG_CHAR(n)        DatumGetChar(PG_GETARG_DATUM(n))
 274 #define PG_GETARG_BOOL(n)        DatumGetBool(PG_GETARG_DATUM(n))
 275 #define PG_GETARG_OID(n)         DatumGetObjectId(PG_GETARG_DATUM(n))
 276 #define PG_GETARG_POINTER(n) DatumGetPointer(PG_GETARG_DATUM(n))
 277 #define PG_GETARG_CSTRING(n) DatumGetCString(PG_GETARG_DATUM(n))
 278 #define PG_GETARG_NAME(n)        DatumGetName(PG_GETARG_DATUM(n))
 279 #define PG_GETARG_TRANSACTIONID(n)      DatumGetTransactionId(PG_GETARG_DATUM(n))
 280 /* these macros hide the pass-by-reference-ness of the datatype: */
 281 #define PG_GETARG_FLOAT4(n)  DatumGetFloat4(PG_GETARG_DATUM(n))
 282 #define PG_GETARG_FLOAT8(n)  DatumGetFloat8(PG_GETARG_DATUM(n))
 283 #define PG_GETARG_INT64(n)       DatumGetInt64(PG_GETARG_DATUM(n))
 284 /* use this if you want the raw, possibly-toasted input datum: */
 285 #define PG_GETARG_RAW_VARLENA_P(n)      ((struct varlena *) PG_GETARG_POINTER(n))
 286 /* use this if you want the input datum de-toasted: */
 287 #define PG_GETARG_VARLENA_P(n) PG_DETOAST_DATUM(PG_GETARG_DATUM(n))
 288 /* and this if you can handle 1-byte-header datums: */
 289 #define PG_GETARG_VARLENA_PP(n) PG_DETOAST_DATUM_PACKED(PG_GETARG_DATUM(n))
 290 /* DatumGetFoo macros for varlena types will typically look like this: */
 291 #define DatumGetByteaPP(X)                      ((bytea *) PG_DETOAST_DATUM_PACKED(X))
 292 #define DatumGetTextPP(X)                       ((text *) PG_DETOAST_DATUM_PACKED(X))
 293 #define DatumGetBpCharPP(X)                     ((BpChar *) PG_DETOAST_DATUM_PACKED(X))
 294 #define DatumGetVarCharPP(X)            ((VarChar *) PG_DETOAST_DATUM_PACKED(X))
 295 #define DatumGetHeapTupleHeader(X)      ((HeapTupleHeader) PG_DETOAST_DATUM(X))
 296 /* And we also offer variants that return an OK-to-write copy */
 297 #define DatumGetByteaPCopy(X)           ((bytea *) PG_DETOAST_DATUM_COPY(X))
 298 #define DatumGetTextPCopy(X)            ((text *) PG_DETOAST_DATUM_COPY(X))
 299 #define DatumGetBpCharPCopy(X)          ((BpChar *) PG_DETOAST_DATUM_COPY(X))
 300 #define DatumGetVarCharPCopy(X)         ((VarChar *) PG_DETOAST_DATUM_COPY(X))
 301 #define DatumGetHeapTupleHeaderCopy(X)  ((HeapTupleHeader) PG_DETOAST_DATUM_COPY(X))
 302 /* Variants which return n bytes starting at pos. m */
 303 #define DatumGetByteaPSlice(X,m,n)      ((bytea *) PG_DETOAST_DATUM_SLICE(X,m,n))
 304 #define DatumGetTextPSlice(X,m,n)       ((text *) PG_DETOAST_DATUM_SLICE(X,m,n))
 305 #define DatumGetBpCharPSlice(X,m,n) ((BpChar *) PG_DETOAST_DATUM_SLICE(X,m,n))
 306 #define DatumGetVarCharPSlice(X,m,n) ((VarChar *) PG_DETOAST_DATUM_SLICE(X,m,n))
 307 /* GETARG macros for varlena types will typically look like this: */
 308 #define PG_GETARG_BYTEA_PP(n)           DatumGetByteaPP(PG_GETARG_DATUM(n))
 309 #define PG_GETARG_TEXT_PP(n)            DatumGetTextPP(PG_GETARG_DATUM(n))
 310 #define PG_GETARG_BPCHAR_PP(n)          DatumGetBpCharPP(PG_GETARG_DATUM(n))
 311 #define PG_GETARG_VARCHAR_PP(n)         DatumGetVarCharPP(PG_GETARG_DATUM(n))
 312 #define PG_GETARG_HEAPTUPLEHEADER(n)    DatumGetHeapTupleHeader(PG_GETARG_DATUM(n))
 313 /* And we also offer variants that return an OK-to-write copy */
 314 #define PG_GETARG_BYTEA_P_COPY(n)       DatumGetByteaPCopy(PG_GETARG_DATUM(n))
 315 #define PG_GETARG_TEXT_P_COPY(n)        DatumGetTextPCopy(PG_GETARG_DATUM(n))
 316 #define PG_GETARG_BPCHAR_P_COPY(n)      DatumGetBpCharPCopy(PG_GETARG_DATUM(n))
 317 #define PG_GETARG_VARCHAR_P_COPY(n) DatumGetVarCharPCopy(PG_GETARG_DATUM(n))
 318 #define PG_GETARG_HEAPTUPLEHEADER_COPY(n)       DatumGetHeapTupleHeaderCopy(PG_GETARG_DATUM(n))
 319 /* And a b-byte slice from position a -also OK to write */
 320 #define PG_GETARG_BYTEA_P_SLICE(n,a,b) DatumGetByteaPSlice(PG_GETARG_DATUM(n),a,b)
 321 #define PG_GETARG_TEXT_P_SLICE(n,a,b)  DatumGetTextPSlice(PG_GETARG_DATUM(n),a,b)
 322 #define PG_GETARG_BPCHAR_P_SLICE(n,a,b) DatumGetBpCharPSlice(PG_GETARG_DATUM(n),a,b)
 323 #define PG_GETARG_VARCHAR_P_SLICE(n,a,b) DatumGetVarCharPSlice(PG_GETARG_DATUM(n),a,b)
 324 /*
 325  * Obsolescent variants that guarantee INT alignment for the return value.
 326  * Few operations on these particular types need alignment, mainly operations
 327  * that cast the VARDATA pointer to a type like int16[].  Most code should use
 328  * the ...PP(X) counterpart.  Nonetheless, these appear frequently in code
 329  * predating the PostgreSQL 8.3 introduction of the ...PP(X) variants.
 330  */
 331 #define DatumGetByteaP(X)                       ((bytea *) PG_DETOAST_DATUM(X))
 332 #define DatumGetTextP(X)                        ((text *) PG_DETOAST_DATUM(X))
 333 #define DatumGetBpCharP(X)                      ((BpChar *) PG_DETOAST_DATUM(X))
 334 #define DatumGetVarCharP(X)                     ((VarChar *) PG_DETOAST_DATUM(X))
 335 #define PG_GETARG_BYTEA_P(n)            DatumGetByteaP(PG_GETARG_DATUM(n))
 336 #define PG_GETARG_TEXT_P(n)                     DatumGetTextP(PG_GETARG_DATUM(n))
 337 #define PG_GETARG_BPCHAR_P(n)           DatumGetBpCharP(PG_GETARG_DATUM(n))
 338 #define PG_GETARG_VARCHAR_P(n)          DatumGetVarCharP(PG_GETARG_DATUM(n))
 339
 340 /* To access options from opclass support functions use this: */
 341 #define PG_HAS_OPCLASS_OPTIONS()        has_fn_opclass_options(fcinfo->flinfo)
 342 #define PG_GET_OPCLASS_OPTIONS()        get_fn_opclass_options(fcinfo->flinfo)
 343
 344 /* To return a NULL do this: */
 345 #define PG_RETURN_NULL()  \
 346         do { fcinfo->isnull = true; return (Datum) 0; } while (0)
 347
 348 /* A few internal functions return void (which is not the same as NULL!) */
 349 #define PG_RETURN_VOID()         return (Datum) 0
 350
 351 /* Macros for returning results of standard types */
 352
 353 #define PG_RETURN_DATUM(x)       return (x)
 354 #define PG_RETURN_INT32(x)       return Int32GetDatum(x)
 355 #define PG_RETURN_UINT32(x)  return UInt32GetDatum(x)
 356 #define PG_RETURN_INT16(x)       return Int16GetDatum(x)
 357 #define PG_RETURN_UINT16(x)  return UInt16GetDatum(x)
 358 #define PG_RETURN_CHAR(x)        return CharGetDatum(x)
 359 #define PG_RETURN_BOOL(x)        return BoolGetDatum(x)
 360 #define PG_RETURN_OID(x)         return ObjectIdGetDatum(x)
 361 #define PG_RETURN_POINTER(x) return PointerGetDatum(x)
 362 #define PG_RETURN_CSTRING(x) return CStringGetDatum(x)
 363 #define PG_RETURN_NAME(x)        return NameGetDatum(x)
 364 #define PG_RETURN_TRANSACTIONID(x)      return TransactionIdGetDatum(x)
 365 /* these macros hide the pass-by-reference-ness of the datatype: */
 366 #define PG_RETURN_FLOAT4(x)  return Float4GetDatum(x)
 367 #define PG_RETURN_FLOAT8(x)  return Float8GetDatum(x)
 368 #define PG_RETURN_INT64(x)       return Int64GetDatum(x)
 369 #define PG_RETURN_UINT64(x)  return UInt64GetDatum(x)
 370 /* RETURN macros for other pass-by-ref types will typically look like this: */
 371 #define PG_RETURN_BYTEA_P(x)   PG_RETURN_POINTER(x)
 372 #define PG_RETURN_TEXT_P(x)    PG_RETURN_POINTER(x)
 373 #define PG_RETURN_BPCHAR_P(x)  PG_RETURN_POINTER(x)
 374 #define PG_RETURN_VARCHAR_P(x) PG_RETURN_POINTER(x)
 375 #define PG_RETURN_HEAPTUPLEHEADER(x)  return HeapTupleHeaderGetDatum(x)
 376
 377
 378 /*-------------------------------------------------------------------------
 379  *              Support for detecting call convention of dynamically-loaded functions
 380  *
 381  * Dynamically loaded functions currently can only use the version-1 ("new
 382  * style") calling convention.  Version-0 ("old style") is not supported
 383  * anymore.  Version 1 is the call convention defined in this header file, and
 384  * must be accompanied by the macro call
 385  *
 386  *              PG_FUNCTION_INFO_V1(function_name);
 387  *
 388  * Note that internal functions do not need this decoration since they are
 389  * assumed to be version-1.
 390  *
 391  *-------------------------------------------------------------------------
 392  */
 393
 394 typedef struct
 395 {
 396         int                     api_version;    /* specifies call convention version number */
 397         /* More fields may be added later, for version numbers > 1. */
 398 } Pg_finfo_record;
 399
 400 /* Expected signature of an info function */
 401 typedef const Pg_finfo_record *(*PGFInfoFunction) (void);
 402
 403 /*
 404  *      Macro to build an info function associated with the given function name.
 405  *
 406  *      As a convenience, also provide an "extern" declaration for the given
 407  *      function name, so that writers of C functions need not write that too.
 408  *
 409  *      On Windows, the function and info function must be exported.  Our normal
 410  *      build processes take care of that via .DEF files or --export-all-symbols.
 411  *      Module authors using a different build process might need to manually
 412  *      declare the function PGDLLEXPORT.  We do that automatically here for the
 413  *      info function, since authors shouldn't need to be explicitly aware of it.
 414  */
 415 #define PG_FUNCTION_INFO_V1(funcname) \
 416 extern PGDLLEXPORT Datum funcname(PG_FUNCTION_ARGS); \
 417 extern PGDLLEXPORT const Pg_finfo_record * CppConcat(pg_finfo_,funcname)(void); \
 418 const Pg_finfo_record * \
 419 CppConcat(pg_finfo_,funcname) (void) \
 420 { \
 421         static const Pg_finfo_record my_finfo = { 1 }; \
 422         return &my_finfo; \
 423 } \
 424 extern int no_such_variable
 425
 426
 427 /*
 428  * Declare _PG_init/_PG_fini centrally. Historically each shared library had
 429  * its own declaration; but now that we want to mark these PGDLLEXPORT, using
 430  * central declarations avoids each extension having to add that.  Any
 431  * existing declarations in extensions will continue to work if fmgr.h is
 432  * included before them, otherwise compilation for Windows will fail.
 433  */
 434 extern PGDLLEXPORT void _PG_init(void);
 435 extern PGDLLEXPORT void _PG_fini(void);
 436
 437
 438 /*-------------------------------------------------------------------------
 439  *              Support for verifying backend compatibility of loaded modules
 440  *
 441  * We require dynamically-loaded modules to include the macro call
 442  *              PG_MODULE_MAGIC;
 443  * so that we can check for obvious incompatibility, such as being compiled
 444  * for a different major PostgreSQL version.
 445  *
 446  * To compile with versions of PostgreSQL that do not support this,
 447  * you may put an #ifdef/#endif test around it.  Note that in a multiple-
 448  * source-file module, the macro call should only appear once.
 449  *
 450  * The specific items included in the magic block are intended to be ones that
 451  * are custom-configurable and especially likely to break dynamically loaded
 452  * modules if they were compiled with other values.  Also, the length field
 453  * can be used to detect definition changes.
 454  *
 455  * Note: we compare magic blocks with memcmp(), so there had better not be
 456  * any alignment pad bytes in them.
 457  *
 458  * Note: when changing the contents of magic blocks, be sure to adjust the
 459  * incompatible_module_error() function in dfmgr.c.
 460  *-------------------------------------------------------------------------
 461  */
 462
 463 /* Definition of the magic block structure */
 464 typedef struct
 465 {
 466         int                     len;                    /* sizeof(this struct) */
 467         int                     version;                /* PostgreSQL major version */
 468         int                     funcmaxargs;    /* FUNC_MAX_ARGS */
 469         int                     indexmaxkeys;   /* INDEX_MAX_KEYS */
 470         int                     namedatalen;    /* NAMEDATALEN */
 471         int                     float8byval;    /* FLOAT8PASSBYVAL */
 472         char            abi_extra[32];  /* see pg_config_manual.h */
 473 } Pg_magic_struct;
 474
 475 /* The actual data block contents */
 476 #define PG_MODULE_MAGIC_DATA \
 477 { \
 478         sizeof(Pg_magic_struct), \
 479         PG_VERSION_NUM / 100, \
 480         FUNC_MAX_ARGS, \
 481         INDEX_MAX_KEYS, \
 482         NAMEDATALEN, \
 483         FLOAT8PASSBYVAL, \
 484         FMGR_ABI_EXTRA, \
 485 }
 486
 487 StaticAssertDecl(sizeof(FMGR_ABI_EXTRA) <= sizeof(((Pg_magic_struct *) 0)->abi_extra),
 488                                  "FMGR_ABI_EXTRA too long");
 489
 490 /*
 491  * Declare the module magic function.  It needs to be a function as the dlsym
 492  * in the backend is only guaranteed to work on functions, not data
 493  */
 494 typedef const Pg_magic_struct *(*PGModuleMagicFunction) (void);
 495
 496 #define PG_MAGIC_FUNCTION_NAME Pg_magic_func
 497 #define PG_MAGIC_FUNCTION_NAME_STRING "Pg_magic_func"
 498
 499 #define PG_MODULE_MAGIC \
 500 extern PGDLLEXPORT const Pg_magic_struct *PG_MAGIC_FUNCTION_NAME(void); \
 501 const Pg_magic_struct * \
 502 PG_MAGIC_FUNCTION_NAME(void) \
 503 { \
 504         static const Pg_magic_struct Pg_magic_data = PG_MODULE_MAGIC_DATA; \
 505         return &Pg_magic_data; \
 506 } \
 507 extern int no_such_variable
 508
 509
 510 /*-------------------------------------------------------------------------
 511  *              Support routines and macros for callers of fmgr-compatible functions
 512  *-------------------------------------------------------------------------
 513  */
 514
 515 /* These are for invocation of a specifically named function with a
 516  * directly-computed parameter list.  Note that neither arguments nor result
 517  * are allowed to be NULL.  Also, the function cannot be one that needs to
 518  * look at FmgrInfo, since there won't be any.
 519  */
 520 extern Datum DirectFunctionCall1Coll(PGFunction func, Oid collation,
 521                                                                          Datum arg1);
 522 extern Datum DirectFunctionCall2Coll(PGFunction func, Oid collation,
 523                                                                          Datum arg1, Datum arg2);
 524 extern Datum DirectFunctionCall3Coll(PGFunction func, Oid collation,
 525                                                                          Datum arg1, Datum arg2,
 526                                                                          Datum arg3);
 527 extern Datum DirectFunctionCall4Coll(PGFunction func, Oid collation,
 528                                                                          Datum arg1, Datum arg2,
 529                                                                          Datum arg3, Datum arg4);
 530 extern Datum DirectFunctionCall5Coll(PGFunction func, Oid collation,
 531                                                                          Datum arg1, Datum arg2,
 532                                                                          Datum arg3, Datum arg4, Datum arg5);
 533 extern Datum DirectFunctionCall6Coll(PGFunction func, Oid collation,
 534                                                                          Datum arg1, Datum arg2,
 535                                                                          Datum arg3, Datum arg4, Datum arg5,
 536                                                                          Datum arg6);
 537 extern Datum DirectFunctionCall7Coll(PGFunction func, Oid collation,
 538                                                                          Datum arg1, Datum arg2,
 539                                                                          Datum arg3, Datum arg4, Datum arg5,
 540                                                                          Datum arg6, Datum arg7);
 541 extern Datum DirectFunctionCall8Coll(PGFunction func, Oid collation,
 542                                                                          Datum arg1, Datum arg2,
 543                                                                          Datum arg3, Datum arg4, Datum arg5,
 544                                                                          Datum arg6, Datum arg7, Datum arg8);
 545 extern Datum DirectFunctionCall9Coll(PGFunction func, Oid collation,
 546                                                                          Datum arg1, Datum arg2,
 547                                                                          Datum arg3, Datum arg4, Datum arg5,
 548                                                                          Datum arg6, Datum arg7, Datum arg8,
 549                                                                          Datum arg9);
 550
 551 /*
 552  * These functions work like the DirectFunctionCall functions except that
 553  * they use the flinfo parameter to initialise the fcinfo for the call.
 554  * It's recommended that the callee only use the fn_extra and fn_mcxt
 555  * fields, as other fields will typically describe the calling function
 556  * not the callee.  Conversely, the calling function should not have
 557  * used fn_extra, unless its use is known to be compatible with the callee's.
 558  */
 559 extern Datum CallerFInfoFunctionCall1(PGFunction func, FmgrInfo *flinfo,
 560                                                                           Oid collation, Datum arg1);
 561 extern Datum CallerFInfoFunctionCall2(PGFunction func, FmgrInfo *flinfo,
 562                                                                           Oid collation, Datum arg1, Datum arg2);
 563
 564 /* These are for invocation of a previously-looked-up function with a
 565  * directly-computed parameter list.  Note that neither arguments nor result
 566  * are allowed to be NULL.
 567  */
 568 extern Datum FunctionCall0Coll(FmgrInfo *flinfo, Oid collation);
 569 extern Datum FunctionCall1Coll(FmgrInfo *flinfo, Oid collation,
 570                                                            Datum arg1);
 571 extern Datum FunctionCall2Coll(FmgrInfo *flinfo, Oid collation,
 572                                                            Datum arg1, Datum arg2);
 573 extern Datum FunctionCall3Coll(FmgrInfo *flinfo, Oid collation,
 574                                                            Datum arg1, Datum arg2,
 575                                                            Datum arg3);
 576 extern Datum FunctionCall4Coll(FmgrInfo *flinfo, Oid collation,
 577                                                            Datum arg1, Datum arg2,
 578                                                            Datum arg3, Datum arg4);
 579 extern Datum FunctionCall5Coll(FmgrInfo *flinfo, Oid collation,
 580                                                            Datum arg1, Datum arg2,
 581                                                            Datum arg3, Datum arg4, Datum arg5);
 582 extern Datum FunctionCall6Coll(FmgrInfo *flinfo, Oid collation,
 583                                                            Datum arg1, Datum arg2,
 584                                                            Datum arg3, Datum arg4, Datum arg5,
 585                                                            Datum arg6);
 586 extern Datum FunctionCall7Coll(FmgrInfo *flinfo, Oid collation,
 587                                                            Datum arg1, Datum arg2,
 588                                                            Datum arg3, Datum arg4, Datum arg5,
 589                                                            Datum arg6, Datum arg7);
 590 extern Datum FunctionCall8Coll(FmgrInfo *flinfo, Oid collation,
 591                                                            Datum arg1, Datum arg2,
 592                                                            Datum arg3, Datum arg4, Datum arg5,
 593                                                            Datum arg6, Datum arg7, Datum arg8);
 594 extern Datum FunctionCall9Coll(FmgrInfo *flinfo, Oid collation,
 595                                                            Datum arg1, Datum arg2,
 596                                                            Datum arg3, Datum arg4, Datum arg5,
 597                                                            Datum arg6, Datum arg7, Datum arg8,
 598                                                            Datum arg9);
 599
 600 /* These are for invocation of a function identified by OID with a
 601  * directly-computed parameter list.  Note that neither arguments nor result
 602  * are allowed to be NULL.  These are essentially fmgr_info() followed by
 603  * FunctionCallN().  If the same function is to be invoked repeatedly, do the
 604  * fmgr_info() once and then use FunctionCallN().
 605  */
 606 extern Datum OidFunctionCall0Coll(Oid functionId, Oid collation);
 607 extern Datum OidFunctionCall1Coll(Oid functionId, Oid collation,
 608                                                                   Datum arg1);
 609 extern Datum OidFunctionCall2Coll(Oid functionId, Oid collation,
 610                                                                   Datum arg1, Datum arg2);
 611 extern Datum OidFunctionCall3Coll(Oid functionId, Oid collation,
 612                                                                   Datum arg1, Datum arg2,
 613                                                                   Datum arg3);
 614 extern Datum OidFunctionCall4Coll(Oid functionId, Oid collation,
 615                                                                   Datum arg1, Datum arg2,
 616                                                                   Datum arg3, Datum arg4);
 617 extern Datum OidFunctionCall5Coll(Oid functionId, Oid collation,
 618                                                                   Datum arg1, Datum arg2,
 619                                                                   Datum arg3, Datum arg4, Datum arg5);
 620 extern Datum OidFunctionCall6Coll(Oid functionId, Oid collation,
 621                                                                   Datum arg1, Datum arg2,
 622                                                                   Datum arg3, Datum arg4, Datum arg5,
 623                                                                   Datum arg6);
 624 extern Datum OidFunctionCall7Coll(Oid functionId, Oid collation,
 625                                                                   Datum arg1, Datum arg2,
 626                                                                   Datum arg3, Datum arg4, Datum arg5,
 627                                                                   Datum arg6, Datum arg7);
 628 extern Datum OidFunctionCall8Coll(Oid functionId, Oid collation,
 629                                                                   Datum arg1, Datum arg2,
 630                                                                   Datum arg3, Datum arg4, Datum arg5,
 631                                                                   Datum arg6, Datum arg7, Datum arg8);
 632 extern Datum OidFunctionCall9Coll(Oid functionId, Oid collation,
 633                                                                   Datum arg1, Datum arg2,
 634                                                                   Datum arg3, Datum arg4, Datum arg5,
 635                                                                   Datum arg6, Datum arg7, Datum arg8,
 636                                                                   Datum arg9);
 637
 638 /* These macros allow the collation argument to be omitted (with a default of
 639  * InvalidOid, ie, no collation).  They exist mostly for backwards
 640  * compatibility of source code.
 641  */
 642 #define DirectFunctionCall1(func, arg1) \
 643         DirectFunctionCall1Coll(func, InvalidOid, arg1)
 644 #define DirectFunctionCall2(func, arg1, arg2) \
 645         DirectFunctionCall2Coll(func, InvalidOid, arg1, arg2)
 646 #define DirectFunctionCall3(func, arg1, arg2, arg3) \
 647         DirectFunctionCall3Coll(func, InvalidOid, arg1, arg2, arg3)
 648 #define DirectFunctionCall4(func, arg1, arg2, arg3, arg4) \
 649         DirectFunctionCall4Coll(func, InvalidOid, arg1, arg2, arg3, arg4)
 650 #define DirectFunctionCall5(func, arg1, arg2, arg3, arg4, arg5) \
 651         DirectFunctionCall5Coll(func, InvalidOid, arg1, arg2, arg3, arg4, arg5)
 652 #define DirectFunctionCall6(func, arg1, arg2, arg3, arg4, arg5, arg6) \
 653         DirectFunctionCall6Coll(func, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6)
 654 #define DirectFunctionCall7(func, arg1, arg2, arg3, arg4, arg5, arg6, arg7) \
 655         DirectFunctionCall7Coll(func, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
 656 #define DirectFunctionCall8(func, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) \
 657         DirectFunctionCall8Coll(func, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
 658 #define DirectFunctionCall9(func, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) \
 659         DirectFunctionCall9Coll(func, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
 660 #define FunctionCall1(flinfo, arg1) \
 661         FunctionCall1Coll(flinfo, InvalidOid, arg1)
 662 #define FunctionCall2(flinfo, arg1, arg2) \
 663         FunctionCall2Coll(flinfo, InvalidOid, arg1, arg2)
 664 #define FunctionCall3(flinfo, arg1, arg2, arg3) \
 665         FunctionCall3Coll(flinfo, InvalidOid, arg1, arg2, arg3)
 666 #define FunctionCall4(flinfo, arg1, arg2, arg3, arg4) \
 667         FunctionCall4Coll(flinfo, InvalidOid, arg1, arg2, arg3, arg4)
 668 #define FunctionCall5(flinfo, arg1, arg2, arg3, arg4, arg5) \
 669         FunctionCall5Coll(flinfo, InvalidOid, arg1, arg2, arg3, arg4, arg5)
 670 #define FunctionCall6(flinfo, arg1, arg2, arg3, arg4, arg5, arg6) \
 671         FunctionCall6Coll(flinfo, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6)
 672 #define FunctionCall7(flinfo, arg1, arg2, arg3, arg4, arg5, arg6, arg7) \
 673         FunctionCall7Coll(flinfo, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
 674 #define FunctionCall8(flinfo, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) \
 675         FunctionCall8Coll(flinfo, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
 676 #define FunctionCall9(flinfo, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) \
 677         FunctionCall9Coll(flinfo, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
 678 #define OidFunctionCall0(functionId) \
 679         OidFunctionCall0Coll(functionId, InvalidOid)
 680 #define OidFunctionCall1(functionId, arg1) \
 681         OidFunctionCall1Coll(functionId, InvalidOid, arg1)
 682 #define OidFunctionCall2(functionId, arg1, arg2) \
 683         OidFunctionCall2Coll(functionId, InvalidOid, arg1, arg2)
 684 #define OidFunctionCall3(functionId, arg1, arg2, arg3) \
 685         OidFunctionCall3Coll(functionId, InvalidOid, arg1, arg2, arg3)
 686 #define OidFunctionCall4(functionId, arg1, arg2, arg3, arg4) \
 687         OidFunctionCall4Coll(functionId, InvalidOid, arg1, arg2, arg3, arg4)
 688 #define OidFunctionCall5(functionId, arg1, arg2, arg3, arg4, arg5) \
 689         OidFunctionCall5Coll(functionId, InvalidOid, arg1, arg2, arg3, arg4, arg5)
 690 #define OidFunctionCall6(functionId, arg1, arg2, arg3, arg4, arg5, arg6) \
 691         OidFunctionCall6Coll(functionId, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6)
 692 #define OidFunctionCall7(functionId, arg1, arg2, arg3, arg4, arg5, arg6, arg7) \
 693         OidFunctionCall7Coll(functionId, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
 694 #define OidFunctionCall8(functionId, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) \
 695         OidFunctionCall8Coll(functionId, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
 696 #define OidFunctionCall9(functionId, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) \
 697         OidFunctionCall9Coll(functionId, InvalidOid, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
 698
 699
 700 /* Special cases for convenient invocation of datatype I/O functions. */
 701 extern Datum InputFunctionCall(FmgrInfo *flinfo, char *str,
 702                                                            Oid typioparam, int32 typmod);
 703 extern bool InputFunctionCallSafe(FmgrInfo *flinfo, char *str,
 704                                                                   Oid typioparam, int32 typmod,
 705                                                                   fmNodePtr escontext,
 706                                                                   Datum *result);
 707 extern bool DirectInputFunctionCallSafe(PGFunction func, char *str,
 708                                                                                 Oid typioparam, int32 typmod,
 709                                                                                 fmNodePtr escontext,
 710                                                                                 Datum *result);
 711 extern Datum OidInputFunctionCall(Oid functionId, char *str,
 712                                                                   Oid typioparam, int32 typmod);
 713 extern char *OutputFunctionCall(FmgrInfo *flinfo, Datum val);
 714 extern char *OidOutputFunctionCall(Oid functionId, Datum val);
 715 extern Datum ReceiveFunctionCall(FmgrInfo *flinfo, fmStringInfo buf,
 716                                                                  Oid typioparam, int32 typmod);
 717 extern Datum OidReceiveFunctionCall(Oid functionId, fmStringInfo buf,
 718                                                                         Oid typioparam, int32 typmod);
 719 extern bytea *SendFunctionCall(FmgrInfo *flinfo, Datum val);
 720 extern bytea *OidSendFunctionCall(Oid functionId, Datum val);
 721
 722
 723 /*
 724  * Routines in fmgr.c
 725  */
 726 extern const Pg_finfo_record *fetch_finfo_record(void *filehandle, const char *funcname);
 727 extern Oid      fmgr_internal_function(const char *proname);
 728 extern Oid      get_fn_expr_rettype(FmgrInfo *flinfo);
 729 extern Oid      get_fn_expr_argtype(FmgrInfo *flinfo, int argnum);
 730 extern Oid      get_call_expr_argtype(fmNodePtr expr, int argnum);
 731 extern bool get_fn_expr_arg_stable(FmgrInfo *flinfo, int argnum);
 732 extern bool get_call_expr_arg_stable(fmNodePtr expr, int argnum);
 733 extern bool get_fn_expr_variadic(FmgrInfo *flinfo);
 734 extern bytea *get_fn_opclass_options(FmgrInfo *flinfo);
 735 extern bool has_fn_opclass_options(FmgrInfo *flinfo);
 736 extern void set_fn_opclass_options(FmgrInfo *flinfo, bytea *options);
 737 extern bool CheckFunctionValidatorAccess(Oid validatorOid, Oid functionOid);
 738
 739 /*
 740  * Routines in dfmgr.c
 741  */
 742 extern PGDLLIMPORT char *Dynamic_library_path;
 743
 744 extern void *load_external_function(const char *filename, const char *funcname,
 745                                                                         bool signalNotFound, void **filehandle);
 746 extern void *lookup_external_function(void *filehandle, const char *funcname);
 747 extern void load_file(const char *filename, bool restricted);
 748 extern void **find_rendezvous_variable(const char *varName);
 749 extern Size EstimateLibraryStateSpace(void);
 750 extern void SerializeLibraryState(Size maxsize, char *start_address);
 751 extern void RestoreLibraryState(char *start_address);
 752
 753 /*
 754  * Support for aggregate functions
 755  *
 756  * These are actually in executor/nodeAgg.c, but we declare them here since
 757  * the whole point is for callers to not be overly friendly with nodeAgg.
 758  */
 759
 760 /* AggCheckCallContext can return one of the following codes, or 0: */
 761 #define AGG_CONTEXT_AGGREGATE   1       /* regular aggregate */
 762 #define AGG_CONTEXT_WINDOW              2       /* window function */
 763
 764 extern int      AggCheckCallContext(FunctionCallInfo fcinfo,
 765                                                                 MemoryContext *aggcontext);
 766 extern fmAggrefPtr AggGetAggref(FunctionCallInfo fcinfo);
 767 extern MemoryContext AggGetTempMemoryContext(FunctionCallInfo fcinfo);
 768 extern bool AggStateIsShared(FunctionCallInfo fcinfo);
 769 extern void AggRegisterCallback(FunctionCallInfo fcinfo,
 770                                                                 fmExprContextCallbackFunction func,
 771                                                                 Datum arg);
 772
 773 /*
 774  * We allow plugin modules to hook function entry/exit.  This is intended
 775  * as support for loadable security policy modules, which may want to
 776  * perform additional privilege checks on function entry or exit, or to do
 777  * other internal bookkeeping.  To make this possible, such modules must be
 778  * able not only to support normal function entry and exit, but also to trap
 779  * the case where we bail out due to an error; and they must also be able to
 780  * prevent inlining.
 781  */
 782 typedef enum FmgrHookEventType
 783 {
 784         FHET_START,
 785         FHET_END,
 786         FHET_ABORT,
 787 } FmgrHookEventType;
 788
 789 typedef bool (*needs_fmgr_hook_type) (Oid fn_oid);
 790
 791 typedef void (*fmgr_hook_type) (FmgrHookEventType event,
 792                                                                 FmgrInfo *flinfo, Datum *arg);
 793
 794 extern PGDLLIMPORT needs_fmgr_hook_type needs_fmgr_hook;
 795 extern PGDLLIMPORT fmgr_hook_type fmgr_hook;
 796
 797 #define FmgrHookIsNeeded(fn_oid)                                                        \
 798         (!needs_fmgr_hook ? false : (*needs_fmgr_hook)(fn_oid))
 799
 800 #endif                                                  /* FMGR_H */