PostgreSQL Source Code git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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
64typedef 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 */
72typedef 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 */
89static 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 */
101static inline Datum
103{
104 return (Datum) (X ? 1 : 0);
105}
106
107/*
108 * DatumGetChar
109 * Returns character value of a datum.
110 */
111static inline char
113{
114 return (char) X;
115}
116
117/*
118 * CharGetDatum
119 * Returns datum representation for a character.
120 */
121static inline Datum
123{
124 return (Datum) X;
125}
126
127/*
128 * Int8GetDatum
129 * Returns datum representation for an 8-bit integer.
130 */
131static inline Datum
133{
134 return (Datum) X;
135}
136
137/*
138 * DatumGetUInt8
139 * Returns 8-bit unsigned integer value of a datum.
140 */
141static inline uint8
143{
144 return (uint8) X;
145}
146
147/*
148 * UInt8GetDatum
149 * Returns datum representation for an 8-bit unsigned integer.
150 */
151static inline Datum
153{
154 return (Datum) X;
155}
156
157/*
158 * DatumGetInt16
159 * Returns 16-bit integer value of a datum.
160 */
161static inline int16
163{
164 return (int16) X;
165}
166
167/*
168 * Int16GetDatum
169 * Returns datum representation for a 16-bit integer.
170 */
171static inline Datum
173{
174 return (Datum) X;
175}
176
177/*
178 * DatumGetUInt16
179 * Returns 16-bit unsigned integer value of a datum.
180 */
181static inline uint16
183{
184 return (uint16) X;
185}
186
187/*
188 * UInt16GetDatum
189 * Returns datum representation for a 16-bit unsigned integer.
190 */
191static inline Datum
193{
194 return (Datum) X;
195}
196
197/*
198 * DatumGetInt32
199 * Returns 32-bit integer value of a datum.
200 */
201static inline int32
203{
204 return (int32) X;
205}
206
207/*
208 * Int32GetDatum
209 * Returns datum representation for a 32-bit integer.
210 */
211static inline Datum
213{
214 return (Datum) X;
215}
216
217/*
218 * DatumGetUInt32
219 * Returns 32-bit unsigned integer value of a datum.
220 */
221static inline uint32
223{
224 return (uint32) X;
225}
226
227/*
228 * UInt32GetDatum
229 * Returns datum representation for a 32-bit unsigned integer.
230 */
231static inline Datum
233{
234 return (Datum) X;
235}
236
237/*
238 * DatumGetObjectId
239 * Returns object identifier value of a datum.
240 */
241static inline Oid
243{
244 return (Oid) X;
245}
246
247/*
248 * ObjectIdGetDatum
249 * Returns datum representation for an object identifier.
250 */
251static inline Datum
253{
254 return (Datum) X;
255}
256
257/*
258 * DatumGetTransactionId
259 * Returns transaction identifier value of a datum.
260 */
261static inline TransactionId
263{
264 return (TransactionId) X;
265}
266
267/*
268 * TransactionIdGetDatum
269 * Returns datum representation for a transaction identifier.
270 */
271static inline Datum
273{
274 return (Datum) X;
275}
276
277/*
278 * MultiXactIdGetDatum
279 * Returns datum representation for a multixact identifier.
280 */
281static inline Datum
283{
284 return (Datum) X;
285}
286
287/*
288 * DatumGetCommandId
289 * Returns command identifier value of a datum.
290 */
291static inline CommandId
293{
294 return (CommandId) X;
295}
296
297/*
298 * CommandIdGetDatum
299 * Returns datum representation for a command identifier.
300 */
301static inline Datum
303{
304 return (Datum) X;
305}
306
307/*
308 * DatumGetPointer
309 * Returns pointer value of a datum.
310 */
311static inline Pointer
313{
314 return (Pointer) X;
315}
316
317/*
318 * PointerGetDatum
319 * Returns datum representation for a pointer.
320 */
321static inline Datum
322PointerGetDatum(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 */
334static 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 */
349static inline Datum
350CStringGetDatum(const char *X)
351{
352 return PointerGetDatum(X);
353}
354
355/*
356 * DatumGetName
357 * Returns name value of a datum.
358 */
359static 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 */
372static 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 */
384static 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
402static inline Datum
404{
405 return (Datum) X;
406}
407#else
408extern 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 */
418static 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 */
435static inline Datum
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 */
457static 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 */
474static inline Datum
476{
477 union
478 {
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 */
493static 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
518static inline Datum
520{
521 union
522 {
524 int64 retval;
525 } myunion;
526
527 myunion.value = X;
528 return Int64GetDatum(myunion.retval);
529}
530#else
531extern 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:700
uint8_t uint8
Definition: c.h:483
char * Pointer
Definition: c.h:476
int64_t int64
Definition: c.h:482
double float8
Definition: c.h:584
TransactionId MultiXactId
Definition: c.h:616
int16_t int16
Definition: c.h:480
int8_t int8
Definition: c.h:479
int32_t int32
Definition: c.h:481
uint64_t uint64
Definition: c.h:486
uint16_t uint16
Definition: c.h:484
uint32_t uint32
Definition: c.h:485
float float4
Definition: c.h:583
uint32 CommandId
Definition: c.h:620
uint32 TransactionId
Definition: c.h:606
static struct @161 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 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 char * DatumGetCString(Datum X)
Definition: postgres.h:335
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:695