Branch data 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 : 404180961 : DatumGetBool(Datum X)
101 : : {
102 : 404180961 : 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 : 301492133 : BoolGetDatum(bool X)
113 : : {
114 [ + + ]: 301492133 : return (Datum) (X ? 1 : 0);
115 : : }
116 : :
117 : : /*
118 : : * DatumGetChar
119 : : * Returns character value of a datum.
120 : : */
121 : : static inline char
122 : 128824568 : DatumGetChar(Datum X)
123 : : {
124 : 128824568 : return (char) X;
125 : : }
126 : :
127 : : /*
128 : : * CharGetDatum
129 : : * Returns datum representation for a character.
130 : : */
131 : : static inline Datum
132 : 112226905 : CharGetDatum(char X)
133 : : {
134 : 112226905 : 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 : 69527477 : DatumGetInt16(Datum X)
163 : : {
164 : 69527477 : return (int16) X;
165 : : }
166 : :
167 : : /*
168 : : * Int16GetDatum
169 : : * Returns datum representation for a 16-bit integer.
170 : : */
171 : : static inline Datum
172 : 67555094 : Int16GetDatum(int16 X)
173 : : {
174 : 67555094 : return (Datum) X;
175 : : }
176 : :
177 : : /*
178 : : * DatumGetUInt16
179 : : * Returns 16-bit unsigned integer value of a datum.
180 : : */
181 : : static inline uint16
182 : 7433923 : DatumGetUInt16(Datum X)
183 : : {
184 : 7433923 : return (uint16) X;
185 : : }
186 : :
187 : : /*
188 : : * UInt16GetDatum
189 : : * Returns datum representation for a 16-bit unsigned integer.
190 : : */
191 : : static inline Datum
192 : 2729786 : UInt16GetDatum(uint16 X)
193 : : {
194 : 2729786 : return (Datum) X;
195 : : }
196 : :
197 : : /*
198 : : * DatumGetInt32
199 : : * Returns 32-bit integer value of a datum.
200 : : */
201 : : static inline int32
202 : 1376663957 : DatumGetInt32(Datum X)
203 : : {
204 : 1376663957 : return (int32) X;
205 : : }
206 : :
207 : : /*
208 : : * Int32GetDatum
209 : : * Returns datum representation for a 32-bit integer.
210 : : */
211 : : static inline Datum
212 : 1368560667 : Int32GetDatum(int32 X)
213 : : {
214 : 1368560667 : return (Datum) X;
215 : : }
216 : :
217 : : /*
218 : : * DatumGetUInt32
219 : : * Returns 32-bit unsigned integer value of a datum.
220 : : */
221 : : static inline uint32
222 : 66723953 : DatumGetUInt32(Datum X)
223 : : {
224 : 66723953 : return (uint32) X;
225 : : }
226 : :
227 : : /*
228 : : * UInt32GetDatum
229 : : * Returns datum representation for a 32-bit unsigned integer.
230 : : */
231 : : static inline Datum
232 : 55220341 : UInt32GetDatum(uint32 X)
233 : : {
234 : 55220341 : return (Datum) X;
235 : : }
236 : :
237 : : /*
238 : : * DatumGetObjectId
239 : : * Returns object identifier value of a datum.
240 : : */
241 : : static inline Oid
242 : 535379805 : DatumGetObjectId(Datum X)
243 : : {
244 : 535379805 : return (Oid) X;
245 : : }
246 : :
247 : : /*
248 : : * ObjectIdGetDatum
249 : : * Returns datum representation for an object identifier.
250 : : */
251 : : static inline Datum
252 : 125673164 : ObjectIdGetDatum(Oid X)
253 : : {
254 : 125673164 : return (Datum) X;
255 : : }
256 : :
257 : : /*
258 : : * DatumGetObjectId8
259 : : * Returns 8-byte object identifier value of a datum.
260 : : */
261 : : static inline Oid8
262 : 4442 : DatumGetObjectId8(Datum X)
263 : : {
264 : 4442 : 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 : 1064612 : DatumGetTransactionId(Datum X)
283 : : {
284 : 1064612 : return (TransactionId) X;
285 : : }
286 : :
287 : : /*
288 : : * TransactionIdGetDatum
289 : : * Returns datum representation for a transaction identifier.
290 : : */
291 : : static inline Datum
292 : 556927 : TransactionIdGetDatum(TransactionId X)
293 : : {
294 : 556927 : return (Datum) X;
295 : : }
296 : :
297 : : /*
298 : : * MultiXactIdGetDatum
299 : : * Returns datum representation for a multixact identifier.
300 : : */
301 : : static inline Datum
302 : 90483 : MultiXactIdGetDatum(MultiXactId X)
303 : : {
304 : 90483 : 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 : 1114987309 : DatumGetPointer(Datum X)
333 : : {
334 : 1114987309 : 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 : 63153414 : DatumGetCString(Datum X)
366 : : {
367 : 63153414 : 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 : 59553002 : CStringGetDatum(const char *X)
384 : : {
385 : 59553002 : return PointerGetDatum(X);
386 : : }
387 : :
388 : : /*
389 : : * DatumGetName
390 : : * Returns name value of a datum.
391 : : */
392 : : static inline Name
393 : 118264047 : DatumGetName(Datum X)
394 : : {
395 : 118264047 : 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 : 2293385 : NameGetDatum(const NameData *X)
407 : : {
408 : 2293385 : return CStringGetDatum(NameStr(*X));
409 : : }
410 : :
411 : : /*
412 : : * DatumGetInt64
413 : : * Returns 64-bit integer value of a datum.
414 : : */
415 : : static inline int64
416 : 71213288 : DatumGetInt64(Datum X)
417 : : {
418 : 71213288 : return (int64) X;
419 : : }
420 : :
421 : : /*
422 : : * Int64GetDatum
423 : : * Returns datum representation for a 64-bit integer.
424 : : */
425 : : static inline Datum
426 : 55231001 : Int64GetDatum(int64 X)
427 : : {
428 : 55231001 : return (Datum) X;
429 : : }
430 : :
431 : : /*
432 : : * DatumGetUInt64
433 : : * Returns 64-bit unsigned integer value of a datum.
434 : : */
435 : : static inline uint64
436 : 8377467 : DatumGetUInt64(Datum X)
437 : : {
438 : 8377467 : return (uint64) X;
439 : : }
440 : :
441 : : /*
442 : : * UInt64GetDatum
443 : : * Returns datum representation for a 64-bit unsigned integer.
444 : : */
445 : : static inline Datum
446 : 5939798 : UInt64GetDatum(uint64 X)
447 : : {
448 : 5939798 : 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 : 18593266 : DatumGetFloat4(Datum X)
465 : : {
466 : : union
467 : : {
468 : : int32 value;
469 : : float4 retval;
470 : : } myunion;
471 : :
472 : 18593266 : myunion.value = DatumGetInt32(X);
473 : 18593266 : 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 : 1429617 : Float4GetDatum(float4 X)
482 : : {
483 : : union
484 : : {
485 : : float4 value;
486 : : int32 retval;
487 : : } myunion;
488 : :
489 : 1429617 : myunion.value = X;
490 : 1429617 : 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 : 17457368 : DatumGetFloat8(Datum X)
499 : : {
500 : : union
501 : : {
502 : : int64 value;
503 : : float8 retval;
504 : : } myunion;
505 : :
506 : 17457368 : myunion.value = DatumGetInt64(X);
507 : 17457368 : 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 : 8267591 : Float8GetDatum(float8 X)
516 : : {
517 : : union
518 : : {
519 : : float8 value;
520 : : int64 retval;
521 : : } myunion;
522 : :
523 : 8267591 : myunion.value = X;
524 : 8267591 : 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 */
|
