Table of Contents

Assignment 1: Warm-Up

Assignment 1: Warm-Up

Due Monday, September 8 2025, 11:59 pm Central Time

Submissions handed in by the due date receive a small on-time bonus.

All students are granted a pre-approved extension or “grace period” of 24 hours after the due date. Late submissions are accepted during the grace period with no penalty.

The grace period expires Tuesday, September 9 2025, 11:59 pm Central Time, after which no further late submissions are accepted (or are even possible).

This project is an individual homework. No group work is allowed.

Introduction

It is not uncommon for students come into this course without basic C software development skills, and invest a great deal of time and frustrating effort in the first two projects before concluding they will not pass the course and must drop. We have created this simple warm-up to determine whether or not students are prepared to work on C programming projects. Most students should find this project to be relatively easy (a few hours of work, mostly understanding the APIs). If you do not find this project to be relatively straight-forward, you may want to reconsider whether or not you are ready to take this course.

Relation to Lectures and Reading

None. This project requires only C programming skills and basic familiarity with command line interfaces and Makefiles that incoming students should already possess. Mastery of the material covered in a class like CSC4103 should be enough to make this project straightforward.

Project Objectives

Ensure students have a working Linux development environment.
Ensure students can code, compile, test and debug simple C programs.
Introduce and demonstrate the ability to use basic POSIX file operations.
Introduce and demonstrate the ability to process command line arguments.
Introduce and demonstrate the ability to catch and handle run-time exceptions.
Introduce and demonstrate the ability to return informative exit status.
Demonstrate the ability to research and exploit non-trivial APIs.
Demonstrate the ability to construct a standard Makefile.
Demonstrate the ability to write software that conforms to a Command Line Interface (CLI) specification.

Deliverables

A single C source module that compiles cleanly (with gcc, with no errors or warnings).
A work/Makefile to build the program (targets: all, check)
Two screen snapshot(s) from a gdb session:
- results/backtrace.png: showing a segfault and associated stack-trace
- results/breakpoint.png: showing a breakpoint and variable inspection
A results/README.md file with identification information, a description of the included files, the smoke-test cases in the check target, and any other information about your submission that you would like to bring to our attention (e.g., research, limitations, features, testing methodology).

Environment Setup

Please refer to this page for a description of how to install a development environment needed to work on the group projects.

Creating your Initial Assignment 1 Clone using Github Classroom

Congratulations, at this point you are ready for working on the assignment!

Over the course of this semester we will rely on Github Classroom to manage assignments. For more information on Github Classroom please see here.

In this course, we will manage assignments in repositories hosted on Github. The moment you accept an assignment on Github Classroom, you will get access to your own repository that is a clone of the original repository containing the starter code. Your clone of this repository is private by default. This means that nobody except yourself and the course staff is able to see it.

You are responsible to keep the visibility of the repository and its content private. If you change your repository’s visibility to public or make the content of your repository available to others in any way, then you make yourself vulnerable to allegations of plagiarism - with all related consequences.

Please be also aware that by accepting an homework assignment you agree on sharing your name and your LSU email address in the context of this course with Github. Please be aware that the work you turn in for this course, along with the respective student identifiers will be submitted to Github for review, for providing feedback, for performance analysis, and for grading purposes.

Here’s what to do next:

Open a browser and navigate to this url.
If asked, select your name from the list
Click the “Accept this assignment” button.

You should see a new page which says “You are ready to go!” The page will provide the link to your assignment 1 repo, e.g., https://github.com/hkaiserteaching/csc7103-fall2025-assignment1-your-name. Click on that link.

You will now see the homepage for your assignment 1 repo.

At this point, you’ve created a clone of the starter repository on Github.

Next, if you are working on your local machine, you’ll want to create a clone of the assignment starter repository on your local machine as well. For that step you need to have all prerequisites for this course installed on your local computer (CMake, Git, Visual Studio Code).

If you click on the blue “Open in Visual Studio Code” now, you should see VSCode open a window on your local machine with the repository cloned. Use this only if you are working based on a local installation of the prerequisites.

If you prefer working fully online using codespaces, follow the instructions here to create a new Github Codespaces instance and attach a fully online version of VSCode to it.

Open the Repository in the Docker Container

The starter repository has been set up in a way that allows to seamlessly run project in an docker environment. For this:

Again, make sure Docker, VSCode, and the VSCode Remote Development Extension Pack are installed
Choose Reopen in Container in VScode. For details refer this tutorial
Wait for the Docker container to be pulled.
After the new VSCode window pops out you are good to go.

Project Description

(if you are not already familiar with them) study the following manual sections:
- POSIX file operations:
  - open
  - creat
  - close
  - dup
  - read
  - write
  - exit
  - signal
- strerror: function that interprets the error codes returned from failed system calls.
- getopt: the framework we will use for argument handling in all projects for this course.
- gdb, and the run, bt, list, print, and break commands in particular: a Linux debugger for C/C++ programs.
You will probably find understanding getopt to be the most difficult part of this project. Feel free to seek out other examples/tutorials for these functions, but make sure you cite those sources in your results/README.md.
Write a program that copies its standard input to its standard output by read-ing from file descriptor 0 (i.e. STDIN_FILENO, until encountering an end of file) and write-ing to file descriptor 1 (i.e. STDOUT_FILENO). If no errors (other than EOF) are encountered, your program should exit with a return code of 0.

Do not use the stream based functions fopen, fclose, fread or fwrite.

Your program executable should be called assignment1, and accept the following (optional) command line arguments (in any combination or order):

--input=filename: use the specified file as standard input (making it the new file descriptor 0). If you are unable to open the specified input file, report the failure (on stderr, file descriptor 2, i.e. STDERR_FILENO) using fprintf, and exit with a return code of 2.
--output=filename: create the specified file and use it as standard output (on stderr, file descriptor 2, i.e. STDERR_FILENO) using fprintf, and exit with a return code of 3.
--segfault: force a segmentation fault (e.g., by calling a subroutine that sets a char* pointer to NULL and then assigns some value through the null pointer). If this argument is specified, do it immediately, and do not copy from stdin to stdout.
--catch: use signal to register a SIGSEGV handler that catches the segmentation fault, logs an error message (on stderr, file descriptor 2) and exit with a return code of 4.

When you print out an error message (e.g., because an open failed), your message should include enough information to enable a user to understand not merely the nature of the problem but its cause, for example:

Which argument caused the problem, e.g., --input
Which file could not be opened, e.g., myfile.txt
The reason it could not be opened, e.g., no such file

Do your argument parsing with getopt_long. This is, for historical reasons, a somewhat convoluted API, but …

It is very similar APIs are used in many other languages and systems.
I want you to gain experience with the very common trial-and-error process of learning how to use a non-trivial API.

If you encounter an unrecognized argument you should print out an error message including a correct usage line, and exit with a return code of 1.

To ensure that operations are performed in the right order when multiple arguments are specified, it is suggested that you

First process all arguments and store the results in variables
Then check which options were specified and carry actions out in the correct order:
1. Do any file redirection
2. Register the signal handler
3. Cause the segfault
4. If no segfault was caused, copy STDIN_FILENO to STDOUT_FILENO until EOF is reported.

It is relatively easy to generate primitive error messages with perror, but if you study the documentation you will see how to get access to the underlying error descriptions, which you could then use with fprintf(stderr, ...) to generate better formatted error messages to the correct file descriptor.

Note that to use the advanced debugging features of gdb you will need to compile your program with the -g option, which adds debugging symbol table information to your program.

The provided work/Makefile supports the following targets:
- (default): builds the assignment1 executable. To maximize compile-time error checking, you should compile your program with the -Wall and -Wextra options. Yopu may want to add those to the Makefile, also add -g to enable debugging.
- check: runs a set of tests onthat check whether or not the program seems to work, supports the required arguments, and properly reports success or failure. You may have to adapt these to check for the error messages you generate. Please include a brief description (in your results/README.md) of what modifications you applied.
- clean: deletes all files created by the Makefile, and return the directory to its original state.
Run your program (with the --segfault argument) under gdb
- Take the fault
- Get a stack backtrace
- Take a screen snapshot (to be included with your submission as results/backtrace.png)
Putting the code that causes the SEGFAULT in a separate subroutine will make the stack trace a little more interesting.
Run your program (with the --segfault argument) under gdb
- Set a break-point at the bad assignment
- Run the program up to the breakpoint
- Inspect the pointer to confirm that it is indeed NULL
- Take a screen snapshot (to be included with your submission)
You will not be able to list lines of code, print data, or set breakpoints in gdb unless your program has been compiled with the -g (debug symbols) switch.

The starter repository contains a file .vscode/launch.json that configures running the assignment1 executable using the built-in gdb debugger. This allows you to launch the executable in gdb from the VSCode debugging pane:

In order to supply command line arguments to the executable while running in gdb, you need to edit the args configuration setting, e.g.,:
    "args": [ 
       "--input", "foo",
       "--output", "bar",
    ],

Summary of exit codes

Exit code	Reason
`0`	copy successful
`1`	unrecognized argument
`2`	unable to open input file
`3`	unable to open output file
`4`	caught and received `SIGSEGV`

Submission

Once you’ve finished everything, you are ready to submit your work. You are submitting your assignment results as commits that have to be pushed to the github repository. The section about staging and committing changes in VSCode gives you a good introduction on how to do this.

We will be using Github Classrom to collect assignments and Moodle to release your scores. We will use Git for version control in the class. If you are new to Git, there are plenty of tutorials online that you can read, e.g., this one.

We will test it on a departmental Linux server. You would be well advised to test all the functionality of your submission on that platform before submitting it.

Please also note, that once you push to your repository, Github will compile and run your code automatically. This will result in a green check mark being added to the home page of your repository, telling you that all tests you added have successfully passed. If you see a red cross instead, then one or more of the tests in your code have failed and you will have to debug your code. Simply commit and push again once you have fixed the problems.

There is also an introduction to Git available that describes the overall concepts and the use of Git from a command line. It also answers some frequently asked questions.

We have a Github tutorial you might want to have a look at as well.

Last but not least, you can have a look at this document if you are interested in knowing more about Github Classroom.

And that’s it! You’re done!