PostgreSQL Source Code  git master
pg_type.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * pg_type.h
4  * definition of the "type" system catalog (pg_type)
5  *
6  *
7  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
8  * Portions Copyright (c) 1994, Regents of the University of California
9  *
10  * src/include/catalog/pg_type.h
11  *
12  * NOTES
13  * The Catalog.pm module reads this file and derives schema
14  * information.
15  *
16  *-------------------------------------------------------------------------
17  */
18 #ifndef PG_TYPE_H
19 #define PG_TYPE_H
20 
21 #include "catalog/genbki.h"
22 #include "catalog/objectaddress.h"
23 #include "catalog/pg_type_d.h"
24 #include "nodes/nodes.h"
25 
26 /* ----------------
27  * pg_type definition. cpp turns this into
28  * typedef struct FormData_pg_type
29  *
30  * Some of the values in a pg_type instance are copied into
31  * pg_attribute instances. Some parts of Postgres use the pg_type copy,
32  * while others use the pg_attribute copy, so they must match.
33  * See struct FormData_pg_attribute for details.
34  * ----------------
35  */
36 CATALOG(pg_type,1247,TypeRelationId) BKI_BOOTSTRAP BKI_ROWTYPE_OID(71,TypeRelation_Rowtype_Id) BKI_SCHEMA_MACRO
37 {
38  Oid oid; /* oid */
39 
40  /* type name */
42 
43  /* OID of namespace containing this type */
44  Oid typnamespace BKI_DEFAULT(pg_catalog) BKI_LOOKUP(pg_namespace);
45 
46  /* type owner */
47  Oid typowner BKI_DEFAULT(POSTGRES) BKI_LOOKUP(pg_authid);
48 
49  /*
50  * For a fixed-size type, typlen is the number of bytes we use to
51  * represent a value of this type, e.g. 4 for an int4. But for a
52  * variable-length type, typlen is negative. We use -1 to indicate a
53  * "varlena" type (one that has a length word), -2 to indicate a
54  * null-terminated C string.
55  */
57 
58  /*
59  * typbyval determines whether internal Postgres routines pass a value of
60  * this type by value or by reference. typbyval had better be false if
61  * the length is not 1, 2, or 4 (or 8 on 8-byte-Datum machines).
62  * Variable-length types are always passed by reference. Note that
63  * typbyval can be false even if the length would allow pass-by-value; for
64  * example, type macaddr8 is pass-by-ref even when Datum is 8 bytes.
65  */
66  bool typbyval BKI_ARRAY_DEFAULT(f);
67 
68  /*
69  * typtype is 'b' for a base type, 'c' for a composite type (e.g., a
70  * table's rowtype), 'd' for a domain, 'e' for an enum type, 'p' for a
71  * pseudo-type, or 'r' for a range type. (Use the TYPTYPE macros below.)
72  *
73  * If typtype is 'c', typrelid is the OID of the class' entry in pg_class.
74  */
75  char typtype BKI_DEFAULT(b) BKI_ARRAY_DEFAULT(b);
76 
77  /*
78  * typcategory and typispreferred help the parser distinguish preferred
79  * and non-preferred coercions. The category can be any single ASCII
80  * character (but not \0). The categories used for built-in types are
81  * identified by the TYPCATEGORY macros below.
82  */
83 
84  /* arbitrary type classification */
85  char typcategory BKI_ARRAY_DEFAULT(A);
86 
87  /* is type "preferred" within its category? */
88  bool typispreferred BKI_DEFAULT(f) BKI_ARRAY_DEFAULT(f);
89 
90  /*
91  * If typisdefined is false, the entry is only a placeholder (forward
92  * reference). We know the type's name and owner, but not yet anything
93  * else about it.
94  */
95  bool typisdefined BKI_DEFAULT(t);
96 
97  /* delimiter for arrays of this type */
98  char typdelim BKI_DEFAULT(',');
99 
100  /* associated pg_class OID if a composite type, else 0 */
102 
103  /*
104  * Type-specific subscripting handler. If typsubscript is 0, it means
105  * that this type doesn't support subscripting. Note that various parts
106  * of the system deem types to be "true" array types only if their
107  * typsubscript is array_subscript_handler.
108  */
110 
111  /*
112  * If typelem is not 0 then it identifies another row in pg_type, defining
113  * the type yielded by subscripting. This should be 0 if typsubscript is
114  * 0. However, it can be 0 when typsubscript isn't 0, if the handler
115  * doesn't need typelem to determine the subscripting result type. Note
116  * that a typelem dependency is considered to imply physical containment
117  * of the element type in this type; so DDL changes on the element type
118  * might be restricted by the presence of this type.
119  */
120  Oid typelem BKI_DEFAULT(0) BKI_LOOKUP_OPT(pg_type);
121 
122  /*
123  * If there is a "true" array type having this type as element type,
124  * typarray links to it. Zero if no associated "true" array type.
125  */
126  Oid typarray BKI_DEFAULT(0) BKI_ARRAY_DEFAULT(0) BKI_LOOKUP_OPT(pg_type);
127 
128  /*
129  * I/O conversion procedures for the datatype.
130  */
131 
132  /* text format (required) */
135 
136  /* binary format (optional) */
139 
140  /*
141  * I/O functions for optional type modifiers.
142  */
143  regproc typmodin BKI_DEFAULT(-) BKI_LOOKUP_OPT(pg_proc);
144  regproc typmodout BKI_DEFAULT(-) BKI_LOOKUP_OPT(pg_proc);
145 
146  /*
147  * Custom ANALYZE procedure for the datatype (0 selects the default).
148  */
150 
151  /* ----------------
152  * typalign is the alignment required when storing a value of this
153  * type. It applies to storage on disk as well as most
154  * representations of the value inside Postgres. When multiple values
155  * are stored consecutively, such as in the representation of a
156  * complete row on disk, padding is inserted before a datum of this
157  * type so that it begins on the specified boundary. The alignment
158  * reference is the beginning of the first datum in the sequence.
159  *
160  * 'c' = CHAR alignment, ie no alignment needed.
161  * 's' = SHORT alignment (2 bytes on most machines).
162  * 'i' = INT alignment (4 bytes on most machines).
163  * 'd' = DOUBLE alignment (8 bytes on many machines, but by no means all).
164  * (Use the TYPALIGN macros below for these.)
165  *
166  * See include/access/tupmacs.h for the macros that compute these
167  * alignment requirements. Note also that we allow the nominal alignment
168  * to be violated when storing "packed" varlenas; the TOAST mechanism
169  * takes care of hiding that from most code.
170  *
171  * NOTE: for types used in system tables, it is critical that the
172  * size and alignment defined in pg_type agree with the way that the
173  * compiler will lay out the field in a struct representing a table row.
174  * ----------------
175  */
176  char typalign;
177 
178  /* ----------------
179  * typstorage tells if the type is prepared for toasting and what
180  * the default strategy for attributes of this type should be.
181  *
182  * 'p' PLAIN type not prepared for toasting
183  * 'e' EXTERNAL external storage possible, don't try to compress
184  * 'x' EXTENDED try to compress and store external if required
185  * 'm' MAIN like 'x' but try to keep in main tuple
186  * (Use the TYPSTORAGE macros below for these.)
187  *
188  * Note that 'm' fields can also be moved out to secondary storage,
189  * but only as a last resort ('e' and 'x' fields are moved first).
190  * ----------------
191  */
192  char typstorage BKI_DEFAULT(p) BKI_ARRAY_DEFAULT(x);
193 
194  /*
195  * This flag represents a "NOT NULL" constraint against this datatype.
196  *
197  * If true, the attnotnull column for a corresponding table column using
198  * this datatype will always enforce the NOT NULL constraint.
199  *
200  * Used primarily for domain types.
201  */
202  bool typnotnull BKI_DEFAULT(f);
203 
204  /*
205  * Domains use typbasetype to show the base (or domain) type that the
206  * domain is based on. Zero if the type is not a domain.
207  */
208  Oid typbasetype BKI_DEFAULT(0) BKI_LOOKUP_OPT(pg_type);
209 
210  /*
211  * Domains use typtypmod to record the typmod to be applied to their base
212  * type (-1 if base type does not use a typmod). -1 if this type is not a
213  * domain.
214  */
215  int32 typtypmod BKI_DEFAULT(-1);
216 
217  /*
218  * typndims is the declared number of dimensions for an array domain type
219  * (i.e., typbasetype is an array type). Otherwise zero.
220  */
221  int32 typndims BKI_DEFAULT(0);
222 
223  /*
224  * Collation: 0 if type cannot use collations, nonzero (typically
225  * DEFAULT_COLLATION_OID) for collatable base types, possibly some other
226  * OID for domains over collatable types
227  */
228  Oid typcollation BKI_DEFAULT(0) BKI_LOOKUP_OPT(pg_collation);
229 
230 #ifdef CATALOG_VARLEN /* variable-length fields start here */
231 
232  /*
233  * If typdefaultbin is not NULL, it is the nodeToString representation of
234  * a default expression for the type. Currently this is only used for
235  * domains.
236  */
237  pg_node_tree typdefaultbin BKI_DEFAULT(_null_) BKI_ARRAY_DEFAULT(_null_);
238 
239  /*
240  * typdefault is NULL if the type has no associated default value. If
241  * typdefaultbin is not NULL, typdefault must contain a human-readable
242  * version of the default expression represented by typdefaultbin. If
243  * typdefaultbin is NULL and typdefault is not, then typdefault is the
244  * external representation of the type's default value, which may be fed
245  * to the type's input converter to produce a constant.
246  */
247  text typdefault BKI_DEFAULT(_null_) BKI_ARRAY_DEFAULT(_null_);
248 
249  /*
250  * Access permissions
251  */
252  aclitem typacl[1] BKI_DEFAULT(_null_);
253 #endif
255 
256 /* ----------------
257  * Form_pg_type corresponds to a pointer to a row with
258  * the format of pg_type relation.
259  * ----------------
260  */
262 
263 DECLARE_TOAST(pg_type, 4171, 4172);
264 
265 DECLARE_UNIQUE_INDEX_PKEY(pg_type_oid_index, 2703, TypeOidIndexId, pg_type, btree(oid oid_ops));
266 DECLARE_UNIQUE_INDEX(pg_type_typname_nsp_index, 2704, TypeNameNspIndexId, pg_type, btree(typname name_ops, typnamespace oid_ops));
267 
268 MAKE_SYSCACHE(TYPEOID, pg_type_oid_index, 64);
269 MAKE_SYSCACHE(TYPENAMENSP, pg_type_typname_nsp_index, 64);
270 
271 #ifdef EXPOSE_TO_CLIENT_CODE
272 
273 /*
274  * macros for values of poor-mans-enumerated-type columns
275  */
276 #define TYPTYPE_BASE 'b' /* base type (ordinary scalar type) */
277 #define TYPTYPE_COMPOSITE 'c' /* composite (e.g., table's rowtype) */
278 #define TYPTYPE_DOMAIN 'd' /* domain over another type */
279 #define TYPTYPE_ENUM 'e' /* enumerated type */
280 #define TYPTYPE_MULTIRANGE 'm' /* multirange type */
281 #define TYPTYPE_PSEUDO 'p' /* pseudo-type */
282 #define TYPTYPE_RANGE 'r' /* range type */
283 
284 #define TYPCATEGORY_INVALID '\0' /* not an allowed category */
285 #define TYPCATEGORY_ARRAY 'A'
286 #define TYPCATEGORY_BOOLEAN 'B'
287 #define TYPCATEGORY_COMPOSITE 'C'
288 #define TYPCATEGORY_DATETIME 'D'
289 #define TYPCATEGORY_ENUM 'E'
290 #define TYPCATEGORY_GEOMETRIC 'G'
291 #define TYPCATEGORY_NETWORK 'I' /* think INET */
292 #define TYPCATEGORY_NUMERIC 'N'
293 #define TYPCATEGORY_PSEUDOTYPE 'P'
294 #define TYPCATEGORY_RANGE 'R'
295 #define TYPCATEGORY_STRING 'S'
296 #define TYPCATEGORY_TIMESPAN 'T'
297 #define TYPCATEGORY_USER 'U'
298 #define TYPCATEGORY_BITSTRING 'V' /* er ... "varbit"? */
299 #define TYPCATEGORY_UNKNOWN 'X'
300 #define TYPCATEGORY_INTERNAL 'Z'
301 
302 #define TYPALIGN_CHAR 'c' /* char alignment (i.e. unaligned) */
303 #define TYPALIGN_SHORT 's' /* short alignment (typically 2 bytes) */
304 #define TYPALIGN_INT 'i' /* int alignment (typically 4 bytes) */
305 #define TYPALIGN_DOUBLE 'd' /* double alignment (often 8 bytes) */
306 
307 #define TYPSTORAGE_PLAIN 'p' /* type not prepared for toasting */
308 #define TYPSTORAGE_EXTERNAL 'e' /* toastable, don't try to compress */
309 #define TYPSTORAGE_EXTENDED 'x' /* fully toastable */
310 #define TYPSTORAGE_MAIN 'm' /* like 'x' but try to store inline */
311 
312 /* Is a type OID a polymorphic pseudotype? (Beware of multiple evaluation) */
313 #define IsPolymorphicType(typid) \
314  (IsPolymorphicTypeFamily1(typid) || \
315  IsPolymorphicTypeFamily2(typid))
316 
317 /* Code not part of polymorphic type resolution should not use these macros: */
318 #define IsPolymorphicTypeFamily1(typid) \
319  ((typid) == ANYELEMENTOID || \
320  (typid) == ANYARRAYOID || \
321  (typid) == ANYNONARRAYOID || \
322  (typid) == ANYENUMOID || \
323  (typid) == ANYRANGEOID || \
324  (typid) == ANYMULTIRANGEOID)
325 
326 #define IsPolymorphicTypeFamily2(typid) \
327  ((typid) == ANYCOMPATIBLEOID || \
328  (typid) == ANYCOMPATIBLEARRAYOID || \
329  (typid) == ANYCOMPATIBLENONARRAYOID || \
330  (typid) == ANYCOMPATIBLERANGEOID || \
331  (typid) == ANYCOMPATIBLEMULTIRANGEOID)
332 
333 /* Is this a "true" array type? (Requires fmgroids.h) */
334 #define IsTrueArrayType(typeForm) \
335  (OidIsValid((typeForm)->typelem) && \
336  (typeForm)->typsubscript == F_ARRAY_SUBSCRIPT_HANDLER)
337 
338 /*
339  * Backwards compatibility for ancient random spellings of pg_type OID macros.
340  * Don't use these names in new code.
341  */
342 #define CASHOID MONEYOID
343 #define LSNOID PG_LSNOID
344 
345 #endif /* EXPOSE_TO_CLIENT_CODE */
346 
347 
348 extern ObjectAddress TypeShellMake(const char *typeName,
349  Oid typeNamespace,
350  Oid ownerId);
351 
352 extern ObjectAddress TypeCreate(Oid newTypeOid,
353  const char *typeName,
354  Oid typeNamespace,
355  Oid relationOid,
356  char relationKind,
357  Oid ownerId,
358  int16 internalSize,
359  char typeType,
360  char typeCategory,
361  bool typePreferred,
362  char typDelim,
363  Oid inputProcedure,
364  Oid outputProcedure,
365  Oid receiveProcedure,
366  Oid sendProcedure,
367  Oid typmodinProcedure,
368  Oid typmodoutProcedure,
369  Oid analyzeProcedure,
370  Oid subscriptProcedure,
371  Oid elementType,
372  bool isImplicitArray,
373  Oid arrayType,
374  Oid baseType,
375  const char *defaultTypeValue,
376  char *defaultTypeBin,
377  bool passedByValue,
378  char alignment,
379  char storage,
380  int32 typeMod,
381  int32 typNDims,
382  bool typeNotNull,
383  Oid typeCollation);
384 
385 extern void GenerateTypeDependencies(HeapTuple typeTuple,
386  Relation typeCatalog,
387  Node *defaultExpr,
388  void *typacl,
389  char relationKind, /* only for relation
390  * rowtypes */
391  bool isImplicitArray,
392  bool isDependentType,
393  bool makeExtensionDep,
394  bool rebuild);
395 
396 extern void RenameTypeInternal(Oid typeOid, const char *newTypeName,
397  Oid typeNamespace);
398 
399 extern char *makeArrayTypeName(const char *typeName, Oid typeNamespace);
400 
401 extern bool moveArrayTypeName(Oid typeOid, const char *typeName,
402  Oid typeNamespace);
403 
404 extern char *makeMultirangeTypeName(const char *rangeTypeName,
405  Oid typeNamespace);
406 
407 #endif /* PG_TYPE_H */
Datum array_typanalyze(PG_FUNCTION_ARGS)
Datum array_recv(PG_FUNCTION_ARGS)
Definition: arrayfuncs.c:1272
Datum array_send(PG_FUNCTION_ARGS)
Definition: arrayfuncs.c:1549
Datum array_in(PG_FUNCTION_ARGS)
Definition: arrayfuncs.c:180
Datum array_out(PG_FUNCTION_ARGS)
Definition: arrayfuncs.c:1017
Datum array_subscript_handler(PG_FUNCTION_ARGS)
Definition: arraysubs.c:539
signed short int16
Definition: c.h:482
signed int int32
Definition: c.h:483
Oid regproc
Definition: c.h:638
#define BKI_LOOKUP(catalog)
Definition: genbki.h:46
#define BKI_LOOKUP_OPT(catalog)
Definition: genbki.h:47
#define BKI_BOOTSTRAP
Definition: genbki.h:26
#define BKI_ROWTYPE_OID(oid, oidmacro)
Definition: genbki.h:28
#define storage
Definition: indent_codes.h:68
int b
Definition: isn.c:70
int x
Definition: isn.c:71
char * makeMultirangeTypeName(const char *rangeTypeName, Oid typeNamespace)
Definition: pg_type.c:944
DECLARE_UNIQUE_INDEX_PKEY(pg_type_oid_index, 2703, TypeOidIndexId, pg_type, btree(oid oid_ops))
TypeRelation_Rowtype_Id BKI_SCHEMA_MACRO
Definition: pg_type.h:37
void GenerateTypeDependencies(HeapTuple typeTuple, Relation typeCatalog, Node *defaultExpr, void *typacl, char relationKind, bool isImplicitArray, bool isDependentType, bool makeExtensionDep, bool rebuild)
Definition: pg_type.c:558
void RenameTypeInternal(Oid typeOid, const char *newTypeName, Oid typeNamespace)
Definition: pg_type.c:759
ObjectAddress TypeCreate(Oid newTypeOid, const char *typeName, Oid typeNamespace, Oid relationOid, char relationKind, Oid ownerId, int16 internalSize, char typeType, char typeCategory, bool typePreferred, char typDelim, Oid inputProcedure, Oid outputProcedure, Oid receiveProcedure, Oid sendProcedure, Oid typmodinProcedure, Oid typmodoutProcedure, Oid analyzeProcedure, Oid subscriptProcedure, Oid elementType, bool isImplicitArray, Oid arrayType, Oid baseType, const char *defaultTypeValue, char *defaultTypeBin, bool passedByValue, char alignment, char storage, int32 typeMod, int32 typNDims, bool typeNotNull, Oid typeCollation)
Definition: pg_type.c:196
char * makeArrayTypeName(const char *typeName, Oid typeNamespace)
Definition: pg_type.c:834
int16 typlen BKI_ARRAY_DEFAULT(-1)
bool moveArrayTypeName(Oid typeOid, const char *typeName, Oid typeNamespace)
Definition: pg_type.c:899
char typalign
Definition: pg_type.h:176
FormData_pg_type
Definition: pg_type.h:254
CATALOG(pg_type, 1247, TypeRelationId) BKI_BOOTSTRAP BKI_ROWTYPE_OID(71
FormData_pg_type * Form_pg_type
Definition: pg_type.h:261
ObjectAddress TypeShellMake(const char *typeName, Oid typeNamespace, Oid ownerId)
Definition: pg_type.c:58
DECLARE_UNIQUE_INDEX(pg_type_typname_nsp_index, 2704, TypeNameNspIndexId, pg_type, btree(typname name_ops, typnamespace oid_ops))
Oid typnamespace BKI_DEFAULT(pg_catalog) BKI_LOOKUP(pg_namespace)
MAKE_SYSCACHE(TYPEOID, pg_type_oid_index, 64)
NameData typname
Definition: pg_type.h:41
DECLARE_TOAST(pg_type, 4171, 4172)
unsigned int Oid
Definition: postgres_ext.h:31
Definition: nodes.h:129
Definition: c.h:730
Definition: c.h:676