Dict Lab: A Serious Introduction to C

In Part 1, you will have to implement the bulk of the dictionary library in dict.c.

The main function will contain the main loop of your program and should behave like this:

1. Create an empty dictionary
2. Print "> " on the standard output (this is important).
3. Read the command from the user; the first three characters are the command name, then a space, then the arguments, and a newline character \n.
4. If the command is unknown, exit.
5. If end-of-file was read (EOF), destroy the dictionary, print "goodbye." followed by a newline and exit.
6. Otherwise, execute the corresponding command and go back to 2.

To read from the standard input, you will be using the stream reading functions from the standard library, with stream being stdin, a variable defined in <stdio.h>:

• int fgetc(FILE* stream): read one character of the given stream. This returns the constant EOF on end of file.
• char* fgets (char* s, int size, FILE* stream): read in at most one less than size chars from stream and stores them into the buffer pointed to by s. Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer. A terminating null byte (\0) is stored after the last character.

The function fgets is a bit tricky to work with when you want to read a whole line. Indeed, if the line is very long, fgets needs to be called multiple times. A video aside for this lab walks you through implementing a robust “readline” function.

To write to the standard output, you will be using printf(3).

Two new commands should now be made available:

• clr: clear the dictionary. Nothing is printed in return.
• siz: print the current size of the dictionary.

The only difficulty here is that your previous commands had argument(s), while these two have none. Here is an example run:

$ src/dict
> put a:b
> siz
1
> put a:c
> siz
1
> get a
c
> clr
> siz
0
> get a

>

Also, now that dict_destroy is available, your program is expected to call it when finishing treating the input. Consequently, your program should have no memory leaks.

The dictlab is graded as follows:

• Basic: 210 points, basic test on Part 1 and 2
• Part 1: 60 points, comprehensive test on Part 1
• Part 2: 30 points, comprehensive test on Part 2, 6 of which are for lack of memory leaks

This project is evaluated by a test driver. You can run the full driver by typing, at the root of your project, i.e. dictlab:

$ make test

For each test, the driver prints what is the command executed. For instance, the command:

$ ../src/dict < ./traces/short-P1-01.txt

runs ../src/dict and executes the commands found in ./traces/short-P1-01.txt.

The result, for each test, is readily printed; in bracket, there’s a shorthand notation for the result:

• OK: Test passed
• KO: Test failed, your dict printed something unexpected
• TO: Time out, your dict took too long to answer, it’s usually caused by an infinite loop. See Section GDB for more on how to debug time outs.
• MM: Memory problem, your dict made an illegal memory access (or other similar errors, as printed.) Valgrind will list the line in which the problem occurred. See Section Valgrind for more on Valgrind on how to debug memory problems.

$ cat
hello  ← typed by user
hello  ← printed by cat
CTRL-d
$

You should be fairly familiar with GDB at this point, but here are a few tips.

• Run your program with arguments or with a redirection:

  (gdb) r arg1 arg2 < file1
  

  This will run your program with arguments arg1 arg2 and replace the standard input with file1. To silence the output of your program, you can add > /dev/null to that command line.

• Print variables:

  (gdb) p *dict
  $1 = {head = 0x0, size = 0}
  (gdb) p dict->size
  $2 = 0
  

  The command p can print a lot of objects. It is not limited to variables, as you can call functions with arguments:

  (gdb) p (int) strlen ("lorem")
  $3 = 5
  

• Put/delete/list breakpoints:

  (gdb) b main
  Breakpoint 1 at 0x1150: file main.c, line 63.
  (gdb) b main.c:77
  Breakpoint 2 at 0x1276: file main.c, line 77.
  (gdb) d 2
  (gdb) info b
  Num     Type           Disp Enb Address            What
  1       breakpoint     keep y   0x0000000000001150 in main at main.c:63
  

• Continue from a break point:

  Breakpoint 1, main (argc=1, argv=0x7fffffffe078) at main.c:63
  63      int main (int argc, char** argv) {
  (gdb) c
  

  With a numeric argument, c will skip the next crossings:

  (gdb) c 3
  Will ignore next 2 crossings of breakpoint 1.  Continuing.
  

  The command until can be used to continue until a certain line is reached:

  (gdb) until main.c:72
  main (argc=<optimized out>, argv=<optimized out>) at main.c:72
  

• Stepping into/over, finishing a call:

  Breakpoint 5, cmd_del (dict=0x55555555a2f0) at main.c:151
  151       dict_del (dict, del_arg);
  (gdb) s
  dict_del (dic=0x55555555a2f0, key=0x55555555abc0 "x") at dict.c:275
  

  The command s steps into a call.

  Breakpoint 5, cmd_del (dict=0x55555555a2f0) at main.c:151
  151       dict_del (dict, del_arg);
  (gdb) n
  152       free (del_arg);
  

  The command n steps over calls. When in a function, the command finish completes the call, hence s followed by finish is the same as n:

  Breakpoint 5, cmd_del (dict=0x55555555a2f0) at main.c:151
  151       dict_del (dict, del_arg);
  (gdb) s
  dict_del (dic=0x55555555a2f0, key=0x55555555abc0 "x") at dict.c:275
  275       dict_list_t* el = dict_find_elt (dic, key);
  (gdb) finish
  Run till exit from #0  dict_del (dic=0x55555555a2f0, key=0x55555555abc0 "x") at dict.c:275
  cmd_del (dict=0x55555555a2f0) at main.c:152
  152       free (del_arg);
  

• Looking up and down the call stack:

  Breakpoint 5, cmd_del (dict=0x55555555a2f0) at main.c:151
  151       dict_del (dict, del_arg);
  (gdb) s
  dict_del (dic=0x55555555a2f0, key=0x55555555abc0 "x") at dict.c:275
  275       dict_list_t* el = dict_find_elt (dic, key);
  (gdb) bt
  #0  dict_del (dic=0x55555555a2f0, key=0x55555555abc0 "x") at dict.c:275
  #1  0x00005555555559ab in cmd_del (dict=0x55555555a2f0) at main.c:151
  #2  0x0000555555555276 in main (argc=<optimized out>, argv=<optimized out>) at main.c:75
  (gdb) up
  #1  0x00005555555559ab in cmd_del (dict=0x55555555a2f0) at main.c:151
  151       dict_del (dict, del_arg);
  (gdb) down
  #0  dict_del (dic=0x55555555a2f0, key=0x55555555abc0 "x") at dict.c:275
  275       dict_list_t* el = dict_find_elt (dic, key);
  

  In this example, we first step into dict_del, then print the call stack (bt standing for backtrace). Then we move around the call stack using up and down; note that this does not change the current instruction, we are just visiting the call stack.

• History: Use the Up and Down arrow keys to navigate your history, which is persistent across sessions. To search for something you typed recently, hit CTRL-r:

  (gdb) r very long command line carefully crafted < input > output
     ...
  (gdb) CTRL-r and typing "r v"
  (reverse-i-search)`r v': r very long command line carefully crafted < input > output
  

• Graphical interface. That’s right, GDB has a very nice user interface:

  

  To access the interface, type tui enable (tui stands for Text User Interface). In that mode, the arrow keys move up and down the code, while CTRL-p and CTRL-n behave like your usual history keys. If you print things in your program, this will garble the output of GDB; you can either refresh the GDB window by typing CTRL-l, or run your program with > /dev/null (see first GDB tip).

You can run your code with a long trace, but in GDB. You can then stop GDB using CTRL-c, and see where it is stuck:

$ make test
* PART 1
[TO] ../src/dict < /home/zhuang/.../traces/grading-P1-01.txt
CTRL-c
$ gdb src/dict
(gdb) r < /home/zhuang/.../traces/grading-P1-01.txt > /dev/null
  CTRL-c
(gdb) bt