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