Line data    Source code

       1             : /*-------------------------------------------------------------------------
       2             :  *
       3             :  * postgres.h
       4             :  *    Primary include file for PostgreSQL server .c files
       5             :  *
       6             :  * This should be the first file included by PostgreSQL backend modules.
       7             :  * Client-side code should include postgres_fe.h instead.
       8             :  *
       9             :  *
      10             :  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
      11             :  * Portions Copyright (c) 1995, Regents of the University of California
      12             :  *
      13             :  * src/include/postgres.h
      14             :  *
      15             :  *-------------------------------------------------------------------------
      16             :  */
      17             : /* IWYU pragma: always_keep */
      18             : /*
      19             :  *----------------------------------------------------------------
      20             :  *   TABLE OF CONTENTS
      21             :  *
      22             :  *      When adding stuff to this file, please try to put stuff
      23             :  *      into the relevant section, or add new sections as appropriate.
      24             :  *
      25             :  *    section   description
      26             :  *    -------   ------------------------------------------------
      27             :  *      1)      Datum type + support functions
      28             :  *      2)      miscellaneous
      29             :  *
      30             :  *   NOTES
      31             :  *
      32             :  *  In general, this file should contain declarations that are widely needed
      33             :  *  in the backend environment, but are of no interest outside the backend.
      34             :  *
      35             :  *  Simple type definitions live in c.h, where they are shared with
      36             :  *  postgres_fe.h.  We do that since those type definitions are needed by
      37             :  *  frontend modules that want to deal with binary data transmission to or
      38             :  *  from the backend.  Type definitions in this file should be for
      39             :  *  representations that never escape the backend, such as Datum.
      40             :  *
      41             :  *----------------------------------------------------------------
      42             :  */
      43             : #ifndef POSTGRES_H
      44             : #define POSTGRES_H
      45             : 
      46             : /* IWYU pragma: begin_exports */
      47             : 
      48             : #include "c.h"
      49             : #include "utils/elog.h"
      50             : #include "utils/palloc.h"
      51             : 
      52             : /* IWYU pragma: end_exports */
      53             : 
      54             : /* ----------------------------------------------------------------
      55             :  *              Section 1:  Datum type + support functions
      56             :  * ----------------------------------------------------------------
      57             :  */
      58             : 
      59             : /*
      60             :  * A Datum contains either a value of a pass-by-value type or a pointer to a
      61             :  * value of a pass-by-reference type.  Therefore, we must have
      62             :  * sizeof(Datum) >= sizeof(void *).  No current or foreseeable Postgres
      63             :  * platform has pointers wider than 8 bytes, and standardizing on Datum being
      64             :  * exactly 8 bytes has advantages in reducing cross-platform differences.
      65             :  *
      66             :  * The functions below and the analogous functions for other types should be used to
      67             :  * convert between a Datum and the appropriate C type.
      68             :  */
      69             : 
      70             : typedef uint64_t Datum;
      71             : 
      72             : /*
      73             :  * This symbol is now vestigial, but we continue to define it so as not to
      74             :  * unnecessarily break extension code.
      75             :  */
      76             : #define SIZEOF_DATUM 8
      77             : 
      78             : /*
      79             :  * A NullableDatum is used in places where both a Datum and its nullness needs
      80             :  * to be stored. This can be more efficient than storing datums and nullness
      81             :  * in separate arrays, due to better spatial locality, even if more space may
      82             :  * be wasted due to padding.
      83             :  */
      84             : typedef struct NullableDatum
      85             : {
      86             : #define FIELDNO_NULLABLE_DATUM_DATUM 0
      87             :     Datum       value;
      88             : #define FIELDNO_NULLABLE_DATUM_ISNULL 1
      89             :     bool        isnull;
      90             :     /* due to alignment padding this could be used for flags for free */
      91             : } NullableDatum;
      92             : 
      93             : /*
      94             :  * DatumGetBool
      95             :  *      Returns boolean value of a datum.
      96             :  *
      97             :  * Note: any nonzero value will be considered true.
      98             :  */
      99             : static inline bool
     100   564521314 : DatumGetBool(Datum X)
     101             : {
     102   564521314 :     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   418389310 : BoolGetDatum(bool X)
     113             : {
     114   418389310 :     return (Datum) (X ? 1 : 0);
     115             : }
     116             : 
     117             : /*
     118             :  * DatumGetChar
     119             :  *      Returns character value of a datum.
     120             :  */
     121             : static inline char
     122   196602362 : DatumGetChar(Datum X)
     123             : {
     124   196602362 :     return (char) X;
     125             : }
     126             : 
     127             : /*
     128             :  * CharGetDatum
     129             :  *      Returns datum representation for a character.
     130             :  */
     131             : static inline Datum
     132   159086424 : CharGetDatum(char X)
     133             : {
     134   159086424 :     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   175612480 : DatumGetInt16(Datum X)
     173             : {
     174   175612480 :     return (int16) X;
     175             : }
     176             : 
     177             : /*
     178             :  * Int16GetDatum
     179             :  *      Returns datum representation for a 16-bit integer.
     180             :  */
     181             : static inline Datum
     182    99086050 : Int16GetDatum(int16 X)
     183             : {
     184    99086050 :     return (Datum) X;
     185             : }
     186             : 
     187             : /*
     188             :  * DatumGetUInt16
     189             :  *      Returns 16-bit unsigned integer value of a datum.
     190             :  */
     191             : static inline uint16
     192    11348234 : DatumGetUInt16(Datum X)
     193             : {
     194    11348234 :     return (uint16) X;
     195             : }
     196             : 
     197             : /*
     198             :  * UInt16GetDatum
     199             :  *      Returns datum representation for a 16-bit unsigned integer.
     200             :  */
     201             : static inline Datum
     202     2279458 : UInt16GetDatum(uint16 X)
     203             : {
     204     2279458 :     return (Datum) X;
     205             : }
     206             : 
     207             : /*
     208             :  * DatumGetInt32
     209             :  *      Returns 32-bit integer value of a datum.
     210             :  */
     211             : static inline int32
     212  1951144594 : DatumGetInt32(Datum X)
     213             : {
     214  1951144594 :     return (int32) X;
     215             : }
     216             : 
     217             : /*
     218             :  * Int32GetDatum
     219             :  *      Returns datum representation for a 32-bit integer.
     220             :  */
     221             : static inline Datum
     222  2002647192 : Int32GetDatum(int32 X)
     223             : {
     224  2002647192 :     return (Datum) X;
     225             : }
     226             : 
     227             : /*
     228             :  * DatumGetUInt32
     229             :  *      Returns 32-bit unsigned integer value of a datum.
     230             :  */
     231             : static inline uint32
     232    82759670 : DatumGetUInt32(Datum X)
     233             : {
     234    82759670 :     return (uint32) X;
     235             : }
     236             : 
     237             : /*
     238             :  * UInt32GetDatum
     239             :  *      Returns datum representation for a 32-bit unsigned integer.
     240             :  */
     241             : static inline Datum
     242    62048724 : UInt32GetDatum(uint32 X)
     243             : {
     244    62048724 :     return (Datum) X;
     245             : }
     246             : 
     247             : /*
     248             :  * DatumGetObjectId
     249             :  *      Returns object identifier value of a datum.
     250             :  */
     251             : static inline Oid
     252  1336264046 : DatumGetObjectId(Datum X)
     253             : {
     254  1336264046 :     return (Oid) X;
     255             : }
     256             : 
     257             : /*
     258             :  * ObjectIdGetDatum
     259             :  *      Returns datum representation for an object identifier.
     260             :  */
     261             : static inline Datum
     262   186724034 : ObjectIdGetDatum(Oid X)
     263             : {
     264   186724034 :     return (Datum) X;
     265             : }
     266             : 
     267             : /*
     268             :  * DatumGetTransactionId
     269             :  *      Returns transaction identifier value of a datum.
     270             :  */
     271             : static inline TransactionId
     272     1258374 : DatumGetTransactionId(Datum X)
     273             : {
     274     1258374 :     return (TransactionId) X;
     275             : }
     276             : 
     277             : /*
     278             :  * TransactionIdGetDatum
     279             :  *      Returns datum representation for a transaction identifier.
     280             :  */
     281             : static inline Datum
     282      666184 : TransactionIdGetDatum(TransactionId X)
     283             : {
     284      666184 :     return (Datum) X;
     285             : }
     286             : 
     287             : /*
     288             :  * MultiXactIdGetDatum
     289             :  *      Returns datum representation for a multixact identifier.
     290             :  */
     291             : static inline Datum
     292      135902 : MultiXactIdGetDatum(MultiXactId X)
     293             : {
     294      135902 :     return (Datum) X;
     295             : }
     296             : 
     297             : /*
     298             :  * DatumGetCommandId
     299             :  *      Returns command identifier value of a datum.
     300             :  */
     301             : static inline CommandId
     302         194 : DatumGetCommandId(Datum X)
     303             : {
     304         194 :     return (CommandId) X;
     305             : }
     306             : 
     307             : /*
     308             :  * CommandIdGetDatum
     309             :  *      Returns datum representation for a command identifier.
     310             :  */
     311             : static inline Datum
     312         192 : CommandIdGetDatum(CommandId X)
     313             : {
     314         192 :     return (Datum) X;
     315             : }
     316             : 
     317             : /*
     318             :  * DatumGetPointer
     319             :  *      Returns pointer value of a datum.
     320             :  */
     321             : static inline Pointer
     322  1648888814 : DatumGetPointer(Datum X)
     323             : {
     324  1648888814 :     return (Pointer) (uintptr_t) X;
     325             : }
     326             : 
     327             : /*
     328             :  * PointerGetDatum
     329             :  *      Returns datum representation for a pointer.
     330             :  */
     331             : static inline Datum
     332  1479333196 : PointerGetDatum(const void *X)
     333             : {
     334  1479333196 :     return (Datum) (uintptr_t) X;
     335             : }
     336             : 
     337             : /*
     338             :  * DatumGetCString
     339             :  *      Returns C string (null-terminated string) value of a datum.
     340             :  *
     341             :  * Note: C string is not a full-fledged Postgres type at present,
     342             :  * but type input functions use this conversion for their inputs.
     343             :  */
     344             : static inline char *
     345   109537436 : DatumGetCString(Datum X)
     346             : {
     347   109537436 :     return (char *) DatumGetPointer(X);
     348             : }
     349             : 
     350             : /*
     351             :  * CStringGetDatum
     352             :  *      Returns datum representation for a C string (null-terminated string).
     353             :  *
     354             :  * Note: C string is not a full-fledged Postgres type at present,
     355             :  * but type output functions use this conversion for their outputs.
     356             :  * Note: CString is pass-by-reference; caller must ensure the pointed-to
     357             :  * value has adequate lifetime.
     358             :  */
     359             : static inline Datum
     360   103659168 : CStringGetDatum(const char *X)
     361             : {
     362   103659168 :     return PointerGetDatum(X);
     363             : }
     364             : 
     365             : /*
     366             :  * DatumGetName
     367             :  *      Returns name value of a datum.
     368             :  */
     369             : static inline Name
     370   185474894 : DatumGetName(Datum X)
     371             : {
     372   185474894 :     return (Name) DatumGetPointer(X);
     373             : }
     374             : 
     375             : /*
     376             :  * NameGetDatum
     377             :  *      Returns datum representation for a name.
     378             :  *
     379             :  * Note: Name is pass-by-reference; caller must ensure the pointed-to
     380             :  * value has adequate lifetime.
     381             :  */
     382             : static inline Datum
     383     3621520 : NameGetDatum(const NameData *X)
     384             : {
     385     3621520 :     return CStringGetDatum(NameStr(*X));
     386             : }
     387             : 
     388             : /*
     389             :  * DatumGetInt64
     390             :  *      Returns 64-bit integer value of a datum.
     391             :  */
     392             : static inline int64
     393   140413350 : DatumGetInt64(Datum X)
     394             : {
     395   140413350 :     return (int64) X;
     396             : }
     397             : 
     398             : /*
     399             :  * Int64GetDatum
     400             :  *      Returns datum representation for a 64-bit integer.
     401             :  */
     402             : static inline Datum
     403    90307608 : Int64GetDatum(int64 X)
     404             : {
     405    90307608 :     return (Datum) X;
     406             : }
     407             : 
     408             : /*
     409             :  * DatumGetUInt64
     410             :  *      Returns 64-bit unsigned integer value of a datum.
     411             :  */
     412             : static inline uint64
     413    14134180 : DatumGetUInt64(Datum X)
     414             : {
     415    14134180 :     return (uint64) X;
     416             : }
     417             : 
     418             : /*
     419             :  * UInt64GetDatum
     420             :  *      Returns datum representation for a 64-bit unsigned integer.
     421             :  */
     422             : static inline Datum
     423    10491152 : UInt64GetDatum(uint64 X)
     424             : {
     425    10491152 :     return (Datum) X;
     426             : }
     427             : 
     428             : /*
     429             :  * Float <-> Datum conversions
     430             :  *
     431             :  * These have to be implemented as inline functions rather than macros, when
     432             :  * passing by value, because many machines pass int and float function
     433             :  * parameters/results differently; so we need to play weird games with unions.
     434             :  */
     435             : 
     436             : /*
     437             :  * DatumGetFloat4
     438             :  *      Returns 4-byte floating point value of a datum.
     439             :  */
     440             : static inline float4
     441    30657972 : DatumGetFloat4(Datum X)
     442             : {
     443             :     union
     444             :     {
     445             :         int32       value;
     446             :         float4      retval;
     447             :     }           myunion;
     448             : 
     449    30657972 :     myunion.value = DatumGetInt32(X);
     450    30657972 :     return myunion.retval;
     451             : }
     452             : 
     453             : /*
     454             :  * Float4GetDatum
     455             :  *      Returns datum representation for a 4-byte floating point number.
     456             :  */
     457             : static inline Datum
     458     2413580 : Float4GetDatum(float4 X)
     459             : {
     460             :     union
     461             :     {
     462             :         float4      value;
     463             :         int32       retval;
     464             :     }           myunion;
     465             : 
     466     2413580 :     myunion.value = X;
     467     2413580 :     return Int32GetDatum(myunion.retval);
     468             : }
     469             : 
     470             : /*
     471             :  * DatumGetFloat8
     472             :  *      Returns 8-byte floating point value of a datum.
     473             :  */
     474             : static inline float8
     475    26536004 : DatumGetFloat8(Datum X)
     476             : {
     477             :     union
     478             :     {
     479             :         int64       value;
     480             :         float8      retval;
     481             :     }           myunion;
     482             : 
     483    26536004 :     myunion.value = DatumGetInt64(X);
     484    26536004 :     return myunion.retval;
     485             : }
     486             : 
     487             : /*
     488             :  * Float8GetDatum
     489             :  *      Returns datum representation for an 8-byte floating point number.
     490             :  */
     491             : static inline Datum
     492    13511280 : Float8GetDatum(float8 X)
     493             : {
     494             :     union
     495             :     {
     496             :         float8      value;
     497             :         int64       retval;
     498             :     }           myunion;
     499             : 
     500    13511280 :     myunion.value = X;
     501    13511280 :     return Int64GetDatum(myunion.retval);
     502             : }
     503             : 
     504             : /*
     505             :  * Int64GetDatumFast
     506             :  * Float8GetDatumFast
     507             :  *
     508             :  * These macros were intended to allow writing code that does not depend on
     509             :  * whether int64 and float8 are pass-by-reference types, while not
     510             :  * sacrificing performance when they are.  They are no longer different
     511             :  * from the regular functions, though we keep the assertions to protect
     512             :  * code that might get back-patched into older branches.
     513             :  */
     514             : 
     515             : #define Int64GetDatumFast(X) \
     516             :     (AssertVariableIsOfTypeMacro(X, int64), Int64GetDatum(X))
     517             : #define Float8GetDatumFast(X) \
     518             :     (AssertVariableIsOfTypeMacro(X, double), Float8GetDatum(X))
     519             : 
     520             : 
     521             : /* ----------------------------------------------------------------
     522             :  *              Section 2:  miscellaneous
     523             :  * ----------------------------------------------------------------
     524             :  */
     525             : 
     526             : /*
     527             :  * NON_EXEC_STATIC: It's sometimes useful to define a variable or function
     528             :  * that is normally static but extern when using EXEC_BACKEND (see
     529             :  * pg_config_manual.h).  There would then typically be some code in
     530             :  * postmaster.c that uses those extern symbols to transfer state between
     531             :  * processes or do whatever other things it needs to do in EXEC_BACKEND mode.
     532             :  */
     533             : #ifdef EXEC_BACKEND
     534             : #define NON_EXEC_STATIC
     535             : #else
     536             : #define NON_EXEC_STATIC static
     537             : #endif
     538             : 
     539             : #endif                          /* POSTGRES_H */