CSCI 4061 Lab07: nftw()

Due: 11:59pm Mon 3/15/2021 on Gradescope
Approximately 1.00% of total grade

CODE DISTRIBUTION: lab07-code.zip

Download the code distribution
See further setup instructions below

CHANGELOG: Empty

1. Rationale
2. Codepack
3. Higher-order Functions in C Programs
4. QUESTIONS.txt File Contents
5. Submission

1 Rationale

This Lab focuses on a useful function called nftw() which greatly simplifies the otherwise tedious task of traversing an entire subdirectory to perform operations on files within it. It also provides a good example of "higher-order" functions which take as functions arguments. The techniques demonstrated here will be employed fairly directly in an upcoming project.

Grading Policy

Credit for this Lab is earned by completing the exercises here and submitting a Zip of the work to Gradescope. Students are responsible to check that the results produced locally via make test are reflected on Gradescope after submitting their completed Zip. Successful completion earns 1 Engagement Point.

Lab Exercises are open resource/open collaboration and students are encouraged to coopearte on labs. Students may submit work as groups of up to 5 to Gradescope: one person submits then adds the names of their group members to the submission.

See the full policies in the course syllabus.

2 Codepack

The codepack for this lab is linked at the top of this document. Always download it and unzip/unpack it. It should contain the following files which are briefly described.

File	Use	Description
`QUESTIONS.txt`	EDIT	Questions to answer: fill in the multiple choice selections in this file.
`nftw_ls.c`	Study	C file to study to help answer QUIZ questions
`qsort_demo.c`	Study	C file to study to help complete the CODE lab portion
`nftw_listsize.c`	EDIT	C file to complete for CODE portion
`QUESTIONS.txt.bk`	Backup	Backup copy of the original file to help revert if needed
`Makefile`	Build	Enables `make test` and `make zip`
`testy`	Testing	Test running scripts
`test_lab07.org`	Testing	Tests for this lab

3 Higher-order Functions in C Programs

While C is oriented towards low-level programming, it does allow for some "higher-order" features, notably passing functions as arguments to other functions. So-called "higher-order functions" feature more prominently in functional programming languages like Lisp and OCaml but due to their usefulness are supported in C as well.

Higher-order functions appear in certain library interfaces and several are present in the current lab for two functions:

nftw() which takes a function argument to call on all files in a directory hierarchy.
qsort() which takes a "comparator" function to compare elements in an array; this function is used to dictate the order the elements will be sorted.

There are demos and examples of how these work in the lab files which should be studied. The same demo files appear in the current HW.

For more information on higher-order functions making use of "function poitners" in C, consult the following tutorial: https://www-users.cs.umn.edu/~kauffman/2021/function-pointers.html

4 QUESTIONS.txt File Contents

Below are the contents of the QUESTIONS.txt file for the lab. Follow the instructions in it to complete the QUIZ and CODE questions for the lab.

                           __________________

                            LAB 07 QUESTIONS
                           __________________





Lab Instructions
================

  Follow the instructions below to experiment with topics related to
  this lab.
  - For sections marked QUIZ, fill in an (X) for the appropriate
    response in this file. Use the command `make test-quiz' to see if
    all of your answers are correct.
  - For sections marked CODE, complete the code indicated. Use the
    command `make test-code' to check if your code is complete.
  - DO NOT CHANGE any parts of this file except the QUIZ sections as it
    may interfere with the tests otherwise.
  - If your `QUESTIONS.txt' file seems corrupted, restore it by copying
    over the `QUESTIONS.txt.bk' backup file.
  - When you complete the exercises, check your answers with `make test'
    and if all is well, create a zip file with `make zip' and upload it
    to Gradescope. Ensure that the Autograder there reflects your local
    results.
  - IF YOU WORK IN A GROUP only one member needs to submit and then add
    the names of their group.


QUIZ Questions nftw() function
==============================

  Analyze the `nftw_ls.c' program. A similar program is the focus of a
  HW problem. Compile and run it via
  ,----
  | > make nftw_ls
  | ...
  | > ./nftw_ls subdir-small
  `----

  Answer the following questions about the use of the `nftw()' function.


Acroynym
~~~~~~~~

  According to the manual page for the function, the "ftw" part of the
  name `nftw()' stands for
  - ( ) From Top down
  - ( ) Full Traversal Width
  - ( ) File Tree Walk
  - ( ) Far Too Wacky


Arguments
~~~~~~~~~

  `nftw()' takes 4 arguments, the most interesting being argument
  #2. This argument is...
  - ( ) The name of a file at which to begin the traversal
  - ( ) A function to call on each file that is visited during the
    recursive directory traversal
  - ( ) A `struct statbuf' which has information on an open file
  - ( ) The maximum number of file descriptors to keep open while
    traversing the directory tree


Stat Calls
~~~~~~~~~~

  Which of the following best describes the usage of `stat()' during
  calls to `nftw()'
  - ( ) On visiting a file, `nftw()' will already have created a `struct
      statbuf' for each file which is passed via a pointer to its
      parameter function
  - ( ) The parameter function should include code that calls `stat()'
    on each file if stats are required on the files
  - ( ) The parameter function must call `stat()' and set one parameter
    to the results via a deref-set for each file; otherwise `nftw()'
    will fail
  - ( ) It is illegal to call `stat()' during `nftw()' and one cannot
    get file statistics during the directory traversal, a major drawback
    of the function.


CODE Complete nftw_listsize.c
=============================

  An incomplete file called `nftw_listsize.c' is present in the code
  pack which is intended to recursively list all files in a given
  subdirectory but list them by size from smallest to largest.

  A skeleton is provided but a number of TODO/??? items must be filled
  into to complete the program. An example of correct output is below.

  ,----
  | > make                          # compile
  | gcc -Wall -Werror -g  -o nftw_listsize nftw_listsize.c
  | 
  | > ./nftw_listsize subdir-small  # list directory files smallest to largest
  |        2 subdir-small/file_7.txt
  |        2 subdir-small/file_6.txt
  |        2 subdir-small/file_4.txt
  |        2 subdir-small/file_5.txt
  |        2 subdir-small/file_1.txt
  |        2 subdir-small/file_2.txt
  |        4 subdir-small/dir_1/file_13.txt
  |        4 subdir-small/dir_1/file_11.txt
  |        6 subdir-small/dir_3/file_33.txt
  |        6 subdir-small/dir_3/file_34.txt
  |        6 subdir-small/dir_3/file_32.txt
  |        6 subdir-small/dir_3/file_31.txt
  |        8 subdir-small/dir_4/file_41.txt
  |        8 subdir-small/dir_4/file_43.txt
  |        8 subdir-small/dir_4/file_44.txt
  |        8 subdir-small/dir_4/file_42.txt
  |       17 subdir-small/dir_3/file_35.txt
  |       29 subdir-small/file_3.txt
  |       51 subdir-small/dir_1/file_12.txt
  `----

  Study this file and draw from the examples provided in the demo
  program `nftw_ls.c' to complete it.  The demo program is similar to a
  code that is studied in HW07 which has more details of its
  behavior. Additionally, a call to `qsort()' is required so study the
  `qsort_demo.c' program to get a sense of how to use it.

  On completing the code in `nftw_listsize.c' use `make test-code' to
  ensure it functions correctly.

5 Submission

Follow the instructions at the end of Lab01 if you need a refresher on how to upload your completed lab zip to Gradescope.