2 .Dt LIBCDECL \&3 "Cdecl99 Developer's Manual"
6 .Nd C library for making sense of C declarations
10 .Fd struct cdecl *cdecl_parse_decl(const char *declstr);
11 .Fd struct cdecl *cdecl_parse_english(const char *english);
12 .Fd void cdecl_free(struct cdecl *decl);
14 .Fd size_t cdecl_declare(char *buf, size_t n, struct cdecl *decl);
15 .Fd size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl);
17 .Fd const struct cdecl_error *cdecl_get_error(void);
19 .Fd int cdecl_spec_kind(struct cdecl_declspec *spec);
20 .Fd int cdecl_is_abstract(struct cdecl_declarator *declarator);
23 provides support for parsing C declarations and translating them to something
24 resembling English and vice-versa.
25 This manual describes the programmers' interface only; for details such as what
26 C language features are supported or the syntax of English declarations, please
32 is intended to be portable to any system with a standard C compiler.
33 The library is thread-safe when appropriate facilities exist and are enabled at
37 reserves all identifiers beginning with either
41 in both the tag and ordinary identifier namespaces.
42 All external names beginning with
44 are reserved, and the library headers may define object-like macros beginning
49 library headers may use other identifiers where they do not pollute the global
50 namespaces, such as struct members or function parameter names.
51 Such internal identifiers shall not contain any upper-case letters.
52 As these internal identifiers can only conflict with object-like macros, this
53 practice is safe as long as the convention of defining object-like macros using
54 upper-case letters is adhered to.
56 External names beginning with
58 followed by two consecutive underscores are not considered part of the ABI and
59 are thus subject to change at any time.
60 .Sh ABSTRACT SYNTAX TREE
63 generally operate on an abstract syntax tree representing a C declaration.
64 A string is parsed into an AST which can be subsequently rendered into another
66 Since some information about the original string is discarded when generating
67 the AST, parsing a declaration and then rendering to the same format is not the
69 The AST is represented by the following structure:
70 .Bd -literal -offset indent
73 struct cdecl_declspec *specifiers;
74 struct cdecl_declarator *declarators;
78 At the top level, every declaration consists of one or more declaration
79 specifiers followed by one or more full declarators; hence, the
83 members are always non-null.
84 A declaration with more than one declarator is represented by using the
86 member to form a singly-linked list of ASTs, one element for each declarator.
87 In the case of the toplevel declaration, the declaration specifiers will be
88 identical for all elements of the list.
89 But when the same kind of list is used to represent function parameters, the
90 specifiers may be different for each element.
92 There are four kinds of declaration specifiers: storage-class, function and
93 type specifiers, as well as type qualifiers.
94 All are represented by the structure:
95 .Bd -literal -offset indent
96 struct cdecl_declspec {
97 struct cdecl_declspec *next;
103 When multiple declaration specifiers are present, they are represented as
104 a singly-linked list, one element for each specifier.
105 Specifiers can appear in any order.
108 .Fd int cdecl_spec_kind(struct cdecl_declspec *spec);
110 can be used to determine what kind of specifier
112 is. The result is one of the following values:
113 .Bl -column ".Dv CDECL_SPEC_TYPE"
114 .It Em Kind Ta Em Description
115 .It Dv CDECL_SPEC_TYPE Ta Type specifier .
116 .It Dv CDECL_SPEC_STOR Ta Storage-class specifier .
117 .It Dv CDECL_SPEC_QUAL Ta Type qualifier .
118 .It Dv CDECL_SPEC_FUNC Ta Function specifier .
121 The following table describes all the possible types of declaration specifiers:
122 .Bl -column ".Dv CDECL_TYPE_IMAGINARY"
123 .It Em Em Type Ta Em Description
124 .It Dv CDECL_TYPE_VOID Ta Fa void No type specifier .
125 .It Dv CDECL_TYPE_CHAR Ta Fa char No type specifier .
126 .It Dv CDECL_TYPE_SHORT Ta Fa short No type specifier .
127 .It Dv CDECL_TYPE_INT Ta Fa int No type specifier .
128 .It Dv CDECL_TYPE_LONG Ta Fa long No type specifier .
129 .It Dv CDECL_TYPE_FLOAT Ta Fa float No type specifier .
130 .It Dv CDECL_TYPE_DOUBLE Ta Fa double No type specifier .
131 .It Dv CDECL_TYPE_SIGNED Ta Fa signed No type specifier .
132 .It Dv CDECL_TYPE_UNSIGNED Ta Fa unsigned No type specifier .
133 .It Dv CDECL_TYPE_BOOL Ta Fa _Bool No type specifier .
134 .It Dv CDECL_TYPE_COMPLEX Ta Fa _Comples No type specifier .
135 .It Dv CDECL_TYPE_IMAGINARY Ta Fa _Imaginary No type specifier .
136 .It Dv CDECL_TYPE_STRUCT Ta Fa struct No type specifier .
139 member points to a C string containing the struct tag.
140 .It Dv CDECL_TYPE_UNION Ta Fa union No type specifier .
143 member points to a C string containing the union tag.
144 .It Dv CDECL_TYPE_ENUM Ta Fa enum No type specifier .
147 member points to a C string containing the enum tag.
148 .It Dv CDECL_TYPE_IDENT Ta Typedef name type specifier .
151 member points to a C string containing the identifier.
152 .It Dv CDECL_STOR_TYPEDEF Ta Fa typedef No storage-class specifier .
153 .It Dv CDECL_STOR_EXTERN Ta Fa extern No storage-class specifier .
154 .It Dv CDECL_STOR_STATIC Ta Fa static No storage-class specifier .
155 .It Dv CDECL_STOR_AUTO Ta Fa auto No storage-class specifier .
156 .It Dv CDECL_STOR_REGISTER Ta Fa register No storage-class specifier .
157 .It Dv CDECL_QUAL_RESTRICT Ta Fa restrict No type qualifier .
158 .It Dv CDECL_QUAL_VOLATILE Ta Fa volatile No type qualifier .
159 .It Dv CDECL_QUAL_CONST Ta Fa const No type qualifier .
160 .It Dv CDECL_FUNC_INLINE Ta Fa inline No function specifier .
163 Declarators are represented by the structure:
164 .Bd -literal -offset indent
165 struct cdecl_declarator {
166 struct cdecl_declarator *child;
170 struct cdecl_pointer pointer;
171 struct cdecl_array array;
172 struct cdecl_function function;
177 With the exception of function parameters (which are handled separately),
178 declarators form a chain from
179 .Do outermost Dc to Do innermost Dc
181 This relationship is expressed by the
183 struct member, which points to the next innermost declarator in the chain.
184 Unfortunately, C's declaration syntax is, in a sense, inside-out.
185 Thus, one needs to follow the chain backwards (from innermost to outermost) to
186 understand the semantic relationship between declarators in the chain.
187 In the next section, we will use the word
189 to describe this inverted child relationship: we consider the outermost
192 as the declaration's base type (found amongst the declaration specifiers,
193 .No e.g. Li int , const unsigned long ,
196 The five types of declarators, described below, are distinguished by the
199 Each declarator (except null declarators) carries additional information
200 specific to its type, which corresponds to the members of the union
202 The possible values are described by the following table:
203 .Bl -column ".Dv CDECL_DECL_FUNCTION" ".Em Union Member"
204 .It Em Declarator Type Ta Em Union Member Ta Em Description
205 .It Dv CDECL_DECL_NULL Ta (none) Ta Declares nothing. This
206 declarator terminates the declarator chain, and has a NULL
208 .It Dv CDECL_DECL_IDENT Ta Va ident Ta Declares an identifier. This
209 declarator has a NULL
211 .It Dv CDECL_DECL_POINTER Ta Va pointer Ta Declares a pointer, as in
212 .Do pointer to Va parent Dc
213 .It Dv CDECL_DECL_ARRAY Ta Va array Ta Declares an array, as in
214 .Do array of Va parent Dc
215 .It Dv CDECL_DECL_FUNCTION Ta Va function Ta Declares a function, as in
216 .Do function returning Va parent Dc
218 .Ss Terminal Declarators
219 Null and identifier declarators have no children and are thus leaf nodes.
220 A null declarator is not strictly a C language construct, but is used by
222 to indicate an abstract declarator; that is, one which does not declare any
224 Such declarators appear in type names and possibly function parameters.
225 An identifier declarator has the obvious meaning; the
227 union member points to the C string containing the identifier.
229 Since a null declarator may be deeply nested in the declarator chain, the
232 .Fd int cdecl_is_abstract(struct cdecl_declarator *declarator);
234 can be used to determine whether or not a given declarator declares an
236 The result is true if and only if the declarator is abstract.
237 .Ss Pointer Declarators
238 .Bd -literal -offset indent
239 struct cdecl_pointer {
240 struct cdecl_declspec *qualifiers;
246 member is non-null, then it points to the first element of a singly-linked list
248 .Ss Array Declarators
249 .Bd -literal -offset indent
250 typedef unsigned long long cdecl_uintmax; /* depends on configuration */
253 cdecl_uintmax length;
259 member is non-null, then this declarator is a variable-length array declarator.
262 member points to an identifier if it is known, else it points to the empty
266 is positive, then this is an array declarator with the specified length.
267 Otherwise, this is an incomplete array declarator.
269 If the library was configured using a compiler which does not support
270 .Vt unsigned long long ,
281 .Ss Function Declarators
282 .Bd -literal -offset indent
283 typedef _Bool cdecl_bool; /* depends on configuration */
284 struct cdecl_function {
285 struct cdecl *parameters;
292 is null, then this is a non-prototype function declarator with an empty
296 points to the first element of a singly-linked list of declarations
297 representing the function parameters.
298 Note that, unlike toplevel declarations, each function parameter has exactly
299 one full declarator (abstract or otherwise).
302 is non-zero, then the function is variadic.
304 Please note that if the compiler used to build the library does not support
311 In most cases these will have a compatible binary representation, provided
312 that applications do not set
314 to any values besides 0 or 1.
316 Old-style function declarations with non-empty identifier lists cannot be
317 directly represented by this structure.
318 Such declarations are syntactically identical to a prototype with every
319 parameter consisting solely of a typedef name.
321 cannot tell these apart when parsing and thus will return a parameter
322 list, which can be rendered as expected.
327 Such functions will be documented as indicating an error condition in a
329 It is sometimes necessary to know more about a particular error in order to
330 print an informative error message or perform some other action.
333 provides a structure which describes a particular error.
334 .Bd -literal -offset indent
343 member identifies the sort of error which has occurred, while the
345 member points to a string containing a human-readable description of the error.
346 This error information can be retrieved by calling the function
348 .Fd const struct cdecl_error *cdecl_get_error(void);
350 which returns a pointer to the error structure most recently generated in the
352 It is therefore thread-safe in the sense that errors occurring concurrently
353 in another thread will not interfere with a call to
354 .Fn cdecl_get_error .
355 The returned structure shall remain valid until the next call to any function
358 by the same thread, other than another call to
359 .Fn cdecl_get_error .
363 call has indicated that an error occurred in the current thread, the result
367 .Sh PARSING DECLARATIONS
370 .Fd struct cdecl *cdecl_parse_decl(const char *decl);
371 .Fd struct cdecl *cdecl_parse_english(const char *english);
373 parse a string into an abstract syntax tree representing the declaration.
376 function interprets the string as C declaration syntax, while
377 .Fn cdecl_parse_english
378 uses the English declaration syntax.
379 If successful, a pointer to the abstract syntax tree representing the
380 declaration is returned.
381 If the parse fails for any reason, the function returns NULL, and
383 may be used to retrieve the reason for failure.
385 The manner in which memory is allocated by these functions for the returned
386 tree structure is unspecified.
387 In particular, multiple nodes may share memory or may be implemented as
388 read-only static allocations.
389 Thus, the caller should not directly modify any part of the returned structure,
390 as the results may be unexpected.
391 A copy should be made if modifications are required.
393 When the structure returned by either parsing function is no longer needed, the
396 .Fd void cdecl_free(struct cdecl *decl);
398 may be used to release all memory allocations associated with that parse tree.
399 .Sh RENDERING DECLARATIONS
400 An abstract syntax tree (which may be the result of calling one of the parsing
401 functions or constructed explicitly by the program) can be rendered to a string
405 .Fd size_t cdecl_declare(char *buf, size_t n, struct cdecl *decl);
406 .Fd size_t cdecl_explain(char *buf, size_t n, struct cdecl *decl);
408 perform this rendering.
411 function produces output in C declaration syntax, while the
413 function produces output in the English declaration syntax.
415 Only one top-level full declarator is rendered by each call; that is, these
416 functions do not traverse the
418 linked list at the top level.
419 The caller can traverse this list to render multiple declarators.
420 In order to assist with generating C declaration syntax, as a special case,
427 structure may be a null pointer.
428 In this case, only the declarator is rendered.
430 The string is output in a manner similar to that of
434 bytes, including the '\\0' terminator, are written to
438 is zero, it is acceptable for
440 to be a null pointer.
442 The number of characters that would be written to
446 were large enough is returned, not including the '\\0' terminator.
447 Hence the entire string was written if the returned value is less than
451 is non-zero, the resulting string is '\\0' terminated even if it was truncated.
453 Nick Bowler <nbowler@draconx.ca>
455 Copyright \(co 2011\(en2012, 2021, 2023\(en2024 Nick Bowler
457 Permission is granted to copy, distribute and/or modify this manual under the
458 terms of the GNU General Public License as published by the Free Software
459 Foundation, either version 3 of the License, or (at your option) any later
projects / cdecl99.git / blob