NAME
----
     dcc - Disciplined C Checker (version 2.9X)

SYNOPSIS
--------
     Syntax : dcc [[options] sourceFile [[options] sourceFile [...]]]

DESCRIPTION
-----------
     dcc  is  a  C checker program, described in the December 1995 issue of ACM
     SIGPLAN Notices (see also 'dccarticle.ps' and  'dccarticle.ascii' included
     files).

Copyright
---------
     Copyright Ecole Superieure d'Electricite ('Supelec'), France, 1995.
     All Rights Reserved.

Agreement
---------
     TITLE.   Title,  ownership rights, and intellectual property rights in and
     to the Software shall remain in Supelec and/or its suppliers. The Software
     is protected by international copyright treaties.

     DISCLAIMER OF WARRANTY. Since  the  Software  is  provided free of charge,
     the  Software is  provided on an  "AS IS" basis, without  warranty  of any
     kind,  including  without  limitation  the warranties  of merchantability,
     fitness for a particular purpose and non-infringement. The  entire risk as
     to the quality and performance of the Software is borne by you. Should the
     Software prove  defective, you and not  Supelec  assume the entire cost of
     any  service and repair. The author and  distributors has no obligation to
     provide maintenance, support, updates, enhancements, or modifications.
     This disclaimer of warranty constitutes an essential part of the agreement.
     SOME  STATES/COUNTRIES  DO NOT  ALLOW  EXCLUSIONS  OF AN IMPLIED WARRANTY,
     SO THIS  DISCLAIMER  MAY NOT  APPLY TO YOU  AND YOU MAY  HAVE  OTHER LEGAL
     RIGHTS THAT VARY FROM STATE/COUNTRY TO STATE/COUNTRY OR BY JURISDICTION.

     LIMITATION OF LIABILITY. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY,
     TORT, CONTRACT, OR OTHERWISE, SHALL SUPELEC OR ITS SUPPLIERS OR  RESELLERS
     BE LIABLE TO YOU OR ANY OTHER PERSON  FOR  ANY  DIRECT, INDIRECT,  SPECIAL,
     INCIDENTAL, OR  CONSEQUENTIAL  DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT
     LIMITATION,  DAMAGES   FOR  LOSS  OF  GOODWILL,  WORK  STOPPAGE,  COMPUTER
     FAILURE OR  MALFUNCTION,  OR  ANY  AND  ALL  OTHER  COMMERCIAL  DAMAGES OR
     LOSSES, ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
     DERIVATIVE  THEREOF,  EVEN IF SUPELEC  OR ITS  SUPPLIERS OR RESELLERS HAVE
     BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     SOME  STATES/COUNTRIES  DO  NOT  ALLOW  THE  EXCLUSION  OR  LIMITATION  OF
     INCIDENTAL OR CONSEQUENTIAL DAMAGES,  SO THIS LIMITATION AND EXCLUSION MAY
     NOT APPLY TO YOU.

Version&Author
--------------
     dcc version 2.9,       March     15th 2002 (stillborn)
     dcc version 2.9a,      March     27th 2002
     dcc version 2.9b,      December  4th  2002
     dcc version 2.9c,      February  21th 2002

         Yves Noyelle (<Yves.Noyelle@supelec.fr>)
         Supelec, Service Informatique,
         Plateau de Moulon, F-91192 Gif/Yvette Cedex

Contents
--------
      1 - Generalities
      2 - In the event of bug
      3 - Distribution files
      4 - Configuration, compilation and installation of dcc
      5 - Execution files
      6 - Test files
      7 - Article
      8 - Available d-pragmas
      9 - Indentation rules
     10 - Options
     11 - Environment variables
     12 - Exit statuses
     13 - Badly implemented features (as of now)
     14 - Unimplemented features (as of now)
     15 - Known bug(s)
     16 - Main changes with respect to previous version
     17 - About '16 bits int' platforms

- 1 - Generalities
------------------
     dcc  verifies  that a C  source  file  complies  with the  precepts of
     Disciplined C, a set of rules aiming at elevating ANSI C to  the  rank
     of high level language (as opposed to portable assembly language), and
     making as much semantics as possible  flow  from  the  design  to  the
     source   code.    This   is   achieved   mainly  via  quasi-compulsory
     types/constants naming and 'const' qualifier use.

     It  also  detects  most  of  the pitfalls of the C language, helps the
     programmer organize his program modules and write them  so  that  they
     are  well structured, well encapsulated and more portable, and finally
     gives some much-needed compile-time checking tools.

     dcc  is quite fast (from 5 to 10 times faster than a compiler), and is
     itself written in Disciplined C.

- 2 - In the event of bug
-------------------------
     No  guarantee  is  given  that  this  version  of dcc is free of bugs,
     although every efforts are made to chase and eliminate them.

     If  you  uncover  one  (or  more...),  please  let  me know (at e-mail
     <dccsupport@supelec.fr>); a bug report should include a description of
     the  problem  and  a  short  source  file  causing  it, along with the
     version/release number of dcc (see  paragraph  10)  and  the  platform
     (machine/system) used.

- 3 - Distribution files
------------------------
    There are five sets of files :

    - program files
        configdc.th
        dccFiles.mng
        dc.th
        dcblk.c/h/ph
        dcdecl.c/h/ph
        dcdir.c/h/ph
        dcexp.c/h/ph
        dcext.c/h/ph
        dcfmt.c/h
        dcinst.c/h/ph
        dcmain.c/h/ph
        dcprag.c/h/ph
        dcrec.c/h/ph
        dcrecdir.c/ph/th
        dctxttok.c/h
        dcmsg.*

    - installation files
        adaptstarterfilevms.com (VMS)  (courtesy of C. Bocage, CRI Supelec)
        askfordfltopt.com    (VMS)
        bccdos.sym           (DOS/WINDOWS)
        cldos.sym            (DOS/WINDOWS)
        createlocalexec      (UNIX)
        descrip.mms          (VMS)
        extracthdrfilesvms.com (VMS)   (courtesy of J. Lauret, SUNY@SB, USA)
        frsttime.mms         (VMS)
        gccunix.sym          (UNIX)
        goDcc.bat            (DOS/WINDOWS)
        install.bat          (DOS/WINDOWS)
        installdccvms.com    (VMS)
        installfile          (UNIX)
        makefile             (UNIX/WINDOWS) (courtesy of C. Bocage, CRI Supelec)
        makefile.sym         (UNIX/WINDOWS)
        rmdirvms.com         (VMS)
        setbcc.bat, setbcc1.bat, setbcc1N.bat (DOS/WINDOWS)
        setcl.bat,  setcl1.bat,  setcl1N.bat  (DOS/WINDOWS)

        plus all files in subdirectory 'Utilities'.

    - execution files
        *.adj                (adjustment files)
        dynarray.h           (header file for dynamic arrays, independent of
                                                                         dcc)
        predefmacvmsvax.txt
        predefmacvmsalpha.txt
        starter.dccCcHP715        (courtesy of F. Mullet, alumnus)
        starter.dccBccWin32
        starter.dccClWin32        (courtesy of E. Bezine, alumnus)
        starter.dccDjgpp          (courtesy of J.F. Tilman, alumnus)
        starter.dccGccAlphaSkel
        starter.dccGccFreeBSDSkel (courtesy of R. Nordier, freelance, ZA)
        starter.dccGccHPUXSkel
        starter.dccGccLinuxSkel   (courtesy of Ch. Duverger, alumnus)
        starter.dccGccMipsSkel
        starter.dccGccSunosSkel   (courtesy of Ch. Duverger, alumnus)
        starter.dccVmsAlpha
        starter.dccVmsVax
        starter.dccXlcAix         (courtesy of W. Briscoe, freelance, UK)

    - test files
        tstdcc               (UNIX)
        tstdcc.bat           (DOS/WINDOWS)
        tstdccvms.com        (VMS)
        trydcc.c/h
        restrydcc.txt
        srchdiffrestry.com   (VMS)

    - files describing dcc
        dccarticle.ps
        dccarticle.ascii

     FILES  FROM  OLD DISTRIBUTIONS SHOULD BE DISCARDED BEFORE INSTALLING A
     NEW VERSION (except possibly local adjustment files).

     Note :  each dcc source file begins with a  /* <fileName> */  comment,
             and ends with a /* End <fileName> */ comment, to  make it easy
             to check that it has not been truncated by error.

- 4 - Configuration, compilation and installation of dcc
--------------------------------------------------------
     The   configuration   phase   means   possible  adaptations  of  files
     'configdc.th',  'dccFiles.mng',  and  'dcmsg.txt'.   Choice  of   file
     'starter.dcc' is discussed paragraph 5.

     File 'configdc.th' serves to configurate dcc (buffer sizes and so on);
     most settings should be valid on any machine (except  perhaps  smaller
     memory  machines, or machines  where NULL is  not all-zeros); comments
     are  supposed to be  meaningful enough  to make clear  the use of each
     defined symbol.
     The  symbol  LONGLONG  should only be  defined on  platforms  having a
     larger integer size than 'long'; its value is then the  naming of that
     type (e.g. "#define LONGLONG long long" or "#define LONGLONG __int64".)
     In the latter case, a "#define __int64 long long" should be put in the
     starter  file. If LONGLONG  is  not  defined,  the  syntax  for  'long
     long'  numerical constants ("LL") is not recognized (except in  system
     header  files).
     The  macro  IsVisibleChar governs what an 'invisible character' is; it
     is to be adapted according to the display device used.
     The  SignedChar/SignedIntField  symbols  may  have to be adapted  from
     their default value.
     EBCDIC character coding could be supported by  changing the 'charInfo'
     array (file 'dcrec.c').
     Input/output  is  done  entirely  via   fopen/fread/feof/fflush/fputs/
     fclose/getchar/setvbuf. The  only other  used  system  functions  are:
     malloc/realloc/free,  setjmp/longjmp, exit/abort, system (to pass con-
     trol to the local compiler), fileno/isatty, and getenv.
     The creation/installation of the image uses chdir/uname (chdir only on
     DOS/WINDOWS platforms).

     File 'dccFiles.mng' is to be adapted to local conditions; it indicates
     the directory where dcc execution  files  (adjustment  files  and  the
     starter file) are to be found, and the system header files  directory.
     If there are several  system  header  files  directories,  use  symbol
     'PredefDCCDFLTS'  (see  paragraph  10; for gcc  platforms, the command
     file 'createLocalFilesMngFile'  computes the value  of  this  symbol).
     The content of environment  variable DCCFILES, if defined,  supersedes
     these values; its format is:
       <dccExecFilesDir> or
       <dccExecFilesDir>|<sysHdrDir>.

     Files   'dcmsg.###'  contain  the  text  of  all  messages  (including
     errors/warnings); since these messages are C string literals, they may
     be  changed  at will.  '###' indicates the language used for messages;
     at present, there exist "eng"lish  and  "fre"nch  versions.  In  these
     files,  the  character  sequence '@x', where x is a digit in the range
     '1'-'9', is not outputted as such, but replaced by a text generated by
     dcc.  The  character  sequence  '@0'  toggles  a flip-flop controlling
     output  of  the  '@0'  parenthesized  message  chunks  (output  if  in
     interactive  mode  after 'e'/'E' command, or if option  '+zve'/'+zvve'
     activated).

  UNIX/LINUX

     On an UNIX/LINUX system, once these files set, compilation  is done by
     typing 'make'. Then test dcc on itself (command  file  'tstdcc'): this
     should  generate no error nor warning.
     The  'make install'  command  installs dcc into the system (first edit
     file  'installfile'  to  define  where you  want it to be; unmodified,
     this file installs dcc in  /usr/local/bin/,  and the 'execution' files
     in  /usr/local/lib/DccExecFiles/  (if  changed,  change  also value of
     symbol DccExecFilesDir in file 'dccFiles.mng').

     'make clean' removes .o files.

  VMS

     On  a VMS system, use the 'installdccvms.com' file.  The following DCL
     logical names have to be defined beforehand:

    dccexecfilesdir
       directory where dcc execution files are installed,

    dccsyshdrdir
       directory  where system  header files ('stdio.h' etc.)  can be found
       (in text form).

     Also,  'dcc'  has  to  be  defined as a "foreign" command ($ dcc :== $
     <complete executable file name>). The test file is 'tstdccvms.com'.

  DOS/WindowsXX with Visual C/C++ environment

     On these platforms, do as follows:
     1) first get the dcc package into a (for example) 'Dcc' directory that
        you can create anywhere in your directory hierarchy (but preferably
        near the root);
     2) then un'zip'/un'tar' the dcc package, which will create a 'Dcc-vXX'
        subdirectory.
     3) Open a 'MS-DOS Commands' window (for example, menu 'Start', submenu
        'Programs',  possibly   sub-submenu   'Accessories',   item  'MSDOS
        commands'; or menu 'Start', item 'Execute', file 'cmd'),  and  goto
        the just  created  'Dcc-vXX'  subdirectory (command 'cd ...').
     4) Possibly edit file 'setcl1.bat' to change the directories  pertain-
        ing to the 'cl' Visual C++ compiler (file 'cl.exe').
     5) Execute  the 'setcl'  command file (just type 'setcl').  Should you
        get the  'insufficient environment space'  message in  response  to
        that  command,  click the upper  left corner of the current window,
        choose  the  Properties  menu  and  then  the  Memory  tab;  in the
        'conventional memory'  panel, set the  'initial environment' to 512
        or more, click on OK, close the 'MS_DOS Commands' window and reopen
        it.
     6) Execute  the 'nmake' command (if it does  not work, go back to step
        4; to see  what goes  wrong, you can also  define  macro  SILENT as
        empty (file 'cldos.sym')).
     7) Then test dcc on itself (commands 'dcc' and 'tstdcc'); the last one
        should generate  no  error nor warning (to be checked by looking at
        file 'tstdcc.res', created by command 'tstdcc').
     8) Finally, install dcc (command 'install');  unmodified, this command
        file  installs   dcc   in   a   'Dcc'   subdirectory   created   in
        'c:\Program Files\'.  The   only  other  modification  is  to  file
        'autoexec.bat', to add paths to dcc and cl.
     9) The initial 'Dcc' directory may now be removed.
     10)For  the  installation  to  become  permanent, stop and reboot your
        system, so that file 'autoexec.bat' gets executed.

     dcc can only be used  from a text  window (e.g. 'MS_DOS Commands'); no
     graphical  interface  yet  (could  be  done economically  by  renaming
     'cl.exe'  to 'clz.exe', 'dcc.exe'  to 'cl.exe', and replacing  'cl' by
     'clz' in definition of macro '__dcc' in file 'starter.dccClWin32' ?).

  DOS/WindowsXX with Borland CBuilder5 C/C++ environment

     On these platforms, do exactly the same as for Visual C/C++, replacing
     only 'cl' by 'bcc', and 'nmake' by 'make'. The compiler name is bcc32.

  Other

     On other platforms, you are on your own...

  Note : possible local compiler warnings while compiling dcc may safely be
         ignored (provided the compiler is mature).

- 5 - Execution files
---------------------
     Several files are needed by dcc to execute correctly:

  Starter file

     Its  purpose  is  to  define  those symbols that are predefined by the
     local compiler.  It also gives the name of the compiler (via a  string
     literal,  that  must  be  the  value  of  the '__dcc' symbol), and can
     override local features (such as specific  specifiers/qualifiers, e.g.
     the "globalvalue" specifier of VMS C compilers). Starter files for VMS
     C compilers (both VAXs and  ALPHAs), the ULTRIX gcc compiler, the OSF1
     gcc  compiler,  the  HP-UX cc/gcc  compilers, the LINUX gcc  compiler,
     the SUNOS gcc compiler, the AIX xlc compiler, the  Djgpp compiler, the
     FreeBSD gcc compiler, the  Windows  CBuilder bcc compiler, the Windows
     VisualC++ cl compiler and the Darwin (MacOS) cc compiler are included.
     For  SUNOS,  the system  header files directory must be the gcc header
     files directory.

     When  the  value  of  the  '__dcc'  symbol  indicates  gcc (or cc on a
     VMS/Alpha   platform:   command   file   adaptstarterfilevms.com),   a
     'skeleton' starter file is automatically completed with  the  compiler
     predefined  macros.  This could be done for other compilers,  provided
     they give a mean to obtain these macros.

     Note 1 : the  called  compiler  can  be  changed  from the  default by 
              redefining  the '__dcc'  symbol in the dcc  command line ('-D'
              or '/DEF' option), but then the  starter  file may have to be
              changed.

     Note 2 : system  include files  are  configurated via several symbols,
              such as _XOPEN_SOURCE  or _POSIX_C_SOURCE; these symbols  are
              not defined  by default in dcc (except if the called compiler
              is gcc or VMS/Alpha cc), which may result in 'undefined func-
              tion'  messages. To set such  symbols, either  define them in
              the 'starter.dcc' file (then they are global  for all users),
              or define them using the '-D' command  line  option (possibly
              via the DCCDFLTS environment variable, see paragraph 10).

     Note 3 : if a compiler is  really gcc, but given another name (such as
              cc for example), 'trick' the recognizing mechanism by putting
              a  comment  line  in the  appropriate  starter file, such as:
              /* __dcc "gcc */ (see for ex. file 'starter.dccDarwinSkel').

  Adjustment files

     Their  purpose  is  to  amend system header files, so that they do not
     cause dcc to issue undue warnings.  Conceptually, an  adjustment  file 
     is  appended  to the  end of the  corresponding header file (after the
     first   inclusion,   or    after    each    inclusion    if     symbol
     ADJFILES_INCLUDED_AT_EACH_INCL is defined in the starter file; cf file
     'time.adj').

     An  adjustment  file may redeclare at will  system  function, objects,
     typedefs (even already used ones) and  macros. But it cannot  declare/
     define anything not declared/defined  by the corresponding header file
     (if  something  is missing  in  it, e.g. the  prototype for the "sbrk"
     function in stdlib.h, see d-pragma /*~AddedObj*/, paragraph 8).

     So an identifier not declared in the corresponding  system header file
     is ignored. On the other hand, there  may be several redefinitions for
     a given function/structure/union;the  one that is chosen is the one of
     the same sort and with the same number of parameters/fields.

     A system  macro (with parameter, that is, not a  symbol), for  example
     "setjmp", after  having been  met once in an  adjustment  file, is not
     expanded any more (being replaced by a function prototype).

     The 'bool' type is implicitely  defined inside an adjustment file, but
     precautions  should be taken if is also  defined by the  corresponding
     system header file (cf. 'curses.adj').

     Any  preprocessor feature can be used in an adjustment file.  Besides,
     the  'cdefined'  function,  similar  to  the  'defined'   preprocessor
     function  but  answering  True if  its parameter  is a defined  system
     'program' identifier (as  opposed to a 'preprocessor' identifier), can
     also be used (see for example 'signal.adj').

     By   convention,   for   a  system  header  file  named  'xxx.h',  the
     corresponding adjustment file is named 'xxx.adj', and is  searched  by
     default  in  the  DccExecFilesDir  directory.   If  one  wants another
     suffix, or wants to put (some) adjustment files in other  directories,
     one  has  to  create  an  'adjFiles.dcc'  file  in the DccExecFilesDir
     directory, file whose format is (for each line):

       "<system header file name>" , "<corresponding adjustment file
                                         full name (with absolute path)>" ;

     Example of 'adjFiles.dcc' file:
       #define X11AdjDir "/usr/local/include/DccAdj/"
       "icon.h", X11AdjDir "icon.adj";
       "Kn/Knvas.h", X11AdjDir "Knvas.adj";
       ...
       #undef X11AdjDir

     Should  any  header  file  reveal  to be unamendable, it can be purely
     replaced by the  corresponding  adjustment  file.   It  must  then  be
     described in the 'adjFiles. dcc' file, and the corresponding line must
     be prefixed by an exclamation point ('!').

     Adjustment  files  for most C system header files (curses.h:  courtesy
     of W. Briscoe, freelance, UK) are included; adjustment files  for  the
     X-Window library are available, but only partially checked.

- 6 - Test files
----------------
     The  command  files  'tstdcc*' just check dcc on its own source files;
     this check should not generate any error nor warning.

     You can get a feeling of what dcc can do for you by typing the command
     "dcc trydcc.c".  You can also limit dcc scrutiny by using  appropriate
     options  (see paragraph 10) or by  conditional  compilation  using the
     '__dcc' symbol.

     There  are  many  more  non-regression  check  files, but they are not
     included.

- 7 - Article
-------------
     Unfortunatly,  the wrong version of the paper was published in SIGPLAN
     Notices; so the right version  (in  fact  updated  and  somewhat  more
     detailed)  is  included,  in  Postscript form, along with a pure ASCII
     form (for 'diff' purposes).

- 8 - Available d-pragmas
-------------------------
     For  the following, a "file identifier" is defined to be composed of a
     "file access path" (machine name, directories...), followed first by a
     "file  name"  and  then by a "file suffix" that begins on the last dot
     '.' seen in the file identifier.

     A "header" file is a source file whose file suffix contains the letter
     'h' at least once, and which is included via the '#include' directive;
     a  "system  header"  file  is a header file whose '#include' directive
     uses the '<...>' form. A "body" file is a source file which is neither
     a header file, nor a file included by a header file.

     Except  /*~DccCompliant*/, /*~DollarSign*/, /*~NoWarn*/, /*~PopWarn*/,
     /*~Private*/,   /*~PrivateTo*/,   /*~Public*/,   /*~TypeCombination*/,
     /*~Warn*/, d-pragmas have purely local effect, that is they have to be
     used each time the corresponding situation occurs.

  /*~AddedObj*/

   allows a new function/object/type to be added in an adjustment file:
       void sbrk/*~AddedObj*/(long);

  /*~BackBranch*/

   avoids warning on backward branches:
       goto alrdDefLabel /*~BackBranch*/;

  /*~CastTo <type> */

   allows  pseudo-cast  between  parallel types; also to  be used  to avoid
   warning on comparison of difference(s) of unsigned int:
       typedef struct {int x;}Ts; typedef Ts Ts1;
       Ts s; Ts1 s1; unsigned int ui1, ui2;
       ...
       s1 = /*~CastTo Ts1*/ s;
       if (/*~CastTo unsigned int */ (ui2 - ui1) > 1) ...

  /*~ComposingHdr*/

   tells  that the whole service provided by the included header file is to
   be part of the service offered by the including header file:
       #include <math.h> /*~ComposingHdr*/
   Permits also a header file to carry a name  different from its body file
   (through a dummy header file carrying the right name).

  /*~DccCompliant*/

   in a system  header file, indicates  that the (remaining portion of the)
   file  conforms to dcc  requirements, and  that  'typedefs'  will  create
   parallel types if applicable; usable anywhere (in a system header file).

  /*~DollarSign*/

   must be at  beginning of module (possibly after comments); autorizes '$'
   in identifiers.

  /*~DynInit*/

   avoids  warning on  dynamic  initialization  (by constants) of  compound
   objects:
       [auto] struct _s toto = {...} /*~DynInit*/;

  /*~EndLongjmpCallable*/

   tells the 'volatile'  qualifier  checking  algorithm that the  "longjmp"
   function won't  be called  beyond  this point.   Usable  anywhere in the
   body of a function, after a "setjmp"-controlled 'if' statement.
.

  /*~ExactCmp*/

   avoids warning on floating point comparison for (in)equality:
       if (fltVar == 0 /*~ExactCmp*/) ...

  /*~FullEnum*/

   asks dcc to warn if not every  constant  of the (enum)  switch  type has
   been  used as case values; only useful if  a  'default'  clause  is used
   (for example to catch possible "strange" values of the enum expression):
       default: /*~FullEnum*/ ...

  /*~Generic*/

   tells dcc that the  returned  type of a function is  compatible with any
   non-closed descendant  of this  type (subtyping) or, in case of 'void *'
   returning function, with  any  pointer. Not  valid if any  parameter  is
   marked /*~ResultType*/ or /*~ResultPtr*/;incompatible with /*~Utility*/:
       int atoi(const char *) /*~Generic*/;
       double sin(double) /*~Generic*/;
       void *allocateChunk() /*~Generic*/;
   The variant /*~Generic <fctList> */ is allowed  only in adjustment files
   (see /*~RootTyp*/).
   /*~Generic*/  can also be used  with  function  formal parameters  (just
   after  their type), to specify  that the so-qualified  parameter is also
   compatible with closed descendants, or, in case of pointed-at  functions
   (callbacks), with any non-closed descendant:
       size_t strlen(const char * /*~Generic*/);
       void (*savPSCF)(char /*~Generic*/);
   Remark 1: There is an ambiguity in case:
       ... (..., void * (*param)(int) /*~Generic*/, ...)
     because  this is  interpreted  as 'param' being a (normal)  pointer on
     a  generic void*  returning  function. To get the  interpretation that
     param is a generic parameter, write:
       ... (..., void * (*param)(int) /*~SeparDP*//*~Generic*/, ...)
   Remark 2: If a formal parameter p of an (unamended) system function is a
     pointer on a function ('callback'),  then the formal parameters of the
     function pointed by p are automatically  marked /*~Generic*/ (provided
     no d-pragma is used in that function).
   
  /*~Ignore*/

   tells  dcc  to  ignore  object-like  or  function-like calls to  defined
   pseudo-macro. Allowed only in starter files:
       #define /*~Ignore*/ __asm

  /*~IndexType <type> */

   specifies  type of index  values usable for an  array, allocated  either
   statically or dynamically  (default  index type for static  arrays: type
   of bound, except if bound given by a plain arithmetic constant; then any
   integral arithmetic type), or that can be added to a pointer. To be used
   in array/pointer declaration:
       Color arr[ArrSiz /*~IndexType ColorIndex */];
       bool * /*~IndexType Trow*/ * /*~IndexType Tcol*/ twoDimSwitchArray;
   or pointer creation:
       & /*~IndexType Tcol*/ col

  /*~Init <varList>*/

   tells  the  initialization-checking  algorithm  that,  from  now on, all 
   variables  in the list  can be considered as  initialized. Very specific
   (see X-Window  applications, or adjustment  files). Usable  anywhere (in
   the  scope  of the variables):
       XtSetArg(arg[0], XmNchildren, /*~Init children*/ &children);

  /*~LiteralCst*/

   tells  that expressions  of a so qualified  parallel type accept unnamed
   constants without  warnings (see also options '-zuc', '-zgpr', paragraph
   10):
       typedef int Int /*~LiteralCst*/;

  /*~LocalAdr*/

   avoids  warning when returning  address of local object from a function,
   or assigning such address to global/external pointer or formal parameter
   marqued as /*~Saved*/:
       gblPtr = &localObject + 1 /*~ LocalAdr */;

  /*~Masking*/

   avoids  warning  if a macro  name  is the same as  an  already  existing
   identifier:
       #define /*~Masking*/ macroName macroBody

  /*~MayModify*/

   indicates  that  modifications  may  occur through a  supposedly  const-
   pointing  pointer  parameter (via  casting), or  through a  struct/union
   parameter  containing  non-const pointers. To be used in functions whose
   name  implies  modifications (such as freeing  functions), or in case of
   (possible) slight modifications:
       void freeTree(const struct _tree *x /*~MayModify*/);
       void clipTree(struct _tree x /*~MayModify*/);
   See also /*~ResultPtr*/ d-pragma.

  /*~NeverReturns*/

   documents that a void function never returns control:
       static void errExit(...) /*~NeverReturns*/;
   The variant  /*~NeverReturns <fctList> */  is allowed only in adjustment
   files (see /*~RootTyp*/).

  /*~NoBreak*/

   avoids warning if falling through the end of a 'case' statement:
       case C1 : i = 1;  /*~NoBreak*/
       case C2 : i++;  break;

  /*~NoDefault*/

   avoids  warning  if no 'default'  case at  end of 'switch'  statement on
   enumeration  (not  needed of course if all  constants have  been used as
   case values):
       case Cn : i = ... ;
       /*~NoDefault*/

  /*~NonConstExp*/

   makes dcc believe that a (parenthesized) expression is not constant:
       if ((~0==-1)/*~NonConstExp*/) ...
   Notice  that the  Pascalian  form "while (TRUE)"  can be  advantageously
   replaced by the C idiom "for (;;)",

  /*~NotUsed*/

   prevents  warning on  not-used  object or enum constant  or formal para-
   meter (function or macro):
       enum {Ce1, Ce2 /*~NotUsed*/, Ce3 ...}
       static void shift(Tstring x, TtypeElt y /*~NotUsed*/);
       #define Sink(x /*~ NotUsed */)
       static const char *versionName = "Version 3.3.1" /*~NotUsed*/;

  /*~NoWarn*/

   to be  used in front of  sections of code not (yet)  dcc-compliant  (see
   also /*~Warn*/, /*~PopWarn*/ d-pragmas);  usable anywhere.  Warnings are
   automatically disabled inside system header files.

  /*~OddCast*/

   to make dcc swallow a cast it frowns upon:
       ptrInt = (int * /*~OddCast*/) ptrStruct;

  /*~OddCast*/

   idem /*~OddCast*/, plus prevents possible modification via const pointer
   from being recorded

  /*~PopWarn*/

   goes  back to  previous  Warn/NoWarn  state (see /*~Warn*/, /*~No Warn*/
   d-pragmas); usable anywhere. At least 16 levels kept.

  /*~PortableQM*/

   to make dcc swallow a cast it has  good reasons to believe not portable:
       ptrFloat = (float * /*~PortableQM*/)ptrDbl;

  /*~Private*/

   if   used  in  header  file  X.xhy (x = y = any string, often empty), is
   strictly equivalent to /*~PrivateTo "X.xhy", "X.c" */; else illegal.

  /*~PrivateTo "<fileName>" [, "<fileName>"]* */

   indicates  that struct/union members, or enum constants, declared there-
   after are  only visible  from  the  indicated  file(s),  or from  macros
   defined in the  indicated file(s) or called by such macros. Also  needed
   to  indicate  in which file is  defined an incomplete  struct/union  (if
   /*~PrivateTo */  indicates several files, this file is taken as the last
   one).
   Usable anywhere (in a header file).
   Scope: until  next /*~Private*/, /*~PrivateTo*/ or /*~Public*/ d-pragma;
   an '#include' of (another) header file  creates a hole in the  scope for
   the  duration of the inclusion. File names  may contain joker characters
   ('*' matches any set of characters; '%' matches any character):
       /*~PrivateTo "dcrec.c", "dc%%%.*h*" */

  /*~PseudoOut*/

   tells that the actual parameter corresponding to a so-qualified and non-
   'const' array/pointer formal parameter does not have to be used:
       void pixelAttributes(Pixel, Color* /*~PseudoOut*/, Intensity*
                                                            /*~PseudoOut*/)

  /*~PseudoVoid*/

   authorizes a so-declared (non  void-returning) function  to be used as a
   statement:
       char *strcpy(char *x, const char *y) /*~PseudoVoid*/;
   The variant  /*~PseudoVoid <fctList> */  is  allowed  only in adjustment
   files (see /*~RootTyp*/).

  /*~Public*/

   indicates end of last /*~Private#*/ scope; usable  anywhere (in a header
   file).

  /*~ReExporting <identList>*/

   indicates, for each  identifier of  the list, that it can be  redeclared
   (perhaps in a more constrained way), for 'exportation' purpose.  Only to
   be used inside a body file:
       #include "generalHeader.h"  /* contains declarations of a, b, c */
       /*~ReExporting a, c*/
       #include "currentModuleHeader.h" /* contains  (possibly  more  cons-
                                      trained) declarations of 'a' and 'c',
                                      that the current module wants to make
                                      visible (but it does not  want 'b' to
                                      be visible). */

  /*~ResultPtr*/

   to be  used for  (pointer)  parameter that is  returned as  result; same
   effect  as  /*~ResultType*/,  plus  allows (at calling level) "should be
   'const'" pointer checking propagation:
       char *strchr(const char * /*~ResultPtr*/, char);

  /*~ResultType*/

   indicates  that the result type of a function  call is the type (or  the
   first common type) of the  current actual parameter(s)  corresponding to
   the so qualified formal parameter(s):
       void *realloc(void *old /*~ResultType*/, size_t size);
       Window mergeWindow(Window/*~ResultType*/, Window/*~ResultType*/);
       long sum(long m /*~ResultType*/, long n /*~ResultType*/);
       short s; signed char b; unsigned char ub;

       s = sum(b, s);  /* OK; returned type behaves as 'short' from dcc
                                                             standpoint. */
       s = sum(ub, s); /* idem */
       b = sum(SCHAR_MAX + 1, b); /* WRONG, because returned type is
                                     'short', and b is of narrower type. */

  /*~RootType*/

   closes (renders incompatible with its hierarchy) the type subtree headed
   by the so qualified (parallel) type:
       typedef unsigned int Talgn /*~RootType*/;
   The  variant  /*~RootType  <typeList>*/  is  allowed  only in adjustment
   files:
       /*~RootType wchar_t, wint_t*/

  /*~SameValue*/

   avoids  warning if an enum  constant have the same value that a previous
   constant of the same enum:
       enum _colors {BEG_COLORS, INFRARED=BEG_COLORS /* ~SameValue not
          necessary here, because 'BEG_COLORS' is last defined constant */,
           RED, ORANGE, YELLOW, ..., BEG_VISIBLE_COLORS=RED /*~SameValue*/}

  /*~Saved*/

   to be  used  if a  formal  parameter  which is a  pointer is saved  into
   permanent storage (static/extern):
       void qio(Semaphore * /*~Saved*/);

  /*~SeparDP*/
   used to desambiguate /*~Generic*/, /*~Utility*/ (see these d-pragmas).

  /*~SideEffectOK*/

   tells that a side effect via a macro parameter is OK:
       #define DangerousMin(x, y/*~SideEffectOK*/) (x<y)? x : y

       DangerousMin(oldMin, tab[i++])

  /*~SizeOfMemBlk*/

   allows  to  check,  for   'malloc'-like  functions   using  'sizeof'  as
   parameter,  whether the type of the (first) sizeof  argument is the type
   pointed by the receiving pointer:
       void *malloc(size_t /*~SizeOfMemBlk*/);

  /*~SizeOK*/

   avoids  warning  when  no  width  limit  is  specified  in a  conversion
   specification  of  'sscanf', or  when a large  struct/union is passed as
   parameter:
       (void)sscanf(charPtr1, "%s", charPtr2/*~SizeOK*/);

  /*~TypeCombination <combList>*/

   indicates allowed combinations  between (a priori incompatible) parallel
   types. Syntax:
       <combList>::= <combElt> [ , <combElt> ]*
       <combElt> ::= <typeIdent> <operator> <typeIdent> -> <typeIdent>
   The possible operators are:  +, -, *, /, %, ~+ (non-commutative add) and
   ~* (non-commutative multiply).  For the / operator, if one operand is  a
   descendant  of  the other, the result type can be a native type (for use
   as a generic coefficient). Besides, some combinations  are automatically
   deduced:
   - for '+', from Ta + Tb -> Tc are deduced:
                   Tb + Ta -> Tc   (1)
                   Ta - Tb -> Tc   (2) (deduced only if Tc = Ta)
   - for '*', from Ta * Tb -> Tc are deduced:
                   Tb * Ta -> Tc   (3)
                   Tc / Ta -> Tb   (4)
                   Tc % Ta -> Tc   (5)
                   Tc / Tb -> Ta   (6)
                   Tc % Tb -> Tc   (7)
     Lines 5 and 7 are deduced only if Ta and Tb are of integer type.
   If necessary, type  hierarchy  is  searched  to find  an  applying  type
   combination.  D-pragma usable  only  outside  of any  block. Once given,
   cannot be desactivated:
       typedef float Volt, Amp, Watt, Ohm;
       typedef int Tgen;   /* 'generic' type */
       typedef Tgen Tspe;  /* specialization of Tgen */
       /*~TypeCombination Volt  * Amp  -> Watt,
                          Amp   * Ohm  -> Volt,
                          Watt  / Watt -> float,
                          Tspe ~+ Tgen -> Tspe */
       typedef int Fruit;
       typedef Fruit Apple, Pear;
       /*~TypeCombination Apple + Pear -> Fruit */
       {
         Volt v; Amp i; Watt p, p1; Ohm r; Tspe spe; Tgen gen;
         typedef Apple MacIntosh;
         MacIntosh macIntosh; Fruit fruit; Pear pear;

         p = r * i * i;    /* OK */
         p = v * (v / r);  /* OK */
         r *= p/p1;        /* OK */
         spe -= gen;       /* OK; illegal if no ~TypeCombination, because
                                contrary to dcc default hierarchy rules. */
         fruit = pear + macIntosh;  /* idem */
        }

  /*~Undef <identList>*/
=head2 /*~UndefTag <identList>*/

   terminates  (for dcc) the scope of all indicated  identifiers ('general'
   or 'tag' name space); usable anywhere (outside of any block):
       /*~Undef TpermSto, headPermSto*/

  /*~Utility*/

   to be used for  functions  returning a  representation  type that has no
   reason to be named. Incompatible with /*~Generic*/:
       int scanf(const char *, ...) /*~Utility*/;
   Can also be used for a function formal parameter, to specify that actual
   parameter cannot be of parallel type.

  /*~VoidToOther*/

   autorizes  automatic  conversion from (non-generic) 'void *' type to any
   other pointer type, or to read, via scanf, into a 'void *' variable:
       objPtr = /*~VoidToOther*/ ptrOnVoid;
       scanf("%i", /*~VoidToOther*/ ptrOnVoid);

  /*~Warn*/

   to be used in front of dcc-compliant code (default state at beginning of
   program,  except  if  '-znw'  option  used); usable  anywhere.  See also
   /*~PopWarn*/, /*~NoWarn*/ d-pragmas.

  /*~zif <boolExp> <stringCst> */

   causes  emission on  stderr (at  dcc  execution  time) of <stringCst> if
   compile-time evaluable <boolExp> is true; can make use of  special 'zif'
   functions  (see "Compile-time checking tool"  paragraph  in the paper on
   dcc), and be used anywhere (also inside macros):
       /*~ zif (sizeof(typArray)/sizeof(typArray[0]) !=
                    __extent(TtypName)+1) "Array 'typArray': bad length" */

       typedef struct{int a, b, c;} AnyStruct;
       static AnyStruct x = {
         0  /*~zif !__member(a) "misplaced init for field 'a'" */,
         3  /*~zif !__member(b) "misplaced init for field 'b'" */,
         -2 /*~zif !__member(c) "misplaced init for field 'c'" */,
         /*~zif !__member() "Structure 'x' not fully initialized" */};

  Notes

   - for dcc, a  d-pragma  is   made  up  of  tokens,  the inner ones being
     perfectly  macro-substitutable; for  instance,  the  /*~LocalAdr*/  d-
     pragma consists of the three following tokens:
        /*~         (special token)
        LocalAdr    (identifier)
        */          (special token)
   - an empty d-pragma name is legal; the d-pragma is then  ignored (except
     in the reach of a '#' preprocessing  operator, in which case it trans-
     lates into a space),
   - d-pragmas are visible in the list generated by the '+zlt' option,
   - numerous examples of d-pragmas use can be found in dcc source files.

- 9 - Indentation rules
-----------------------
     Indentation  is  checked  only on lines  beginning a  declaration or a
     statement.

    General case :
      Indentation level is increased on  entering  a  block (just after its
      opening brace), for the duration of the block, or on entering  a sub-
      statement (statement  controlled  by  'if',  'else',  'do',  'while',
      'for'), for the duration of the substatement.

    Special cases :
      - no change of indentation level for construct "else if", both tokens
        being on same line;
      - block as substatement may be lined up with controlling statement;
      - 'case/default's may be lined up with corresponding 'switch'.

- 10 - Options
--------------
     Their  list can be  obtained  by  executing  a  dcc  command alone (no
     argument); the version/release number is also given. If the prefix '+'
     is replaced by '-', or vice versa, the option effect is reversed.

     A given option is valid for all files met subsequently in the  command
     line, unless reverted or cancelled (cf. option '+zrst'); options given
     after last file name apply only to last file (VMS).

     Available options :
      -zac  no missing 'const' qualifier check,
      -zbo  no 'bool' type check,
      -zcc  do not call compiler,
      -zcw  call compiler only if no warning/error,
      -zefi no check of inefficient constructs,
      -zfciZ do not check first  character of  identifiers (see description
             of Z at end of option list),
      -zfrt no check for unnamed return type (function),
      -zgpr no check of "good programming practices",
      -zinc no '#include' position check,
      -zind no indentation check,
      -zlvlX call compiler only if there is no warning of level >= X,
      -znui no check of unused identifiers,
      -znup no check of unused function parameters,
      -znw  start in "no warning" mode,
      -zpe  no check of various possible errors,
      -zpo  no portability check,
      -zrd  no readability check,
      -zsam no stopping after each message,
      -ztr  no trailer,
      -zuc  no check of unnamed constants,
      -zwa  no warnings,
      -zwr  no forced newline at 80 characters,
      -z.   take all following options as compiler options (up to next
            source file),
      +zae  report all  errors/warnings (default is, after a few  messages,
            to report only first error of each statement or declaration),
      +zafn always display  current file  name  in  error/warning messages,
      +zccZ Z is compiler name (default name given by symbol '__dcc'),
      +zcin ask for coherent indentation across functions,
      +zdol allows '$' in identifiers,
      +zepl warn on empty formal parameter list,
      +zkwm keywords redefinable (via macro),
      +zltX last  tokens  processed  before error/warning (X = buffer size,
            default: 80 characters),
      +zmcc check all pointers for missing 'const' qualifier,
      +zmic more index type checking,
      +zmpo more portability checking,
      +zmsgX  X: maximum number of emitted messages (default is 20),
      +zpnt check that function parameters are of named type,
      +zrhw report only errors or else highest level warnings,
      +zrst reset all previous options,
      +zsy  print each block's symbol table,
      +ztabX  X: tab  spacing (for indentation purposes; 8 is default),
      +ztypX output  type  descriptions  in  full; X: buffer size (default:
            160 characters),
      +zudt warn on tags declared (but not defined) in header files,
      +zusg give 'usage',
      +zve  output more informative error/warning messages,
      +zvveX short for '+zve' + 'ztypX',
      +zwrX X = size of screen line (default: 80 characters).

     The 'zfciZ' option, if  Z  contains uppercase letters, and for the VMS
     system, should be between  double quotes '"'. Z can be  empty, or have
     the following syntax:
       { L { M }? }+
     where:
       L is a letter, chosen  in the  following set, describing the element
       named by the identifier:
           v,V  (local) variable,
           g,G  (global) variable,
           e,E  (external) variable,
           f,F  (internal) function,
           x,X  (external) function,
           p,P  function parameter,
           t,T  type (defined via typedef, except for 'bool'),
           r,R  member of struct/union,
           s,S  symbol (macro without parameter),
           m,M  macro (with parameter list, possibly empty),
           q,Q  macro parameter,
           n,N  enum constant,
           a,A  (struct/union/enum) tag.
         A lower (upper) case letter indicates that the corresponding iden-
         tifier can start by a lower (upper) case letter.
       M is a modifier:
           '_' means allow also underscore to begin identifier,
           '/' means allow only underscore to begin identifier.
     If some descriptions are missing, the previous  description stays into
     effect.
     The  naming   conventions  for  local  variables  and  symbols  naming
     constants or fields should be disjoint (not lead to ambiguity).
     As an example, the  default dcc  naming  conventions  (as  set in  the
     'configdc.th' file) correspond to the following option:
          +zfciEe_gvfx_XTMm_r_pSs_a/Nq_Q
     which means:
       external variables can begin with anything,
       global variables should begin with lowercase,
       local variables should begin with lowercase,
       internal functions should begin with lowercase,
       external functions can begin with anything,
       types should begin with uppercase,
       macros can begin with anything,
       struct/union members should begin with lowercase or '_',
       function parameters should begin with lowercase,
       symbols can begin with anything,
       tags should begin with '_',
       enum constants should begin with uppercase,
       macro parameters can begin with anything.
     '+zfci'  alone comes back to the default naming conventions,
     '-zfciZ' specifies  that no check is to be  performed on the naming of
              the indicated element(s):
         -zfcias => no check on tags or symbols identifier.

     Options not beginning with `+z'/`-z'  are transmitted to compiler, but
     dcc interprets `-I'/`-D'/`-U' cc options (or their VMS  counterparts),
     besides  passing  them to the  compiler. For VMS,  /DEF, /INCL, /UNDEF
     options must  be spelled that way, and separated by spaces.

     The environment variable DCCDFLTS can  contain any part of the command
     line;  its  content  is  logically  added  (just  after  'dcc') to the
     beginning  of  all following  dcc  command  lines.  The  value  of the
     'PrefixDCCDFLTS'  symbol (file 'dccFiles. mng') is also  added (before
     DCCDFLTS), but its possible  `-I'  options are not  transmitted to the
     compiler.
     Examples of setting of DCCDFLTS:
     - UNIX         setenv DCCDFLTS '-zsam +zvve +zlt'
     - VMS          $ DCCDFLTS = "-zsam +zvve +zlt"
     - DOS          set DCCDFLTS=-zsam +zvve +zlt

- 11 - Environment variables
----------------------------
     There are two of them: DCCFILES (see  paragraph  4), and DCCDFLTS (see
     paragraph 10).

- 12 - Exit statuses
--------------------
     dcc provides six different exit statuses, whose values depend on local
     platform (see file 'configdc.th'):  EXIT_SUCCESS,  two  EXIT_WARNINGS,
     two  EXIT_ERRORS,  and  EXIT_FAILURE  (returned  when  dcc has to stop
     before end).

- 13 - Badly implemented features
---------------------------------
     - floating  constants are  recognized  lexically, but ill converted if
       they have a  fractional  part or a non-nul exponent (only noticeable
       in  fancy  array  declaration,  e.g.  "char arr[(int)(2.5+6.5)]"  =>
       arr[4], not [9]),
     - not all cases of non-portability checked.

     Note: 'sizeof' does not take into account alignment holes, but this is
     done  on purpose, to render  portable some checks via the  /*~zif*/ d-
     pragma.

- 14 - Unimplemented features
-----------------------------
     - check for non-ambiguity of external identifiers,
     - size of objects not given ('+zsy' option),
     - computation of floating-point constant expressions.

- 15 - Known bugs
-----------------
     None

- 16 - Main changes with respect to version 2.8
-----------------------------------------------
     - tabulations are kept in source text displayed in messages,
     - option 'zctn' removed,
     - new options 'z.', 'zmpo', 'ztyp',
     - new syntax for options 'zcc', 'zfci', 'zvve', 'zwr',
     - new 'zif' function: __isarray,
     - new d-pragmas: /*~ReExporting*/, /*~SeparDP*/,
     - parameters of system 'callback' function are marked /*~Generic*/
       automatically,
     - better management of d-pragmas inside function declaration,
     - conditional compilation now allowed inside d-pragmas,
     - portage on WindowsNT done,
     - bugs corrected...

- 17 - About 16 bits int platforms
----------------------------------
     Portage completed (but not tested).

