File Elements

Although some of the file queries operate on identifier properties, all file queries produce file-list data as their result. Clicking on an element of a file list leads you to a page with a summary of the file.

File: /home/user/src/cscout/example/awk/main.c

Details

  • Read-only: No
  • Used in project(s):
    • awk
  • Other exact copies: (none)

Listings

Include Files

Metrics

MetricValue
Number of characters5155
Number of comment characters1878
Number of space characters754
Number of line comments0
Number of block comments27
Number of lines190
Maximum number of characters in a line107
Number of character strings25
Number of unprocessed lines0
Number of C preprocessor directives9
Number of processed C preprocessor conditionals (ifdef, if, elif)0
Number of defined C preprocessor function-like macros0
Number of defined C preprocessor object-like macros1
Number of preprocessed tokens893
Number of compiled tokens921
Number of copies of the file1
Number of statements123
Number of defined project-scope functions3
Number of defined file-scope (static) functions0
Number of defined project-scope variables13
Number of defined file-scope (static) variables0
Number of complete aggregate (struct/union) declarations0
Number of declared aggregate (struct/union) members0
Number of complete enumeration declarations0
Number of declared enumeration elements0
Number of directly included files8

Main page - Web: Home Manual


CScout
The page contains some representative metrics for the given file, the projects using this file, links for viewing the file's source code, and links for listing include file dependencies.

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

  1. The plain source code, will only provide you the file's code text
  2. The source code with unprocessed regions marked, will enable you to see which parts of the file was not processed due to conditional compilation instructions. You may want to use the marked parts as a guide to construct a more inclusive workspace definition (perhaps by processing the project multiple times, with different preprocessor options).
      360 #if defined(__GNUC__) && defined(__STDC__)
      361 static __inline int __sputc(int _c, FILE *_p) {
      362         if (--_p->_w >= 0 || (_p->_w >= _p->_lbfsize && (char)_c != '\n'))
      363                 return (*_p->_p++ = _c);
      364         else
      365                 return (__swbuf(_c, _p));
      366 }
      367 #else
      368 /*
      369  * This has been tuned to generate reasonable code on the vax using pcc.
      370  */
      371 #define __sputc(c, p) \
      372         (--(p)->_w < 0 ? \
      373                 (p)->_w >= (p)->_lbfsize ? \
      374                         (*(p)->_p = (c)), *(p)->_p != '\n' ? \
      375                                 (int)*(p)->_p++ : \
      376                                 __swbuf('\n', p) : \
      377                         __swbuf((int)(c), p) : \
      378                 (*(p)->_p = (c), (int)*(p)->_p++))
      379 #endif
      380 
  3. 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_statexists)
            struct stat *from_stat;
            int exists;
    {
            if (exists && unlink(to.p_path)) {
                    warn("unlink: %s", to.p_path);
                    return (1);
            }
            if (mkfifo(to.p_pathfrom_stat->st_mode)) {
                    warn("mkfifo: %s", to.p_path);
                    return (1);
            }
            return (pflag ? setfile(from_stat, 0) : 0);
    }

  4. 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);
    }
  5. Source code with hyperlinks to function and macro declarations provides you hyperlinks to the function pages for each function declaration (implicit or explict) and macro definition. Again, here is an example:
    #if !defined(_ANSI_SOURCE) && !defined(_POSIX_SOURCE)
    int     digittoint __P((int));
    int     isascii __P((int));
    int     isblank __P((int));
    int     ishexnumber __P((int));
    int     isideogram __P((int));
    int     isnumber __P((int));
    int     isphonogram __P((int));
    int     isrune __P((int));
    int     isspecial __P((int));
    int     toascii __P((int));
    #endif
    __END_DECLS

    #define __istype(c,f)    (!!__maskrune((c),(f)))

    #define isalnum(c)       __istype((c), _CTYPE_A|_CTYPE_D)
    #define isalpha(c)       __istype((c), _CTYPE_A)
    #define iscntrl(c)       __istype((c), _CTYPE_C)
    #define isdigit(c)       __isctype((c), _CTYPE_D) /* ANSI -- locale independent */
    #define isgraph(c)       __istype((c), _CTYPE_G)
    #define islower(c)       __istype((c), _CTYPE_L)
    #define isprint(c)       __istype((c), _CTYPE_R)
    #define ispunct(c)       __istype((c), _CTYPE_P)
    #define isspace(c)       __istype((c), _CTYPE_S)
    #define isupper(c)       __istype((c), _CTYPE_U)
    #define isxdigit(c)      __isctype((c), _CTYPE_X) /* ANSI -- locale independent */
    #define tolower(c)       __tolower(c)
    #define toupper(c)       __toupper(c)

File Metrics

File metrics produces a summary of the workspace's file-based metrics like the following:

File Metrics

Writable Files

Number of elements: 14

MetricTotalMinMaxAvg
Number of characters16062519234329711473.2
Number of comment characters30314063072165.29
Number of space characters2908129887352077.21
Number of line comments120120.857143
Number of block comments760019054.2857
Number of lines65571001913468.357
Maximum number of characters in a line11022410778.7143
Number of character strings742015453
Number of unprocessed lines12080.857143
Number of C preprocessor directives376010226.8571
Number of processed C preprocessor conditionals (ifdef, if, elif)6030.428571
Number of defined C preprocessor function-like macros300222.14286
Number of defined C preprocessor object-like macros16209211.5714
Number of preprocessed tokens39883354121892848.79
Number of compiled tokens441190140203151.36
Number of copies of the file14111
Number of statements429301589306.643
Number of defined project-scope functions16805112
Number of defined file-scope (static) functions2010.142857
Number of defined project-scope variables14903610.6429
Number of defined file-scope (static) variables191017413.6429
Number of complete aggregate (struct/union) declarations12060.857143
Number of declared aggregate (struct/union) members560324
Number of complete enumeration declarations0000
Number of declared enumeration elements0000
Number of directly included files820205.85714

Read-only Files

Number of elements: 14

MetricTotalMinMaxAvg
Number of characters3973722798762838.36
Number of comment characters2680510756951914.64
Number of space characters280513948200.357
Number of line comments0000
Number of block comments1282609.14286
Number of lines10741327576.7143
Maximum number of characters in a line1025508573.2143
Number of character strings4030.285714
Number of unprocessed lines17051.21429
Number of C preprocessor directives18615813.2857
Number of processed C preprocessor conditionals (ifdef, if, elif)27061.92857
Number of defined C preprocessor function-like macros300132.14286
Number of defined C preprocessor object-like macros860316.14286
Number of preprocessed tokens3107161068221.929
Number of compiled tokens17790602127.071
Number of copies of the file14111
Number of statements0000
Number of defined project-scope functions0000
Number of defined file-scope (static) functions0000
Number of defined project-scope variables6030.428571
Number of defined file-scope (static) variables0000
Number of complete aggregate (struct/union) declarations7030.5
Number of declared aggregate (struct/union) members560234
Number of complete enumeration declarations0000
Number of declared enumeration elements0000
Number of directly included files4010.285714

Main page - Web: Home Manual


CScout

All files

The "All files" link will list all the project's files, including source files, and directly and indirectly included files. You can use this list to create a "bill of materials" for the files your workspace requires to compile. The following is an example of the output:

All Files

You can bookmark this page to save the respective query

Main page


CScout 1.6 - 2003/06/04 15:14:51

Read-only files

The "Read-only files" link will typically show you the system files your project used. The following output was generated using the "Show file lists with file name in context" option.

Read-only Files

DirectoryFile
/usr/include/ ctype.h
/usr/include/ err.h
/usr/include/ errno.h
/usr/include/ fcntl.h
/usr/include/ fts.h
/usr/include/ limits.h
/usr/include/ locale.h
/usr/include/machine/ ansi.h
/usr/include/machine/ endian.h
/usr/include/machine/ limits.h
/usr/include/machine/ param.h
/usr/include/machine/ signal.h
/usr/include/machine/ trap.h
/usr/include/machine/ types.h
/usr/include/machine/ ucontext.h
/usr/include/ runetype.h
/usr/include/ stdio.h
/usr/include/ stdlib.h
/usr/include/ string.h
/usr/include/sys/ _posix.h
/usr/include/sys/ cdefs.h
/usr/include/sys/ inttypes.h
/usr/include/sys/ param.h
/usr/include/sys/ signal.h
/usr/include/sys/ stat.h
/usr/include/sys/ syslimits.h
/usr/include/sys/ time.h
/usr/include/sys/ types.h
/usr/include/sys/ ucontext.h
/usr/include/sys/ unistd.h
/usr/include/ sysexits.h
/usr/include/ syslog.h
/usr/include/ time.h
/usr/include/ unistd.h

You can bookmark this page to save the respective query

Main page - Web: Home Manual


CScout 2.0 - 2004/07/31 12:37:12

Writable files

Correspondingly the "Writable files" link will only show you all your workspace's source files:

Writable Files

You can bookmark this page to save the respective query

Main page


CScout 1.6 - 2003/06/04 15:14:51

Files containing unused project-scoped writable identifiers

The link ``files containing unused project-scoped writable identifiers'' performs an identifier query, but lists as output files containing matching identifiers. Specifically, the link will produce a list of files containing global (project-scoped) unused writable identifiers. Modern compilers can detect unused block-local or even file-local (static) identifiers, but detecting global identifiers is more tricky, since it requires processing of all files that will be linked together. The restriction to writable identifiers will filter-out noise generated through the use of the system's library functions.

In our example, the following list is generated:

Files Containing Unused Project-scoped Writable Identifiers

Matching Files

DirectoryFile
/vol/src/bin/cp/ cp.cmarked source
/vol/src/bin/date/ date.cmarked source

You can bookmark this page to save the respective query

Main page - Web: Home Manual


CScout 2.0 - 2004/07/31 12:37:12
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

The link ``files containing unused file-scoped writable identifiers'' performs an identifier query, but lists as output files containing matching identifiers. Specifically, the link will produce a list of files containing file-scoped (static) unused writable identifiers. Although some modern compilers can detect file-local identifiers, they fail to detect macros and some types of variable declarations. The CScout query is more general and can be more reliable. The restriction to writable identifiers will filter-out noise generated through the use of the system's library functions.

In our example, the following list is generated:

Files Containing Unused File-scoped Writable Identifiers

Matching Files

DirectoryFile
/vol/src/bin/cp/ cp.cmarked source
/vol/src/bin/cp/ utils.cmarked source
/vol/src/bin/date/ date.cmarked source
/vol/src/bin/echo/ echo.cmarked source

You can bookmark this page to save the respective query

Main page - Web: Home Manual


CScout 2.0 - 2004/07/31 12:37:12
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

The ``writable .c files without any statements'' will locate C files that do not contain any C statements. You can use it to locate files that only contain variable definitions, or files that are #ifdef'd out.

In our example, the result set only contains the processing script (the compiled workspace definition file).

Writable .c Files Without Any Statments

You can bookmark this page to save the respective query

Main page


CScout 1.6 - 2003/06/04 15:14:51
The processing script (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 unprocessed lines

The ``writable files containing unprocessed lines'' link will present you C files containing lines that were skipped by the C preprocossor, due to conditional compilation directives. The files are ordered according to the number of unprocessed lines (files with the largest number will appear on the top).

In our case the results are:

Writable Files Containing Unprocessed Lines

DirectoryFileNumber of unprocessed lines
/vol/src/bin/cp/ utils.c30
/home/dds/src/cscout/ cscout_defs.h3
/vol/src/bin/echo/ echo.c2
/vol/src/bin/date/ date.c2
/vol/src/bin/cp/ cp.c2
/home/dds/src/cscout/ cscout_incs.h2

You can bookmark this page to save the respective query

Main page - Web: Home Manual


CScout 2.0 - 2004/07/31 12:37:12
Lines skipped by the C preprocessor can be detrimental to the analysis and the refactoring you perform. If those lines contain live code that will be used under some other circumstances (a different platform, or different configuration options), then any results you obtain may miss important data. The list of files allows you to see if there are any large chunks of code that CScout ignored. If there are, think about specifying additional configuration options as preprocessor variables. If some configuration options are mutually exclusive you can process the same source multiple times, with different preprocessor variables set.

Writable files containing strings

The ``writable files containing strings'' link will present you C files containing C strings. In some applications user-messages are not supposed to be put in the source code, to aid localization efforts. This file query can then help you locate files that contain strings.

In our case the results are:

Writable Files Containing Strings

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

Some coding conventions dictate against recursive #include invocations. This query can be used to find files that break such a guideline. As usual, read-only system files are excluded; these typically use recursive #include invocations as a matter of course.

In our example, the result is:

Writable .h Files With #include directives

You can bookmark this page to save the respective query

Main page


CScout 1.6 - 2003/06/04 15:14:51