home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / clint / clt167 / readme < prev    next >
Text File  |  1994-03-28  |  52KB  |  1,526 lines
  1.  
  2.                                   CLINT V1.67
  3.                                   ───────────
  4.  
  5.                       The Ultimate C Source Checking Tool
  6.  
  7.                (c) 1992-1994 R&D Associates - All Rights Reserved
  8.  
  9.           ┌──────────────────────────────────────────────────────────┐
  10.           │                                                          │
  11.           │       R&D Associates, 356 D. W. Highway Suite 232,       │
  12.           │                Merrimack, NH 03054, USA                  │
  13.           │                                                          │
  14.           │         R&D Associates, 16 High Street, Rainham,         │
  15.           │                   Kent ME8 7JE, ENGLAND                  │
  16.           │                                                          │
  17.           ├──────────────────────────────────────────────────────────┤
  18.           │                                                          │
  19.           │             R&D Associates can be contacted on           │
  20.           │                COMPUSERVE by mailing user ID:            │
  21.           │                                                          │
  22.           │                     100013,1042 (USA)                    │
  23.           │                   100111,1162 (Europe)                   │
  24.           │                                                          │
  25.           └──────────────────────────────────────────────────────────┘
  26.  
  27.      NEW with version 1.67! Added -Jname for include environment name, -3
  28.      for 32 bit ints,  added new warning  messages,  added @name indirect
  29.      command line file support, new warning messages.
  30.  
  31.  
  32.                                  WHAT IS CLINT?
  33.                                  ──────────────
  34.  
  35.      CLint  is a tool which reads the  source files of your C programs, and
  36.      generates  reports about possible problems. As  it can look at ALL the
  37.      files  in a program, it is able to report far more than any C compiler
  38.      can.  Use CLint while developing your  programs, and you'll be assured
  39.      of type safe linkage, efficient code, and excellent portability.
  40.  
  41.      This  version of CLint  is released as SHAREWARE.  This means that you
  42.      use  it on a  try-before-you-buy basis. If you  find CLint useful, you
  43.      must  register within 30 days. We'll then send you the latest version,
  44.      with  more  documentation,  and  you'll receive  news  of  updates and
  45.      technical support. R&D Associates regrets that it is unable to provide
  46.      any  support for it's shareware  products without registration. Please
  47.      read the file LICENSE.DOC for more details.
  48.  
  49.      CLint  understands all  the industry  standard extensions  to the ANSI
  50.      standard  such as near, far,  huge, cdecl, pascal, asm,  and so on for
  51.      all  the supported compilers. It  understands and supports the Borland
  52.      psuedo registers, and segment types, and the Microsoft special segment
  53.      control extensions.
  54.  
  55.      A  special  feature  of CLint  is  that  it does  not  support models.
  56.      Instead, all type modifiers are unique, that is:
  57.  
  58.           char *    char far *          char near *    char huge *
  59.  
  60.  
  61.                                     Page - 1
  62.  
  63.  
  64.  
  65.      and  all variations are considered unique pointer types. The advantage
  66.      is  that regardless  of the  model you use  for any  project, if CLint
  67.      produces  no warnings, then  you can safely change  models with no ill
  68.      effects.  At the same  time, it understands that  near pointers may be
  69.      converted  to far or huge  by default. For those  of you that have had
  70.      problems with mixed model programming, this feature alone will justify
  71.      your purchase!
  72.  
  73.      Clint  costs just  US$35 in the  USA or Canada,  and £19 in  the UK or
  74.      Europe.  Register today for an easier programming life. Please use the
  75.      enclosed file ORDER.DOC.
  76.  
  77.                             **** UPDATE RECORD ****
  78.                             ───────────────────────
  79.  
  80.      Version  1.41  added '-x'  switch which  releases  50K more  memory to
  81.      CLint,  but makes  checking fractionally slower.  Great for BorlandC++
  82.      with Windows!
  83.  
  84.      Versions 1.42 - 1.44, fixed some minor bugs concerning the handling of
  85.      prototypes  with  the 'register'  keyword,  and improved  detection of
  86.      illegal initialisations.
  87.  
  88.      Version  1.45 fixed some previously fatal error reports when extremely
  89.      outrageous syntax was used.
  90.  
  91.      Version  1.46 fixed 'UL' constant modifier error and a couple of minor
  92.      I/O irritations.
  93.  
  94.      Version  1.47 fixed  upper/lower case problem  in library redefinition
  95.      warning,  added '_asm'  and '_segname'  keywords for  MSC users, added
  96.      '-wlib' and '-w-lib' switches to enable/disable warnings about library
  97.      symbol redefinition.
  98.  
  99.      Version  1.50: Major  Upgrade. Replaced  SETUP.EXE with  a menu driven
  100.      program  CSETUP.EXE which  allows CLINT.CFG  to be  edited rather than
  101.      replaced  when  options  are  changed,  and  also  automatically edits
  102.      AUTOEXEC.BAT  if you  allow it. Added  the ability to  be invoked from
  103.      inside  the Borland IDE, with reports collected and usable by the IDE.
  104.      Added   indirect  files  with   .CLN  extension,  allowing  convenient
  105.      specification of collections of files for projects.
  106.  
  107.      Added  support for  the Intel iC96  compiler, and  other compilers for
  108.      micro  controllers which use the syntax  'extern register' for the on-
  109.      board I/O registers.
  110.  
  111.      Added support for Borland C++ 3.1 and it's massive runtime library.
  112.  
  113.      Added  the '-u'  switch to supress  messages when  partial programs or
  114.      libraries are examined.
  115.  
  116.      Added  the '-T'  switch to request  that Clint  reccomend variables or
  117.      functions which could be static.
  118.  
  119.  
  120.  
  121.  
  122.                                     Page - 2
  123.  
  124.  
  125.  
  126.      Added the '-E' switch to use CLint as a full ANSI preprocessor.
  127.  
  128.      Version  1.51 -  1.52 fixed a  couple of minor  errors, fixed address,
  129.      corrected non-ANSI handling of labels.
  130.  
  131.      Version 1.53: added support for the Intel iC86 compiler, the Microsoft
  132.      C++ 7.0 compiler, and the Microsoft QuickC for Windows compiler. Added
  133.      '-w-lnf'  to allow bit  fields longer than 16  bits. Major re-write of
  134.      the manual to include all the new features.
  135.  
  136.      Version  1.54: fixed a  problem when the  last line of  a file did not
  137.      have a line feed.
  138.  
  139.      Version 1.55: fixed a problem with #else after #elif.
  140.  
  141.      Version  1.56: Added support  for the Archimedes  68HC11 compiler, and
  142.      the  Mix PowerC compiler. Also fixed a problem with functions taking a
  143.      pointer-to-function  with  no  arguments. Added  support  for #message
  144.      which has the syntax:
  145.  
  146.           #message any_string
  147.  
  148.      and   prints  the  string.  Very   useful  for  debugging  conditional
  149.      compilations, but not supported by all compilers.
  150.  
  151.      Version  1.57:  Fixed  a  problem  with  division  by  floating  point
  152.      constants, and constant expression evaluation.
  153.  
  154.      Version 1.58:  Fixed a  problem with  long command  option lines  from
  155.      *.CLN files which caused improper out of memory complaints.
  156.  
  157.      Version 1.59: Fixed an internal error report with sizeof("string").
  158.  
  159.      Version 1.61:  Fixed a problem with multiple CLint libraries not being
  160.      properly checked.
  161.  
  162.      Version 1.62:  Added  support  for  Microsoft  Visual C,  Watcom C386,
  163.      and Symantec C++ Pro 6.0.
  164.  
  165.      Version 1.63: Fixed error when given 'f(int x,)'.
  166.  
  167.      Version 1.64: Added support for Borland C++ 4.0, made DOS Extended.
  168.  
  169.      Version 1.65: Fixed pipe problem.
  170.  
  171.      Version 1.66: Fixed initializer problem.
  172.  
  173.      Version 1.67: Added -Jname for include environment name, -3 for 32 bit
  174.      ints,  added new warning messages,  added @name  indirect command line
  175.      file support.
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.                                     Page - 3
  184.  
  185.  
  186.  
  187.                                   INSTALLATION
  188.                                   ────────────
  189.  
  190.      Clint  shareware may  be downloaded  from bulletin  boards as  a self-
  191.      extracting  archive, or  on a floppy  disk from  shareware vendors. If
  192.      downloaded,  you must create  a directory (we  suggest C:\CLINT), copy
  193.      the  downloaded file  there, then execute  it, then  execute CSETUP to
  194.      complete the configuration.
  195.  
  196.      To install from a floppy insert the supplied CLint disk in a drive (we
  197.      assume drive A: here), then type:
  198.  
  199.           A:
  200.           CSETUP
  201.  
  202.      CSETUP  now  has an  easy to  use menu  interface. Specify  the target
  203.      directory,  select the compiler  you're using, and  specify where your
  204.      compiler lives. CSETUP fully supports your mouse, and has full on-line
  205.      context sensitive help. It writes (or updates if already existing) the
  206.      CLINT.CFG  file  according  to  your  choices,  renaming  any existing
  207.      CLINT.CFG  file as CLINTOLD.CFG. You can  use CSETUP again at any time
  208.      to change your choices.
  209.  
  210.      CSETUP  will automatically update your  AUTOEXEC.BAT file if required.
  211.      You  may  refuse CSETUP  permission to  change it,  in which  case you
  212.      should add the line:
  213.  
  214.           SET CLINT=C:\CLINT
  215.  
  216.      or similar if you installed to a different directory, and add CLint's
  217.      directory to your path.
  218.  
  219.      If  you use a ram disk, CLint will  run faster if you tell it to place
  220.      its  temporary files on ram disk. Assuming  you have a ram disk called
  221.      D: then add to the following line to your AUTOEXEC.BAT file:
  222.  
  223.           SET TMP=D: (or E: etc.)
  224.      or
  225.           SET TEMP=D:
  226.  
  227.                WARNING:  Don't specify  a nonexistent  name here,  or CLint
  228.                won't work!
  229.  
  230.      If  CSETUP modifies your AUTOEXEC.BAT, it  will reboot the computer to
  231.      allow  the changes  to take effect.  If instead you  manually make the
  232.      changes, you will need to re-boot.
  233.  
  234.                PLEASE  NOTE: If you change your  version of C you will need
  235.                to run CSETUP again when you make the change.
  236.  
  237.      For the Shareware version only, you must complete your installation by
  238.      executing  the batch file corresponding  to your chosen compiler. This
  239.      will  construct in your  CLint directory the  library file required to
  240.      check all uses of your compiler's runtime library.
  241.  
  242.  
  243.  
  244.                                     Page - 4
  245.  
  246.  
  247.  
  248.                                CONFIGURING CLINT
  249.                                ─────────────────
  250.  
  251.      You  can configure CLint  to your personal  preferences by editing the
  252.      supplied  CLINT.CFG file  which looks  like this  (varies according to
  253.      what you told CSETUP when CLint was installed):
  254.  
  255.           # (c) R&D Associates 1992.
  256.           # CLINT.CFG
  257.           -IC:\TC\INCLUDE         # TurboC++ 1.0
  258.           -lC:\CLINTREG\CTCPP10   # Clint Library for TurboC++ 1.0
  259.           #
  260.           # Add additional include directories with -I
  261.           # Add your Clint library directory with -l
  262.           # Add your common Clint warning switches:
  263.           # -wxxx to enable warning xxx,
  264.           # -w-xxx to disable warning xxx.
  265.           #
  266.  
  267.      As you will see later, you can add any of CLint's options to this file
  268.      as  you see  fit. The  '-I' line specifies  the name  of the directory
  269.      where  your compiler's header files are  - change this as required, or
  270.      use  CSETUP.  The  '-l'  line specifies  where  you  keep  the library
  271.      definitions, and the name of the definition file. If you use CSETUP to
  272.      change   your  CLint  configuration,  it  edits  your  CLINT.CFG  file
  273.      retaining all the information that did not need to be changed.
  274.  
  275.            ─────────────────────────────────────────────────────────
  276.            NOTE: You MUST specify complete pathnames with -I and -l!
  277.            ─────────────────────────────────────────────────────────
  278.  
  279.      CLint  searches for  CLINT.CFG in the  current directory,  then in the
  280.      directory  specified  in  the CLINT  environment  (SET)  variable. You
  281.      should  set up  the standard  CLINT.CFG file  to reflect  your general
  282.      needs.  If a special case arises in  one of your programs, simply copy
  283.      CLINT.CFG to that directory:
  284.  
  285.           CD MYDIR
  286.           COPY \CLINT\CLINT.CFG
  287.  
  288.      and edit it as required. No other use of CLint will be affected. CLint
  289.      expects  that each  line in CLINT.CFG  is a CLint  option which starts
  290.      with  '-' and is followed by an  option letter, and any required text.
  291.      Any  number of  other lines  may be  present in  the file  and will be
  292.      ignored. You can also comment any line by using '#' like this:
  293.  
  294.           -l\clint\cbcpp30    # BorlandC++ 3.0
  295.  
  296.      Such comments are ignored. CLint is insensitive to case in the command
  297.      line or in CLINT.CFG except as detailed later.
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.                                     Page - 5
  306.  
  307.  
  308.  
  309.                                   USING CLINT
  310.                                   ───────────
  311.  
  312.      In the simplest case, you will use CLint like this:
  313.  
  314.           CLINT *.C
  315.  
  316.      CLint  will read all of the  source files, analyse them carefully, and
  317.      report on any possibly problems, ANSI violations, portability problems
  318.      and  so forth. It assumes that all the files specified are part of one
  319.      program,  and will  be linked together,  and linked  with the run-time
  320.      library  routines specified in  CLINT.CFG or with  '-l' options on the
  321.      command line.
  322.  
  323.      It  checks carefully  that symbols  declared in  one file  and used in
  324.      another  have the same  declaration in both  files; that all functions
  325.      defined  are actually called; that all  variables defined are used. If
  326.      CLint  produces no  warnings or errors  about such things,  you can be
  327.      assured that the program when linked is type-safe.
  328.  
  329.      There may be cases where you have run-time libraries supplied by other
  330.      vendors,  or written  by yourself. You  will need to  tell CLint about
  331.      them  to obtain full checking. If you don't, CLint will complain about
  332.      symbols which are never defined.
  333.  
  334.      Let's assume that you have a library called MYLIB in \MYLIB, which has
  335.      a  header MYLIB.H. The first  thing to do is  verify that there are no
  336.      errors in MYLIB:
  337.  
  338.           CD \MYLIB
  339.           CLINT *.C -u
  340.  
  341.      Fix any errors reported before proceeding! Then you do:
  342.  
  343.           CLINT MYLIB.H -L MYLIBDEF
  344.  
  345.      And finally you add the line:
  346.  
  347.           -l\MYLIB\MYLIBDEF
  348.  
  349.      to  CLINT.CFG. (If you  don't want to  add this line,  simply type the
  350.      '-l' option when you run CLint.)
  351.  
  352.      The really important options you may need to use are:
  353.  
  354.           -Dname=value   define a preprocessor macro
  355.           -Uname         undefine a preprocessor macro
  356.           -lfile         specify a CLint library file to check against
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.                                     Page - 6
  367.  
  368.  
  369.  
  370.      When   reading  header  files,   CLint  distinguishes  between  header
  371.      directories specified in CLINT.CFG, and those specified in the command
  372.      line.  The former  are assumed to  be your compiler  or library header
  373.      files, the latter header files which are part of the program.
  374.  
  375.      This  is  only  important  when '-w-shd'  is  used  (don't  warn about
  376.      compiler headers - the default), as CLint will only be silent on minor
  377.      problems in compiler headers - not program ones.
  378.  
  379.      The search order for headers which use "file.h" is:
  380.  
  381.           1) Current directory,
  382.  
  383.           2) Directories given in -I in the command,
  384.  
  385.           3) Directories given in -I in CLINT.CFG.
  386.  
  387.      For headers which use <file.h> only (2) and (3) are searched.
  388.  
  389.      The  built-in preprocessor is  a full ANSI  implementation. It defines
  390.      the required preprocessor macros:
  391.  
  392.           __LINE__, __FILE_, __DATE__, __TIME__
  393.  
  394.      and also the macros
  395.  
  396.           __DOS__ and __CLINT__
  397.  
  398.      with  the value '1'. If you require __STDC__ place '-D__STDC__' on the
  399.      command line or in CLINT.CFG.
  400.  
  401.      Some  users have encountered problems with compilers which claim to be
  402.      ANSI, but don't have fully ANSI preprocessors. Lines like:
  403.  
  404.           #ifdef (sizeof(int) == sizeof(short))
  405.  
  406.      often  in LIMITS.H are a dead giveaway. The ANSI standard specifically
  407.      prohibits  expressions  like this:  you can't  have casts,  sizeof, or
  408.      enumeration  constants  in a  #if expression.  It  is usually  done by
  409.      compilers that are trying to deduce the model you are using. Compliant
  410.      compilers define preprocessor symbols instead.
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.                                     Page - 7
  428.  
  429.  
  430.  
  431.                        USING CLINT FROM THE BORLAND IDE.
  432.                        ─────────────────────────────────
  433.  
  434.      You  can arrange to call  CLint from inside the  Borland IDE for Turbo
  435.      C++ 1.0 and upwards like this:
  436.  
  437.           From  the main  menu select Options,  then Transfer,  then Edit a
  438.           blank entry entering the following information:
  439.  
  440.                Program Title:  ~CLint current file
  441.  
  442.                Program Path:  C:\CLINT\CLINT.EXE
  443.  
  444.                Command Line:  $SAVE CUR $NOSWAP $CAP MSG(CLNT2MSG) -u -x -Z
  445.                               -D__TURBOC__ $EDNAME
  446.  
  447.           Then select Shift-F9 as the hotkey.
  448.  
  449.           Then  from the main menu select Options, then Transfer, then Edit
  450.           a blank entry entering the following information:
  451.  
  452.                Program Title:  C~Lint PROJECT.CLN
  453.  
  454.                Program Path:  C:\CLINT\CLINT.EXE
  455.  
  456.                Command Line:  $SAVE ALL $NOSWAP $CAP MSG(CLNT2MSG) -x -Z
  457.                               _D__TURBOC__ PROJECT.CLN
  458.  
  459.           Then select Shift-F10 as the hotkey.
  460.  
  461.      If  you installed CLint  in a different  directory, use that directory
  462.      name instead. If you told SETUP that you're using one of the supported
  463.      Borland  compilers, the  output filter  CLNT2MSG.EXE is  copied to the
  464.      compiler's BIN directory. The command line options for the IDE are:
  465.  
  466.           $SAVE CUR:     save the current file
  467.  
  468.           $NOSWAP:       don't switch screens
  469.  
  470.           $CAP:          capture CLint's output
  471.  
  472.           MSG(CLNT2MSG): pipe CLint's output through the filter
  473.  
  474.           -x, -u:        standard CLint switches
  475.  
  476.           -Z:            a special CLint switch for the IDE only
  477.  
  478.           $EDNAME:       the name of the current IDE file
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.                                     Page - 8
  489.  
  490.  
  491.  
  492.      Unfortunately,  if  you have  existing project  files, you'll  need to
  493.      enter this information for each one.
  494.  
  495.      Shift-F9  runs CLint  against the  current file.  As it  uses the '-u'
  496.      option,  tests for  interaction with libraries  or other  files in the
  497.      project are suppressed. It is useful for rapid checks of a file whilst
  498.      being edited.
  499.  
  500.      To  use the second option, create  a file PROJECT.CLN for your project
  501.      containing a line for each source file in the project. You should also
  502.      place any project specific options using '-I', '-l', '-w' etc. one per
  503.      line as though they were being typed on the command line (see the next
  504.      section for details). This allows you to run CLint against your entire
  505.      project  by typing  Shift-F10, and  when CLint  finishes the  IDE will
  506.      correctly position the cursor against any errors or warnings detected.
  507.  
  508.      Once  you've created  PROJECT.CLN, it is  just as useful  from the DOS
  509.      command line - just type:
  510.  
  511.           CLINT
  512.  
  513.      as the special file PROJECT.CLN is used (if it exists) when CLint is
  514.      invoked with no file specifications. If you use MAKE, you may find it
  515.      convenient to add a target:
  516.  
  517.           clint:
  518.                clint -o report
  519.  
  520.      to  completely  check your  entire project,  and  leave the  report in
  521.      'REPORT'.
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.                                     Page - 9
  550.  
  551.  
  552.  
  553.                            THE COMMAND LINE OPTIONS.
  554.                            ─────────────────────────
  555.  
  556.      CLint  takes a number  of source file  names, possibly with wildcards,
  557.      and  analyses these sources. To control  the analysis and reporting, a
  558.      number   of  options  may  occur  on  the  command  line,  or  in  the
  559.      configuration  file CLINT.CFG, or  in files with  a '.CLN' extension -
  560.      PROJECT.CLN is special, if no files are specified and that file exists
  561.      it is used by default.
  562.  
  563.      The  filenames may be specified in full  or in part. Filenames with no
  564.      extension  are assumed to have the  extension '.C', failing which they
  565.      are  assumed to have the extension  '.CLN'. The files are inspected in
  566.      order  of  their  occurrence  on  the  command  line.  When  wild card
  567.      expansion occurs, the expanded names are ordered alphabetically.
  568.  
  569.      File  names with  no wildcards  and no  extension if  not matching any
  570.      files  with the extension '.C' have the extension '.CLN' appended, and
  571.      are then searched for in the current directory.
  572.  
  573.      Files  with the extension  '.CLN' are assumed  to contain command line
  574.      options  and filenames, one per line.  If filenames are present in the
  575.      file,  no wildcards  are permitted,  neither are  nested '.CLN' files.
  576.      Such  files are supported to allow the convenient specification of the
  577.      group of files comprising a project and the options they need. You may
  578.      have  any number of blank lines in  the file, and you can add comments
  579.      to any line by prefixing them with the '#' character.
  580.  
  581.      If  you use any version of the Borland IDE from Turbo C++ 1.0 upwards,
  582.      you  should  name such  files PROJECT.CLN  as described  earlier. Such
  583.      files  are read strictly  in left to right  order as encountered while
  584.      reading the command line. The effect is exactly as though each line of
  585.      the  '.CLN'  file is  inserted as  an argument  into the  command line
  586.      replacing  the '.CLN' filename argument. In subsequent discussion, all
  587.      comments regarding the precedence of command line options includes any
  588.      options found in '.CLN' files too.
  589.  
  590.      All  CLint options  begin with  a leading  '-' or  '/' character  - in
  591.      examples  below, we  use '-'. Except  as described  below, options are
  592.      case  insensitive unless the  C standard or  operating system requires
  593.      otherwise.
  594.  
  595.      Options  may occur in  any order on the  command line, intermixed with
  596.      file names. The options are read in the order:
  597.  
  598.           CLINT.CFG
  599.      and
  600.           command line left-to-right
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.                                    Page - 10
  611.  
  612.  
  613.  
  614.      which  can  be important.  Options in  the  command line  may override
  615.      options in CLINT.CFG or earlier options in the command line.
  616.  
  617.      ──────────────────────────────────────────────────────────────────────
  618.      NOTE: CLint searches for CLINT.CFG first in the current directory, and
  619.      then  in the directory  specified in your  CLINT environment variable.
  620.      CLint issues no warnings if CLINT.CFG can't be found.
  621.      ──────────────────────────────────────────────────────────────────────
  622.  
  623.      Typing:
  624.  
  625.           CLINT /?
  626.  
  627.      produces a usage screen summarising the options.
  628.      ──────────────────────────────────────────────────────────────────────
  629.           -Ipath
  630.           -ipath
  631.  
  632.      where  'path' is a directory name.  Case may be important in directory
  633.      names  depending  on  the operating  system  you use.  It  specifies a
  634.      directory  to search for header  files. There may be  as many of these
  635.      options as required. The order of search for:
  636.  
  637.           #include "file"
  638.  
  639.      is
  640.  
  641.           current directory,
  642.           -I directories given on the command line,
  643.           -I directories given in CLINT.CFG.
  644.  
  645.      and for:
  646.  
  647.           #include <file>
  648.  
  649.      is
  650.  
  651.           -I directories given on the command line,
  652.           -I directories given in CLINT.CFG.
  653.  
  654.      You  can force  CLint to  forget all  the -I  options in  CLINT.CFG by
  655.      giving  '-I-' or '-i-' on the command  line prior to any other include
  656.      paths.
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.                                    Page - 11
  672.  
  673.  
  674.  
  675.      ──────────────────────────────────────────────────────────────────────
  676.           -Dname
  677.           -dname
  678.           -Dname=value
  679.           -dname=value
  680.  
  681.      These  options define preprocessor macros.  Although the option letter
  682.      is  case insensitive,  the macro names  and values are  NOT. The first
  683.      form  defines a  macro with default  replacement text  '1'. The second
  684.      form  gives the replacement text explicitly. For your convenience, you
  685.      may append several definitions to an option with ';' like this:
  686.  
  687.           -Dname1;name2=4;name3=5;name4
  688.  
  689.      Note that the DOS command line can't handle options like:
  690.  
  691.           -Dname="1"
  692.  
  693.      properly.
  694.  
  695.      ──────────────────────────────────────────────────────────────────────
  696.           -Uname
  697.  
  698.      This  option  deletes a  preprocessor  macro. It  is  not an  error to
  699.      specify  a macro which was  not defined. It is  an error to attempt to
  700.      undefine:
  701.  
  702.           '__TIME__', '__DATE__', '__FILE__', or '__LINE__'.
  703.  
  704.      It can be used to undefine
  705.  
  706.           '__CLINT__' or '__DOS__'
  707.  
  708.      or  any  symbols defined  in CLINT.CFG.  As with  '-D' you  can append
  709.      several names with ';' like this:
  710.  
  711.           -Uname1;name2
  712.  
  713.      The order of '-D' and '-U' is important - you may only undefine macros
  714.      whose definition precedes the '-U' option.
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.                                    Page - 12
  733.  
  734.  
  735.  
  736.      ──────────────────────────────────────────────────────────────────────
  737.           -o file
  738.           -O file
  739.           -ofile
  740.           -Ofile
  741.  
  742.      This option specifies a file to receive CLint's output. By default the
  743.      output  is written  to 'stderr'. If  you use this  option, CLint still
  744.      writes  the source file name it is  working on to 'stderr' to show you
  745.      how  it is proceeding.  If more than  one of these  options occur, the
  746.      rightmost one is used.
  747.  
  748.      ──────────────────────────────────────────────────────────────────────
  749.           -e0
  750.  
  751.      By  default CLint stops reading a file  if 15 errors are produced, and
  752.      proceeds  to the next file with the  message 'Too many errors'. If you
  753.      use this option the limit is removed.
  754.  
  755.      ──────────────────────────────────────────────────────────────────────
  756.           -eNNN
  757.  
  758.      Use  this option to specify  the error limit you  need. The default is
  759.      15.  If this  option and  '-e0' occur  together, the  rightmost one is
  760.      obeyed.
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.                                    Page - 13
  794.  
  795.  
  796.  
  797.                                     WARNINGS
  798.                                     ────────
  799.  
  800.      ──────────────────────────────────────────────────────────────────────
  801.           -w0
  802.           -W0
  803.  
  804.      By  default, CLint stops  reading a file if  60 warnings are produced,
  805.      and proceeds to the next file with the message 'Too many warnings'. If
  806.      you use this option the limit is removed.
  807.  
  808.      ──────────────────────────────────────────────────────────────────────
  809.           -wNNN
  810.  
  811.      Use  this option to specify the warning limit you need. The default is
  812.      60.  If this  option and  '-w0' occur  together, the  rightmost one is
  813.      obeyed.
  814.  
  815.      ──────────────────────────────────────────────────────────────────────
  816.           -wall
  817.  
  818.      A  number of CLint's  warnings are optional, and  OFF by default. This
  819.      turns all warnings on.
  820.  
  821.      ──────────────────────────────────────────────────────────────────────
  822.           -w-all
  823.  
  824.      This turns all warnings off. It may usefully occur in CLINT.CFG when
  825.      followed by '-wxxx' options to turn on only those warnings you need.
  826.  
  827.      ──────────────────────────────────────────────────────────────────────
  828.           -wxxx
  829.  
  830.      Turn the specified warning on.
  831.  
  832.      ──────────────────────────────────────────────────────────────────────
  833.           -w-xxx
  834.  
  835.      Turn the specified warning off.
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.                                    Page - 14
  855.  
  856.  
  857.  
  858.      ──────────────────────────────────────────────────────────────────────
  859.  
  860.      This is the complete list of warning switches. Any of them may be used
  861.      in  CLINT.CFG or  on the  command line.  Unless changed  by CLINT.CFG,
  862.      those switches marked below with '*' are enabled by default.
  863.  
  864.       *wcom         warn of nested comments
  865.        webr         else needs '{'
  866.        wfbr         for needs '{'
  867.        wibr         if needs '{'
  868.        wwbr         while needs '{'
  869.        wspc         advise on spacing
  870.        wlfb         warn of functions longer than 120 lines
  871.        wlfbNNN      warn of functions greater than NNN lines long
  872.        wtyb         typedefing primitive types
  873.       *wtye         warn of typedefing enums
  874.       *wtyg         warn of general (complex) typedefs
  875.       *wtyp         warn of typedefing pointer types
  876.       *wtys         warn of typedefed structs with lower case names
  877.        wtysU        typedefed structs with names not fully in upper case
  878.       *wstv         warn of passed/returned structs (by value)
  879.       *wcon         warn of constant conditions
  880.       *whdr         show warnings in user header files
  881.        wshd         show warnings in system header files
  882.       *wprn         warn of misuse of printf (sprintf, fprintf, etc)
  883.       *wenu         warn of enum misuse
  884.       *wtri         warn about trigraphs
  885.       *winc         warn of multiply included header files
  886.       *wiag         warn of auto aggregate initialisation
  887.       *wunr         warn of unreachable code
  888.       *welb         warn of empty loop bodies
  889.       *wcil         long constant needs 'L'
  890.       *wsig         warn of loss of significance with longs
  891.        wsig+        warn of loss of significance with any type
  892.       *wmxp         warn of mixed pointers to signed/unsigned char
  893.       *wenu         warn of enum misuse
  894.       *wnus         warn of variables defined but not used
  895.       *wpro         warn of function use without a prototype
  896.       *wret         warn of return misuse
  897.       *wlib         warn of library symbol redefinition
  898.       *wlnf         warn of bit fields longer than 16 bits
  899.       *wreg         warn of register usage
  900.       *wpua         warn of possibly unintended assignments
  901.       *wbbr         warn of non-ANSI initializer bracing
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.                                    Page - 15
  916.  
  917.  
  918.  
  919.                                 SPECIAL OPTIONS
  920.                                 ───────────────
  921.  
  922.           -L file
  923.  
  924.      This  important option  instructs CLint  to change  it's behaviour, in
  925.      that  it knows that the source files will be headers not program text.
  926.      Each  prototype or external declaration in the source files is written
  927.      to  the 'file' in  a form to be  later read into  CLint using the '-l'
  928.      option. This file is needed if CLint is to check your usage of library
  929.      functions and variables properly.
  930.  
  931.      Note  that many errors will  be reported if this  option is applied to
  932.      program  source, and that the  '-L' MUST be upper  case. The file name
  933.      case is only important if your operating system requires.
  934.  
  935.      ──────────────────────────────────────────────────────────────────────
  936.           -lfile
  937.  
  938.      This  option  instructs CLint  to  read a  definition  file previously
  939.      prepared  with  the '-L'  option above  after  reading all  the source
  940.      files. Declarations and usage in your source files will be compared to
  941.      those recorded in the definition file, and may result in the warning:
  942.  
  943.           Warning: 'name' in file(NNN) hides a library symbol in 'file'
  944.  
  945.      If this happens, you have defined a function or variable which is also
  946.      defined in a library. C allows this, but in some cases it may be a bug
  947.      in  your  code.  You may  suppress  these warnings  with  the '-w-lib'
  948.      option.
  949.  
  950.      If  you don't use the '-l' option for each library you use, CLint will
  951.      complain  about a  long list of  functions and variables  used but not
  952.      defined  (exactly as  the linker  would if you  failed to  link in the
  953.      library at link time).
  954.  
  955.      The  '-l'  option is  used differently  in CLINT.CFG:  you must  use a
  956.      directory name. For example, suppose that you place all the definition
  957.      files you created with the '-L' option above in
  958.  
  959.           \CLINT\MYLIBS
  960.  
  961.      If you want CLint to check usage in ALIB in this directory, you place:
  962.  
  963.           -l\clint\mylibs
  964.  
  965.      in CLINT.CFG, and on the command line use:
  966.  
  967.           -lalib
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.                                    Page - 16
  977.  
  978.  
  979.  
  980.      ──────────────────────────────────────────────────────────────────────
  981.           -E
  982.  
  983.      Use  CLint  as  an ANSI  C  pre-processor.  The output  is  written to
  984.      'stdout'  and may  be redirected,  or the '-o'  option may  be used to
  985.      write  the output  to any  named file.  If wild  cards are  used, each
  986.      source file is pre-processed in turn resulting in all output appearing
  987.      in the same file.
  988.  
  989.      ──────────────────────────────────────────────────────────────────────
  990.           -u
  991.  
  992.      This  switch  informs CLint  that the  files  given are  not complete,
  993.      either  they are  a library or  only part  of a program.  In any case,
  994.      complaints about symbols used but not defined and defined but not used
  995.      are suppressed.
  996.  
  997.      ──────────────────────────────────────────────────────────────────────
  998.           -T
  999.  
  1000.      This  switch tells Clint  to detect functions  and variables which are
  1001.      only  used in the  file in which  they are declared.  It then prints a
  1002.      warning  about  all  such  variables, observing  that  they  should be
  1003.      declared 'static'.
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.  
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.                                    Page - 17
  1038.  
  1039.  
  1040.  
  1041.                               CONTROL OF TYPEDEFS
  1042.                               ───────────────────
  1043.  
  1044.      'typedef'  is often  misused. You  can control  the way  CLint reports
  1045.      these misuses in a number of ways:
  1046.  
  1047.      ──────────────────────────────────────────────────────────────────────
  1048.      -wtye enables reports of typedefing enums, for example:
  1049.  
  1050.           typedef enum { A, B} THING;
  1051.  
  1052.      provokes   the  report:  "typedefed  enum  as  'THING'".  We  consider
  1053.      typedefing  enums to be  poor practise as  discussed elsewhere, except
  1054.      for the example given below.
  1055.  
  1056.      ──────────────────────────────────────────────────────────────────────
  1057.      -wtys  enables reports about  typedefing structs or  unions without an
  1058.      initial  capital letter in the name, -wtysU enables reports about this
  1059.      without  the name being all upper case.  We consider that at least the
  1060.      name should start with a capital letter, preferably all upper case.
  1061.  
  1062.      ──────────────────────────────────────────────────────────────────────
  1063.      -wtyp enables reports about typedefing pointer types. We consider this
  1064.      to be one of the major abuses of typedef.
  1065.  
  1066.      ──────────────────────────────────────────────────────────────────────
  1067.      -wtyg  enables reports about strange typedefs - for example typedefing
  1068.      an  array. We  produce this message  for any typedef  which is complex
  1069.      (not  a  primitive type,  struct,  union, enum,  or  pointer). Complex
  1070.      typedefs   are  in  our  opinion  dangerous  as  they  hide  too  much
  1071.      information.
  1072.  
  1073.      ──────────────────────────────────────────────────────────────────────
  1074.      -wtyb  enables reports about typedefing  primitive types such as 'int'
  1075.      with names that are not all lower case. There are occasions where this
  1076.      is  useful, but  we believe that  for clarity the  typedef name should
  1077.      always be lower case.
  1078.  
  1079.      CLint  already knows about standard ANSI names which are typedefed, as
  1080.      follows:
  1081.  
  1082.           div_t, ldiv_t, size_t, wchar_t, clock_t, time_t,
  1083.           fpos_t, jmp_buf, va_list, tm,
  1084.  
  1085.      and will never complain about their definitions.
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.                                    Page - 18
  1099.  
  1100.  
  1101.  
  1102.                               DISCUSSION SECTIONS
  1103.                               ───────────────────
  1104.  
  1105.      We  believe that  C programs  should be  understandable, maintainable,
  1106.      portable, and above all efficient. CLint was designed to assist in the
  1107.      achievement  of these goals. CLint  produces several reports which can
  1108.      help  you write code  meeting these objectives.  We discuss several of
  1109.      the reports which may occur.
  1110.  
  1111.      1. EFFICIENCY
  1112.      ─────────────
  1113.  
  1114.      ──────────────────────────────────────────────────────────────────────
  1115.      auto aggregate initialisation
  1116.  
  1117.           An  'aggregate'  is  any  structure,  union  or  array  -  i.e. a
  1118.           collection  of more primitive objects.  All compilers use code to
  1119.           initialise  'auto'  objects.  Where these  objects  are primitive
  1120.           types, the code is equivalent to assignment.
  1121.  
  1122.           Where  the object is a 'struct', 'union', or array, the compilers
  1123.           generate  a static unnamed object of the same type and initialise
  1124.           that  - and then generate code to copy this hidden object to your
  1125.           object.
  1126.  
  1127.           You  can save  code and  speed up  your program  by declaring the
  1128.           object   'static'  which   avoids  the  copy   operation  as  the
  1129.           initialisation  is performed once at compile time. This will only
  1130.           work  if you never  modify the object! If  you do, then carefully
  1131.           examine  the logic of  your code - it  is almost never necessary,
  1132.           and often confusing. A common case is:
  1133.  
  1134.                void f()
  1135.                {
  1136.                     char string[] = "a string ....";
  1137.                }
  1138.  
  1139.           where  if 'string' is  not modified it should  be static. You can
  1140.           disable this warning with -w-iag.
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.                                    Page - 19
  1160.  
  1161.  
  1162.  
  1163.      ──────────────────────────────────────────────────────────────────────
  1164.      struct/union passed by value
  1165.      struct/union value returned
  1166.  
  1167.           Both  these  cases  cause  a significant  amount  of  code  to be
  1168.           generated,  and stack space  usage equivalent to  the size of the
  1169.           object.  When you  pass a  structure value,  the entire  value is
  1170.           pushed  on the stack. When you  return a structure, space for the
  1171.           return value is reserved on the stack, and in normal cases copied
  1172.           from the stack to the destination, for example:
  1173.  
  1174.                struct x {
  1175.                     ......
  1176.                };
  1177.  
  1178.                struct x f(void)
  1179.                {
  1180.                     struct x y;
  1181.  
  1182.                     ......
  1183.                     return y;
  1184.                }
  1185.  
  1186.           This  typical  code  skeleton  copies the  value  of  'y'  to the
  1187.           reserved  space on the stack, and (assuming you use the result by
  1188.           assignment)  copies that value  to the destination!  If you don't
  1189.           want these warnings, use -w-stv.
  1190.  
  1191.      ──────────────────────────────────────────────────────────────────────
  1192.      '<name>' not used
  1193.      static '<name>' not used
  1194.      '<name>' assigned to but not used
  1195.      static '<name>' assigned to but not used
  1196.      argument '<name>' not used
  1197.  
  1198.           These  all indicate problems with the  program logic - often they
  1199.           are  a  result  of  code  changes  which  cause  previously  used
  1200.           variables  to become unused. Sometimes they indicate a real bug -
  1201.           you  assigned a value  for a reason,  but then that  value is not
  1202.           used.  However they  arise, they should  be cleared -  if only to
  1203.           reduce the size of the program.
  1204.  
  1205.           In  the case of "argument 'x' not used" this may be intentional -
  1206.           you can silence CLint by placing:
  1207.  
  1208.                #pragma argsused
  1209.  
  1210.           ahead of the function declaration. This clearly announces what is
  1211.           going on to any people reading the code too.
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.                                    Page - 20
  1221.  
  1222.  
  1223.  
  1224.      ──────────────────────────────────────────────────────────────────────
  1225.      label '<name>' unused
  1226.  
  1227.           Most  compilers assume when they see  a label that control may be
  1228.           transferred  to  a label  by  'goto', and  therefore  discard the
  1229.           values  of any registers they may be remembering. A label that is
  1230.           not used will usually not be detected as such, and will cause the
  1231.           same  action.  This  can  result  in  larger  slower  code  being
  1232.           generated immediately following such a label.
  1233.  
  1234.      2. CODING STYLE
  1235.      ───────────────
  1236.  
  1237.      ──────────────────────────────────────────────────────────────────────
  1238.      statement after 'for' should have '{'
  1239.      statement after 'while' should have '{'
  1240.      statement after 'do' should have '{'
  1241.      statement after 'if' should have '{'
  1242.      statement after 'else' should have '{'
  1243.  
  1244.           Any of these not followed by a keyword, as for example:
  1245.  
  1246.                if (x > 5)
  1247.                     ++i;
  1248.  
  1249.           should be fully braced like this:
  1250.  
  1251.                if (x < 5) {
  1252.                     ++i;
  1253.                }
  1254.  
  1255.           If  you agree  with us,  any of  these may  be enabled  by -wfbr,
  1256.           -wwbr, -wibr, -webr.
  1257.  
  1258.      ──────────────────────────────────────────────────────────────────────
  1259.      ' ' advised after '='
  1260.      ' ' advised after ','
  1261.      ' ' advised after ';'
  1262.      ' ' advised after ':'
  1263.  
  1264.           Some  spacing  styles  are  hard to  read.  We  believe  that all
  1265.           operators  should have white  space either side,  but this is too
  1266.           draconian, so we object to things like:
  1267.  
  1268.                a=1,b=2;f(3,a);
  1269.  
  1270.           which will provoke 5 complaints. It should be written as:
  1271.  
  1272.                a = 1, b = 2; f(3, a);
  1273.  
  1274.      If you want this checking, enable it with -wspc.
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.                                    Page - 21
  1282.  
  1283.  
  1284.  
  1285.      ──────────────────────────────────────────────────────────────────────
  1286.      ' ' advised after '<keyword>'
  1287.  
  1288.           We  believe  that  many  people  reading  code  use  visual clues
  1289.           extensively.  One of the clues often  used is function calls have
  1290.           the  form 'name(...)'. Some  programmers have a  habit of writing
  1291.           language clauses as though they were function calls, like:
  1292.  
  1293.                if(j == 0)
  1294.  
  1295.           At  first glance, this is enough like a function call to at least
  1296.           arrest the eye. This is also enabled by -wspc.
  1297.  
  1298.  
  1299.      3. USE OF TYPEDEF.
  1300.      ──────────────────
  1301.  
  1302.      ──────────────────────────────────────────────────────────────────────
  1303.      typedefed enum as '<name'>
  1304.      typedefed struct/union as '<name>' - use initial capital
  1305.      typedefed a pointer as '<name>'
  1306.      typedefed 'unsigned char' as '<name>' - use lower case
  1307.  
  1308.           We  consider typedef misuse  to be one of  the major crimes often
  1309.           committed  with  C. Some  extremely obscure  code can  occur when
  1310.           typedefs  are used, and  if the declaration is  in a header file,
  1311.           considerable  time may be needed to discover what the code really
  1312.           means - for example, given:
  1313.  
  1314.                #include "junk.h"
  1315.  
  1316.                void f()
  1317.                {
  1318.                     garbage x;
  1319.  
  1320.                     ........
  1321.                }
  1322.  
  1323.           what is 'x'? We propose some rules for the use of typedef to make
  1324.           it at least possible to get some hints:
  1325.  
  1326.                1) When typedefing unions or structs, always have an initial
  1327.                capital letter in the name - or capitalise the entire name.
  1328.  
  1329.                2) Never typedef an enumeration - use 'enum thing x' instead
  1330.                which clearly announces to the reader what is going on.
  1331.  
  1332.                3)  Never typedef pointer types - the presence of the '*' in
  1333.                the declaration is a valuable clue to understanding.
  1334.  
  1335.                4) When typedefing a primitive type, always use a lower case
  1336.                name,  the reader  can then be  assured that  all lower case
  1337.                type names are really simple objects like 'int'.
  1338.  
  1339.  
  1340.  
  1341.  
  1342.                                    Page - 22
  1343.  
  1344.  
  1345.  
  1346.           These  objections can  be enabled  if you  agree with  us: -wtye,
  1347.           -wtys, -wtyp, -wtyb.
  1348.  
  1349.      4. POTENTIALLY SERIOUS BUGS
  1350.      ───────────────────────────
  1351.  
  1352.      There  are many potential  bugs which CLint warns  about. Some of them
  1353.      can lead to extremely obscure problems. The most important are:
  1354.  
  1355.      ──────────────────────────────────────────────────────────────────────
  1356.      '<name>' possibly used before definition
  1357.  
  1358.                You will recall that 'auto' and 'register' objects which are
  1359.                not  the arguments  of functions have  undefined values (for
  1360.                this  read 'whatever was on the  stack before the call'). If
  1361.                you  refer to the value of such  an object before a value is
  1362.                assigned to it you are guaranteed to get junk. Sometimes the
  1363.                message may be inappropriate, as in:
  1364.  
  1365.                     struct x {
  1366.                          struct x *next;
  1367.                          ......
  1368.                     } *head, *p, *q;
  1369.  
  1370.      ──>            for (p = head; p; p = q) {
  1371.                          q = p->next;
  1372.                     }
  1373.  
  1374.                This  provokes "'q' possibly used  before definition" at the
  1375.                line  marked with the arrow - but  we can see that 'q' is in
  1376.                fact  assigned before it's  value is required  in the 'for'.
  1377.                Almost  any other occurrence of this bug is a genuine error,
  1378.                and   it  is  worth  clearing  this  non-error  occasion  by
  1379.                initialising 'q' to NULL anyway.
  1380.      ──────────────────────────────────────────────────────────────────────
  1381.      "evaluation order undefined"
  1382.  
  1383.                The standard clearly states that in a statement like:
  1384.  
  1385.                     int a[10], i;
  1386.  
  1387.                     a[i] = ++i;
  1388.  
  1389.                that  the meaning of the  statement is undefined because the
  1390.                compiler   writer  is   free  to   evaluate  the  expression
  1391.                components in any order that is convenient - to the compiler
  1392.                writer!  In cases like  this, he may  decide to evaluate the
  1393.                address  of the  array element  before evaluating  the right
  1394.                hand side - or he may not.
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.                                    Page - 23
  1404.  
  1405.  
  1406.  
  1407.                Similar  problems arise with  any operator which  has a side
  1408.                effect,  and CLint takes some care  to check them all. It is
  1409.                also  careful that when operators  whose evaluation order is
  1410.                defined  by the  standard are  used, ('||',  '&&', '?', ',')
  1411.                that improper complaints don't occur.
  1412.  
  1413.                A  particular  trap with  optimising  compilers is  that the
  1414.                order of evaluation of function arguments is undefined, so:
  1415.  
  1416.                     f(a[i], i++);
  1417.  
  1418.                provokes this complaint too.
  1419.  
  1420.      ──────────────────────────────────────────────────────────────────────
  1421.      ambiguous operators need parentheses
  1422.  
  1423.                This occurs if any of the operators '||', '&&', '|', '&', or
  1424.                '^'  are  adjacent and  different  in an  expression without
  1425.                parentheses round one of them. For example:
  1426.  
  1427.                     if (flag && test1 || test2) ....
  1428.  
  1429.                is true if 'flag && test' or 'test2'. This occurred in CLint
  1430.                itself  - in several places! -  before we fixed it. What was
  1431.                meant was of course:
  1432.  
  1433.                     if (flag && (test1 || test2)) ....
  1434.  
  1435.                This  can cause no end of  grief, because most people forget
  1436.                the relative precedences of these operators.
  1437.  
  1438.      ──────────────────────────────────────────────────────────────────────
  1439.      printf: ....
  1440.  
  1441.                There  are a  series of  possible errors  that can  be given
  1442.                concerning  the use  of 'printf',  'fprintf', and 'sprintf'.
  1443.                All  calls to these library functions are tested argument by
  1444.                argument   against  the  ANSI  standard  for  the  supported
  1445.                conversions.  Each  '%'  conversion is  checked  against the
  1446.                corresponding  argument to be of  the correct type. This can
  1447.                catch  a  surprising number  of  bugs in  apparently working
  1448.                programs.
  1449.  
  1450.                You  can also define  functions of your  own which work like
  1451.                'printf()'. You should then use the -FNname switch to inform
  1452.                CLint  of these functions  so that it can  check your use of
  1453.                these functions.
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.                                    Page - 24
  1465.  
  1466.  
  1467.  
  1468.      ──────────────────────────────────────────────────────────────────────
  1469.      unreachable code
  1470.  
  1471.                This may occur due to any number of logical problems. It can
  1472.                also  be  caused by  providing  a 'return  x'  which Borland
  1473.                compilers  sometimes incorrectly  insists on  at the  end of
  1474.                functions.  In cases where you  know the statement concerned
  1475.                can't be reached, precede the offending statement with:
  1476.  
  1477.                     #pragma notreached
  1478.  
  1479.                which  will  silence  CLint, but  not  unfortunately Borland
  1480.                compilers.
  1481.  
  1482.      ──────────────────────────────────────────────────────────────────────
  1483.      value should be returned
  1484.      both return and return of a value
  1485.  
  1486.                These  are often a hold-over from pre-ANSI C code. You would
  1487.                often write:
  1488.  
  1489.                     func()
  1490.                     {
  1491.                          .....
  1492.                     }
  1493.  
  1494.                where under ANSI you should write:
  1495.  
  1496.                     void func(void)
  1497.                     {
  1498.                          .....
  1499.                     }
  1500.  
  1501.                The second case is more worthy of attention. A number of so-
  1502.                called working programs exhibit this one - it can be a nasty
  1503.                trap.  Often,  the program  will work  - under  a particular
  1504.                compiler  - because the value in the return register left by
  1505.                a  prior expression just happened  to be the value required!
  1506.                You should always fix this.
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.                                    Page - 25
  1526.