1. Computing

Developing Utility Programs in C

By

Utility programs are short single purpose programs that run from the command line. They may need a configuration file though often they don't and if they do it will be short, most likely in plain text rather than XML.

UNIX was built on the principle of small, often simple tools, that can be combined in many ways to perform often complex tasks.

This tutorial is about writing a typical utility in C, and the downloadable source code includes a fully working utility. I've created a simple utility that counts the lines of code, comments and blank lines in a file. It's meant for .c,.cpp, .h and .hpp files and understands C and C++ comments in the specified file.

This is meant for running on Windows and is compiled using Visual C++ 2010 Express so no C99 source code is used. I'll eventually write the Linux equivalent using gcc. Note I've used the Microsoft safe versions of strncpy etc, these all have _s on the end and usually an extra paramter or two indicating a maximum size. If you are using a different compiler use the original versions eg strncpy not strncpy_s.

Microsoft cleaned up its act big time after they discovered that lots of C code was vulnerable because the original functions didn't prevent writes outside the intended area. They produced these safe functions and I've decided I should use them in my C code from now on as a good example.

What is a Utility Program?

It's just a simple program run from the command line, usually with no database access that does a simple task. It has the following features. (Note this is my definition):

  • Can have command line option arguments usually separated by - or / (use - or / on \Windows, just - on Linux as / is for folders).
  • Uses stdiin, and stdout so Windows pipeline commands !! > and < all work
  • Includes a simple help triggered by no input or -h or --help command line inputs
  • View the source code cutil.c (as a .txt file).

Implementing the line count utility

This counts how many lines of code are in a file, distinguishing between code and comments and counting blank lines as well. This means reading the entire file line by line and seeing if any of the following are found:

  • If it's a blank line, just increment numBlanks.
  • It starts with a C++ comment //. Add 1 to numComments
  • If the "incomment" flag is set does the line contain a C end comment */. if so it clears the flag
  • It starts or contains a C start comment /*. This sets the "incomment" flag

If none of these are true then:

if (incomment)
  numcomments++;
else
  numlines++;

The only possibly issue is if a C++ comment is used inside of a C comment as in

/*
// Will this break?
/*

It shouldn't cause any issues. Whether or not a C++ comment // occurs inside a C comment is irrelevant. That line is a comment and does not affect the incomment flag.

the ProcessFile() function does all of the donkeywork and returns an error code (0=ok) if it all goes ok. Error 1 is can't read the file, error 2 is an error reading the file (possibly because something else has it open) and error 3 is finding a /* inside an existing /* block that hasn't yet been finished.

An improvement here might be to return the Windows error.

At the end it outputs the three numbers, numLines, numComments and numBlanks. That's all it does. Nice and simple, a classic utility program.

To check for blank lines I needed a string trim function and found a nice short one on StackOverflow from Adam Rosenfield, so thank you to Adam and StackOverflow.

Notes: This is fairly simple, and fast but it doesn't completely correctly deal with comments on lines of code. A line like this:

}; // Is this counted as code or comment?

It could be argued that it's either code or a comment, but the way // is only found at the start of a line (that's why trim was needed) means it will only treat this as a line of code, and not be counted as a comment.

I think it should be code, because the number of lines of code is a more important metric than the number of lines of comments. If it counted as both then the total would exceed the number of lines in the file.

  1. About.com
  2. Computing
  3. C / C++ / C#
  4. C Programming
  5. How To Do Things in C
  6. Developing a Utility Program in C

©2014 About.com. All rights reserved.