CSC 209H: Assignment 2

Weight: 10% of course grade.

Due date: 10:00 p.m. Thursday October 27, 2005.

Introduction

In this assignment you will be asked to write two C programs that manipulate files and directories. You are free to use any standard system library calls available on CDF, but you must check the return value from each function call for errors. Your assignment must compile and run on the CDF system without any unavoidable compiler warnings or errors.

Part 1 - phonem

The success of many companies depend on phone numbers that are easy to remember. There are only a few easily recognizable sequences of digits, so we assign letters to most numbers to permit words to be formed. Many companies find recognizable words or phrases for their phone numbers and publicise this mnemonic in their advertising.

For this assignment, you are write a C program called phonem to help find such mnemonics for given phone numbers. Your program will be run in the following way:

• phonem [-d dictionary] string

Your program will find words in the given dictionary (or in /usr/share/dict/words if no dictionary is given) that match the given string. Only digits 0 through 9 and letters A through Z (upper or lower case) may appear in string. The dictionary is a list of words, one word per line (spaces, hyphens and other punctuation may appear within dictionary words). Your program must accept and correctly process strings of length up to and including 10 characters.

We say a word in the dictionary matches string if the letters in the word correspond (in order) to the contents of string such that

• each letter appearing in string matches the identical letter (ignoring case) in word,
• each 2 in string matches either an A, B or C in word,
• each 3 in string matches either a D, E or F in word,
• each 4 in string matches either a G, H or I in word,
• each 5 in string matches either a J, K or L in word,
• each 6 in string matches either an M, N or O in word,
• each 7 in string matches either a P, Q, R or S in word,
• each 8 in string matches either a T, U or V in word,
• each 9 in string matches either an W, X, Y or Z in word,

If a 0 or 1 appears in string, no word will match string.

Your program should output a list of words from the dictionary, one per line, that match string. You may print this list in any order. If no words match string, your program should not print anything. If any errors are detected (dictionary doesn't exist, string is invalid, etc.), a suitable error message should be printed to stderr.

The return value from your program (the program status reported to the shell) should be 0 on success, or 2 on encountering an unrecoverable error.

Examples

Suppose mydict contains the following lines:

foo
bar
cat
and
dog
cab
car

We might run the following commands:

$ ./phonem -d mydict 227
bar
car
$ ./phonem 227
bar
cap
car

A paint company might be lucky enough to run:

$ ./phonem -d /u/csc209h/fall/pub/linux.words 2279542
acrylic

A condiments company whose phone number is 538-2487 might gain some market share from Heinz if they realized the value of their phone number by running the following:

$ ./phonem -d /usr/share/dict/american-english 5382487
ketchup

Here's another example:

$ ./phonem -d /u/csc209h/fall/pub/linux.words 7333
reed
reef
seed
$ ./phonem 7333
Reed
peed
reed
reef
seed

We can glue words together by calling the command multiple times. For example, we can find a mnemonic for the U of T police by running the following.

$ ./phonem 782 ; echo ""; ./phonem 323

We can also use our program to find that calling the Computer Science Undergraduate Office, 978.6360, from a campus phone is as simple as dialing UNDO-0.

Hints and Clarifications

• Start now! Start trying to accomplish simple tasks in C first before writing the whole program.
• Put the C code for your program in a file named phonem.c. A basic Makefile to help compile your program is available here.
• You will probably use the string library functions (man 3 string). You might also find the isalpha and toupper / tolower families of functions useful.
• On the CDF system, /usr/share/dict/words is huge, containing nearly 700,000 words! A smaller dictionary is available at /u/csc209h/fall/pub/linux.words containing just 45,000 words.
• Use a #define directive to define the default dictionary location. That way, you can test your program using small default dictionaries, and can easily change the default once your program is working.
• Since the dictionary may be large, and we are only interested in matching entire words, it is more efficient to check each word in the dictionary once to see if it matches string. Define a function
  int phonemmatch (char *word, char *string)
  that returns true if word matches string and call it once for each word in the dictionary.
• You must check the return values from each library function call and take appropriate action based on these return values (such as printing an error message, exiting with error, or continuing normally).
• You may find the standard library function perror useful for printing error messages.
• For full marks, your phonem.c program must be well-documented, follow good programming style, and be easily understandable by the marker. You must also provide a short README.phonem text file (probably less than a page) explaining the usage of your program in your own words, and describing your approach and design of your program. Include mention of any interesting features you may have added!

Part 2 - newerthan

Often one may want to know which files in a directory are newer than some particular file. Perhaps we want to know what source files have changed since our last compile. Or we want to find out which log files have changed recently. For this assignment, we will write a simple C program called newerthan to accomplish this task.

Your program should support being run in the following manner:

$ newerthan [-a] [-c | -u] file [directory ...]

If your program is run without any options, it should print a list of regular files in each specified directory with modification time (mtime) strictly later than the modification time of file. If no directory is specified, the current directory should be used.

Your program should also support the following options. Options may be specified in any order, but must appear before file.

• -u: print regular files in each specified directory (or in current directory if no directory is specified) whose access time (atime) is strictly later than the access time of file (the mtime is not examined).
• -c: print regular files in each specified directory (or in current directory if no directory is specified) whose file status change time (ctime) is strictly later than the change time of file (the mtime is not examined).
• -a: also include hidden files (i.e., filenames that start with .).

Only one of -u or -c may be specified. You may assume that any command line argument starting with a - is meant to be an option. If the user specifies a bad option, you should print a short usage message and exit.

Typically, the output of your newerthan program should print one filename per line that matches the conditions appropriate to the command line. If a specified directory does not exist, if the user does not have permission to list it, or if it is not a directory, print a suitable error message.

Examples

Because this program interacts deeply with the system, it's hard to present meaningful examples. But if you were to run newerthan in your a2 directory, you would expect to get results like the following:

$ ./newerthan phonem.c .
./Makefile
./phonem
./README.phonem
./newerthan
./newerthan.c
$ touch .testing
$ ./newerthan newerthan.c
newerthan
$ ./newerthan -a -u newerthan.c
.testing

You may wish to use ls with some of its command line options to confirm the behaviour of your program. You might also want to use the stat system command to check the values of the stat data structure by hand.

Hints and Clarifications

• Start now! Try to get something simple working first before adding extra functionality.
• You will probably find the stat, opendir, readdir and closedir library functions very useful. Their man pages are in sections 2 (for stat) or 3 (for the directory commands) of the manual.
• You must check the return values from each library function call and take appropriate action based on these return values (such as printing an error message, exiting with error, or continuing normally).
• For full marks, your newerthan.c program must be well-documented, follow good programming style, and be easily understandable by the marker. You must also provide a short README.newerthan text file explaining the usage of your program in your own words, and describing your approach and design of your program.
• If the -a option is not specified, you should hide (omit) the hidden files in the directory.
• Only one of -u or -c can be specified.
  • If neither option is specified, compare the mtime of each file.
  • If -u is specified, just compare the atime (don't check the mtime).
  • If -c is specified, just compare the ctime (don't check the mtime).

Learning Objectives

• Basic C programs, arrays, structures, pointers.
• Writing basic C functions.
• File and directory manipulation in a C program.
• The stat library function call.
• Command line argument processing in C.
• Managing large files efficiently in C.
• Variant behaviour of C programs based on option settings.

What to hand in

You will commit to the a2 directory of your CSC209 repository the following files:

• newerthan.c
• phonem.c
• Any additional files needed by newerthan or phonem (header files, etc.)
• Makefile, containing commands to compile newerthan and phonem simply by running make
• README.newerthan, giving usage details for your newerthan program and explaining your algorithm and any other design decisions you made
• README.phonem, giving usage details for your phonem program and explaining your algoithm and any other design decisions you made

You are strongly encouraged to take advantage of the version control system and commit your work frequently so that you can keep track of your progress. Please note that perfectly fine (and even recommended) that you keep any additional files related to this assignment (such as files used for testing) under version control. The markers will simply ignore such files.