CDECL(1)            Linux Programmer's Manual            CDECL(1)

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 definition defined
       by  Kernighan & Ritchie's The C Programming Language book,
       or the C language defined by the  Ritchie  PDP-11  C  com-
       piler.   The  C++ language is based on Bjarne Stroustrup's
       The C++ Programming Language, plus the version  2.0  addi-
       tions 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 interac-
              tive mode.

       -c     Create compilable C or C++ code as  output.   Cdecl
              will  add  a  semicolon to the end of a declaration
              and a pair of curly braces 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
       Cdecl may be invoked under a number of different names (by
       either  renaming  the executable, or creating a symlink or
       hard link to it).  If it is invoked as cdecl then  ANSI  C
       is the default language.  If it is invoked as c++decl then
       C++ is the default.  If it is invoked as  either  explain,
       cast,  or  declare  then it will interpret the rest of the
       command line options as parameters to that  command,  exe-
       cute  the  command, and exit.  It will also do this if the
       first non-switch argument on the command line  is  one  of
       those three commands.  Input may also come from a file.

       Cdecl reads the named files for statements in the language
       described below.  A transformation is made from that  lan-
       guage  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 input will be read.  If standard input is  coming
       from a terminal, (or the -i option is used), a prompt will
       be written to the terminal before each line.   The  prompt
       can  be  turned  off by the -q option (or the set noprompt
       command).  If cdecl is  invoked  as  explain,  declare  or
       cast,  or  the  first argument is one of the commands dis-
       cussed  below,  the  argument  list  will  be  interpreted
       according  to  the  grammar shown below instead of as file
       names.

       When it is run interactively, cdecl uses the GNU  readline
       library  to  provide  keyword  completion and command line
       history, very much like bash(1) (q.v.).  Pressing TAB will
       complete  the  partial  keyword  before the cursor, unless
       there is more than one possible completion, in which  case
       a  second  TAB  will show the list of possible completions
       and redisplay the command line.  The left and right  arrow
       keys  and  backspace  can be used for editing in a natural
       way, and the up and down arrow keys retrieve previous com-
       mand  lines  from  the history.  Most other familiar keys,
       such as Ctrl-U to delete all text from the cursor back  to
       the  beginning of the line, work as expected.  There is an
       ambiguity between the int and  into  keywords,  but  cdecl
       will guess which one you meant, and it always guesses cor-
       rectly.

       You can use cdecl as you create a C program with an editor
       like  vi(1)  or  emacs(1).  You simply type in the pseudo-
       English version of the declaration and apply  cdecl  as  a
       filter to the line.  (In vi(1), type ``!!cdecl<cr>''.)

       If  the  create program option -c is used, the output will
       include semi-colons after variable declarations and  curly
       brace pairs after function declarations.

       The  -V  option  will print out the version numbers of the
       files used to create the process.  If the source  is  com-
       piled  with debugging information turned on, the -d option
       will enable it to be output.  If the  source  is  compiled
       with  YACC  debugging information turned on, the -D option
       will enable it to be output.

COMMAND LANGUAGE
       There are six statements in  the  language.   The  declare
       statement  composes  a  C  type declaration from a verbose
       description.  The cast statement composes a C type cast as
       might  appear  in  an  expression.   The explain statement
       decodes a C type declaration or cast, producing a  verbose
       description.   The  help (or ?)  statement provides a help
       message.  The quit (or exit)  statement  (or  the  end  of
       file)  exits  the  program.   The set statement allows the
       command line options to be set interactively.  Each state-
       ment 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 right column of the structure, not the ones in  the
       left column.  TAB completion is a lot less useful when the
       leading characters of different 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; and NL 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 set command takes several options.  You can  type  set
       or set options to see the currently selected options and a
       summary of the options which  are  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  the declarations output by cdecl.  This
              corresponds to the -c command 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  only available if they have been compiled into cdecl.
       The last two options correspond to the -d and  -D  command
       line options, respectively.  Debugging information is nor-
       mally used in program development, and  is  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, you
       can make sense out of it by doing

              explain char *(*fptab[])()

       The proper declaration for  signal(2),  ignoring  function
       prototypes, is easily described in cdecl's language:

              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 returning void

       provides  the  following  solution  (when  run with the -c
       option):

              void (*signal(arg1,arg2))() { }

       If we want to add in the function prototypes, the function
       prototype  for  a  function  such  as  _exit(2)  would  be
       declared with:

              declare _exit as function (retvalue as int) return-
              ing void

       giving

              void _exit(int retvalue) { }

       As  a more complex example using function prototypes, sig-
       nal(2) could be fully defined 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 ) { }

       Cdecl can help figure out the where to put the "const" and
       "volatile" modifiers in 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++decl can help with declaring references, thus

              declare x as reference to pointer to character

       gives

              char *&x

       C++decl  can help with pointers to member of classes, thus
       declaring 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 func-
              tion (arg1, arg2) returning pointer to class Y

       gives

              class Y *(X::*foo)(arg1, arg2)

DIAGNOSTICS
       The declare, cast and explain statements try to point  out
       constructions that are 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 work only in Algol-68.  The  list  of  unsupported  C
       constructs is dependent on which version of the C language
       is  being  used  (see  the  ANSI,  pre-ANSI,  and  Ritchie
       options).  The set of supported C++ constructs is a super-
       set of the ANSI set, with the  exception  of  the  noalias
       keyword.

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 within The C Pro-
       gramming Language by B. Kernighan & D. Ritchie.

       Section 8 of the C++ Reference Manual within The C++  Pro-
       gramming Language by B. Stroustrup.

CAVEATS
       The pseudo-English syntax is excessively verbose.

       There  is  a  wealth of semantic checking that isn't being
       done.

       Cdecl was written before the  ANSI  C  standard  was  com-
       pleted,  and  no  attempt has been made to bring it up-to-
       date.  Nevertheless, it is very  close  to  the  standard,
       with the obvious exception of noalias.

       Cdecl's scope 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  the
       type  of  the variable.  Cdecl doesn't know anything about
       variable  length  argument  lists.   (This  includes   the
       ``,...''  syntax.)

       Cdecl  thinks  all the declarations you utter are going to
       be used as external definitions.   Some  declaration  con-
       texts  in  C allow more flexibility than this.  An example
       of this is:

              declare argv as array of array of char

       where cdecl responds with

              Warning: Unsupported in C -- 'Inner array of unspecified size'
                      (maybe you mean "array of pointer")
              char argv[][]

       Tentative support for  the  noalias  keyword  was  put  in
       because it was in the draft ANSI specifications.

AUTHORS
       Originally  written  by Graham Ross, improved and expanded
       by David Wolverton, Tony Hansen, and Merlyn LeRoy.

       GNU readline support and Linux port by  David  R.  Conrad,
       <conrad@detroit.freenet.org>

SEE ALSO
       bash(1), emacs(1), malloc(3), vi(1).

Version 2.5              15 January 1996                        1