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