MAN page from Old RedHat 5.X cdecl-2.5-7.i386.rpm
CDECL
Section: Linux Programmer's Manual (1)
Updated: 15 January 1996
Index NAME
cdecl, c++decl - Compose C and C++ type declarations
SYNOPSIS
cdecl[-a | -+ | -p | -r][-ciqdDV]
- [[ files ...] |explain ... | declare ... | cast ... | set ... | help | ? ]
c++decl[-a | -+ | -p | -r][-ciqdDV]
- [[ files ...] |explain ... | declare ... | cast ... | set ... | help | ? ]
explain ...
declare ...
cast ...
DESCRIPTION
Cdecl(and
c++decl)is a program for encoding and decoding C (or C++) type declarations.The C language is based on the (draft proposed) X3J11 ANSI Standard;optionally, the C language may be based on the pre-ANSI definitiondefined by Kernighan & Ritchie's
The C Programming Languagebook, or the C language defined by the Ritchie PDP-11 C compiler.The C++ language is based on Bjarne Stroustrup's
The C++ Programming Language,plus the version 2.0 additions to the language.
OPTIONS
- -a
- Use the ANSI C dialect of the C language.
- -p
- Use the pre-ANSI dialect defined by Kernighan & Ritchie's book.
- -r
- Use the dialect defined by the Ritchie PDP-11 C compiler.
- -+
- Use the C++ language, rather than C.
- -i
- Run in interactive mode (the default when reading from a terminal).This also turns on prompting, line editing, and line history.
- -q
- Quiet the prompt.Turns off the prompt in interactive mode.
- -c
- Create compilable C or C++ code as output.Cdeclwill add a semicolon to the end of a declaration and a pair of curlybraces to the end of a function definition.
- -d
- Turn on debugging information (if compiled in).
- -D
- Turn on YACC debugging information (if compiled in).
- -V
- Display version information and exit.
INVOKING
Cdeclmay be invoked under a number of different names (by eitherrenaming the executable, or creating a symlink or hard link to it).If it is invoked as
cdeclthen ANSI C is the default language.If it is invoked as
c++declthen C++ is the default.If it is invoked as either
explain,
cast, or
declarethen it will interpret the rest of the command line options asparameters to that command, execute the command, and exit.It will also do this if the first non-switch argument on thecommand line is one of those three commands.Input may also come from a file.
Cdeclreads the named files for statements in the language described below.A transformation is made from that language to C (C++) or pseudo-English.The results of this transformation are written on standard output.If no files are named, or a filename of ``-'' is encountered, standard inputwill be read.If standard input is coming from a terminal, (or the-ioption is used), a prompt will be written to the terminal before each line.The prompt can be turned off by the-qoption (or theset nopromptcommand).Ifcdeclis invoked as explain,declareorcast,or the first argument is one of the commands discussed below, the argumentlist will be interpreted according to the grammar shown below instead of asfile names.
When it is run interactively,cdecluses the GNU readline library to provide keyword completion and commandline history, very much likebash(1)(q.v.).Pressing TAB will complete the partial keyword before the cursor, unlessthere is more than one possible completion, in which case a second TAB willshow the list of possible completions and redisplay the command line.The left and right arrow keys and backspace can be used for editing in anatural way, and the up and down arrow keys retrieve previous commandlines from the history.Most other familiar keys, such as Ctrl-U to delete all text from the cursorback to the beginning of the line, work as expected.There is an ambiguity between theint and intokeywords, butcdeclwill guess which one you meant, and it always guesses correctly.
You can usecdeclas you create a C program with an editor likevi(1) or emacs(1).You simply type in the pseudo-English version of the declaration and applycdeclas a filter to the line.(Invi(1),type ``!!cdecl<cr>''.)
If the create programoption-cis used, the output will include semi-colons after variable declarations andcurly brace pairs after function declarations.
The-Voption will print out the version numbers of the files used to create theprocess.If the source is compiled with debugging information turned on, the-doption will enable it to be output.If the source is compiled with YACC debugging information turned on, the-Doption will enable it to be output.
COMMAND LANGUAGE
There are six statements in the language.The
declarestatement composes a C type declaration from a verbose description.The
caststatement composes a C type cast as might appear in an expression.The
explainstatement decodes a C type declaration or cast, producing a verbosedescription.The
help(or
?)statement provides a help message.The
quit(or
exit)statement (or the end of file) exits the program.The
setstatement allows the command line options to be set interactively.Each statement is separated by a semi-colon or a newline.
SYNONYMS
Some synonyms are permitted during a declaration:
character is a synonym for char constant is a synonym for const enumeration is a synonym for enum func is a synonym for function integer is a synonym for int ptr is a synonym for pointer ref is a synonym for reference ret is a synonym for returning structure is a synonym for struct vector is a synonym for array
The TAB completion feature only knows about the keywords in the rightcolumn of the structure, not the ones in the left column.TAB completion is a lot less useful when the leading characters ofdifferent keywords are the same (the keywords confict with one another),and putting both columns in would cause quite a few conflicts.
GRAMMAR
The following grammar describes the language.In the grammar, words in "<>" are non-terminals,bare lower-case words are terminals that stand for themselves.Bare upper-case words are other lexical tokens:NOTHING means the empty string;NAME means a C identifier;NUMBER means a string of decimal digits; andNL means the new-line or semi-colon characters.
<program> ::= NOTHING | <program> <stmt> NL <stmt> ::= NOTHING | declare NAME as <adecl> | declare <adecl> | cast NAME into <adecl> | cast <adecl> | explain <optstorage> <ptrmodlist> <type> <cdecl> | explain <storage> <ptrmodlist> <cdecl> | explain ( <ptrmodlist> <type> <cast> ) optional-NAME | set <options> | help | ? | quit | exit <adecl> ::= array of <adecl> | array NUMBER of <adecl> | function returning <adecl> | function ( <adecl-list> ) returning <adecl> | <ptrmodlist> pointer to <adecl> | <ptrmodlist> pointer to member of class NAME <adecl> | <ptrmodlist> reference to <adecl> | <ptrmodlist> <type> <cdecl> ::= <cdecl1> | * <ptrmodlist> <cdecl> | NAME :: * <cdecl> | & <ptrmodlist> <cdecl> <cdecl1> ::= <cdecl1> ( ) | <cdecl1> ( <castlist> ) | <cdecl1> [ ] | <cdecl1> [ NUMBER ] | ( <cdecl> ) | NAME <cast> ::= NOTHING | ( ) | ( <cast> ) ( ) | ( <cast> ) ( <castlist> ) | ( <cast> ) | NAME :: * <cast> | * <cast> | & <cast> | <cast> [ ] | <cast> [ NUMBER ] <type> ::= <typename> | <modlist> | <modlist> <typename> | struct NAME | union NAME | enum NAME | class NAME <castlist> ::= <castlist> , <castlist> | <ptrmodlist> <type> <cast> | <name> <adecllist> ::= <adecllist> , <adecllist> | NOTHING | <name> | <adecl> | <name> as <adecl> <typename> ::= int | char | double | float | void <modlist> ::= <modifier> | <modlist> <modifier> <modifier> ::= short | long | unsigned | signed | <ptrmod> <ptrmodlist> ::= <ptrmod> <ptrmodlist> | NOTHING <ptrmod> ::= const | volatile | noalias <storage> ::= auto | extern | register | auto <optstorage> ::= NOTHING | <storage> <options> ::= NOTHING | <options> | create | nocreate | prompt | noprompt | ritchie | preansi | ansi | cplusplus | debug | nodebug | yydebug | noyydebug
SET OPTIONS
The
setcommand takes several options.You can type
set or
set optionsto see the currently selected options and a summary of the options whichare available.The first four correspond to the
-a,
-p,
-r, and
-+command line options, respectively.
- ansi
- Use the ANSI C dialect of the C language.
- preansi
- Use the pre-ANSI dialect defined by Kernighan & Ritchie's book.
- ritchie
- Use the dialect defined by the Ritchie PDP-11 C compiler.
- cplusplus
- Use the C++ language, rather than C.
- [no]prompt
- Turn on or off the prompt in interactive mode.
- [no]create
- Turn on or off the appending of semicolon or curly braces to thedeclarations output bycdecl.This corresponds to the-ccommand line option.
- [no]debug
- Turn on or off debugging information.
- [no]yydebug
- Turn on or off YACC debugging information.
Note: debugging information and YACC debugging information are onlyavailable if they have been compiled intocdecl.The last two options correspond to the-d and -Dcommand line options, respectively.Debugging information is normally used in program development, andis not generally compiled into distributed executables.
EXAMPLES
To declare an array of pointers to functions that are like
malloc(3),do
- declare fptab as array of pointer to function returning pointer to char
The result of this command is
- char *(*fptab[])()
When you see this declaration in someone else's code, youcan make sense out of it by doing
- explain char *(*fptab[])()
The proper declaration for signal(2), ignoring function prototypes, is easilydescribed incdecl'slanguage:
- declare signal as function returning pointer to function returning void
which produces
- void (*signal())()
The function declaration that results has two sets of empty parentheses.The author of such a function might wonder where to put the parameters:
- declare signal as function (arg1,arg2) returning pointer to function returningvoid
provides the following solution (when run with the-coption):
- void (*signal(arg1,arg2))(){}
If we want to add in the function prototypes, the function prototype for afunction such as _exit(2) would be declared with:
- declare _exit as function (retvalue as int) returning void
giving
- void _exit(int retvalue){}
As a more complex example using function prototypes, signal(2) could be fullydefined as:
- declare signal as function(x as int, y as pointer to function(int)returning void) returning pointer to function(int) returning void
giving (with -c)
- void (*signal(int x, void (*y)(int )))(int ){}
Cdeclcan help figure out the where to put the "const" and "volatile" modifiersin declarations, thus
- declare foo as pointer to const int
gives
- const int *foo
while
- declare foo as const pointer to int
gives
- int * const foo
C++declcan help with declaring references, thus
- declare x as reference to pointer to character
gives
- char *&x
C++declcan help with pointers to member of classes, thusdeclaring a pointer to an integer member of a class X with
- declare foo as pointer to member of class X int
gives
- int X::*foo
and
- declare foo as pointer to member of class X function (arg1, arg2) returningpointer to class Y
gives
- class Y *(X::*foo)(arg1, arg2)
DIAGNOSTICS
The declare, cast and explain statements try to point out constructions thatare not supported in C.In some cases, a guess is made as to what was really intended.In these cases, the C result is a toy declaration whose semantics will workonly in Algol-68.The list of unsupported C constructs is dependent on which version of the Clanguage is being used (see the ANSI, pre-ANSI, and Ritchie options).The set of supported C++ constructs is a superset of the ANSI set, with theexception of the
noaliaskeyword.
REFERENCES
ANSI Standard X3.159-1989 (ANSI C)
ISO/IEC 9899:1990 (the ISO standard)
The comp.lang.c FAQ
http://www.eskimo.com/~scs/C-faq.top.html
Section 8.4 of the C Reference Manual withinThe C Programming Languageby B. Kernighan & D. Ritchie.
Section 8 of the C++ Reference Manual withinThe C++ Programming Languageby B. Stroustrup.
CAVEATS
The pseudo-English syntax is excessively verbose.
There is a wealth of semantic checking that isn't being done.
Cdeclwas written before the ANSI C standard was completed, and no attempt hasbeen made to bring it up-to-date.Nevertheless, it is very close to the standard, with the obvious exceptionofnoalias.
Cdecl'sscope is intentionally small.It doesn't help you figure out initializations.It expects storage classes to be at the beginning of a declaration,followed by the the const, volatile and noalias modifiers, followed by thetype of the variable.Cdecldoesn't know anything about variable length argument lists.(This includes the``,...''syntax.)
Cdeclthinks all the declarations you utter are going to be used as externaldefinitions.Some declaration contexts in C allow more flexibility than this.An example of this is:
- declare argv as array of array of char
wherecdeclresponds with
Warning: Unsupported in C -- 'Inner array of unspecified size' (maybe you mean "array of pointer")char argv[][]
Tentative support for thenoaliaskeyword was put in because it was in the draft ANSI specifications.
AUTHORS
Originally written by Graham Ross, improved and expanded by DavidWolverton, Tony Hansen, and Merlyn LeRoy.
GNU readline support and Linux port by David R. Conrad,<conradAATTdetroit.freenet.org>
SEE ALSO
bash(1),
emacs(1),
malloc(3),
vi(1).
Index
- NAME
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- INVOKING
- COMMAND LANGUAGE
- SYNONYMS
- GRAMMAR
- SET OPTIONS
- EXAMPLES
- DIAGNOSTICS
- REFERENCES
- CAVEATS
- AUTHORS
- SEE ALSO
This document was created byman2html,using the manual pages.
