2 .Dt CDECL99 \&1 "Cdecl99 User's Manual"
6 .Nd Make sense of C declarations
11 .Op Fl f Ar file Ns | Ns Fl e Ar command Op Fl e Ar command ...
14 is the command-line interface to libcdecl, enabling you to make heads and tails
15 of complicated C declarations.
16 It supports parsing almost any syntactically valid C99 declaration, producing
17 output similar to that of
22 fully supports all relevant C99 keywords, has no undue restrictions on
23 identifiers, groks features such as complex types, variadic functions and
24 named parameters, and can also understand plain type names.
27 does not support any older versions of C, nor does it support C++ other than
28 the common subset of those other languages and C99.
30 is also much stricter than
32 and will reject many invalid declarations that
36 .Bl -tag -width indent
38 Suppress the welcome message when starting
41 Run in batch (non-interactive) mode.
42 Execute the commands provided on standard input as usual, but do not print any
44 Exit with status 0 if and only if all commands complete successfully.
48 .It Fl i , \-interactive
49 Run in interactive mode. This is the default.
50 .It Fl e , \-execute Ar command
53 as if it were entered at the prompt, then exit.
54 This option can be specified multiple times; all commands are run in the same
55 order as specified on the command line.
59 .It Fl f , \-file Ar file
62 instead of standard input. If both
73 Print a version message and exit.
75 Print a help message and exit.
80 commands consist of a single word followed by one or more spaces, followed by
82 Whitespace preceding the command name is ignored.
83 .Bl -tag -width indent
84 .It explain Ar declaration
85 Translates a given C declaration or type name into something resembling
87 .It simplify Ar declaration
88 Simplifies a given C declaration or type name by eliminating redundant
90 .It declare Ar identifier No as Ar english-decl
91 Translates an English declaration into C code.
92 .It type Ar english-decl
93 Translates an English type name into C code.
95 Displays an overview of all available commands.
99 .Sh ENGLISH DECLARATIONS
101 uses a language similar to English to explain or construct C declarations.
102 The format is based on the one used in
104 and is described by the following context-free grammar.
105 This grammar is for illustrative purposes only: it is ambiguous and doesn't
106 capture all the nuances of the C language.
107 In this grammar, nonterminals are represented
109 \[*e] represents the empty string, and both
111 and successive \[->] under the same nonterminal indicate alternation. All
112 other symbols are terminals. The nonterminals
113 .Va [ identifier ] , [ type-specifier ] ,
114 .Va [ type-qualifier ] , [ storage-class-specifier ]
116 .Va [ function-specifier ]
118 .Bl -column -offset indent ".Va english-decl" ""
119 .It Va english Ta \[->] Ta Li declare Va [ identifier ] Li as Va [ english-decl ]
120 .It Ta \[->] Ta Li type Va [ english-decl ]
121 .It Va english-decl Ta \[->] Ta Va [ sf-specs ] [ declarator ]
122 .It Va declarator Ta \[->] Ta Va [ qualifiers ] Li pointer to Va [ declarator ]
123 .It Ta \[->] Ta Li array Va [ size ] Li of Va [ declarator ]
124 .It Ta \[->] Ta Li function Va [ parameters ] Li returning Va [ declarator ]
125 .It Ta \[->] Ta Va [ tq-specs ]
126 .It Va qualifiers Ta \[->] Ta Va [ type-qualifier ] [ qualifiers ] | No \[*e]
127 .It Va tq-specs Ta \[->] Ta Va [ type-qualifier ] [ tq-specs ]
128 .It Ta \[->] Ta Va [ type-specifier ] [ tq-specs ]
129 .It Ta \[->] Ta \[*e]
130 .It Va sf-specs Ta \[->] Ta Va [ storage-class-specifier ] [ sf-specs ]
131 .It Ta \[->] Ta Va [ function-specifier ] [ sf-specs ]
132 .It Ta \[->] Ta \[*e]
133 .It Va size Ta \[->] Ta Va [ integer ] | Va [ identifier ] | Li * | No \[*e]
134 .It Va parameters Ta \[->] Ta Po Va [ param-list ] Pc
135 .It Ta \[->] Ta Po Va [ param-list ] Li , ... Pc
136 .It Ta \[->] Ta \[*e]
137 .It Va param-list Ta \[->] Ta Va [ parameter ] | Va [ parameter ] Li , Va [ param-list ]
138 .It Va parameter Ta \[->] Ta Va [ identifier ] Li as Va [ english-decl ]
139 .It Ta \[->] Ta Va [ english-decl ]
141 .Sh RESOLVING AMBIGUITIES
142 The C context-free grammar has many ambiguities regarding declarations.
143 Ordinarily, these ambiguities are resolved by the context in which the
144 declaration appears, such as which typedef names are currently in scope.
146 For example, the meaning of the declaration
148 depends on whether or not a typedef named
151 If such a typedef is in scope, this declares
153 as a function that takes (after adjustment) a pointer to a function that takes
156 and returns an int, returning an int.
157 If there is no such typedef, then this declares
159 as a function that takes an int and returns an int.
163 isn't a C compiler, on several occasions it has to arbitrarily pick one of two
165 The rule that is generally applied is that
167 will choose the alternative with the simplest explanation.
168 Thus, f is interpreted as a function which takes an int and returns an int.
170 .Bl -tag -width Output:
176 .Li explain static int* x, y;
178 .Li declare x as static pointer to int
180 .Li declare y as static int
182 .Li explain extern int printf(const char *fmt, ...);
184 .Li declare printf as extern function (fmt as pointer to const char, ...) returning int
186 .Li explain size_t volatile * const (* restrict)[1][2][3]
188 .Li type restrict pointer to array 1 of array 2 of array 3 of const pointer to volatile int
194 .Li type function (pointer to const char) returning size_t
196 .Li size_t (const char *)
198 .Li declare f as inline function (g as pointer to array 6 of pointer to const char) returning pointer to function (int, ...) returning int
200 .Li inline int (*f(const char *(*g)[6]))(int, ...)
202 .Li simplify const int const ((*restrict x))
204 .Li const int * restrict x
207 Nick Bowler <nbowler@draconx.ca>
209 Copyright \(co 2011, 2021, 2023 Nick Bowler
211 Permission is granted to copy, distribute and/or modify this manual under the
212 terms of the GNU General Public License as published by the Free Software
213 Foundation, either version 3 of the License, or (at your option) any later