NAME ---- dcc - Disciplined C Checker (version 2.7X) SYNOPSIS -------- Syntax : dcc [options] [sourceFile [sourceFile [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. 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 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. 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.7, February 19th 2001 Yves Noyelle () 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 ); 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 adaptStarterFile (UNIX) (courtesy of C. Bocage, CRI Supelec) adaptstarterfilevms.com (VMS) (courtesy of C. Bocage, CRI Supelec) askfordfltopt.com (VMS) chooseMsgLanguage (UNIX) chooseStarterFile (UNIX) createLocalFilesMngFile (UNIX) (courtesy of C. Bocage, CRI Supelec) createlocalexec (UNIX) descrip.mms (VMS) extracthdrfilesvms.com (VMS) (courtesy of J. Lauret, SUNY@SB, USA) frsttime.mms (VMS) installdccvms.com (VMS) installfile (UNIX) makefile (UNIX) (courtesy of C. Bocage, CRI Supelec) makefile.win32 (WINDOWS) (courtesy of C. Enache, UPB student, Romania) rmdirvms.com (VMS) - 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.dccClWin32 (courtesy of E. Bezine, alumnus) starter.dccDjgpp (courtesy of J.F. Tilman, alumnus) starter.dccGccAlphaSkel 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 tstdccvms.com trydcc.c/h restrydcc.txt srchdiffrestry.com - 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 /* */ comment, and ends with a /* End */ 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 to locally used character set extension. 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. 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: or . 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 options '+zve', '+zvve' activated). UNIX OS On an UNIX system, once these files set, compilation is done by typing 'make'. 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 DccExecFilesDir symbol in file 'dccFiles.mng'). Then test dcc on itself (command file 'tstdcc'): this should generate no error nor warning. VMS OS 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 :== $ ). The test file is 'tstdccvms.com'. WindowsXX OS On WindowsXX, with Microsoft VisualC++ 4.0, use 'makefile.win32' file; do not forget to set the INCLUDE, LIB, and PATH environment variables, e.g. : set INCLUDE=C:\Program Files\DevStudio\VC\include set LIB=C:\Program Files\DevStudio\VC\lib set PATH=C:\Program Files\DevStudio\VC\bin;C:\Program Files\ DevStudio\SharedIDE\bin Other On other systems, 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 and the Windows VisualC++ cl 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), a 'skeleton' starter file is automatically completed with the compiler predefined macros (command files adaptStarterFile*). 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 a symbol, either define it in the 'starter.dcc' file (then it is global for all users), or define it using the '-D' command line option (possibly via the DCCDFLTS environment variable, see paragraph 10). 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 cannot declare/define anything not declared/ defined by the corresponding header file (except if something is missing in it, e.g. the prototype for the "sbrk" function in stdlib.h; see then d-pragma /*~AddedObj*/, paragraph 8). They may redeclare at will system function, objects, typedefs (even already used ones) and macros. An identifier not declared in the corresponding system header file is ignored. 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): "" , "" ; 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 */ 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 /*~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 */ is allowed only in adjustment files (see /*~RootTyp*/). /*~Generic*/ can also be used with function parameters, to specify that the so-qualified formal parameter is compatible with any descendant (closed or not): size_t strlen(const char * /*~Generic*/); void (*savPSCF)(char /*~Generic*/); /*~Ignore*/ tells dcc to ignore object-like or function-like calls to defined pseudo-macro. Allowed only in starter files: #define /*~Ignore*/ __asm /*~IndexType */ 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 */ 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: 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 */ 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; /*~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.*h*, is strictly equivalent to /*~PrivateTo "", "X.c" */. /*~PrivateTo "" [, ""]* */ 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 /*~Private* */ 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 include. File names may contain joker characters ('*' matches any set of characters; '%' matches any character): /*~PrivateTo "dcrec.c", "dc%%%.*h*" */ /*~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 */ is allowed only in adjustment files (see /*~RootTyp*/). /*~Public*/ indicates end of last /*~Private#*/ scope; usable anywhere (in a header file). /*~ResultPtr*/ to be used for (pointer) parameters that are 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 smallest 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 return type is 'short'. */ /*~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 */ 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*/); /*~SideEffectOK*/ tells that a side effect via a macro parameter is OK: #define DangerousMin(x, y/*~SideEffectOK*/) (x*/ indicates allowed combinations between (a priori incompatible) parallel types. Syntax: ::= [ , ]* ::= -> 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 */ =head2 /*~UndefTag */ 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 */ causes emission on stderr (at dcc execution time) of if compile-time evaluable 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 use of d-pragmas 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, -zfci do not check first character of identifiers, -zfrt no unnamed function return type check, -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, +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, +zctn check first character of (created) type names (if '-zfci'), +zdol allows '$' in identifiers, +zepl warn on empty formal parameter list, +zkwm keywords redefinable (via macro), +zlt/+zltX list last tokens processed before error/warning (X = buffer length), +zmcc check all pointers for missing 'const' qualifier, +zmic more index type 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), +zudt warn on tags declared (but not defined) in header files, +zusg give 'usage', +zve output more informative error/warning messages, +zvve idem '+zve', plus output type descriptions in full. 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, only one macro can be defined by a given /DEF; /DEF, /INCL, /UNDEF options have to be named 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. Examples of setting of DCCDFLTS: - UNIX setenv DCCDFLTS '-zsam +zvve +zlt' - VMS $ 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 d-pragma /*~zif*/. - 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.6 ----------------------------------------------- - d-pragma /*~NotUsedAfter*/ removed (not useful anymore), - big improvement in management of adjustment files (cf. modifications to paragraph 5), - revision of all adjustment files, - cases of '16-bits int' platforms, and of platforms where NULL is not all-zeros, taken care of (but not tested). - 17 - About 16 bits int platforms ---------------------------------- Portage completed (but not tested).