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