PostgreSQL Source Code  git master
postgres.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * postgres.h
4  * Primary include file for PostgreSQL server .c files
5  *
6  * This should be the first file included by PostgreSQL backend modules.
7  * Client-side code should include postgres_fe.h instead.
8  *
9  *
10  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
11  * Portions Copyright (c) 1995, Regents of the University of California
12  *
13  * src/include/postgres.h
14  *
15  *-------------------------------------------------------------------------
16  */
17 /*
18  *----------------------------------------------------------------
19  * TABLE OF CONTENTS
20  *
21  * When adding stuff to this file, please try to put stuff
22  * into the relevant section, or add new sections as appropriate.
23  *
24  * section description
25  * ------- ------------------------------------------------
26  * 1) Datum type + support functions
27  * 2) miscellaneous
28  *
29  * NOTES
30  *
31  * In general, this file should contain declarations that are widely needed
32  * in the backend environment, but are of no interest outside the backend.
33  *
34  * Simple type definitions live in c.h, where they are shared with
35  * postgres_fe.h. We do that since those type definitions are needed by
36  * frontend modules that want to deal with binary data transmission to or
37  * from the backend. Type definitions in this file should be for
38  * representations that never escape the backend, such as Datum.
39  *
40  *----------------------------------------------------------------
41  */
42 #ifndef POSTGRES_H
43 #define POSTGRES_H
44 
45 #include "c.h"
46 #include "utils/elog.h"
47 #include "utils/palloc.h"
48 
49 /* ----------------------------------------------------------------
50  * Section 1: Datum type + support functions
51  * ----------------------------------------------------------------
52  */
53 
54 /*
55  * A Datum contains either a value of a pass-by-value type or a pointer to a
56  * value of a pass-by-reference type. Therefore, we require:
57  *
58  * sizeof(Datum) == sizeof(void *) == 4 or 8
59  *
60  * The functions below and the analogous functions for other types should be used to
61  * convert between a Datum and the appropriate C type.
62  */
63 
64 typedef uintptr_t Datum;
65 
66 /*
67  * A NullableDatum is used in places where both a Datum and its nullness needs
68  * to be stored. This can be more efficient than storing datums and nullness
69  * in separate arrays, due to better spatial locality, even if more space may
70  * be wasted due to padding.
71  */
72 typedef struct NullableDatum
73 {
74 #define FIELDNO_NULLABLE_DATUM_DATUM 0
76 #define FIELDNO_NULLABLE_DATUM_ISNULL 1
77  bool isnull;
78  /* due to alignment padding this could be used for flags for free */
80 
81 #define SIZEOF_DATUM SIZEOF_VOID_P
82 
83 /*
84  * DatumGetBool
85  * Returns boolean value of a datum.
86  *
87  * Note: any nonzero value will be considered true.
88  */
89 static inline bool
91 {
92  return (X != 0);
93 }
94 
95 /*
96  * BoolGetDatum
97  * Returns datum representation for a boolean.
98  *
99  * Note: any nonzero value will be considered true.
100  */
101 static inline Datum
103 {
104  return (Datum) (X ? 1 : 0);
105 }
106 
107 /*
108  * DatumGetChar
109  * Returns character value of a datum.
110  */
111 static inline char
113 {
114  return (char) X;
115 }
116 
117 /*
118  * CharGetDatum
119  * Returns datum representation for a character.
120  */
121 static inline Datum
123 {
124  return (Datum) X;
125 }
126 
127 /*
128  * Int8GetDatum
129  * Returns datum representation for an 8-bit integer.
130  */
131 static inline Datum
133 {
134  return (Datum) X;
135 }
136 
137 /*
138  * DatumGetUInt8
139  * Returns 8-bit unsigned integer value of a datum.
140  */
141 static inline uint8
143 {
144  return (uint8) X;
145 }
146 
147 /*
148  * UInt8GetDatum
149  * Returns datum representation for an 8-bit unsigned integer.
150  */
151 static inline Datum
153 {
154  return (Datum) X;
155 }
156 
157 /*
158  * DatumGetInt16
159  * Returns 16-bit integer value of a datum.
160  */
161 static inline int16
163 {
164  return (int16) X;
165 }
166 
167 /*
168  * Int16GetDatum
169  * Returns datum representation for a 16-bit integer.
170  */
171 static inline Datum
173 {
174  return (Datum) X;
175 }
176 
177 /*
178  * DatumGetUInt16
179  * Returns 16-bit unsigned integer value of a datum.
180  */
181 static inline uint16
183 {
184  return (uint16) X;
185 }
186 
187 /*
188  * UInt16GetDatum
189  * Returns datum representation for a 16-bit unsigned integer.
190  */
191 static inline Datum
193 {
194  return (Datum) X;
195 }
196 
197 /*
198  * DatumGetInt32
199  * Returns 32-bit integer value of a datum.
200  */
201 static inline int32
203 {
204  return (int32) X;
205 }
206 
207 /*
208  * Int32GetDatum
209  * Returns datum representation for a 32-bit integer.
210  */
211 static inline Datum
213 {
214  return (Datum) X;
215 }
216 
217 /*
218  * DatumGetUInt32
219  * Returns 32-bit unsigned integer value of a datum.
220  */
221 static inline uint32
223 {
224  return (uint32) X;
225 }
226 
227 /*
228  * UInt32GetDatum
229  * Returns datum representation for a 32-bit unsigned integer.
230  */
231 static inline Datum
233 {
234  return (Datum) X;
235 }
236 
237 /*
238  * DatumGetObjectId
239  * Returns object identifier value of a datum.
240  */
241 static inline Oid
243 {
244  return (Oid) X;
245 }
246 
247 /*
248  * ObjectIdGetDatum
249  * Returns datum representation for an object identifier.
250  */
251 static inline Datum
253 {
254  return (Datum) X;
255 }
256 
257 /*
258  * DatumGetTransactionId
259  * Returns transaction identifier value of a datum.
260  */
261 static inline TransactionId
263 {
264  return (TransactionId) X;
265 }
266 
267 /*
268  * TransactionIdGetDatum
269  * Returns datum representation for a transaction identifier.
270  */
271 static inline Datum
273 {
274  return (Datum) X;
275 }
276 
277 /*
278  * MultiXactIdGetDatum
279  * Returns datum representation for a multixact identifier.
280  */
281 static inline Datum
283 {
284  return (Datum) X;
285 }
286 
287 /*
288  * DatumGetCommandId
289  * Returns command identifier value of a datum.
290  */
291 static inline CommandId
293 {
294  return (CommandId) X;
295 }
296 
297 /*
298  * CommandIdGetDatum
299  * Returns datum representation for a command identifier.
300  */
301 static inline Datum
303 {
304  return (Datum) X;
305 }
306 
307 /*
308  * DatumGetPointer
309  * Returns pointer value of a datum.
310  */
311 static inline Pointer
313 {
314  return (Pointer) X;
315 }
316 
317 /*
318  * PointerGetDatum
319  * Returns datum representation for a pointer.
320  */
321 static inline Datum
322 PointerGetDatum(const void *X)
323 {
324  return (Datum) X;
325 }
326 
327 /*
328  * DatumGetCString
329  * Returns C string (null-terminated string) value of a datum.
330  *
331  * Note: C string is not a full-fledged Postgres type at present,
332  * but type input functions use this conversion for their inputs.
333  */
334 static inline char *
336 {
337  return (char *) DatumGetPointer(X);
338 }
339 
340 /*
341  * CStringGetDatum
342  * Returns datum representation for a C string (null-terminated string).
343  *
344  * Note: C string is not a full-fledged Postgres type at present,
345  * but type output functions use this conversion for their outputs.
346  * Note: CString is pass-by-reference; caller must ensure the pointed-to
347  * value has adequate lifetime.
348  */
349 static inline Datum
350 CStringGetDatum(const char *X)
351 {
352  return PointerGetDatum(X);
353 }
354 
355 /*
356  * DatumGetName
357  * Returns name value of a datum.
358  */
359 static inline Name
361 {
362  return (Name) DatumGetPointer(X);
363 }
364 
365 /*
366  * NameGetDatum
367  * Returns datum representation for a name.
368  *
369  * Note: Name is pass-by-reference; caller must ensure the pointed-to
370  * value has adequate lifetime.
371  */
372 static inline Datum
374 {
375  return CStringGetDatum(NameStr(*X));
376 }
377 
378 /*
379  * DatumGetInt64
380  * Returns 64-bit integer value of a datum.
381  *
382  * Note: this function hides whether int64 is pass by value or by reference.
383  */
384 static inline int64
386 {
387 #ifdef USE_FLOAT8_BYVAL
388  return (int64) X;
389 #else
390  return *((int64 *) DatumGetPointer(X));
391 #endif
392 }
393 
394 /*
395  * Int64GetDatum
396  * Returns datum representation for a 64-bit integer.
397  *
398  * Note: if int64 is pass by reference, this function returns a reference
399  * to palloc'd space.
400  */
401 #ifdef USE_FLOAT8_BYVAL
402 static inline Datum
403 Int64GetDatum(int64 X)
404 {
405  return (Datum) X;
406 }
407 #else
408 extern Datum Int64GetDatum(int64 X);
409 #endif
410 
411 
412 /*
413  * DatumGetUInt64
414  * Returns 64-bit unsigned integer value of a datum.
415  *
416  * Note: this function hides whether int64 is pass by value or by reference.
417  */
418 static inline uint64
420 {
421 #ifdef USE_FLOAT8_BYVAL
422  return (uint64) X;
423 #else
424  return *((uint64 *) DatumGetPointer(X));
425 #endif
426 }
427 
428 /*
429  * UInt64GetDatum
430  * Returns datum representation for a 64-bit unsigned integer.
431  *
432  * Note: if int64 is pass by reference, this function returns a reference
433  * to palloc'd space.
434  */
435 static inline Datum
436 UInt64GetDatum(uint64 X)
437 {
438 #ifdef USE_FLOAT8_BYVAL
439  return (Datum) X;
440 #else
441  return Int64GetDatum((int64) X);
442 #endif
443 }
444 
445 /*
446  * Float <-> Datum conversions
447  *
448  * These have to be implemented as inline functions rather than macros, when
449  * passing by value, because many machines pass int and float function
450  * parameters/results differently; so we need to play weird games with unions.
451  */
452 
453 /*
454  * DatumGetFloat4
455  * Returns 4-byte floating point value of a datum.
456  */
457 static inline float4
459 {
460  union
461  {
462  int32 value;
463  float4 retval;
464  } myunion;
465 
466  myunion.value = DatumGetInt32(X);
467  return myunion.retval;
468 }
469 
470 /*
471  * Float4GetDatum
472  * Returns datum representation for a 4-byte floating point number.
473  */
474 static inline Datum
476 {
477  union
478  {
479  float4 value;
480  int32 retval;
481  } myunion;
482 
483  myunion.value = X;
484  return Int32GetDatum(myunion.retval);
485 }
486 
487 /*
488  * DatumGetFloat8
489  * Returns 8-byte floating point value of a datum.
490  *
491  * Note: this function hides whether float8 is pass by value or by reference.
492  */
493 static inline float8
495 {
496 #ifdef USE_FLOAT8_BYVAL
497  union
498  {
499  int64 value;
500  float8 retval;
501  } myunion;
502 
503  myunion.value = DatumGetInt64(X);
504  return myunion.retval;
505 #else
506  return *((float8 *) DatumGetPointer(X));
507 #endif
508 }
509 
510 /*
511  * Float8GetDatum
512  * Returns datum representation for an 8-byte floating point number.
513  *
514  * Note: if float8 is pass by reference, this function returns a reference
515  * to palloc'd space.
516  */
517 #ifdef USE_FLOAT8_BYVAL
518 static inline Datum
520 {
521  union
522  {
523  float8 value;
524  int64 retval;
525  } myunion;
526 
527  myunion.value = X;
528  return Int64GetDatum(myunion.retval);
529 }
530 #else
531 extern Datum Float8GetDatum(float8 X);
532 #endif
533 
534 
535 /*
536  * Int64GetDatumFast
537  * Float8GetDatumFast
538  *
539  * These macros are intended to allow writing code that does not depend on
540  * whether int64 and float8 are pass-by-reference types, while not
541  * sacrificing performance when they are. The argument must be a variable
542  * that will exist and have the same value for as long as the Datum is needed.
543  * In the pass-by-ref case, the address of the variable is taken to use as
544  * the Datum. In the pass-by-val case, these are the same as the non-Fast
545  * functions, except for asserting that the variable is of the correct type.
546  */
547 
548 #ifdef USE_FLOAT8_BYVAL
549 #define Int64GetDatumFast(X) \
550  (AssertVariableIsOfTypeMacro(X, int64), Int64GetDatum(X))
551 #define Float8GetDatumFast(X) \
552  (AssertVariableIsOfTypeMacro(X, double), Float8GetDatum(X))
553 #else
554 #define Int64GetDatumFast(X) \
555  (AssertVariableIsOfTypeMacro(X, int64), PointerGetDatum(&(X)))
556 #define Float8GetDatumFast(X) \
557  (AssertVariableIsOfTypeMacro(X, double), PointerGetDatum(&(X)))
558 #endif
559 
560 
561 /* ----------------------------------------------------------------
562  * Section 2: miscellaneous
563  * ----------------------------------------------------------------
564  */
565 
566 /*
567  * NON_EXEC_STATIC: It's sometimes useful to define a variable or function
568  * that is normally static but extern when using EXEC_BACKEND (see
569  * pg_config_manual.h). There would then typically be some code in
570  * postmaster.c that uses those extern symbols to transfer state between
571  * processes or do whatever other things it needs to do in EXEC_BACKEND mode.
572  */
573 #ifdef EXEC_BACKEND
574 #define NON_EXEC_STATIC
575 #else
576 #define NON_EXEC_STATIC static
577 #endif
578 
579 #endif /* POSTGRES_H */
#define NameStr(name)
Definition: c.h:733
unsigned short uint16
Definition: c.h:492
unsigned int uint32
Definition: c.h:493
signed char int8
Definition: c.h:479
signed short int16
Definition: c.h:480
signed int int32
Definition: c.h:481
char * Pointer
Definition: c.h:470
double float8
Definition: c.h:617
TransactionId MultiXactId
Definition: c.h:649
float float4
Definition: c.h:616
unsigned char uint8
Definition: c.h:491
uint32 CommandId
Definition: c.h:653
uint32 TransactionId
Definition: c.h:639
static struct @150 value
static uint32 DatumGetUInt32(Datum X)
Definition: postgres.h:222
static uint64 DatumGetUInt64(Datum X)
Definition: postgres.h:419
static bool DatumGetBool(Datum X)
Definition: postgres.h:90
static int64 DatumGetInt64(Datum X)
Definition: postgres.h:385
static Datum PointerGetDatum(const void *X)
Definition: postgres.h:322
static Name DatumGetName(Datum X)
Definition: postgres.h:360
static Datum Float4GetDatum(float4 X)
Definition: postgres.h:475
static Datum Int8GetDatum(int8 X)
Definition: postgres.h:132
static char * DatumGetCString(Datum X)
Definition: postgres.h:335
static Datum TransactionIdGetDatum(TransactionId X)
Definition: postgres.h:272
uintptr_t Datum
Definition: postgres.h:64
static float4 DatumGetFloat4(Datum X)
Definition: postgres.h:458
static Datum CommandIdGetDatum(CommandId X)
Definition: postgres.h:302
static Oid DatumGetObjectId(Datum X)
Definition: postgres.h:242
static Datum UInt64GetDatum(uint64 X)
Definition: postgres.h:436
static Datum Int16GetDatum(int16 X)
Definition: postgres.h:172
static Datum MultiXactIdGetDatum(MultiXactId X)
Definition: postgres.h:282
Datum Int64GetDatum(int64 X)
Definition: fmgr.c:1807
static CommandId DatumGetCommandId(Datum X)
Definition: postgres.h:292
static Datum UInt16GetDatum(uint16 X)
Definition: postgres.h:192
static Datum BoolGetDatum(bool X)
Definition: postgres.h:102
static float8 DatumGetFloat8(Datum X)
Definition: postgres.h:494
Datum Float8GetDatum(float8 X)
Definition: fmgr.c:1816
static Datum ObjectIdGetDatum(Oid X)
Definition: postgres.h:252
static Datum NameGetDatum(const NameData *X)
Definition: postgres.h:373
static uint16 DatumGetUInt16(Datum X)
Definition: postgres.h:182
static Pointer DatumGetPointer(Datum X)
Definition: postgres.h:312
static TransactionId DatumGetTransactionId(Datum X)
Definition: postgres.h:262
static uint8 DatumGetUInt8(Datum X)
Definition: postgres.h:142
static Datum UInt8GetDatum(uint8 X)
Definition: postgres.h:152
static char DatumGetChar(Datum X)
Definition: postgres.h:112
static Datum CStringGetDatum(const char *X)
Definition: postgres.h:350
static Datum Int32GetDatum(int32 X)
Definition: postgres.h:212
static int16 DatumGetInt16(Datum X)
Definition: postgres.h:162
struct NullableDatum NullableDatum
static Datum UInt32GetDatum(uint32 X)
Definition: postgres.h:232
static int32 DatumGetInt32(Datum X)
Definition: postgres.h:202
static Datum CharGetDatum(char X)
Definition: postgres.h:122
unsigned int Oid
Definition: postgres_ext.h:31
Datum value
Definition: postgres.h:75
bool isnull
Definition: postgres.h:77
Definition: c.h:728