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-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   427858768 : DatumGetBool(Datum X)
      91             : {
      92   427858768 :     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   323126060 : BoolGetDatum(bool X)
     103             : {
     104   323126060 :     return (Datum) (X ? 1 : 0);
     105             : }
     106             : 
     107             : /*
     108             :  * DatumGetChar
     109             :  *      Returns character value of a datum.
     110             :  */
     111             : static inline char
     112   133821298 : DatumGetChar(Datum X)
     113             : {
     114   133821298 :     return (char) X;
     115             : }
     116             : 
     117             : /*
     118             :  * CharGetDatum
     119             :  *      Returns datum representation for a character.
     120             :  */
     121             : static inline Datum
     122   110895386 : CharGetDatum(char X)
     123             : {
     124   110895386 :     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          86 : UInt8GetDatum(uint8 X)
     153             : {
     154          86 :     return (Datum) X;
     155             : }
     156             : 
     157             : /*
     158             :  * DatumGetInt16
     159             :  *      Returns 16-bit integer value of a datum.
     160             :  */
     161             : static inline int16
     162   115151228 : DatumGetInt16(Datum X)
     163             : {
     164   115151228 :     return (int16) X;
     165             : }
     166             : 
     167             : /*
     168             :  * Int16GetDatum
     169             :  *      Returns datum representation for a 16-bit integer.
     170             :  */
     171             : static inline Datum
     172    75441072 : Int16GetDatum(int16 X)
     173             : {
     174    75441072 :     return (Datum) X;
     175             : }
     176             : 
     177             : /*
     178             :  * DatumGetUInt16
     179             :  *      Returns 16-bit unsigned integer value of a datum.
     180             :  */
     181             : static inline uint16
     182    11344604 : DatumGetUInt16(Datum X)
     183             : {
     184    11344604 :     return (uint16) X;
     185             : }
     186             : 
     187             : /*
     188             :  * UInt16GetDatum
     189             :  *      Returns datum representation for a 16-bit unsigned integer.
     190             :  */
     191             : static inline Datum
     192     2260070 : UInt16GetDatum(uint16 X)
     193             : {
     194     2260070 :     return (Datum) X;
     195             : }
     196             : 
     197             : /*
     198             :  * DatumGetInt32
     199             :  *      Returns 32-bit integer value of a datum.
     200             :  */
     201             : static inline int32
     202  1561461268 : DatumGetInt32(Datum X)
     203             : {
     204  1561461268 :     return (int32) X;
     205             : }
     206             : 
     207             : /*
     208             :  * Int32GetDatum
     209             :  *      Returns datum representation for a 32-bit integer.
     210             :  */
     211             : static inline Datum
     212  1594750782 : Int32GetDatum(int32 X)
     213             : {
     214  1594750782 :     return (Datum) X;
     215             : }
     216             : 
     217             : /*
     218             :  * DatumGetUInt32
     219             :  *      Returns 32-bit unsigned integer value of a datum.
     220             :  */
     221             : static inline uint32
     222    51878370 : DatumGetUInt32(Datum X)
     223             : {
     224    51878370 :     return (uint32) X;
     225             : }
     226             : 
     227             : /*
     228             :  * UInt32GetDatum
     229             :  *      Returns datum representation for a 32-bit unsigned integer.
     230             :  */
     231             : static inline Datum
     232    62921332 : UInt32GetDatum(uint32 X)
     233             : {
     234    62921332 :     return (Datum) X;
     235             : }
     236             : 
     237             : /*
     238             :  * DatumGetObjectId
     239             :  *      Returns object identifier value of a datum.
     240             :  */
     241             : static inline Oid
     242   988828384 : DatumGetObjectId(Datum X)
     243             : {
     244   988828384 :     return (Oid) X;
     245             : }
     246             : 
     247             : /*
     248             :  * ObjectIdGetDatum
     249             :  *      Returns datum representation for an object identifier.
     250             :  */
     251             : static inline Datum
     252   153133662 : ObjectIdGetDatum(Oid X)
     253             : {
     254   153133662 :     return (Datum) X;
     255             : }
     256             : 
     257             : /*
     258             :  * DatumGetTransactionId
     259             :  *      Returns transaction identifier value of a datum.
     260             :  */
     261             : static inline TransactionId
     262      477906 : DatumGetTransactionId(Datum X)
     263             : {
     264      477906 :     return (TransactionId) X;
     265             : }
     266             : 
     267             : /*
     268             :  * TransactionIdGetDatum
     269             :  *      Returns datum representation for a transaction identifier.
     270             :  */
     271             : static inline Datum
     272      500688 : TransactionIdGetDatum(TransactionId X)
     273             : {
     274      500688 :     return (Datum) X;
     275             : }
     276             : 
     277             : /*
     278             :  * MultiXactIdGetDatum
     279             :  *      Returns datum representation for a multixact identifier.
     280             :  */
     281             : static inline Datum
     282      118286 : MultiXactIdGetDatum(MultiXactId X)
     283             : {
     284      118286 :     return (Datum) X;
     285             : }
     286             : 
     287             : /*
     288             :  * DatumGetCommandId
     289             :  *      Returns command identifier value of a datum.
     290             :  */
     291             : static inline CommandId
     292         194 : DatumGetCommandId(Datum X)
     293             : {
     294         194 :     return (CommandId) X;
     295             : }
     296             : 
     297             : /*
     298             :  * CommandIdGetDatum
     299             :  *      Returns datum representation for a command identifier.
     300             :  */
     301             : static inline Datum
     302         192 : CommandIdGetDatum(CommandId X)
     303             : {
     304         192 :     return (Datum) X;
     305             : }
     306             : 
     307             : /*
     308             :  * DatumGetPointer
     309             :  *      Returns pointer value of a datum.
     310             :  */
     311             : static inline Pointer
     312  1503277074 : DatumGetPointer(Datum X)
     313             : {
     314  1503277074 :     return (Pointer) X;
     315             : }
     316             : 
     317             : /*
     318             :  * PointerGetDatum
     319             :  *      Returns datum representation for a pointer.
     320             :  */
     321             : static inline Datum
     322  1285163446 : PointerGetDatum(const void *X)
     323             : {
     324  1285163446 :     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    91796130 : DatumGetCString(Datum X)
     336             : {
     337    91796130 :     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    87620688 : CStringGetDatum(const char *X)
     351             : {
     352    87620688 :     return PointerGetDatum(X);
     353             : }
     354             : 
     355             : /*
     356             :  * DatumGetName
     357             :  *      Returns name value of a datum.
     358             :  */
     359             : static inline Name
     360   145098154 : DatumGetName(Datum X)
     361             : {
     362   145098154 :     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     3112122 : NameGetDatum(const NameData *X)
     374             : {
     375     3112122 :     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    99600960 : DatumGetInt64(Datum X)
     386             : {
     387             : #ifdef USE_FLOAT8_BYVAL
     388    99600960 :     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    40620544 : Int64GetDatum(int64 X)
     404             : {
     405    40620544 :     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     5855060 : DatumGetUInt64(Datum X)
     420             : {
     421             : #ifdef USE_FLOAT8_BYVAL
     422     5855060 :     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     6076534 : UInt64GetDatum(uint64 X)
     437             : {
     438             : #ifdef USE_FLOAT8_BYVAL
     439     6076534 :     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    22516530 : DatumGetFloat4(Datum X)
     459             : {
     460             :     union
     461             :     {
     462             :         int32       value;
     463             :         float4      retval;
     464             :     }           myunion;
     465             : 
     466    22516530 :     myunion.value = DatumGetInt32(X);
     467    22516530 :     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     1900948 : Float4GetDatum(float4 X)
     476             : {
     477             :     union
     478             :     {
     479             :         float4      value;
     480             :         int32       retval;
     481             :     }           myunion;
     482             : 
     483     1900948 :     myunion.value = X;
     484     1900948 :     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    20786966 : DatumGetFloat8(Datum X)
     495             : {
     496             : #ifdef USE_FLOAT8_BYVAL
     497             :     union
     498             :     {
     499             :         int64       value;
     500             :         float8      retval;
     501             :     }           myunion;
     502             : 
     503    20786966 :     myunion.value = DatumGetInt64(X);
     504    20786966 :     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     9684394 : Float8GetDatum(float8 X)
     520             : {
     521             :     union
     522             :     {
     523             :         float8      value;
     524             :         int64       retval;
     525             :     }           myunion;
     526             : 
     527     9684394 :     myunion.value = X;
     528     9684394 :     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 */