Exercise Guidelines

General

In the exercises you have an opportunity to practice basic Operating Systems principles in the framework of the Unix operating system.

All exercises must be submitted! However, you are encouraged to submit in pairs.

Development Environment

Exercises should work in the Linux environment as installed in the college's laboratories. Even if you work at home, you must test and submit your work at your college account.

Exercises should be written in C programming language and compiled using gcc. C++ is not accepted. Your source files must compile with no errors or warnings, with the -Wall switch of the gcc command activated.

The recommended editor is emacs, and a good debugger is ddd.

To make a library (*.a file) from object files (*.o files) use ar(1) and ranlib(1) commands (this is done by the Makefile in the first exercise).

A Makefile should be submitted along with every exercise, except the first one. Running gmake should compile/link only the necessary changed files.

The most important command in the Unix environment is man. Along this document and exercise definitions, every italicised word, as in "see chmod", means that the word exists as a man page - typing "man chmod" will give its usage. When italicised words are followed by a number in parentheses, as in "For the read(2) and write(2) system calls ...", this means that you should type "man 2 write" and "man 2 read" for the desired information.

Files to Submit

The exercises should be submitted on the computer and as hardcopy. The files should be located in your home directory under the directory ~/os/ex# where # is the exercise number (see mkdir, cd).

When submitting an exercise, make sure that all the exercise's file, and only them, are in the proper directory (say ~/os/ex8 for the first exercise). Also make sure that other users can read those files, but giving your group and the world read and execute permissions one these files (see chmod). The submission time will be considered as the latest time and date of changing a file in this directory, so after submitting you may also wish to prevent yourself from write access to it (using 'chmod 555 *', for example).

When two people are submitting one exercise together, make sure that exactly one of them has such a directory that's open for reading. The other partner should either work in a renamed directory, or deprive group and world from read permissions on this directory. This is done so that the bodek will have exactly one place to look for a pair's submission in.

The following files should be submitted:

• A file called README (note, it's README, nor Readme nor readme) with a general description of your exercise and a listing of all the files you submit, and their descriptions. We may ask you to put some more information in this file, so read the exercises' descriptions carefully.
  You have to make sure that the first line in the README file contains only login names of the exercise's authors. For example, if an exercise was written by rogger-rabbit and buggs-bunny then the first line in README looks like this:
  rogger-rabbit, buggs-bunny
  
• You must submit a makefile called Makefile (not makefile!), that should generate all the executables and libraries from the submitted sources using the command gmake.
  The Makefile should work correctly if we copy all the sources and the Makefile to a different directory. Whenever any of the source files is . modifiedand re-links whatever is necessary. , typing gmake re-compiles only the necessary modules,
  
• The source files of the exercise. Make sure the submission directory does not contain any other irrelevant files!

Error Handling and Exit Status

Checking system call return values:

• You should check return values of all the system calls. (One allowed exception is the close(2) system call). If a system call return value is -1 you should print the system's error message (see perror(3)).
• For the read(2) and write(2) system calls you should compare the number of bytes requested to read/write with the number of bytes that were actually read/written. If these values are different then some system error occurred during reading/writing.
• The read(2) system call used for reading from the Internet domain STREAM socket is allowed to return with a number of bytes less than requested. To circumvent this problem you should read from sockets in a loop.

Error handling in library functions:

• You should never exit from within any library routine.
• When an error occurs within a library function (say Func1()) you do the following:

  If the error isn't the system's error:
  issue an informative error message to stderr beginning with the string Func1: and ending with a newline, and return the control to the calling function. The return value should be consistent with the one specified in the exercise's definition: In general, a failure will be denoted by a return value of -1.

  If the error is the system's error:
  print to stderr the corresponding system's error message beginning with the string Func1: and ending with a newline, and return the control to the calling function. The return value should be consistent with the one specified in the exercise's definition.

  The function that called the failed library function should free all the resources it uses and exit immediately with exit-code 1 without any additional error messages.

Error handling in non-library functions, and executable programs exit code:

• When detecting any other (non-library) error your program should print an informative error message to stderr, beginning with the string: "Error: ", and ending with a newline, and exit immediately with exit-code 1 (see exit(2). A program's exit code is also its main() function's return value).
• If no errors have been detected your program should exit with exit-code 0.

Assertions:

• You are encouraged to use the assert(3) function for debugging, and you may leave calls to the assert() function when submitting the exercise.
• Moreover, when preconditions or postconditions of a function are specified in the exercise definition, they must be checked for by assertions in the function's code.
• The exercise will be checked with assertions turned off. Therefore, beware of assertions that change the program's behavior when turned off (as in assert(i++) which changes a variable).
• Do not confuse assertions with parameter checking or exception handling! Assertions check things that must always be true!

Exercise Grading

The source of your program will be carefully read - Make sure your program is readable! Your program may be tested by computer programs as well.

Exercise will be graded by the following categories:

By Documentation and readability we expect professional code - nothing less, especially:

1. Clean and simple design - The design should be submitted with the hardcopy. The design can be hand-written (readable!).
2. Comprehensive Documentation - when it is needed - especially at module (file containing group of related functions) headers and function headers.
3. No clever tricky code.

A bad submission (files are not readable from the appropriate directory, missing files and so forth) costs 5 points. A late submission costs 2 points per day. If you require a postponement for a justified reason, email us and explain why.

Please be aware that the load on the computer increases towards submission dates, and sometimes the computer even crashes as a result. Plan your time, and avoid getting stuck in the last minute.

Appeals on exercise grades must be submitted within two weeks of the date you received them back.
Appeals should be written and given in class. Submitting an appeal will subject the exercise to a second test, which may either raise or lower the grade.