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-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 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 576892196 : DatumGetBool(Datum X) 101 : { 102 576892196 : 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 420588576 : BoolGetDatum(bool X) 113 : { 114 420588576 : return (Datum) (X ? 1 : 0); 115 : } 116 : 117 : /* 118 : * DatumGetChar 119 : * Returns character value of a datum. 120 : */ 121 : static inline char 122 205626518 : DatumGetChar(Datum X) 123 : { 124 205626518 : return (char) X; 125 : } 126 : 127 : /* 128 : * CharGetDatum 129 : * Returns datum representation for a character. 130 : */ 131 : static inline Datum 132 161041400 : CharGetDatum(char X) 133 : { 134 161041400 : return (Datum) X; 135 : } 136 : 137 : /* 138 : * Int8GetDatum 139 : * Returns datum representation for an 8-bit integer. 140 : */ 141 : static inline Datum 142 : Int8GetDatum(int8 X) 143 : { 144 : return (Datum) X; 145 : } 146 : 147 : /* 148 : * DatumGetUInt8 149 : * Returns 8-bit unsigned integer value of a datum. 150 : */ 151 : static inline uint8 152 0 : DatumGetUInt8(Datum X) 153 : { 154 0 : return (uint8) X; 155 : } 156 : 157 : /* 158 : * UInt8GetDatum 159 : * Returns datum representation for an 8-bit unsigned integer. 160 : */ 161 : static inline Datum 162 96 : UInt8GetDatum(uint8 X) 163 : { 164 96 : return (Datum) X; 165 : } 166 : 167 : /* 168 : * DatumGetInt16 169 : * Returns 16-bit integer value of a datum. 170 : */ 171 : static inline int16 172 182355168 : DatumGetInt16(Datum X) 173 : { 174 182355168 : return (int16) X; 175 : } 176 : 177 : /* 178 : * Int16GetDatum 179 : * Returns datum representation for a 16-bit integer. 180 : */ 181 : static inline Datum 182 99331720 : Int16GetDatum(int16 X) 183 : { 184 99331720 : return (Datum) X; 185 : } 186 : 187 : /* 188 : * DatumGetUInt16 189 : * Returns 16-bit unsigned integer value of a datum. 190 : */ 191 : static inline uint16 192 11343904 : DatumGetUInt16(Datum X) 193 : { 194 11343904 : return (uint16) X; 195 : } 196 : 197 : /* 198 : * UInt16GetDatum 199 : * Returns datum representation for a 16-bit unsigned integer. 200 : */ 201 : static inline Datum 202 2278998 : UInt16GetDatum(uint16 X) 203 : { 204 2278998 : return (Datum) X; 205 : } 206 : 207 : /* 208 : * DatumGetInt32 209 : * Returns 32-bit integer value of a datum. 210 : */ 211 : static inline int32 212 1992065432 : DatumGetInt32(Datum X) 213 : { 214 1992065432 : return (int32) X; 215 : } 216 : 217 : /* 218 : * Int32GetDatum 219 : * Returns datum representation for a 32-bit integer. 220 : */ 221 : static inline Datum 222 2027862612 : Int32GetDatum(int32 X) 223 : { 224 2027862612 : return (Datum) X; 225 : } 226 : 227 : /* 228 : * DatumGetUInt32 229 : * Returns 32-bit unsigned integer value of a datum. 230 : */ 231 : static inline uint32 232 82476252 : DatumGetUInt32(Datum X) 233 : { 234 82476252 : return (uint32) X; 235 : } 236 : 237 : /* 238 : * UInt32GetDatum 239 : * Returns datum representation for a 32-bit unsigned integer. 240 : */ 241 : static inline Datum 242 61516742 : UInt32GetDatum(uint32 X) 243 : { 244 61516742 : return (Datum) X; 245 : } 246 : 247 : /* 248 : * DatumGetObjectId 249 : * Returns object identifier value of a datum. 250 : */ 251 : static inline Oid 252 1360448926 : DatumGetObjectId(Datum X) 253 : { 254 1360448926 : return (Oid) X; 255 : } 256 : 257 : /* 258 : * ObjectIdGetDatum 259 : * Returns datum representation for an object identifier. 260 : */ 261 : static inline Datum 262 185166786 : ObjectIdGetDatum(Oid X) 263 : { 264 185166786 : return (Datum) X; 265 : } 266 : 267 : /* 268 : * DatumGetTransactionId 269 : * Returns transaction identifier value of a datum. 270 : */ 271 : static inline TransactionId 272 1626486 : DatumGetTransactionId(Datum X) 273 : { 274 1626486 : return (TransactionId) X; 275 : } 276 : 277 : /* 278 : * TransactionIdGetDatum 279 : * Returns datum representation for a transaction identifier. 280 : */ 281 : static inline Datum 282 665288 : TransactionIdGetDatum(TransactionId X) 283 : { 284 665288 : return (Datum) X; 285 : } 286 : 287 : /* 288 : * MultiXactIdGetDatum 289 : * Returns datum representation for a multixact identifier. 290 : */ 291 : static inline Datum 292 135120 : MultiXactIdGetDatum(MultiXactId X) 293 : { 294 135120 : return (Datum) X; 295 : } 296 : 297 : /* 298 : * DatumGetCommandId 299 : * Returns command identifier value of a datum. 300 : */ 301 : static inline CommandId 302 194 : DatumGetCommandId(Datum X) 303 : { 304 194 : return (CommandId) X; 305 : } 306 : 307 : /* 308 : * CommandIdGetDatum 309 : * Returns datum representation for a command identifier. 310 : */ 311 : static inline Datum 312 192 : CommandIdGetDatum(CommandId X) 313 : { 314 192 : return (Datum) X; 315 : } 316 : 317 : /* 318 : * DatumGetPointer 319 : * Returns pointer value of a datum. 320 : */ 321 : static inline Pointer 322 1666089284 : DatumGetPointer(Datum X) 323 : { 324 1666089284 : return (Pointer) (uintptr_t) X; 325 : } 326 : 327 : /* 328 : * PointerGetDatum 329 : * Returns datum representation for a pointer. 330 : */ 331 : static inline Datum 332 1489334712 : PointerGetDatum(const void *X) 333 : { 334 1489334712 : return (Datum) (uintptr_t) X; 335 : } 336 : 337 : /* 338 : * DatumGetCString 339 : * Returns C string (null-terminated string) value of a datum. 340 : * 341 : * Note: C string is not a full-fledged Postgres type at present, 342 : * but type input functions use this conversion for their inputs. 343 : */ 344 : static inline char * 345 108974430 : DatumGetCString(Datum X) 346 : { 347 108974430 : return (char *) DatumGetPointer(X); 348 : } 349 : 350 : /* 351 : * CStringGetDatum 352 : * Returns datum representation for a C string (null-terminated string). 353 : * 354 : * Note: C string is not a full-fledged Postgres type at present, 355 : * but type output functions use this conversion for their outputs. 356 : * Note: CString is pass-by-reference; caller must ensure the pointed-to 357 : * value has adequate lifetime. 358 : */ 359 : static inline Datum 360 103055918 : CStringGetDatum(const char *X) 361 : { 362 103055918 : return PointerGetDatum(X); 363 : } 364 : 365 : /* 366 : * DatumGetName 367 : * Returns name value of a datum. 368 : */ 369 : static inline Name 370 192003082 : DatumGetName(Datum X) 371 : { 372 192003082 : return (Name) DatumGetPointer(X); 373 : } 374 : 375 : /* 376 : * NameGetDatum 377 : * Returns datum representation for a name. 378 : * 379 : * Note: Name is pass-by-reference; caller must ensure the pointed-to 380 : * value has adequate lifetime. 381 : */ 382 : static inline Datum 383 3606554 : NameGetDatum(const NameData *X) 384 : { 385 3606554 : return CStringGetDatum(NameStr(*X)); 386 : } 387 : 388 : /* 389 : * DatumGetInt64 390 : * Returns 64-bit integer value of a datum. 391 : */ 392 : static inline int64 393 141100756 : DatumGetInt64(Datum X) 394 : { 395 141100756 : return (int64) X; 396 : } 397 : 398 : /* 399 : * Int64GetDatum 400 : * Returns datum representation for a 64-bit integer. 401 : */ 402 : static inline Datum 403 89506600 : Int64GetDatum(int64 X) 404 : { 405 89506600 : return (Datum) X; 406 : } 407 : 408 : /* 409 : * DatumGetUInt64 410 : * Returns 64-bit unsigned integer value of a datum. 411 : */ 412 : static inline uint64 413 14135950 : DatumGetUInt64(Datum X) 414 : { 415 14135950 : return (uint64) X; 416 : } 417 : 418 : /* 419 : * UInt64GetDatum 420 : * Returns datum representation for a 64-bit unsigned integer. 421 : */ 422 : static inline Datum 423 10493178 : UInt64GetDatum(uint64 X) 424 : { 425 10493178 : return (Datum) X; 426 : } 427 : 428 : /* 429 : * Float <-> Datum conversions 430 : * 431 : * These have to be implemented as inline functions rather than macros, when 432 : * passing by value, because many machines pass int and float function 433 : * parameters/results differently; so we need to play weird games with unions. 434 : */ 435 : 436 : /* 437 : * DatumGetFloat4 438 : * Returns 4-byte floating point value of a datum. 439 : */ 440 : static inline float4 441 31685656 : DatumGetFloat4(Datum X) 442 : { 443 : union 444 : { 445 : int32 value; 446 : float4 retval; 447 : } myunion; 448 : 449 31685656 : myunion.value = DatumGetInt32(X); 450 31685656 : return myunion.retval; 451 : } 452 : 453 : /* 454 : * Float4GetDatum 455 : * Returns datum representation for a 4-byte floating point number. 456 : */ 457 : static inline Datum 458 2456870 : Float4GetDatum(float4 X) 459 : { 460 : union 461 : { 462 : float4 value; 463 : int32 retval; 464 : } myunion; 465 : 466 2456870 : myunion.value = X; 467 2456870 : return Int32GetDatum(myunion.retval); 468 : } 469 : 470 : /* 471 : * DatumGetFloat8 472 : * Returns 8-byte floating point value of a datum. 473 : */ 474 : static inline float8 475 27689856 : DatumGetFloat8(Datum X) 476 : { 477 : union 478 : { 479 : int64 value; 480 : float8 retval; 481 : } myunion; 482 : 483 27689856 : myunion.value = DatumGetInt64(X); 484 27689856 : return myunion.retval; 485 : } 486 : 487 : /* 488 : * Float8GetDatum 489 : * Returns datum representation for an 8-byte floating point number. 490 : */ 491 : static inline Datum 492 13457080 : Float8GetDatum(float8 X) 493 : { 494 : union 495 : { 496 : float8 value; 497 : int64 retval; 498 : } myunion; 499 : 500 13457080 : myunion.value = X; 501 13457080 : return Int64GetDatum(myunion.retval); 502 : } 503 : 504 : /* 505 : * Int64GetDatumFast 506 : * Float8GetDatumFast 507 : * 508 : * These macros were intended to allow writing code that does not depend on 509 : * whether int64 and float8 are pass-by-reference types, while not 510 : * sacrificing performance when they are. They are no longer different 511 : * from the regular functions, though we keep the assertions to protect 512 : * code that might get back-patched into older branches. 513 : */ 514 : 515 : #define Int64GetDatumFast(X) \ 516 : (AssertVariableIsOfTypeMacro(X, int64), Int64GetDatum(X)) 517 : #define Float8GetDatumFast(X) \ 518 : (AssertVariableIsOfTypeMacro(X, double), Float8GetDatum(X)) 519 : 520 : 521 : /* ---------------------------------------------------------------- 522 : * Section 2: miscellaneous 523 : * ---------------------------------------------------------------- 524 : */ 525 : 526 : /* 527 : * NON_EXEC_STATIC: It's sometimes useful to define a variable or function 528 : * that is normally static but extern when using EXEC_BACKEND (see 529 : * pg_config_manual.h). There would then typically be some code in 530 : * postmaster.c that uses those extern symbols to transfer state between 531 : * processes or do whatever other things it needs to do in EXEC_BACKEND mode. 532 : */ 533 : #ifdef EXEC_BACKEND 534 : #define NON_EXEC_STATIC 535 : #else 536 : #define NON_EXEC_STATIC static 537 : #endif 538 : 539 : #endif /* POSTGRES_H */