Line data Source code
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-2026, 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 must have
62 : * sizeof(Datum) >= sizeof(void *). No current or foreseeable Postgres
63 : * platform has pointers wider than 8 bytes, and standardizing on Datum being
64 : * exactly 8 bytes has advantages in reducing cross-platform differences.
65 : *
66 : * The functions below and the analogous functions for other types should be used to
67 : * convert between a Datum and the appropriate C type.
68 : */
69 :
70 : typedef uint64_t Datum;
71 :
72 : /*
73 : * This symbol is now vestigial, but we continue to define it so as not to
74 : * unnecessarily break extension code.
75 : */
76 : #define SIZEOF_DATUM 8
77 :
78 : /*
79 : * A NullableDatum is used in places where both a Datum and its nullness needs
80 : * to be stored. This can be more efficient than storing datums and nullness
81 : * in separate arrays, due to better spatial locality, even if more space may
82 : * be wasted due to padding.
83 : */
84 : typedef struct NullableDatum
85 : {
86 : #define FIELDNO_NULLABLE_DATUM_DATUM 0
87 : Datum value;
88 : #define FIELDNO_NULLABLE_DATUM_ISNULL 1
89 : bool isnull;
90 : /* due to alignment padding this could be used for flags for free */
91 : } NullableDatum;
92 :
93 : /*
94 : * DatumGetBool
95 : * Returns boolean value of a datum.
96 : *
97 : * Note: any nonzero value will be considered true.
98 : */
99 : static inline bool
100 310861512 : DatumGetBool(Datum X)
101 : {
102 310861512 : return (X != 0);
103 : }
104 :
105 : /*
106 : * BoolGetDatum
107 : * Returns datum representation for a boolean.
108 : *
109 : * Note: any nonzero value will be considered true.
110 : */
111 : static inline Datum
112 233609551 : BoolGetDatum(bool X)
113 : {
114 233609551 : return (Datum) (X ? 1 : 0);
115 : }
116 :
117 : /*
118 : * DatumGetChar
119 : * Returns character value of a datum.
120 : */
121 : static inline char
122 106604819 : DatumGetChar(Datum X)
123 : {
124 106604819 : return (char) X;
125 : }
126 :
127 : /*
128 : * CharGetDatum
129 : * Returns datum representation for a character.
130 : */
131 : static inline Datum
132 89412470 : CharGetDatum(char X)
133 : {
134 89412470 : return (Datum) X;
135 : }
136 :
137 : /*
138 : * DatumGetUInt8
139 : * Returns 8-bit unsigned integer value of a datum.
140 : */
141 : static inline uint8
142 0 : DatumGetUInt8(Datum X)
143 : {
144 0 : return (uint8) X;
145 : }
146 :
147 : /*
148 : * UInt8GetDatum
149 : * Returns datum representation for an 8-bit unsigned integer.
150 : */
151 : static inline Datum
152 48 : UInt8GetDatum(uint8 X)
153 : {
154 48 : return (Datum) X;
155 : }
156 :
157 : /*
158 : * DatumGetInt16
159 : * Returns 16-bit integer value of a datum.
160 : */
161 : static inline int16
162 95996812 : DatumGetInt16(Datum X)
163 : {
164 95996812 : return (int16) X;
165 : }
166 :
167 : /*
168 : * Int16GetDatum
169 : * Returns datum representation for a 16-bit integer.
170 : */
171 : static inline Datum
172 52917757 : Int16GetDatum(int16 X)
173 : {
174 52917757 : return (Datum) X;
175 : }
176 :
177 : /*
178 : * DatumGetUInt16
179 : * Returns 16-bit unsigned integer value of a datum.
180 : */
181 : static inline uint16
182 5666482 : DatumGetUInt16(Datum X)
183 : {
184 5666482 : return (uint16) X;
185 : }
186 :
187 : /*
188 : * UInt16GetDatum
189 : * Returns datum representation for a 16-bit unsigned integer.
190 : */
191 : static inline Datum
192 2146930 : UInt16GetDatum(uint16 X)
193 : {
194 2146930 : return (Datum) X;
195 : }
196 :
197 : /*
198 : * DatumGetInt32
199 : * Returns 32-bit integer value of a datum.
200 : */
201 : static inline int32
202 996865388 : DatumGetInt32(Datum X)
203 : {
204 996865388 : return (int32) X;
205 : }
206 :
207 : /*
208 : * Int32GetDatum
209 : * Returns datum representation for a 32-bit integer.
210 : */
211 : static inline Datum
212 1105302927 : Int32GetDatum(int32 X)
213 : {
214 1105302927 : return (Datum) X;
215 : }
216 :
217 : /*
218 : * DatumGetUInt32
219 : * Returns 32-bit unsigned integer value of a datum.
220 : */
221 : static inline uint32
222 65250404 : DatumGetUInt32(Datum X)
223 : {
224 65250404 : return (uint32) X;
225 : }
226 :
227 : /*
228 : * UInt32GetDatum
229 : * Returns datum representation for a 32-bit unsigned integer.
230 : */
231 : static inline Datum
232 55980857 : UInt32GetDatum(uint32 X)
233 : {
234 55980857 : return (Datum) X;
235 : }
236 :
237 : /*
238 : * DatumGetObjectId
239 : * Returns object identifier value of a datum.
240 : */
241 : static inline Oid
242 724018605 : DatumGetObjectId(Datum X)
243 : {
244 724018605 : return (Oid) X;
245 : }
246 :
247 : /*
248 : * ObjectIdGetDatum
249 : * Returns datum representation for an object identifier.
250 : */
251 : static inline Datum
252 107199879 : ObjectIdGetDatum(Oid X)
253 : {
254 107199879 : return (Datum) X;
255 : }
256 :
257 : /*
258 : * DatumGetObjectId8
259 : * Returns 8-byte object identifier value of a datum.
260 : */
261 : static inline Oid8
262 7702 : DatumGetObjectId8(Datum X)
263 : {
264 7702 : return (Oid8) X;
265 : }
266 :
267 : /*
268 : * ObjectId8GetDatum
269 : * Returns datum representation for an 8-byte object identifier
270 : */
271 : static inline Datum
272 1620 : ObjectId8GetDatum(Oid8 X)
273 : {
274 1620 : return (Datum) X;
275 : }
276 :
277 : /*
278 : * DatumGetTransactionId
279 : * Returns transaction identifier value of a datum.
280 : */
281 : static inline TransactionId
282 904058 : DatumGetTransactionId(Datum X)
283 : {
284 904058 : return (TransactionId) X;
285 : }
286 :
287 : /*
288 : * TransactionIdGetDatum
289 : * Returns datum representation for a transaction identifier.
290 : */
291 : static inline Datum
292 534779 : TransactionIdGetDatum(TransactionId X)
293 : {
294 534779 : return (Datum) X;
295 : }
296 :
297 : /*
298 : * MultiXactIdGetDatum
299 : * Returns datum representation for a multixact identifier.
300 : */
301 : static inline Datum
302 71403 : MultiXactIdGetDatum(MultiXactId X)
303 : {
304 71403 : return (Datum) X;
305 : }
306 :
307 : /*
308 : * DatumGetCommandId
309 : * Returns command identifier value of a datum.
310 : */
311 : static inline CommandId
312 97 : DatumGetCommandId(Datum X)
313 : {
314 97 : return (CommandId) X;
315 : }
316 :
317 : /*
318 : * CommandIdGetDatum
319 : * Returns datum representation for a command identifier.
320 : */
321 : static inline Datum
322 96 : CommandIdGetDatum(CommandId X)
323 : {
324 96 : return (Datum) X;
325 : }
326 :
327 : /*
328 : * DatumGetPointer
329 : * Returns pointer value of a datum.
330 : */
331 : static inline Pointer
332 872409294 : DatumGetPointer(Datum X)
333 : {
334 872409294 : return (Pointer) (uintptr_t) X;
335 : }
336 :
337 : /*
338 : * PointerGetDatum
339 : * Returns datum representation for a pointer.
340 : */
341 : static inline Datum
342 796266466 : PointerGetDatum(const void *X)
343 : {
344 796266466 : return (Datum) (uintptr_t) X;
345 : }
346 :
347 : /*
348 : * DatumGetCString
349 : * Returns C string (null-terminated string) value of a datum.
350 : *
351 : * Note: C string is not a full-fledged Postgres type at present,
352 : * but type input functions use this conversion for their inputs.
353 : */
354 : static inline char *
355 61689143 : DatumGetCString(Datum X)
356 : {
357 61689143 : return (char *) DatumGetPointer(X);
358 : }
359 :
360 : /*
361 : * CStringGetDatum
362 : * Returns datum representation for a C string (null-terminated string).
363 : *
364 : * Note: C string is not a full-fledged Postgres type at present,
365 : * but type output functions use this conversion for their outputs.
366 : * Note: CString is pass-by-reference; caller must ensure the pointed-to
367 : * value has adequate lifetime.
368 : */
369 : static inline Datum
370 58705562 : CStringGetDatum(const char *X)
371 : {
372 58705562 : return PointerGetDatum(X);
373 : }
374 :
375 : /*
376 : * DatumGetName
377 : * Returns name value of a datum.
378 : */
379 : static inline Name
380 94891809 : DatumGetName(Datum X)
381 : {
382 94891809 : return (Name) DatumGetPointer(X);
383 : }
384 :
385 : /*
386 : * NameGetDatum
387 : * Returns datum representation for a name.
388 : *
389 : * Note: Name is pass-by-reference; caller must ensure the pointed-to
390 : * value has adequate lifetime.
391 : */
392 : static inline Datum
393 1887948 : NameGetDatum(const NameData *X)
394 : {
395 1887948 : return CStringGetDatum(NameStr(*X));
396 : }
397 :
398 : /*
399 : * DatumGetInt64
400 : * Returns 64-bit integer value of a datum.
401 : */
402 : static inline int64
403 61763316 : DatumGetInt64(Datum X)
404 : {
405 61763316 : return (int64) X;
406 : }
407 :
408 : /*
409 : * Int64GetDatum
410 : * Returns datum representation for a 64-bit integer.
411 : */
412 : static inline Datum
413 46754758 : Int64GetDatum(int64 X)
414 : {
415 46754758 : return (Datum) X;
416 : }
417 :
418 : /*
419 : * DatumGetUInt64
420 : * Returns 64-bit unsigned integer value of a datum.
421 : */
422 : static inline uint64
423 7088100 : DatumGetUInt64(Datum X)
424 : {
425 7088100 : return (uint64) X;
426 : }
427 :
428 : /*
429 : * UInt64GetDatum
430 : * Returns datum representation for a 64-bit unsigned integer.
431 : */
432 : static inline Datum
433 5265804 : UInt64GetDatum(uint64 X)
434 : {
435 5265804 : return (Datum) X;
436 : }
437 :
438 : /*
439 : * Float <-> Datum conversions
440 : *
441 : * These have to be implemented as inline functions rather than macros, when
442 : * passing by value, because many machines pass int and float function
443 : * parameters/results differently; so we need to play weird games with unions.
444 : */
445 :
446 : /*
447 : * DatumGetFloat4
448 : * Returns 4-byte floating point value of a datum.
449 : */
450 : static inline float4
451 16264746 : DatumGetFloat4(Datum X)
452 : {
453 : union
454 : {
455 : int32 value;
456 : float4 retval;
457 : } myunion;
458 :
459 16264746 : myunion.value = DatumGetInt32(X);
460 16264746 : return myunion.retval;
461 : }
462 :
463 : /*
464 : * Float4GetDatum
465 : * Returns datum representation for a 4-byte floating point number.
466 : */
467 : static inline Datum
468 1241658 : Float4GetDatum(float4 X)
469 : {
470 : union
471 : {
472 : float4 value;
473 : int32 retval;
474 : } myunion;
475 :
476 1241658 : myunion.value = X;
477 1241658 : return Int32GetDatum(myunion.retval);
478 : }
479 :
480 : /*
481 : * DatumGetFloat8
482 : * Returns 8-byte floating point value of a datum.
483 : */
484 : static inline float8
485 14041370 : DatumGetFloat8(Datum X)
486 : {
487 : union
488 : {
489 : int64 value;
490 : float8 retval;
491 : } myunion;
492 :
493 14041370 : myunion.value = DatumGetInt64(X);
494 14041370 : return myunion.retval;
495 : }
496 :
497 : /*
498 : * Float8GetDatum
499 : * Returns datum representation for an 8-byte floating point number.
500 : */
501 : static inline Datum
502 6925335 : Float8GetDatum(float8 X)
503 : {
504 : union
505 : {
506 : float8 value;
507 : int64 retval;
508 : } myunion;
509 :
510 6925335 : myunion.value = X;
511 6925335 : return Int64GetDatum(myunion.retval);
512 : }
513 :
514 : /*
515 : * Int64GetDatumFast
516 : * Float8GetDatumFast
517 : *
518 : * These macros were intended to allow writing code that does not depend on
519 : * whether int64 and float8 are pass-by-reference types, while not
520 : * sacrificing performance when they are. They are no longer different
521 : * from the regular functions, though we keep the assertions to protect
522 : * code that might get back-patched into older branches.
523 : */
524 :
525 : #define Int64GetDatumFast(X) \
526 : (StaticAssertVariableIsOfTypeMacro(X, int64), Int64GetDatum(X))
527 : #define Float8GetDatumFast(X) \
528 : (StaticAssertVariableIsOfTypeMacro(X, double), Float8GetDatum(X))
529 :
530 :
531 : /* ----------------------------------------------------------------
532 : * Section 2: miscellaneous
533 : * ----------------------------------------------------------------
534 : */
535 :
536 : /*
537 : * pg_ternary
538 : * Boolean value with an extra "unset" value
539 : *
540 : * This enum can be used for values that want to distinguish between true,
541 : * false, and unset.
542 : */
543 : typedef enum pg_ternary
544 : {
545 : PG_TERNARY_FALSE = 0,
546 : PG_TERNARY_TRUE = 1,
547 : PG_TERNARY_UNSET = -1
548 : } pg_ternary;
549 :
550 : /*
551 : * NON_EXEC_STATIC: It's sometimes useful to define a variable or function
552 : * that is normally static but extern when using EXEC_BACKEND (see
553 : * pg_config_manual.h). There would then typically be some code in
554 : * postmaster.c that uses those extern symbols to transfer state between
555 : * processes or do whatever other things it needs to do in EXEC_BACKEND mode.
556 : */
557 : #ifdef EXEC_BACKEND
558 : #define NON_EXEC_STATIC
559 : #else
560 : #define NON_EXEC_STATIC static
561 : #endif
562 :
563 : #endif /* POSTGRES_H */
|
