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 402397357 : DatumGetBool(Datum X)
101 : {
102 402397357 : 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 304110584 : BoolGetDatum(bool X)
113 : {
114 304110584 : return (Datum) (X ? 1 : 0);
115 : }
116 :
117 : /*
118 : * DatumGetChar
119 : * Returns character value of a datum.
120 : */
121 : static inline char
122 128868625 : DatumGetChar(Datum X)
123 : {
124 128868625 : return (char) X;
125 : }
126 :
127 : /*
128 : * CharGetDatum
129 : * Returns datum representation for a character.
130 : */
131 : static inline Datum
132 115533400 : CharGetDatum(char X)
133 : {
134 115533400 : 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 126579567 : DatumGetInt16(Datum X)
163 : {
164 126579567 : return (int16) X;
165 : }
166 :
167 : /*
168 : * Int16GetDatum
169 : * Returns datum representation for a 16-bit integer.
170 : */
171 : static inline Datum
172 68408695 : Int16GetDatum(int16 X)
173 : {
174 68408695 : return (Datum) X;
175 : }
176 :
177 : /*
178 : * DatumGetUInt16
179 : * Returns 16-bit unsigned integer value of a datum.
180 : */
181 : static inline uint16
182 7433577 : DatumGetUInt16(Datum X)
183 : {
184 7433577 : return (uint16) X;
185 : }
186 :
187 : /*
188 : * UInt16GetDatum
189 : * Returns datum representation for a 16-bit unsigned integer.
190 : */
191 : static inline Datum
192 2734068 : UInt16GetDatum(uint16 X)
193 : {
194 2734068 : return (Datum) X;
195 : }
196 :
197 : /*
198 : * DatumGetInt32
199 : * Returns 32-bit integer value of a datum.
200 : */
201 : static inline int32
202 1326721505 : DatumGetInt32(Datum X)
203 : {
204 1326721505 : return (int32) X;
205 : }
206 :
207 : /*
208 : * Int32GetDatum
209 : * Returns datum representation for a 32-bit integer.
210 : */
211 : static inline Datum
212 1379569554 : Int32GetDatum(int32 X)
213 : {
214 1379569554 : return (Datum) X;
215 : }
216 :
217 : /*
218 : * DatumGetUInt32
219 : * Returns 32-bit unsigned integer value of a datum.
220 : */
221 : static inline uint32
222 66070095 : DatumGetUInt32(Datum X)
223 : {
224 66070095 : return (uint32) X;
225 : }
226 :
227 : /*
228 : * UInt32GetDatum
229 : * Returns datum representation for a 32-bit unsigned integer.
230 : */
231 : static inline Datum
232 54905672 : UInt32GetDatum(uint32 X)
233 : {
234 54905672 : return (Datum) X;
235 : }
236 :
237 : /*
238 : * DatumGetObjectId
239 : * Returns object identifier value of a datum.
240 : */
241 : static inline Oid
242 856294352 : DatumGetObjectId(Datum X)
243 : {
244 856294352 : return (Oid) X;
245 : }
246 :
247 : /*
248 : * ObjectIdGetDatum
249 : * Returns datum representation for an object identifier.
250 : */
251 : static inline Datum
252 127702471 : ObjectIdGetDatum(Oid X)
253 : {
254 127702471 : return (Datum) X;
255 : }
256 :
257 : /*
258 : * DatumGetObjectId8
259 : * Returns 8-byte object identifier value of a datum.
260 : */
261 : static inline Oid8
262 10274 : DatumGetObjectId8(Datum X)
263 : {
264 10274 : return (Oid8) X;
265 : }
266 :
267 : /*
268 : * ObjectId8GetDatum
269 : * Returns datum representation for an 8-byte object identifier
270 : */
271 : static inline Datum
272 2161 : ObjectId8GetDatum(Oid8 X)
273 : {
274 2161 : return (Datum) X;
275 : }
276 :
277 : /*
278 : * DatumGetTransactionId
279 : * Returns transaction identifier value of a datum.
280 : */
281 : static inline TransactionId
282 1192608 : DatumGetTransactionId(Datum X)
283 : {
284 1192608 : return (TransactionId) X;
285 : }
286 :
287 : /*
288 : * TransactionIdGetDatum
289 : * Returns datum representation for a transaction identifier.
290 : */
291 : static inline Datum
292 555545 : TransactionIdGetDatum(TransactionId X)
293 : {
294 555545 : return (Datum) X;
295 : }
296 :
297 : /*
298 : * MultiXactIdGetDatum
299 : * Returns datum representation for a multixact identifier.
300 : */
301 : static inline Datum
302 89497 : MultiXactIdGetDatum(MultiXactId X)
303 : {
304 89497 : return (Datum) X;
305 : }
306 :
307 : /*
308 : * DatumGetCommandId
309 : * Returns command identifier value of a datum.
310 : */
311 : static inline CommandId
312 128 : DatumGetCommandId(Datum X)
313 : {
314 128 : return (CommandId) X;
315 : }
316 :
317 : /*
318 : * CommandIdGetDatum
319 : * Returns datum representation for a command identifier.
320 : */
321 : static inline Datum
322 128 : CommandIdGetDatum(CommandId X)
323 : {
324 128 : return (Datum) X;
325 : }
326 :
327 : /*
328 : * DatumGetPointer
329 : * Returns pointer value of a datum.
330 : */
331 : static inline Pointer
332 1123877579 : DatumGetPointer(Datum X)
333 : {
334 1123877579 : return (Pointer) (uintptr_t) X;
335 : }
336 :
337 : /*
338 : * PointerGetDatum
339 : * Returns datum representation for a pointer.
340 : *
341 : * This used to be defined as "static inline Datum PointerGetDatum(const void
342 : * *X) ", but it had the problem that the compiler would see the const
343 : * attribute, and could rightly assume that the function won't modify *X.
344 : * While PointerGetDatum() itself doesn't modify *X, the resulting Datum could
345 : * later be passed to a function that converts it back to a non-const pointer
346 : * and modifies it. Most functions don't modify their arguments passed by
347 : * reference - that would be very bogus for any operators or functions exposed
348 : * in SQL - but some functions like GIN support functions do have output
349 : * arguments that are pointer Datums.
350 : *
351 : * The odd-looking "true ? (X) : NULL" conditional expression has the effect
352 : * of producing a compiler error if X is not a pointer.
353 : */
354 : #define PointerGetDatum(X) \
355 : ((Datum) (uintptr_t) (true ? (X) : NULL))
356 :
357 : /*
358 : * DatumGetCString
359 : * Returns C string (null-terminated string) value of a datum.
360 : *
361 : * Note: C string is not a full-fledged Postgres type at present,
362 : * but type input functions use this conversion for their inputs.
363 : */
364 : static inline char *
365 67699507 : DatumGetCString(Datum X)
366 : {
367 67699507 : return (char *) DatumGetPointer(X);
368 : }
369 :
370 : /*
371 : * CStringGetDatum
372 : * Returns datum representation for a C string (null-terminated string).
373 : *
374 : * We assume that the resulting Datum is not used to modify the string, hence
375 : * the argument can be marked as const.
376 : *
377 : * Note: C string is not a full-fledged Postgres type at present,
378 : * but type output functions use this conversion for their outputs.
379 : * Note: CString is pass-by-reference; caller must ensure the pointed-to
380 : * value has adequate lifetime.
381 : */
382 : static inline Datum
383 64215844 : CStringGetDatum(const char *X)
384 : {
385 64215844 : return PointerGetDatum(X);
386 : }
387 :
388 : /*
389 : * DatumGetName
390 : * Returns name value of a datum.
391 : */
392 : static inline Name
393 119440400 : DatumGetName(Datum X)
394 : {
395 119440400 : return (Name) DatumGetPointer(X);
396 : }
397 :
398 : /*
399 : * NameGetDatum
400 : * Returns datum representation for a name.
401 : *
402 : * Note: Name is pass-by-reference; caller must ensure the pointed-to
403 : * value has adequate lifetime.
404 : */
405 : static inline Datum
406 2281893 : NameGetDatum(const NameData *X)
407 : {
408 2281893 : return CStringGetDatum(NameStr(*X));
409 : }
410 :
411 : /*
412 : * DatumGetInt64
413 : * Returns 64-bit integer value of a datum.
414 : */
415 : static inline int64
416 71663985 : DatumGetInt64(Datum X)
417 : {
418 71663985 : return (int64) X;
419 : }
420 :
421 : /*
422 : * Int64GetDatum
423 : * Returns datum representation for a 64-bit integer.
424 : */
425 : static inline Datum
426 54116204 : Int64GetDatum(int64 X)
427 : {
428 54116204 : return (Datum) X;
429 : }
430 :
431 : /*
432 : * DatumGetUInt64
433 : * Returns 64-bit unsigned integer value of a datum.
434 : */
435 : static inline uint64
436 8370862 : DatumGetUInt64(Datum X)
437 : {
438 8370862 : return (uint64) X;
439 : }
440 :
441 : /*
442 : * UInt64GetDatum
443 : * Returns datum representation for a 64-bit unsigned integer.
444 : */
445 : static inline Datum
446 5936376 : UInt64GetDatum(uint64 X)
447 : {
448 5936376 : return (Datum) X;
449 : }
450 :
451 : /*
452 : * Float <-> Datum conversions
453 : *
454 : * These have to be implemented as inline functions rather than macros, when
455 : * passing by value, because many machines pass int and float function
456 : * parameters/results differently; so we need to play weird games with unions.
457 : */
458 :
459 : /*
460 : * DatumGetFloat4
461 : * Returns 4-byte floating point value of a datum.
462 : */
463 : static inline float4
464 18147514 : DatumGetFloat4(Datum X)
465 : {
466 : union
467 : {
468 : int32 value;
469 : float4 retval;
470 : } myunion;
471 :
472 18147514 : myunion.value = DatumGetInt32(X);
473 18147514 : return myunion.retval;
474 : }
475 :
476 : /*
477 : * Float4GetDatum
478 : * Returns datum representation for a 4-byte floating point number.
479 : */
480 : static inline Datum
481 1413852 : Float4GetDatum(float4 X)
482 : {
483 : union
484 : {
485 : float4 value;
486 : int32 retval;
487 : } myunion;
488 :
489 1413852 : myunion.value = X;
490 1413852 : return Int32GetDatum(myunion.retval);
491 : }
492 :
493 : /*
494 : * DatumGetFloat8
495 : * Returns 8-byte floating point value of a datum.
496 : */
497 : static inline float8
498 17926382 : DatumGetFloat8(Datum X)
499 : {
500 : union
501 : {
502 : int64 value;
503 : float8 retval;
504 : } myunion;
505 :
506 17926382 : myunion.value = DatumGetInt64(X);
507 17926382 : return myunion.retval;
508 : }
509 :
510 : /*
511 : * Float8GetDatum
512 : * Returns datum representation for an 8-byte floating point number.
513 : */
514 : static inline Datum
515 8176533 : Float8GetDatum(float8 X)
516 : {
517 : union
518 : {
519 : float8 value;
520 : int64 retval;
521 : } myunion;
522 :
523 8176533 : myunion.value = X;
524 8176533 : return Int64GetDatum(myunion.retval);
525 : }
526 :
527 : /*
528 : * Int64GetDatumFast
529 : * Float8GetDatumFast
530 : *
531 : * These macros were intended to allow writing code that does not depend on
532 : * whether int64 and float8 are pass-by-reference types, while not
533 : * sacrificing performance when they are. They are no longer different
534 : * from the regular functions, though we keep the assertions to protect
535 : * code that might get back-patched into older branches.
536 : */
537 :
538 : #define Int64GetDatumFast(X) \
539 : (StaticAssertVariableIsOfTypeMacro(X, int64), Int64GetDatum(X))
540 : #define Float8GetDatumFast(X) \
541 : (StaticAssertVariableIsOfTypeMacro(X, double), Float8GetDatum(X))
542 :
543 :
544 : /* ----------------------------------------------------------------
545 : * Section 2: miscellaneous
546 : * ----------------------------------------------------------------
547 : */
548 :
549 : /*
550 : * pg_ternary
551 : * Boolean value with an extra "unset" value
552 : *
553 : * This enum can be used for values that want to distinguish between true,
554 : * false, and unset.
555 : */
556 : typedef enum pg_ternary
557 : {
558 : PG_TERNARY_FALSE = 0,
559 : PG_TERNARY_TRUE = 1,
560 : PG_TERNARY_UNSET = -1
561 : } pg_ternary;
562 :
563 : /*
564 : * NON_EXEC_STATIC: It's sometimes useful to define a variable or function
565 : * that is normally static but extern when using EXEC_BACKEND (see
566 : * pg_config_manual.h). There would then typically be some code in
567 : * postmaster.c that uses those extern symbols to transfer state between
568 : * processes or do whatever other things it needs to do in EXEC_BACKEND mode.
569 : */
570 : #ifdef EXEC_BACKEND
571 : #define NON_EXEC_STATIC
572 : #else
573 : #define NON_EXEC_STATIC static
574 : #endif
575 :
576 : #endif /* POSTGRES_H */
|
