CScout Documentation

Introduction

CScout has already been applied on

• Projects of tens of thousands of lines, like the apache web server (using 36MB of memory, taking 6 minutes on a 500MHz Celeron processor).
• Projects above a million lines of code, like the FreeBSD kernel (using 813MB of memory, taking 3 hours 42 minutes on a 900MHz Itanium 2 processor).
• The complete one true awk source code (6600 lines - including a yacc grammar), without modifying a single byte of the source code.

CScout as a source code analyzer can:

• annotate source code with hyperlinks to each identifier
• list files that would be affected by changing a specific identifier
• determine whether a given identifier belongs to the application or to an external library based on the accessibility and location of the header files that declare or define it
• locate unused identifiers taking into account inter-project dependencies
• perform queries for identifiers based on their namespace, scope, reachability, and regular expressions of their name and the filename(s) they are found in,
• perform queries for files, based on their metrics, or properties of the identifiers they contain
• monitor and report superfluously included header files
• provide accurate metrics on identifiers and files

More importantly, CScout helps you in refactoring code by identifying dead objects to remove, and can automatically perform accurate global rename identifier refactorings. CScout will automatically rename identifiers

• taking into account the namespace of each identifier: a renaming of a structure tag, member, or a statement label will not affect variables with the same name
• respecting the scope of the renamed identifier: a rename can affect multiple files, or variables within a single block, exactly matching the semantics the C compiler would enforce
• across multiple projects when the same identifier is defined in common shared include files
• occuring in macro bodies and parts of other identifiers, when these are created through the C preprocessor's token concatenation feature

Walkthrough

• ../bin/cscout awk.c (under Unix), or
• ..\bin\cscout awk.c (under Windows).

For a more structured walkthrough, read on. Consider the following C file, idtest.c

#define getval(x) ((x).val)

struct number {
        int id;
        double val;
} n;

struct character {
        int id;
        char val;
} c;

static int val;

main(int argc, char *argv[])
{
        int val;

        if (argc > 2)
                goto val;
        return getval(n) + getval(c);
        val: return 0;
}

Although, we are dealing with a single file we need to specify its processing within the context of a workspace. In a realistic concept a workspace will specify how numerous projects consisting of multiple files will be processed; think of a workspace as a collection of Makefiles. CScout will operate across the many source files and related executables in the same way as it operates on our example file idtest.c.

A workspace specifies the set of files on which CScout will operate. Each workspace consists of a number of projects; a project is a set rules for linking together C files to form an executable. The workspace definition file is in our case very simple:

workspace example {
	project idtest {
		file idtest.c
	}
}

Our first step will be to transform the declarative workspace definition file into an imperative processing specification that CScout will handle.

prompt> cswc example.csw >example.c

prompt> cscout example.c
Processing workspace example
Processing project idtest
Processing file idtest.c
Done processing file idtest.c
Done processing project idtest
Done processing workspace example
Post-processing our_path/example.c
Post-processing our_path/idtest.c
Processing identifiers
100%
We are now ready to serve you at http://localhost:8081

The primary interface of CScout is Web-based, so once our files have been processed, we fire-up our Web browser and navigate to the CScout's URL. We leave the CScout process running; its job from now on will be to service the pages we request and perform the operations we specify.

Our browser will show us a page like the following:

CScout Home Files File Metrics All files Read-only files Writable files Files containing unused project-scoped writable identifiers Files containing unused file-scoped writable identifiers Writable .c files without any statements Writable files containing strings Writable .h files with #include directives Specify new file query Identifiers Identifier Metrics All identifiers Read-only identifiers Writable identifiers File-spanning writable identifiers Unused project-scoped writable identifiers Unused file-scoped writable identifiers Unused writable macros Specify new identifier query Operations Global options Select active project Exit - saving changes Exit - ignore changes Main page

In our first example we will only rename an identifier, but as is evident from the page's links CScout provides us with many powerfull tools.

By navigating through the links All files, idtest.c, and Source code with identifier hyperlinks we can see the source code with each recognised identifier marked as a hyperlink:

Source Code With Identifier Hyperlinks: your_path/idtest.c (Use the tab key to move to each marked identifier.) #define getval(x) ((x).val) struct number {         int id;         double val; } n; struct character {         int id;         char val; } c; static int val; main(int argc, char *argv[]) {         int val;         if (argc > 2)                 goto val;         return getval(n) + getval(c);         val: return 0; } Main page

Clicking on the first identifier val (in the macro definition) we are taken to a page specifying the identifier's details. There we can specify the identifier's new name, e.g. value.

Identifier: val Read-only: No Tag for struct/union/enum: No Member of struct/union: Yes Label: No Ordinary identifier: No Macro: No Undefined macro: No Macro argument: No File scope: No Project scope: No Typedef: No Crosses file boundary: No Unused: No Matches 3 occurence(s) Appears in project(s): idtest Substitute with: Dependent Files (Writable) your_path/idtest.c - marked source Dependent Files (All) your_path/idtest.c - marked source Main page

Clicking on the marked source hyperlink, CScout will show us again the corresponding source code, but with only the identifiers val matches marked as hyperlinks:

Identifier val: C:\dds\src\Research\cscout\refactor\idtest.c (Use the tab key to move to each marked identifier.) #define getval(x) ((x).val) struct number {         int id;         double val; } n; struct character {         int id;         char val; } c; static int val; main(int argc, char *argv[]) {         int val;         if (argc > 2)                 goto val;         return getval(n) + getval(c);         val: return 0; } Main page

The marked identifiers will be all the ones and the only ones the replacement we specified will affect. Similarly we can specify the replacement of the val label, the static variable, or the local variable; each one will only affect the relevant identifiers.

Selecting the hyperlink Exit - saving changes from the CScout's main page will commit our changes, modifying the file idtest.c.

Installation and setup

System Requirements

• Have an installation of the Perl interpreter
• Contain the include files of the compiler your programs use
• Support a Web browser (text or graphics-based). CScout uses vanilla HTML and has been tested with Netscape, Microsoft Internet Explorer, and Lynx.
• Be able to retrieve Web content from the Internet
  (The free unsupported version of CScout will `phone home' when run on relatively large workspaces, registering the workspace for public browsing, while your CScout is running. Only file list and source-code browsing facilities are provided to the public; source modification, option changes, and the resource-hungry identifier queries are only allowed when accessing CScout from the local host.)

Installation and Configuration

You install CScout in eight steps:

1. Unpack the distribution file on your system.

2. Copy the executable files cscout and cswc (under Unix) or cscout.exe and cswc.bat (under Windows) from the bin directory into a directory that is part of your path. Under Unix /usr/local/bin is a common suitable choice. Under Windows C:\WINNT\system32 is a location you can use, if your system is not better organized.

3. Under Windows adjust the second line of the file cswc.bat to point to the directory you installed it.

4. Copy the directory etc to the final installation place you prefer (renaming it, if you wish), and arrange for the environment variable CSCOUT_HOME to point to it. As an example, under Unix you would probably have the directory installed as /usr/local/etc/cscout. Under Unix, you can permanently set the CSCOUT_HOME environment variable by editing a file named .profile (sh and derivative shells) .login (csh and derivative shells) in your home directory. Under Windows (NT and later), you can set environment variables through an option in: Control Panel - System - Advanced - Environment Variables, on Windows-95/98/Me you will need to edit the file c:\autoexec.bat.

   Alternativelly, the contents of the directory etc will be searched in $HOME/.cscout and the current directory's .cscout directory.

5. Go in the CScout etc directory and copy the file pair cscout_incs.PLATFORM and cscout_defs.PLATFORM (where PLATFORM is the operating system and the compiler that most closely resemble your setup) as cscout_incs.h and cscout_defs.h.

   In most cases you want CScout to process your code using the include files of the compiler you are normally using. This will allow CScout to handle programs using the libraries and facilities available in your environment (e.g. Unix system calls or the Windows API). If your programs are written in ANSI C and do not use any additional include files, you can use the .GENERIC files and rely on the include files supplied with the CScout distribution.

6. If you decided to use the .GENERIC files copy the include directory to an appropriate location (e.g. /usr/local/include/cscout under Unix).

7. Edit the file cscout_incs.h to specify the location where your compiler's (or the generic) include files reside.

8. If the compiler you are using does not match any of the files supplied, start with the .GENERIC file set and add suitable definitions to sidestep the problems caused by the extensions your compiler supports. As an example, if your compiler supports a quad_double type and associated keyword with semantics roughly equivalent to double you would add a line in cscout_incs:

   #define quad_double double
   

   Have a look in the existing cscout_defs files to see what might be required.

Defining workspaces

Workspace definition files are line-oriented and organized around C-like blocks. Comments are introduced using the # character. Consider the following simple example:

workspace echo {
	project echo {
		cd "/usr/src/bin/echo"
		file echo.c
	}
}

See how we could expand this for two more programs, all residing in our system's /usr/src/bin directory:

workspace bin {
	cd "/usr/src/bin"
	ro_prefix "/usr/include"
	project cp {
		cd "cp"
		file cp.c utils.c
	}
	project echo {
		cd "echo"
		file echo.c
	}
	project date {
		cd "date"
		file date.c
	}
}

You can see the complete syntax of CScout workspaces in the following BNF grammar.

WORKSPACE:
	workspace NAME { WORKSPACE_ELEMENT ... }

WORKSPACE_ELEMENT:
	SCOPED_COMMAND
	GLOBAL_COMMAND
	cd "PATH"
	PROJECT

SCOPED_COMMAND:
	ipath "PATH"
	define MACRO
	define MACRO VALUE

GLOBAL_COMMAND:
	ro_prefix "PATH"
	readonly "FILENAME"

PROJECT:
	project NAME { PROJECT_ELEMENT ... }

PROJECT_ELEMENT:
	SCOPED_COMMAND
	cd "PATH"
	DIRECTORY
	FILE

DIRECTORY:
	directory PATH  { DIRECTORY_ELEMENT ... }

DIRECTORY_ELEMENT:
	SCOPED_COMMAND
	FILE

FILE:
	file FILENAME ...
	file "FILENAME" { FILESPEC ... }

FILESPEC:
	SCOPED_COMMAND
	cd "PATH"
	readonly

The following workspace definition was used for processing the apache web server and includes most of the features and formulations we discussed.

workspace apache {
	cd "/usr/local/src/apache/src"

	ro_prefix "/usr/local/src/apache/src/include/ap_config"

	# Global project definitions
	define HTTPD_ROOT "/usr/local/apache"
	define SUEXEC_BIN "/usr/local/apache/bin/suexec"
	define SHARED_CORE_DIR "/usr/local/apache/libexec"
	define DEFAULT_PIDLOG "logs/httpd.pid"
	define DEFAULT_SCOREBOARD "logs/httpd.scoreboard"
	define DEFAULT_LOCKFILE "logs/httpd.lock"
	define DEFAULT_XFERLOG "logs/access_log"
	define DEFAULT_ERRORLOG "logs/error_log"
	define TYPES_CONFIG_FILE "conf/mime.types"
	define SERVER_CONFIG_FILE "conf/httpd.conf"
	define ACCESS_CONFIG_FILE "conf/access.conf"
	define RESOURCE_CONFIG_FILE "conf/srm.conf"

	define AUX_CFLAGS
	define LINUX 22 
	define USE_HSREGEX 
	define NO_DL_NEEDED

	# Give project-specific directory and include path properties
	project gen_uri_delims {
		cd "main"
		ipath "../os/unix"
		ipath "../include"
		file gen_uri_delims.c
	}

	# Alternative formulation; specify per-file properties
	project gen_test_char {
		file gen_test_char.c {
			cd "main"
			ipath "../os/unix"
			ipath "../include"
		}
	}

	# httpd executable; specify directory-based properties
	project httpd {
		directory main {
			ipath "../os/unix"
			ipath "../include"
 			file alloc.c buff.c http_config.c http_core.c
			file http_log.c http_main.c http_protocol.c
			file http_request.c http_vhost.c util.c util_date.c
			file util_script.c util_uri.c util_md5.c rfc1413.c
		}
		directory regex {
			ipath "."
			ipath "../os/unix"
			ipath "../include"
			define POSIX_MISTAKE
			file regcomp.c regexec.c regerror.c regfree.c
		}
		directory os/unix {
			ipath "../../os/unix"
			ipath "../../include"
			file os.c os-inline.c
		}
		directory ap {
			ipath "../os/unix"
			ipath "../include"
			file ap_cpystrn.c ap_execve.c ap_fnmatch.c ap_getpass.c 
			file ap_md5c.c ap_signal.c ap_slack.c ap_snprintf.c 
			file ap_sha1.c ap_checkpass.c ap_base64.c ap_ebcdic.c
		}
		directory modules/standard {
			ipath "../../os/unix"
			ipath "../../include"
			file mod_env.c mod_log_config.c mod_mime.c
			file mod_negotiation.c mod_status.c mod_include.c
			file mod_autoindex.c mod_dir.c mod_cgi.c mod_asis.c
			file mod_imap.c mod_actions.c mod_userdir.c
			file mod_alias.c mod_access.c mod_auth.c mod_setenvif.c
		}
		directory . {
			ipath "./os/unix"
			ipath "./include"
			file modules.c buildmark.c
		}
	}
}

Execution

The CScout engine (cscout) requires as an argument a cswc-compiled workspace definition file. It will serially process each project and directory parsing the corresponding files specified in the workspace definition file, and then process once more each one of the files examined to establish the location of the identifiers. Note that the bulk of the work is performed in the first pass. During the first pass CScout may report warnings, errors, and fatal errors. Fatal errors will terminate processing, all other errors may result in an incorrect analysis of the particular code fragment. CScout only checks the code to the extend needed to perform its analysis; CScout will hapily process many illegal constructs.

The following lines illustrate the output of CScout when run on the bin workspace.

Entering directory /usr/src/bin
Processing project cp
Entering directory cp
Processing file cp.c
Done processing file cp.c
Processing file utils.c
Done processing file utils.c
Exiting directory cp
Done processing project cp
Processing project echo
Entering directory echo
Processing file echo.c
Done processing file echo.c
Exiting directory echo
Done processing project echo
Processing project date
Entering directory date
Processing file date.c
Done processing file date.c
Exiting directory date
Done processing project date
Exiting directory /usr/src/bin
Done processing workspace bin
Post-processing /home/dds/src/cscout/cscout_defs.h
Post-processing /home/dds/src/cscout/cscout_incs.h
Post-processing /usr/home/dds/src/cscout/bin.c
Post-processing /usr/include/ctype.h
Post-processing /usr/include/err.h
Post-processing /usr/include/errno.h
Post-processing /usr/include/fcntl.h
Post-processing /usr/include/fts.h
Post-processing /usr/include/limits.h
Post-processing /usr/include/locale.h
Post-processing /usr/include/machine/ansi.h
Post-processing /usr/include/machine/endian.h
Post-processing /usr/include/machine/limits.h
Post-processing /usr/include/machine/param.h
Post-processing /usr/include/machine/signal.h
Post-processing /usr/include/machine/trap.h
Post-processing /usr/include/machine/types.h
Post-processing /usr/include/machine/ucontext.h
Post-processing /usr/include/runetype.h
Post-processing /usr/include/stdio.h
Post-processing /usr/include/stdlib.h
Post-processing /usr/include/string.h
Post-processing /usr/include/sys/_posix.h
Post-processing /usr/include/sys/cdefs.h
Post-processing /usr/include/sys/inttypes.h
Post-processing /usr/include/sys/param.h
Post-processing /usr/include/sys/signal.h
Post-processing /usr/include/sys/stat.h
Post-processing /usr/include/sys/syslimits.h
Post-processing /usr/include/sys/time.h
Post-processing /usr/include/sys/types.h
Post-processing /usr/include/sys/ucontext.h
Post-processing /usr/include/sys/unistd.h
Post-processing /usr/include/sysexits.h
Post-processing /usr/include/syslog.h
Post-processing /usr/include/time.h
Post-processing /usr/include/unistd.h
Post-processing /vol/src/bin/cp/cp.c
Post-processing /vol/src/bin/cp/extern.h
Post-processing /vol/src/bin/cp/utils.c
Post-processing /vol/src/bin/date/date.c
Post-processing /vol/src/bin/date/extern.h
Post-processing /vol/src/bin/date/vary.h
Post-processing /vol/src/bin/echo/echo.c
Processing identifiers
100%
We are now ready to serve you at http://localhost:8081

When CScout processes a large project it will contact our server over the Web to say hello. The unsupported version will also send us the identifier and file metrics of the project it has processed and register your CScout project for public browsing over the Web (the unsupported version is licensed only for use on free open-source software).

Preprocessor invocation

Checking invocation

The -c option is often used in conjunction with the -r option. The -r command-line option instructs CScout to report all superfluously included header files and identifiers that are either unused or wrongly scoped. Although it is easy to recognise when a header file must be included (if you do not follow the specification of the respective API, a compiler's error message will act as a reminder) detecting when an included header is no longer needed is a lot more difficult. Thus, as code changes, entire files are duplicated as source code templates, and functions are moved to different files, header files that were once needed may no longer be required. Their existence can confuse the programmers reading the code (why is this header file included?) and unnecessarily burden the compilation process. CScout can detect such files by keeping track of dependencies across files, and report included files that are not required. The following is an example of CScout's output:

$ cscout -rc awk.cs
Processing workspace awk
Processing project awk
Entering directory awk
Processing file awkgram.y
Done processing file awkgram.y
[...]
Processing file tran.c
Done processing file tran.c
Exiting directory awk
Done processing project awk
Done processing workspace awk
Post-processing /home/dds/src/cscout/example/.cscout/cscout_defs.h
[...]
Post-processing /home/dds/src/cscout/include/time.h
Processing identifiers
100%
/home/dds/src/cscout/example/awk/run.c:84: jexit: unused project scoped writable identifier
[...]
/home/dds/src/cscout/example/awk/awkgram.y:93: LASTTOKEN: unused file scoped writable identifier
/home/dds/src/cscout/example/awk/awk.h:152: CFREE: unused writable macro
[...]
/home/dds/src/cscout/example/awk/tran.c:44: CONVFMT: writable identifier should be made static
/home/dds/src/cscout/example/awk/lib.c:36: file: writable identifier should be made static
[...]
/home/dds/src/cscout/example/awk/lib.c:33: unused included file /home/dds/src/cscout/example/awk/ytab.h
/home/dds/src/cscout/example/awk/main.c:29: unused included file /home/dds/src/cscout/include/ctype.h
/home/dds/src/cscout/example/awk/main.c:35: unused included file /home/dds/src/cscout/example/awk/ytab.h
/home/dds/src/cscout/example/awk/tran.c:32: unused included file /home/dds/src/cscout/example/awk/ytab.h

1. Directly included files
2. Included files that are only indirectly included

/* Main file main.c */
main(int argc
#include "comma.h"
char *argv[])
{
}

/* File comma.h */
,

Recently CScout processed a 190KLOC project that is under active development since 1989. The project consists of 231 files, containing 5249 include directives. Following CScout's analysis 765 include directives from 178 files were removed, without a single problem.

The Web interface

• Files: queries that list files and related properties
• Identifiers: queries that locate identifiers
• Operations: changes to CScout's global context

We will examine CScout's functionality using as an example the bin workspace we presented in the previous section.

File elements

You can view a file's source code in three different forms:

1. The plain source code, will only provide you the file's code text
2. Source code with identifier hyperlinks, will provide you with a page of the file's code text where each identifier is represented as a hyperlink leading to the identifier's page. The following is a representative example.

   int copy_fifo(from_stat, exists)         struct stat *from_stat;         int exists; {         if (exists && unlink(to.p_path)) {                 warn("unlink: %s", to.p_path);                 return (1);         }         if (mkfifo(to.p_path, from_stat->st_mode)) {                 warn("mkfifo: %s", to.p_path);                 return (1);         }         return (pflag ? setfile(from_stat, 0) : 0); }

3. As the above display can be overwhelming, you may prefer to browse the source code with hyperlinks only to project-global writable identifiers, which are typically the most important identifiers. Consider again how the above example would be displayed:

   int copy_fifo(from_stat, exists)         struct stat *from_stat;         int exists; {         if (exists && unlink(to.p_path)) {                 warn("unlink: %s", to.p_path);                 return (1);         }         if (mkfifo(to.p_path, from_stat->st_mode)) {                 warn("mkfifo: %s", to.p_path);                 return (1);         }         return (pflag ? setfile(from_stat, 0) : 0); }

File Metrics

All files

Read-only files

Writable files

Files containing unused project-scoped writable identifiers

In our example, the following list is generated:

Files Containing Unused Project-scoped Writable Identifiers Matching Files /vol/src/bin/date/date.c - marked source You can bookmark this page to save the respective query Main page CScout 1.6 - 2003/06/04 15:14:51

The output contains the path to each file, and a link that will generate the file's source code with the offending identifiers marked as hyperlinks. You can use the ``marked source'' link to inspect the identifiers in the context of their source code; simply follow the link with your browser and press tab to go to each hyperlink. In our example the identifier will appear as follows:

void setthetime(fmt, p, jflag, nflag)         const char *fmt;         register const char *p;         int jflag, nflag; {         register struct tm *lt;         struct timeval tv;         const char *dot, *t;         int century;

(In our case the function setthetime is declared as static, but not defined as such.)

Files containing unused file-scoped writable identifiers

In our example, the following list is generated:

Files Containing Unused File-scoped Writable Identifiers Matching Files /vol/src/bin/cp/cp.c - marked source /vol/src/bin/cp/utils.c - marked source /vol/src/bin/date/date.c - marked source /vol/src/bin/echo/echo.c - marked source You can bookmark this page to save the respective query Main page CScout 1.6 - 2003/06/04 15:14:51

In our case all identifiers located were the copyright and the rcsid identifiers.

#ifndef lint static char const copyright[] = "@(#) Copyright (c) 1989, 1993\n\         The Regents of the University of California.  All rights reserved.\n"; #endif /* not lint */ #ifndef lint #if 0 static char sccsid[] = "@(#)echo.c      8.1 (Berkeley) 5/31/93"; #endif static const char rcsid[] =   "$FreeBSD: src/bin/echo/echo.c,v 1.8.2.1 2001/08/01 02:33:32 obrien Exp $"; #endif /* not lint */

Later on we will explain how an identifier query could have used a regular expression to filter-out the noise generated by these two identifiers.

Writable .c files without any statements

In our example, the result set only contains the compiled workspace definition file.

Writable .c Files Without Any Statments /usr/home/dds/src/cscout/bin.c You can bookmark this page to save the respective query Main page CScout 1.6 - 2003/06/04 15:14:51

The compiled workspace definition file follows the C syntax, but only contains preprocessor directives (mostly CScout-specific #pragma commands) to drive the CScout's source code analysis.

Writable files containing strings

In our case the results are:

Writable Files Containing Strings /home/dds/src/cscout/cscout_defs.h /home/dds/src/cscout/cscout_incs.h /usr/home/dds/src/cscout/bin.c /vol/src/bin/cp/cp.c /vol/src/bin/cp/utils.c /vol/src/bin/date/date.c /vol/src/bin/echo/echo.c You can bookmark this page to save the respective query Main page CScout 1.6 - 2003/06/04 15:14:51

Writable .h files with #include directives

In our example, the result is:

Writable .h Files With #include directives /vol/src/bin/cp/extern.h You can bookmark this page to save the respective query Main page CScout 1.6 - 2003/06/04 15:14:51

Generic file queries

You specify the query through the following form:

File Query Writable Read-only Number of characters ignore==!=<> Comment characters ignore==!=<> Space characters ignore==!=<> Number of line comments ignore==!=<> Number of block comments ignore==!=<> Number of lines ignore==!=<> Length of longest line ignore==!=<> Number of C strings ignore==!=<> Number of defined functions ignore==!=<> Number of preprocessor directives ignore==!=<> Number of directly included files ignore==!=<> Number of C statements ignore==!=<> Match any of the above         Match all of the above File names should match RE Query title    Main page CScout 1.6 - 2003/06/04 15:14:51

You start by specifying whether the file should be writable (i.e. typically part of your application) and/or readable (i.e. typically part of the compiler or system). Next come a series of metrics CScout collects for each file. For each metric (e.g. the number of comments) you can specify an operator ==, !=, < or > and a number to match that metric against. Thus to locate files without any comments you would specify
Number of block comments == 0.

You can request to see files matching any of your specifications (Match any of the above) or to see files matching all your specifications (Match all of the above).

Sometimes you may only want to search in a subset of files; you can then specify a regular expression that filenames should match against (File names should match RE).

Finally, you can also specify a title for your query. The title will then appear on the result document annotating the results, and will also provide you with a sensible name when creating a bookmark to it.

C Namespaces

int i = 3;

foo()
{
        int i = 7;
}

main()
{
        foo();
        printf("%d\n", i);
}

In addition, C also partitions a program's identifiers into four namespaces. Identifiers in one namespace, are also considered different from identifiers in another. The four namespaces are:

1. Tags for a struct/union/enum
2. Members of struct/union (actually a separate namespace is assigned to each struct/union)
3. Labels
4. Ordinary identifiers (termed objects in the C standard)

/* structure tag */
struct id {
        int id;         /* structure member */
};

/* Different structure */
struct id2 {
        char id;        /* structure member */
};

/* ordinary identifier */
id()
{
id:     /* label */
}

Normally when you want to locate or change an identifier name, you only consider identifiers in the same scope and namespace. Sometimes however, a C preprocessor macro can semantically unite identifiers living in different namespaces, so that changes in one of them should be propagated to the others. The most common case involves macros that access structure members.

struct s1 {
        int id;
} a;

struct s2 {
        char id;
} b;

#define getid(x) ((x)->id)

main()
{
        printf("%d %c", getid(a), getid(b));
}

Finally, the C preprocessor's token concatenation feature can result in identifiers that should be treated for substitution purposes in separate parts. Consider the following example:

int xleft, xright;
int ytop, ybottom;

#define coord(a, b) (a ## b)

main()
{
        printf("%d %d %d %d\n",
                coord(x, left),
                coord(x, right),
                coord(y, top),
                coord(y, bottom));
}

Identifier elements

• If the identifier is read-only (i.e. it appears in at least one read-only file)
• The C namespace(s) it appears in (the same identifier can be a member of multiple namespaces)
• Whether the identifier is visible at file or project scope
• Whether the identifier is a typedef (typedef's belong to the ``ordinary identifier'' namespace, but are obviously important, so CScout will tag them as such).
• Whether the identifier crosses a file boundary, i.e. it appears in more than one file
• Whether the identifier is unused i.e. it appears in exactly one location
• The identifier's number of occurences in all the workspace's files
• The projects the identifier appears in
• An option to substitute the identifier's name with a different name

Finally, the identifier's page will list the writable and all files the specific identifier appears in. Clicking on the ``marked source'' hyperlink will display the respective file's source code with only the given identifier marked as a hyperlink. By pressing your browser's tab key you can then see where the given identifier is used. In our example the cp.c source code with the copy_file identifier marked would appear as follows:

case S_IFBLK:                 case S_IFCHR:                         if (Rflag) {                                 if (copy_special(curr->fts_statp, !dne))                                         badcp = rval = 1;                         } else {                                 if (copy_file(curr, dne))                                         badcp = rval = 1;                         }                         break;                 case S_IFIFO:                         if (Rflag) {                                 if (copy_fifo(curr->fts_statp, !dne))                                         badcp = rval = 1;                         } else {                                 if (copy_file(curr, dne))                                         badcp = rval = 1;                         }                         break;                 default:                         if (copy_file(curr, dne))                                 badcp = rval = 1;                         break;                 }

Identifier Metrics

All identifiers

Read-only identifiers

Writable identifiers

File-spanning writable identifiers

Unused project-scoped writable identifiers

Unused file-scoped writable identifiers

Unused writable macros

Generic identifier queries

• The properties (namespace, scope, instances) of the identifier
• Whether the specified properties should be treated
  • as a disjunction (match any marked),
  • as a conjunction (match all marked),
  • as a negation excluding all identifiers matching any property (exclude marked), or
  • as an exact match specification matching only identifiers that match exactly the properties specified (exact match)
• A regular expression against which identifier names should match (or not match)
• A regular expression that filenames in which identifiers occur should match
• A query title to be used for naming the result page. The title will appear on the result document annotating the results, and will also provide you with a sensible name when creating a bookmark to it.

As an example, the following query could be used to identify unused file-scoped writable identifiers, but excluding the copyright and rcsid identifiers:

Identifier Query Writable Read-only Tag for struct/union/enum Member of struct/union Label Ordinary identifier Macro Undefined macro Macro argument File scope Project scope Typedef Enumeration constant Crosses file boundary Unused Match any marked         Match all marked         Exclude marked         Exact match Identifier names should ( not) match RE Select identifiers from filenames matching RE Query title    Main page CScout 1.16 - 2003/08/17 12:13:01

Options

Remove Common Path Prefix in File Lists

Sort Identifiers Starting from their Last character

Show Only True Identifier Classes

Show Line Numbers in Source Listings

78 fa *makedfa(const char *s, int anchor)  /* returns dfa for reg expr s */    79 {    80         int i, use, nuse;    81         fa *pfa;    82         static int now = 1;    83     84         if (setvec == 0) {      /* first time through any RE */    85                 maxsetvec = MAXLIN;    86                 setvec = (int *) malloc(maxsetvec * sizeof(int));    87                 tmpset = (int *) malloc(maxsetvec * sizeof(int));    88                 if (setvec == 0 || tmpset == 0)    89                         overflo("out of space initializing makedfa");    90         }    91     92         if (compile_time)       /* a constant for sure */    93                 return mkdfa(s, anchor);    94         for (i = 0; i < nfatab; i++)    /* is it there already? */    95                 if (fatab[i]->anchor == anchor    96                   && strcmp((const char *) fatab[i]->restr, s) == 0) {    97                         fatab[i]->use = now++;    98                         return fatab[i];    99                 }   100         pfa = mkdfa(s, anchor);   101         if (nfatab < NFA) {     /* room for another */   102                 fatab[nfatab] = pfa;   103                 fatab[nfatab]->use = now++;   104                 nfatab++;   105                 return pfa;   106         }

Case-insensitive File Name Regular Expression Match

Code Listing Tab Width

Operations

Select active project

Exit - saving changes

Exit - ignore changes

Interfacing with version management systems

As an example, for a file under RCS control the following commands could be used:

cscout_checkout

#!/bin/sh
co -l $1

cscout_checkin

#!/bin/sh
co -m 'CScout identifier name refactoring' -u $1

Language extensions

1. Initialization designators (C99)
2. Compound literals (C99)
3. Declarations can be intermixed with statements (C99).
4. Recognise __atribute__(__unused__) for determining which identifiers should not be reported as unused (gcc).
5. // line comments (common extension)
6. __asm__ blocks (gcc)
7. enum lists ending with a comma (common extension)
8. Anonymous struct/union members (gcc, Microsoft C)
9. Allow case expression ranges (gcc).
10. __typeof keyword (gcc)
11. A compound statement in brackets can be an expression (gcc)
12. Macros expanding from /##/ into // are then treated as a line comment (Microsoft C)
13. #include_next preprocessor directive (gcc)
14. #warning preprocessor directive (gcc)
15. Variable number of arguments preprocessor macros (support for both the gcc and the C99 syntax)
16. Allow empty member declarations in aggregates (gcc)
17. long long type (common extension)
18. A semicolon can appear as a declatation (common extension)
19. An aggregate declaration body can be empty (gcc)
20. Aggregate member initialization using the member: value syntax (gcc)
21. Statement labels do not require a statement following them (gcc)
22. #ident preprocessor directive (gcc)
23. Allow assignment to case expressions (common extension)
24. Accept an empty translation unit (common extension).
25. Support locally declared labels (__label__) (gcc).
26. Dereferencing a function yields a function (common extension).

Processing yacc files

CScout processes yacc files as follows:

• All terminal and non-terminal names are considered to be defined as file-scoped identifiers.
• All terminal symbols are given an integer type, to emulate yacc's y.tab.h macro definitions.
• Members of the %union construct are defined as members of the YYSTYPE union typedef. These are then considered to be accessed in all %type and the precedence specification constructs, as well as the explicit type specification through the $<tag># construct.
• No yacc-specific macros (yyerrok, YYABORT, YYACCEPT, etc) are defined. Feel free to define anything required to silence CScout as a macro in the workspace definition file.
• Keep in mind that yacc creates an incidental extra-linguistic equivalence between the terminal token names declared in the grammar (which are typically #defined in the resulting C file) and the corresponding macro definitions in the y.tab.h file. These are two separate macro definitions that happen to be the same. CScout can not possibly recognise those, so if you change the name of a terminal token in the yacc file you should also change it in a C file where you refer to it.

CScout is designed to process well-formed modern-style yacc files. All rules must be terminated with a semicolon (apparently this is optional in the original yacc version). The accepted grammar appears below.

body:
	defs '%%' rules tail
	;

tail:
	/* Empty */
	| '%%' c_code
	;

defs:
	/* Empty */
	| defs def
	;

def:
	'%start' IDENTIFIER
	| '%union' '{' member_declaration_list  '}' 
	| '%{' c_code '%}'
	| rword name_list_declaration
	;

rword:
	'%token'
	| '%left'
	| '%right'
	| '%nonassoc'
	| '%type'
	;

tag:
	/* Empty: union tag is optional */
	| '<' IDENTIFIER '>'
	;

name_list_declaration:
	tag name_number
	| name_list_declaration opt_comma name_number
	;

opt_comma:
	/* Empty */
	| ','
	;

name_number:
	name
	| name INT_CONST
	;

name:
	IDENTIFIER
	| CHAR_LITERAL
	;

/* rules section */

rules:
	rule
	| rules rule
	;

rule:
	IDENTIFIER ':'  rule_body_list ';'
	;

rule_body_list:
	rule_body
	| rule_body_list '|' rule_body
	;

rule_body:
	id_action_list prec
	;

id_action_list:
	/* Empty */
	| id_action_list name
        | id_action_list '{' c_code '}' 
	;

prec:
	/* Empty */
	| '%prec' name
	| '%prec' name  '{' c_code '}'
	;

variable:
	'$$'
	| '$' INT_CONST
	| '$-' INT_CONST
		{ $$ = basic(b_int); }
	| '$<' IDENTIFIER '>' variable_suffix
		{ $$ = $3; }
	;

variable_suffix:
	'$'
	| INT_CONST
	| '-' INT_CONST
	;

Regular expression syntax

Regular expressions (``REs''), as defined in IEEE Std 1003.2 (``POSIX.2''), come in two forms: modern REs (roughly those of egrep(1); 1003.2 calls these ``extended'' REs) and obsolete REs (roughly those of ed(1); 1003.2 ``basic'' REs). CScout has adopted the use of modern (extended) REs.

A (modern) RE is one= or more non-empty= branches, separated by `|'. It matches anything that matches one of the branches.

A branch is one= or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.

A piece is an atom possibly followed by a single= `*', `+', `?', or bound. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a sequence of 0 or 1 matches of the atom.

A bound is `{' followed by an unsigned decimal integer, possibly followed by `,' possibly followed by another unsigned decimal integer, always fol- lowed by `}'. The integers must lie between 0 and RE_DUP_MAX (255=) inclusive, and if there are two of them, the first may not exceed the second. An atom followed by a bound containing one integer i and no comma matches a sequence of exactly i matches of the atom. An atom fol- lowed by a bound containing one integer i and a comma matches a sequence of i or more matches of the atom. An atom followed by a bound containing two integers i and j matches a sequence of i through j (inclusive) matches of the atom.

An atom is a regular expression enclosed in `()' (matching a match for the regular expression), an empty set of `()' (matching the null string)=, a bracket expression (see below), `.' (matching any single character), `^' (matching the null string at the beginning of a line), `$' (matching the null string at the end of a line), a `\' followed by one of the characters `^.[$()|*+?{\' (matching that character taken as an ordinary character), a `\' followed by any other character= (matching that character taken as an ordinary character, as if the `\' had not been present=), or a single character with no other significance (matching that character). A `{' followed by a character other than a digit is an ordinary character, not the beginning of a bound=. It is illegal to end an RE with `\'.

A bracket expression is a list of characters enclosed in `[]'. It nor- mally matches any single character from the list (but see below). If the list begins with `^', it matches any single character (but see below) not from the rest of the list. If two characters in the list are separated by `-', this is shorthand for the full range of characters between those two (inclusive) in the collating sequence, e.g. `[0-9]' in ASCII matches any decimal digit. It is illegal= for two ranges to share an endpoint, e.g. `a-c-e'. Ranges are very collating-sequence-dependent, and portable programs should avoid relying on them.

To include a literal `]' in the list, make it the first character (fol- lowing a possible `^'). To include a literal `-', make it the first or last character, or the second endpoint of a range. To use a literal `-' as the first endpoint of a range, enclose it in `[.' and `.]' to make it a collating element (see below). With the exception of these and some combinations using `[' (see next paragraphs), all other special charac- ters, including `\', lose their special significance within a bracket expression.

Within a bracket expression, a collating element (a character, a multi- character sequence that collates as if it were a single character, or a collating-sequence name for either) enclosed in `[.' and `.]' stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. A bracket expression containing a multi-character collating element can thus match more than one character, e.g. if the collating sequence includes a `ch' collating element, then the RE `[[.ch.]]*c' matches the first five characters of `chchcc'.

Within a bracket expression, a collating element enclosed in `[=' and `=]' is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing delimiters were `[.' and `.]'.) For example, if `x' and `y' are the members of an equivalence class, then `[[=x=]]', `[[=y=]]', and `[xy]' are all synonymous. An equivalence class may not= be an end- point of a range.

Within a bracket expression, the name of a character class enclosed in `[:' and `:]' stands for the list of all characters belonging to that class. Standard character class names are:

   alnum    digit    punct
   alpha    graph    space
   blank    lower    upper
   cntrl    print    xdigit

There are two special cases= of bracket expressions: the bracket expres- sions `[[:<:]]' and `[[:>:]]' match the null string at the beginning and end of a word respectively. A word is defined as a sequence of word characters which is neither preceded nor followed by word characters. A word character is an alnum character (as defined by ctype(3)) or an underscore. This is an extension, compatible with but not specified by IEEE Std 1003.2 (``POSIX.2''), and should be used with caution in soft- ware intended to be portable to other systems.

In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, it matches the longest. Subexpressions also match the longest possible substrings, subject to the constraint that the whole match be as long as possible, with subexpressions starting earlier in the RE taking priority over ones starting later. Note that higher-level subexpressions thus take priority over their lower-level component subexpressions.

Match lengths are measured in characters, not collating elements. A null string is considered longer than no match at all. For example, `bb*' matches the three middle characters of `abbbc', `(wee|week)(knights|nights)' matches all ten characters of `weeknights', when `(.*).*' is matched against `abc' the parenthesized subexpression matches all three characters, and when `(a*)*' is matched against `bc' both the whole RE and the parenthesized subexpression match the null string.

If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expres- sion containing both cases, e.g. `x' becomes `[xX]'. When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that (e.g.) `[x]' becomes `[xX]' and `[^x]' becomes `[^xX]'.

IDE and Makefile integration

#pragma echo "STRING"

Will display the STRING on CScout's standard output when that part of the file is reached.

Example:

#pragma echo "Processing workspace date\n"

#pragma ro_prefix "STRING"

Will add STRING to the list of filename prefixes that mark read-only files. This is a global setting.

Example:

#pragma ro_prefix "C:\gcc"

#pragma project "STRING"

Will set the current project to STRING. All identifiers and files processed from then on will belong to the given project.

Example:

#pragma project "date"

#pragma block_enter

Will enter a nested scope block. Two blocks are supported, the first block_enter will enter the project scope (linkage unit); the second encountered nested block_enter will enter the file scope (compilation unit).

#pragma block_exit

Will exit a nested scope block. The number of block_enter pragmas should match the number of block_exit pragmas and there should never be more than two block_enter pragmas in effect.

#pragma process "STRING"

Will analyze (CScout's equivalent to compiling) the C source file named STRING.

Example:

#pragma process "date.d"

#pragma pushd "STRING"

Will set the current directory to STRING, saving the previous current directory in a stack. From that point onward, all relative file accesses will start from the given directory.

Example:

#pragma pushd "cp"

#pragma popd

Will restore the current directory to the one in effect before a previously pushed directory. The number of pushd pragmas should match the number of popd pragmas.

#pragma includepath "STRING"

Will add STRING to the list of directories used for searching included files (the include path).

Example:

#pragma includepath "/usr/lib/gcc-lib/i386-redhat-linux/2.96/include"

#pragma clear_includes

Will clear the include path, allowing the specification of a new one.

#pragma clear_defines

Will clear all defined macros allowing the specification of new ones. Should normally be executed before processing a new file. Note that macros can be defined using the normal #define C preprocessor directive.

// workspace bin
#pragma echo "Processing workspace bin\n"
#pragma ro_prefix "/usr/include"
#pragma echo "Entering directory /usr/src/bin"
#pragma pushd "/usr/src/bin"
// project date
#pragma echo "Processing project date\n"
#pragma project "date"
#pragma block_enter
#pragma echo "Entering directory date"
#pragma pushd "date"
// file date.c
#pragma echo "Processing file date.c\n"
#pragma block_enter
#pragma clear_defines
#pragma clear_include
#include "/home/dds/src/cscout/cscout_defs.h"
#include "/home/dds/src/cscout/cscout_incs.h"
#pragma process "date.c"
#pragma block_exit
#pragma echo "Done processing file date.c\n"
#pragma echo "Exiting directory date\n"
#pragma popd
#pragma block_exit
#pragma echo "Done processing project date\n"
#pragma echo "Exiting directory /usr/src/bin\n"
#pragma popd
#pragma echo "Done processing workspace bin\n"

Case Study: Processing the FreeBSD Kernel

1. Configure a LINT or GENERIC version of each architecture's kernel.
   Example: config LINT
2. Go to the compilation directory, update the dependencies (make depend) and compile (make). This step is used to create all automatically generated C and header files. Also during this step note the include path used, in order to provide CScout with the same specification.
3. Remove the generated object files to force a make operation to rebuild them (rm *.o).
4. Replace the C compiler invocation command in the Makefile with an appropriate series of shell commands.

   .include "$S/conf/kern.pre.mk"
   # The code below was added after the line above
   NORMAL_C= echo '\#pragma echo "Processing file ${.IMPSRC}\n"' >>kernel.cs ;\
           echo '\#pragma block_enter' >>kernel.cs ;\
           echo '\#pragma clear_defines' >>kernel.cs ;\
           echo '\#pragma clear_include' >>kernel.cs ;\
           echo '\#include "cscout_defs.h"' >>kernel.cs ;\
           echo '\#pragma includepath "."' >>kernel.cs ;\
           echo '\#pragma includepath "../../.."' >>kernel.cs ;\
           echo '\#pragma includepath "../../../dev"' >>kernel.cs ;\
           echo '\#pragma includepath "../../../contrib/dev/acpica"' >>kernel.cs ;\
           echo '\#pragma includepath "../../../contrib/ipfilter"' >>kernel.cs ;\
           echo '\#pragma includepath "../../../contrib/dev/ath"' >>kernel.cs ;\
           echo '\#pragma includepath "../../../contrib/dev/ath/freebsd"' >>kernel.cs ;\
           echo '\#define _KERNEL 1' >>kernel.cs ;\
           echo '\#pragma process "opt_global.h"' >>kernel.cs ;\
           echo '\#pragma process "${.IMPSRC}"' >>kernel.cs ;\
           echo '\#pragma block_exit' >>kernel.cs ;\
           echo '\#pragma echo "Done processing file ${.IMPSRC}\n"' >>kernel.cs
   

5. Create a cscout_incs.h file for each different architecture.
6. Remove kernel.cs The existing file documents the way to do it.
7. Run make on the custom Makefile
8. Repeat for each different architecture
9. Create a top-level CScout file to process all architectures:

   #pragma echo "Processing workspace FreeBSD kernel\n"
   
   #pragma echo "Entering directory sys/i386/compile/LINT\n"
   #pragma pushd "sys/i386/compile/LINT"
   #pragma echo "Processing project i386\n"
   #pragma project "i386"
   #pragma block_enter
   #include "kernel.cs"
   #pragma echo "Exiting directory sys/i386/compile/LINT\n"
   #pragma popd
   #pragma echo "Done processing project i386\n"
   #pragma block_exit
   
   #pragma echo "Entering directory sys/amd64/compile/GENERIC\n"
   // [...]
   // and so on for all architectures
   // [...]
   #pragma echo "Exiting directory sys/sparc64/compile/LINT\n"
   #pragma popd
   #pragma echo "Done processing project sparc64\n"
   #pragma block_exit
   

   Note that the block_enter and block_exit pragmas are furnished by this top-level file.

CScout Home File Metrics Writable Files Number of files: 4310 File metric Total Min Max Avg Number of characters 62505770 0 1008345 14502 Comment characters 15921752 0 85059 3694 Space characters 7936401 0 73968 1841 Number of line comments 19 0 4 0 Number of block comments 176253 0 4337 40 Number of lines 2063096 0 27336 478 Length of longest line 337049 0 1867 78 Number of C strings 132519 0 19296 30 Number of defined functions 29584 0 333 6 Number of preprocessor directives 267542 0 27336 62 Number of directly included files 35408 0 1608 8 Number of C statements 679825 0 4465 157

Access control

The supported version of CScout supports an access control list. The list is specified in a file called cscout_acl which should be located in $CSCOUT_HOME, $HOME/.cscout, or .cscout in the current directory. The list contains lines with IP numeric addresses prefixed by an A (allow) or D (deny) prefix and a space. Matching is performed by comparing a substring of a machine's IP address against the specified access rule. Thus an entry such as

A 128.135.11.

• If the address matches an allowed entry the machine will be allowed access.
• If no allowed entries have been specified, the machine will be allowed access unless it has been denied access. (i.e. you can not use a deny entry to exclude a machine from an allowed group)

Shortcomings

1. Conditional compilation

   Some programs have parts of them compiled under conditional preprocessor directives. Consider the following example:

   #ifdef unix
   #include <unistd.h>
   #define erase_file(x) unlink(x)
   #endif
   
   #ifdef WIN32
   #include <windows.h>
   #define erase_file(x) DeleteFile(x)
   #endif
   
   main(int argc, char *argv[])
   {
           erase_file(argv[1]);
   }
   

   As humans we can understand that erase_file occurs three times within the file. However, because CScout preprocesses the file following the C preprocessor semantics, it will typically match only two instances. In some cases you can get around this problem by defining macros that will ensure that all code inside conditional directives gets processed. In other cases this will result in errors (e.g. a duplicate macro definition in the above example). In such cases you can include in your workspace the same project multiple times, each time with a different set of defined macros.

   workspace example {
   	project idtest {
   		define DEBUG 1
   		define TEST 1
   		file idtest.c util.c
   	}
   	project idtest2 {
   		define NDEBUG 1
   		define PRODUCTION
   		file idtest.c util.c
   }
   

2. Partial coverage of macro use

   Consider the following example:

   struct s1 {
           int id;
   } a;
   
   struct s2 {
           char id;
   } b;
   
   struct s3 {
           double id;
   } c;
   
   #define getid(x) ((x)->id)
   
   main()
   {
           printf("%d %c", getid(a), getid(b));
   }
   

   In the above example, changing an id instance should also change the other three instances. However, CScout will not associate the member of s3 with the identifier appearing in the getid macro or the s1 or s2 structures, because there is no getid macro invocation to link them together. If e.g. id is replaced with val the program will compile and function correctly, but when one tries to access the c struture's member in the future using getid an error will result.

   struct s1 {
           int val;
   } a;
   
   struct s2 {
           char val;
   } b;
   
   struct s3 {
           double id;
   } c;
   
   #define getid(x) ((x)->val)
   
   main()
   {
           printf("%d %c", getid(a), getid(b));    /* OK */
           printf(" %g", getid(c));                /* New statement: error */
   }
   

   To avoid this (rare) problem you can introduce dummy macro invocations of the form:

   #ifdef CSCOUT
           (void)getid(d)
   #endif
   

3. Undefined macros

   We employ a heuristic classifying all instances of an undefined macro as being the same identifier. Thus in the following sequence foo will match all three macro instances:

   #undef foo
   
   #ifdef foo
   #endif
   
   #ifdef foo
   #endif
   
   #define foo 1
   

   In most cases this is what you want, but there may be cases where the macro appears in different files and with a different meaning. In such cases the undefined instances of the macro will erroneously match the defined instance.

Error messages

Warnings

• #ifdef argument is not an identifier
  The token following a #ifdef directive is not a legal identifier.

• Application of macro " ... ": operator # only valid before macro parameters
  The stringizing operator # was not followed by a macro parameter.

• Assuming declaration int ... (...)
  An undeclared identifier is used as a function.

• Duplicate (different) macro definition of macro ...
  A defined macro can be redefined only if the two definitions are exactly the same.

• Empty character literal
  Character lirerals must include a character.

• Illegal combination of sign specifiers
  The signedness specifiers used can not be combined (e.g. unsigned signed).

• Processing automatically generated file; #line directive ignored.
  A #line directive was found. This signifies that the source file is automatically generated and refactoring changes on that file may be lost in the future. References to the original source file are ignored.

• Sign specification on non-integral type - ignored
  A signedness specification was given on a non-integral type.

• Undeclared identifier in typeof expression: ...
  The identifier appearing within typeof has not been declared.

• Undeclared identifier: ...
  An undeclared identifier was used in a primary expression.

Fatal Errors

• #pragma pushd: unable to get current directory: ...
  The call to getcwd failed while processing the #pragma pushd CScout-specific directive.

• EOF in comment
  The end of file was reached while processing a block comment.

• Error count exceeds 100; exiting ...
  To avoid cascading errors only the first 100 errors are reported.

• Invalid C token: '$'
  A '$' token was encountered in C code. Values starting with a '$' token are only allowed inside yacc rules.

• Unable to get path of file ...
  The Win32 GetfullPathName system call used to retrieve the unique path file name failed (Windows-specific).

• Unable to stat file ...
  The POSIX stat system call used to retrieve the unique file identifier failed (Unix-specific).

Errors

• #pragma echo: string expected
  The #pragma echo CScout-specific directive was not followed by a string.

• #pragma includepath: string expected
  The #pragma includepath CScout-specific directive was not followed by a string.

• #pragma process: string expected
  The #pragma process CScout-specific directive was not followed by a string.

• #pragma project: string expected
  The #pragma project CScout-specific directive was not followed by a string.

• #pragma pushd: string expected
  The #pragma pushd CScout-specific directive was not followed by a string.

• #pragma readonly: string expected
  The #pragma readonly CScout-specific directive was not followed by a string.

• #pragma ro_prefix: string expected
  The #pragma ro_prefix CScout-specific directive was not followed by a string.

• % not followed by yacc keyword
  In the definitions section of a yacc file the % symbol was not followed by a legal yacc keyword.

• %union does not have a member ...
  The member used in a $<name>X yacc construct was not defined as a %union member.

• Application of macro " ... ": operator # at end of macro pattern
  No argument was supplied to the right of the stringizing operator #.

• Array not an abstract type
  The underlying array object for which a type is specified is not an abstract type.

• At most one storage class can be specified
  More than one storage class was given for the same object.

• Conflicting declarations for identifier ...
  An identifier is declared twice with compilation or linkage unit scope with conflicting declarations.

• Declared parameter does not appear in old-style function parameter list: ...
  While processing an old-style (K&R) parameter declaration, a declared parameter did not match any of the parameters appearing in the function's arguments definition.

• Division by zero in #if expression
  A #if expression divided by zero.

• Duplicate definition of identifier ...
  An identifier is declared twice within the same block.

• Duplicate definition of tag ...
  A structure, union, or enumeration tag was defined twice for the same entity.

• EOF while processing #if directive
  The processing of code within a #if block reached the end of file, without a corresponding #endif / #else / #elif directive.

• Empty #include directive
  A #include directive was not followed by a filename specification.

• End of file in character literal
  The end of file was reached while processing a character literal: a single quote was never closed.

• End of file in string literal
  The end of file was reached while processing a string.

• Explicit element tag without no %union in effect
  The yacc $n syntax was used to specify an element of the %union but no union was defined.

• Illegal characters in hex escape sequence
  A hexadecimal character escape sequence \x continued with a non-hexadecimal character.

• Illegal combination of type specifiers
  The type specifiers used can not be combined (e.g. double char).

• Illegal pointer dereference
  An attempt was made to dereference an element that is not a pointer.

• Invalid #include syntax
  A #include directive was not followed by a legal filename specification.

• Invalid application of basic type, storage class, or type specifier
  A basic type, storage class or type specified was specified in an invalid underlying object.

• Invalid character escape sequence
  A character escape sequence \c can not be recognised.

• Invalid macro name
  The macro name specified in a #define or #undef directive is not a valid identifier.

• Invalid macro parameter name
  A macro parameter name specified in a #define directive is not a valid identifier.

• Invalid macro parameter punctuation
  The formal parameters in a #define macro definition are not separated by commas.

• Invalid preprocessor directive
  An invalid preprocessor directive was found. The directive did not match an identifier.

• Invalid type specification
  An attempt was made to specify a type on an object that did not allow this specification.

• Label ... already defined
  The same goto label is defined more than once in a given function.

• Macro [ ... ]: EOF while reading function macro arguments
  The end of file was reached while gathering a macro's arguments.

• Macro [ ... ]: close bracket expected for function-like macro
  The arguments to a function-like macro did not terminate with a closing bracket.

• Member access in incomplete struct/union: ...
  The member access for a structure or union is applied on an object with an incomplete definition.

• Missing close bracket in defined operator
  The identifier of a defined operator was not followed by a closing bracket.

• Modulo division by zero in #if expression
  A #if expression divided by zero in a modulo expression.

• Multiple storage classes in type declaration
  Incompatible storage classes were specified in a single type declaration.

• No identifier following defined operator
  The defined operator was not followed by an identifier.

• Object is not a function
  The object used as a function to be called is not a function or a pointer to a function.

• Only struct/union anonymous elements allowed
  Anonymous members within a member declaring list (e.g. struct {int x, y;}) can only be structures or unions. (GCC/Microsoft C extension).

• Pointer not an abstract type
  The underlying pointer object for which a type is specified is not an abstract type.

• Popd: directory stack empty
  The #pragma popd CScout-specific directive was performed on an empty directory stack.

• Structure or union does not have a member ...
  The structure or union on the left of the . or -> operator does not have as a member the identifier appearing on the operator's right.

• Subscript not on array or pointer
  The object being subscripted using the [] operator is not an array or a pointer.

• Syntax error in preprocessor expression
  A #if or #elif expression was syntactically incorrect.

• Unable to open include file ...
  The specified include file could not be opened.

• Unbalanced #elif
  A #elif directive was found without a corresponding #if.

• Unbalanced #else
  A #else directive was found without a corresponding #if.

• Unbalanced #endif
  A #endif directive was found without a corresponding #if.

• Undefined label ...
  A goto label used within a function was never defined.

• Unexpected end in character escape sequence
  A character escape sequence (\c) was not completed; no character follows the backslash.

• Unknown preprocessor directive: ...
  An unkown preprocessor directive was found.

• Unkown %union element tag ...
  The yacc %union does not have as a member the identifier appearing on the element's tag.

• Yacc $value out of range
  The number used in a $n yacc variable was greater than the number of identifiers and actions on the rule's left side.

License

The free unsupported CScout version is distributed under the CScout Public License. It allows free use of CScout for analyzing and modifying free/Open Source software.

For using CScout on non-free/proprietary software, the CScout supported version and associated license are available. The supported version comes with a normal commercial software license, with none of the special restrictions of this license.

The intent of this license is to establish freedom to use, share, and change the software regulated by this license under the open source model.

This license applies to any software containing a notice placed by the copyright holder saying that it is covered by the terms of the CSCOUT Public License version 1.0. Such software is herein referred to as the Software. This license covers modification and distribution of the Software and the use of the Software for the development and maintenance of free software.

Granted Rights

1. You are granted the non-exclusive rights set forth in this license provided you agree to and comply with any and all conditions in this license. Whole or partial distribution or use of the Software in any form or way signifies acceptance of this license.

2. You may copy and distribute the Software in unmodified form provided that the entire package, including - but not restricted to - copyright, trademark notices and disclaimers, as released by the initial developer of the Software, is distributed under this license.

3. You may make modifications to the Software's source code and distribute your modifications, in a form that is separate from the Software, such as patches. The following restrictions apply to modifications:

a. Modifications must not alter or remove any copyright notices in the Software.

b. When modifications to the Software are released under this license, a non-exclusive royalty-free right is granted to the initial developer of the Software to distribute your modification in future versions of the Software provided such versions remain available under these terms in addition to any other license(s) of the initial developer.

c. The machine-executable (compiled) parts of the Software shall not be modified.

4. You may use the original or modified versions of the Software to analyze and modify application programs, libraries, or other software legally developed by you or by others provided that when these items are distributed in any form you satisfy following requirements:

a. You must ensure that all recipients of machine-executable forms of these items are also able to receive and use the complete machine-readable source code to the items without any charge beyond the costs of data transfer.

b. You must explicitly license all recipients of your items to use and re-distribute original and modified versions of the items in both machine-executable and source code forms. The recipients must be able to do so without any charges whatsoever, and they must be able to re-distribute to anyone they choose.

c. If the items are not available to the general public, and the initial developer of the Software requests a copy of the items, then you must supply one.

5. You acknowledge and accept the fact that the Software may contain technical measures to enforce parts of this license (such as providing the public with a browsable version of the code you are analyzing, and the transmission of workspace-related data) and agree not to interfere with these measures.

Limitations of Liability

In no event shall the initial developers or copyright holders be liable for any damages whatsoever, including - but not restricted to - lost revenue or profits or other direct, indirect, special, incidental or consequential damages, even if they have been advised of the possibility of such damages, except to the extent invariable law, if any, provides otherwise.

No Warranty

THE SOFTWARE AND ITS DOCUMENTATION ARE PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF DESIGN, MERCHANTIBILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

Choice of Law

This license is governed by the Laws of Greece. Disputes shall be settled by the Courts of Athens.

Differences between the unsupported free version and the supported version licence and software

Frequently asked questions

How do I handle conditional compilation?

What details does CScout send when calling its home base?

Seriously, the data sent to our server consists of

• your workspace's file metrics
• your workspace's identifier metrics
• up to 10 project names you have specified
• up to 50 names of cross-file identifiers
• the version of CScout you are running
• your host name
• a random number, part of a simple challenge-response authentication.

How can I save an identifier or file query?

What do I do with automatically generated files?

The cscout command manual page

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLE

# Some small tools from the src/bin directory
workspace bin {
        ro_prefix "/usr/include"
        cd "/usr/src/bin"
        project cp {
                cd "cp"
                file cp.c utils.c
        }
        project echo {
                cd "echo"
                file echo.c
        }
        project date {
                cd "date"
                file date.c
        }
}

$ cswc bin.prj >bin.cs
$ cscout bin.cs
Processing workspace bin
Entering directory /usr/src/bin
Processing project cp
Entering directory cp
Processing file cp.c
Done processing file cp.c
Processing file utils.c
Done processing file utils.c
Exiting directory cp
Done processing project cp
Processing project echo
Entering directory echo
Processing file echo.c
Done processing file echo.c
Exiting directory echo
Done processing project echo
Processing project date
Entering directory date
Processing file date.c
Done processing file date.c
Exiting directory date
Done processing project date
Exiting directory /usr/src/bin
Done processing workspace bin
Post-processing /usr/home/dds/src/cscout/bin.c
[...]
Post-processing /vol/src/bin/cp/cp.c
Post-processing /vol/src/bin/cp/extern.h
Post-processing /vol/src/bin/cp/utils.c
Post-processing /vol/src/bin/date/date.c
Post-processing /vol/src/bin/date/extern.h
Post-processing /vol/src/bin/date/vary.h
Post-processing /vol/src/bin/echo/echo.c
Processing identifiers
100%
We are now ready to serve you at http://localhost:8081

SEE ALSO

AUTHOR

The cswc command manual page

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLE

workspace apache {
    cd "/usr/local/src/apache/src"

   ro_prefix "/usr/local/src/apache/src/include/ap_config"

   # Global project definitions
    define HTTPD_ROOT "/usr/local/apache"
    define SUEXEC_BIN "/usr/local/apache/bin/suexec"
    define SHARED_CORE_DIR "/usr/local/apache/libexec"
    define DEFAULT_PIDLOG "logs/httpd.pid"
    define DEFAULT_SCOREBOARD "logs/httpd.scoreboard"
    define DEFAULT_LOCKFILE "logs/httpd.lock"
    define DEFAULT_XFERLOG "logs/access_log"
    define DEFAULT_ERRORLOG "logs/error_log"
    define TYPES_CONFIG_FILE "conf/mime.types"
    define SERVER_CONFIG_FILE "conf/httpd.conf"
    define ACCESS_CONFIG_FILE "conf/access.conf"
    define RESOURCE_CONFIG_FILE "conf/srm.conf"

   define AUX_CFLAGS
    define LINUX 22
    define USE_HSREGEX
    define NO_DL_NEEDED

   # Give project-specific directory and include path properties
    project gen_uri_delims {
        cd "main"
        ipath "../os/unix"
        ipath "../include"
        file gen_uri_delims.c
    }

   # Alternative formulation; specify per-file properties
    project gen_test_char {
        file gen_test_char.c {
            cd "main"
            ipath "../os/unix"
            ipath "../include"
        }
    }

   # httpd executable; specify directory-based properties
    project httpd {
        directory main {
            ipath "../os/unix"
            ipath "../include"
            file alloc.c buff.c http_config.c http_core.c
            file http_log.c http_main.c http_protocol.c
            file http_request.c http_vhost.c util.c util_date.c
            file util_script.c util_uri.c util_md5.c rfc1413.c
        }
        directory regex {
            ipath "."
            ipath "../os/unix"
            ipath "../include"
            define POSIX_MISTAKE
            file regcomp.c regexec.c regerror.c regfree.c
        }
        directory os/unix {
            ipath "../../os/unix"
            ipath "../../include"
            file os.c os-inline.c
        }
        directory ap {
            ipath "../os/unix"
            ipath "../include"
            file ap_cpystrn.c ap_execve.c ap_fnmatch.c ap_getpass.c
            file ap_md5c.c ap_signal.c ap_slack.c ap_snprintf.c
            file ap_sha1.c ap_checkpass.c ap_base64.c ap_ebcdic.c
        }
        directory modules/standard {
            ipath "../../os/unix"
            ipath "../../include"
            file mod_env.c mod_log_config.c mod_mime.c
            file mod_negotiation.c mod_status.c mod_include.c
            file mod_autoindex.c mod_dir.c mod_cgi.c mod_asis.c
            file mod_imap.c mod_actions.c mod_userdir.c
            file mod_alias.c mod_access.c mod_auth.c mod_setenvif.c
        }
        directory . {
            ipath "./os/unix"
            ipath "./include"
            file modules.c buildmark.c
        }
    }
}

SEE ALSO

AUTHOR

Change history

Version 1.16

• Declarations can be intermixed with statements (C99).
• __typeof can have as its argument an expression and not only an identifier.
• Support for C99 variable number of arguments preprocessor macros.
• Allow case expression ranges (gcc extension).
• Recognise __atribute__(__unused__) for determining which identifiers should not be reported as unused (gcc extension).
• Command-line option to generate a wrongly scoped identifier and unused include file and identifier warning report.
• Separate identifier attribute for enumeration constants. This allows us stop incorrectly categorizing them as having global (compilation unit) visibility.
• Error reporting format is now compatible with gcc.
• Dereferencing a function yields a function (common extension).
• Command-line option to process the file and exit.
• Document processing of the FreeBSD kernel.
• Correct typing of assembly-annotated declarators.
• Fixed assertion failure that could be caused when parts of concatenated identifiers were no longer available (e.g. when processing files with the -m T option.)
• Correct handling of macro parameters that match other macros and are followed by a concatenation operator (they were erroneously replaced).
• Add workaround for gcc __builtin_va_copy in the provided definition files.
• Corrected the handling of main() in the example definition files.

Version 1.15

• Plugged another memory leak. All remaining memory leaks are caused by STL caching and should be of a constant overhead.

Version 1.14

• Support locally declared labels (__label__) (gcc extension).
• Allow statement labels without a following statement (gcc extension).
• Allow assignment to case expressions (common extension)
• Support C99 initialization designators.
• Support aggregate member initialization using the member: value syntax (gcc extension)
• Major memory leak plugged (a missing virtual destructor). Cscout will now consume about 7 times less memory.
• In #if and #elif directives expand macros before processing the defined operator.
• Support the vararg preprocessor macro syntax (gcc extension).
• Allow empty member declarations in aggregates (gcc extension).
• Allow the declaration of empty structures or unions (gcc extension).
• An __asm__ declaration can be used instead of a function's body (gcc).
• Correct typing of the conditional operator's return type when one argument is a pointer and the other NULL.
• New -m option to specify identifiers to track. Enormous memory savings at the expense of unsound operation.
• Display an error when a file does not end with a newline
• Allow yacc %union declaration to end with a ;
• Accept the #ident preprocessor directive (gcc extension)
• Fixed preprocessor bug: multiple expansions of the same function-like macro inside another macro would fail.
• Correctly handle concatenation of empty macro arguments.
• Correctly handle function prototypes inside old-style argument declarations.
• Do not replace strings or characters matching the name of a macro formal argument.
• Accept an empty translation unit (common extension).
• Adding a pointer to an integer now correctly yields a pointer (adding an integer to a pointer already worked correctly)
• Support C99 compound literals.
• Correct typing of compound statements as expressions (gcc extension)
• Improved configuration definition files for the GNU C compiler

Version 1.13

• Handle GNU __asm__ extension with a single operand
• -d options to cswc for specifying configuration directory
• -p command-line option to specify the web server port
• Small corrections in the FreeBSD definition files.
• Intel IA-64 and AMD-64 support

Version 1.12

• New query: writable identifiers that should be made static
• URLs now work on 64-bit architectures
• Improved distribution format
• Sun SPARC-64 support

Version 1.10

• Allow GNU __asm__ statements with a single operand.
• GNU __asm__ statements can also appear at file scope.
• Accept older "name = {action statements}" yacc syntax.
• Can handle untyped yacc specifications.
• Correctly handle struct/union type specifier followed by a type qualifier.
• Small corrections in the supplied definition files.

Version 1.9

• Now distributed with ready-to-run example; the awk source code. No setup required, just unpack the distribution and run.
• Can now also process yacc files
• Fixed syntax error in workspace compiler source code
• Correctly documented -P switch as -E
• Added stdlib.h generic header

Version 1.8

First public release

Last change: Wednesday, August 27, 2003 4:52 pm
(C) Copyright 2000-2003 Diomidis Spinellis. May be freely viewed using web browsers and similar programs. All other rights reserved.