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