src/include/postgres.h

   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
  64 typedef 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  */
  72 typedef struct NullableDatum
  73 {
  74 #define FIELDNO_NULLABLE_DATUM_DATUM 0
  75         Datum           value;
  76 #define FIELDNO_NULLABLE_DATUM_ISNULL 1
  77         bool            isnull;
  78         /* due to alignment padding this could be used for flags for free */
  79 } NullableDatum;
  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  */
  89 static inline bool
  90 DatumGetBool(Datum X)
  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  */
 101 static inline Datum
 102 BoolGetDatum(bool X)
 103 {
 104         return (Datum) (X ? 1 : 0);
 105 }
 106
 107 /*
 108  * DatumGetChar
 109  *              Returns character value of a datum.
 110  */
 111 static inline char
 112 DatumGetChar(Datum X)
 113 {
 114         return (char) X;
 115 }
 116
 117 /*
 118  * CharGetDatum
 119  *              Returns datum representation for a character.
 120  */
 121 static inline Datum
 122 CharGetDatum(char X)
 123 {
 124         return (Datum) X;
 125 }
 126
 127 /*
 128  * Int8GetDatum
 129  *              Returns datum representation for an 8-bit integer.
 130  */
 131 static inline Datum
 132 Int8GetDatum(int8 X)
 133 {
 134         return (Datum) X;
 135 }
 136
 137 /*
 138  * DatumGetUInt8
 139  *              Returns 8-bit unsigned integer value of a datum.
 140  */
 141 static inline uint8
 142 DatumGetUInt8(Datum X)
 143 {
 144         return (uint8) X;
 145 }
 146
 147 /*
 148  * UInt8GetDatum
 149  *              Returns datum representation for an 8-bit unsigned integer.
 150  */
 151 static inline Datum
 152 UInt8GetDatum(uint8 X)
 153 {
 154         return (Datum) X;
 155 }
 156
 157 /*
 158  * DatumGetInt16
 159  *              Returns 16-bit integer value of a datum.
 160  */
 161 static inline int16
 162 DatumGetInt16(Datum X)
 163 {
 164         return (int16) X;
 165 }
 166
 167 /*
 168  * Int16GetDatum
 169  *              Returns datum representation for a 16-bit integer.
 170  */
 171 static inline Datum
 172 Int16GetDatum(int16 X)
 173 {
 174         return (Datum) X;
 175 }
 176
 177 /*
 178  * DatumGetUInt16
 179  *              Returns 16-bit unsigned integer value of a datum.
 180  */
 181 static inline uint16
 182 DatumGetUInt16(Datum X)
 183 {
 184         return (uint16) X;
 185 }
 186
 187 /*
 188  * UInt16GetDatum
 189  *              Returns datum representation for a 16-bit unsigned integer.
 190  */
 191 static inline Datum
 192 UInt16GetDatum(uint16 X)
 193 {
 194         return (Datum) X;
 195 }
 196
 197 /*
 198  * DatumGetInt32
 199  *              Returns 32-bit integer value of a datum.
 200  */
 201 static inline int32
 202 DatumGetInt32(Datum X)
 203 {
 204         return (int32) X;
 205 }
 206
 207 /*
 208  * Int32GetDatum
 209  *              Returns datum representation for a 32-bit integer.
 210  */
 211 static inline Datum
 212 Int32GetDatum(int32 X)
 213 {
 214         return (Datum) X;
 215 }
 216
 217 /*
 218  * DatumGetUInt32
 219  *              Returns 32-bit unsigned integer value of a datum.
 220  */
 221 static inline uint32
 222 DatumGetUInt32(Datum X)
 223 {
 224         return (uint32) X;
 225 }
 226
 227 /*
 228  * UInt32GetDatum
 229  *              Returns datum representation for a 32-bit unsigned integer.
 230  */
 231 static inline Datum
 232 UInt32GetDatum(uint32 X)
 233 {
 234         return (Datum) X;
 235 }
 236
 237 /*
 238  * DatumGetObjectId
 239  *              Returns object identifier value of a datum.
 240  */
 241 static inline Oid
 242 DatumGetObjectId(Datum X)
 243 {
 244         return (Oid) X;
 245 }
 246
 247 /*
 248  * ObjectIdGetDatum
 249  *              Returns datum representation for an object identifier.
 250  */
 251 static inline Datum
 252 ObjectIdGetDatum(Oid X)
 253 {
 254         return (Datum) X;
 255 }
 256
 257 /*
 258  * DatumGetTransactionId
 259  *              Returns transaction identifier value of a datum.
 260  */
 261 static inline TransactionId
 262 DatumGetTransactionId(Datum X)
 263 {
 264         return (TransactionId) X;
 265 }
 266
 267 /*
 268  * TransactionIdGetDatum
 269  *              Returns datum representation for a transaction identifier.
 270  */
 271 static inline Datum
 272 TransactionIdGetDatum(TransactionId X)
 273 {
 274         return (Datum) X;
 275 }
 276
 277 /*
 278  * MultiXactIdGetDatum
 279  *              Returns datum representation for a multixact identifier.
 280  */
 281 static inline Datum
 282 MultiXactIdGetDatum(MultiXactId X)
 283 {
 284         return (Datum) X;
 285 }
 286
 287 /*
 288  * DatumGetCommandId
 289  *              Returns command identifier value of a datum.
 290  */
 291 static inline CommandId
 292 DatumGetCommandId(Datum X)
 293 {
 294         return (CommandId) X;
 295 }
 296
 297 /*
 298  * CommandIdGetDatum
 299  *              Returns datum representation for a command identifier.
 300  */
 301 static inline Datum
 302 CommandIdGetDatum(CommandId X)
 303 {
 304         return (Datum) X;
 305 }
 306
 307 /*
 308  * DatumGetPointer
 309  *              Returns pointer value of a datum.
 310  */
 311 static inline Pointer
 312 DatumGetPointer(Datum X)
 313 {
 314         return (Pointer) X;
 315 }
 316
 317 /*
 318  * PointerGetDatum
 319  *              Returns datum representation for a pointer.
 320  */
 321 static inline Datum
 322 PointerGetDatum(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  */
 334 static inline char *
 335 DatumGetCString(Datum X)
 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  */
 349 static inline Datum
 350 CStringGetDatum(const char *X)
 351 {
 352         return PointerGetDatum(X);
 353 }
 354
 355 /*
 356  * DatumGetName
 357  *              Returns name value of a datum.
 358  */
 359 static inline Name
 360 DatumGetName(Datum X)
 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  */
 372 static inline Datum
 373 NameGetDatum(const NameData *X)
 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  */
 384 static inline int64
 385 DatumGetInt64(Datum X)
 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
 402 static inline Datum
 403 Int64GetDatum(int64 X)
 404 {
 405         return (Datum) X;
 406 }
 407 #else
 408 extern 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  */
 418 static inline uint64
 419 DatumGetUInt64(Datum X)
 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  */
 435 static inline Datum
 436 UInt64GetDatum(uint64 X)
 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  */
 457 static inline float4
 458 DatumGetFloat4(Datum X)
 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  */
 474 static inline Datum
 475 Float4GetDatum(float4 X)
 476 {
 477         union
 478         {
 479                 float4          value;
 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  */
 493 static inline float8
 494 DatumGetFloat8(Datum X)
 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
 518 static inline Datum
 519 Float8GetDatum(float8 X)
 520 {
 521         union
 522         {
 523                 float8          value;
 524                 int64           retval;
 525         }                       myunion;
 526
 527         myunion.value = X;
 528         return Int64GetDatum(myunion.retval);
 529 }
 530 #else
 531 extern 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 */