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++  Pro-
       gramming 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 termi-
	      nal).  This also turns on prompting, line editing, and line his-
	      tory.

       -q     Quiet the prompt.	 Turns off the prompt in interactive 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 com-
       mand line options as parameters to that command, execute	 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  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 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
       discussed 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 redis-
       play 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 command 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 correctly.

       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 dec-
       laration 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 compiled with debugging  informa-
       tion  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 com-
       poses a C type declaration from a verbose description.  The cast state-
       ment  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 mes-
       sage.  The quit (or exit) statement (or the end of file) exits the pro-
       gram.   The  set	 statement  allows  the command line options to be set
       interactively.  Each statement is separated by a semi-colon or  a  new-
       line.

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  comple-
       tion is a lot less useful when the leading characters of different key-
       words 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: NOTH-
       ING 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 char-
       acters.

	    <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 | static
	    <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  com-
	      mand 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.	Debug-
       ging information is normally 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 return-
	      ing void

       which produces

	      void (*signal())()

       The function declaration that results has two sets of  empty  parenthe-
       ses.   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) returning void

       giving

	      void _exit(int retvalue) { }

       As a more complex example using function prototypes, signal(2) could be
       fully defined as:

	      declare  signal  as  function(x  as  int,	 y as pointer to func-
	      tion(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 function (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 sup-
       ported C++ constructs is a superset 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 Programming Language
       by B. Kernighan & D. Ritchie.

       Section 8 of the C++ Reference Manual within The C++  Programming  Lan-
       guage 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 completed, 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 modi-
       fiers, followed by the type of the variable.  Cdecl doesn't  know  any-
       thing  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 contexts in C allow more flexi-
       bility 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,	 <con-
       rad@detroit.freenet.org>

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



Version 2.5			15 January 1996			      CDECL(1)