UC San Diego SearchMenu


Turning in Homework Assignments via Unix Command Line

Turnin is a program which students use to hand in their homework assignments for a class via the Unix command line. The instructor has to make certain preparations for the use of turnin, so do not use it unless instructed by the professor. Turnin works by copying a file into a special directory in the class umbrella. The directory is under the control of the instructor or TA. Assignment deadlines may be enforced.

Turnin works well in situations where students only need to hand in one file per assignment. In more complex situations, for example where students are required to hand in a a set of files or a directory hierarchy, there is an instructor configurable utility called Bundle which acts as a front-end to turnin.

Information for Students

How to use turnin

The usage for turnin is designed to be flexible. The syntax for simple, direct use of turnin is:

turnin [-c courseid] [file]

The courseid is a code (like cs181w) which identifies the course for which the file is being turned in. The courseid can easily be determined using the allocations command.


This will report the course allocations associated with your account. OCE accounts typically will have more than one course allocation, but it should be easy to pick out the courseids for each class. The courseid used for the turnin command is the same courseid that you would use when doing the prep command for an OCE compatible class. In fact, if you have done a prep command and you do not specify a courseid to turnin, turnin will ask you if the prep'd class is the one to which you want to submit your homework file.


It is not possible to submit a set of homework files by running turnin once for each file. Each successive run of turnin overwrites what was previously turned in. This can be useful if you turnin an assignment and later wish to replace that submission with something better.

The recommended approach to submitting multiple files or directories involves using the "bundle" mechanism described in the online help bundle articles. Bundle requires additional setup by the instructor. Another alternative is to use the tar command in conjunction with turnin. This requires less setup by the instructor, but is more complex for students. The use of tar in conjunction with turnin is demonstrated in one of the examples below.

Example 1: Using turnin after having done prep for the class

Usage: turnin file
Example: turnin hwk1.c

When you do prep for an OCE compatible class, one of the side-effects is that the courseid is stored in the shell environment variable PREPLABEL. Turnin is clever enoungh to take advantage of that, so if you have done prep for the class, you can run turnin without specifying the courseid. You simply identify the file you want to turnin as shown in the example above.

Example 2: Specifying the Course ID

Usage: turnin -c courseid file
Example: turnin -c cs161f hwk1.c

You can explicitly specify a Course ID by using the -c option. This method can be used regardless of whether you have run the prep command. It is appropriate for classes which are not on the OCE model.

Example 3: Using tar with turnin to handle multiple files

As mentioned above, if the material to be turned in for an assignment consists of multiple files or directories the recommended approach is to use the "bundle" mechanism (which must be set-up by the instructor). Another alternative is to use tar in conjunction with turnin. In this case tar packages the files and directories into a single file called a tar archive which turnin can handle.

Usage: tar-command | turnin -c courseid
Example: tar cvf - hw1.dir | turnin -c cs163w

In this example hw1.dir is a directory that contains multiple files and possibly sub-directories. Tar packages the whole hw1.dir directory hierarchy into a archive and that archive is passed via a Unix pipe to turnin. Notice that when turnin receives its input in this way (via stdin in Unix parlance) the courseid MUST be specified using the -c option. That is because turnin is prevented from asking the user to confirm a courseid determined from the prep PREPLABEL setting.

For more information about the tar program see "man tar".

Again, if the user has already turned in a file and is attempting to do so again, turnin will verify with the user that s/he wishes to overwrite the previous turnin (unless turnin is being run non-interactively -- as in the last example -- in which case the overwrite is automatic). In other words, turnin will accept only one file at a time and all subsequent turnins will overwrite previous ones. This is why "tar" is required for multi-file turnins.

Information for instructors and TAs

Setting up turnin for a class

There are two steps which are explained in further detail below.

  1. Create the destination directory to receive the homework assignments.
  2. IMPORTANT- Ensure the instructor's account has adequate disk space.

    The disk space quota for the instructor's account must be sufficiently large to accomodate ALL of the turned-in files. When turned in, the resulting files will be owned by the instructor account. Therefore, they will count against the quota for that account. If you have questions about quotas or need to request additional space, please see this page.

Creating the destination directory

In order to allow your students to use the "turnin" program to hand in homework assignments, you will need to create the destination directory. This directory should be called "turnin.dest" and must exist in the class directory umbrella, and must be owned by the instructor's account (not a TA account). To create the directory, you should log into the instructor's account and issue the following commands:

cd ~/..
mkdir turnin.dest
chmod o-rwx turnin.dest

The first command puts you at the root level of the umbrella. The second creates the turnin.dest directory. Finally, the third command ensures that the directory is not accessible by anyone except the instructor and the TA accounts. This prevents students from accessing files turned in by other students. Again, the turnin.dest directory must be owned and writeable by the instructor's account. The ownership and permissions are verified by the turnin program.

Once the directory has been created, students may begin to use the "turnin" program to hand in assignments. The material submitted by each student will be placed in a file in turnin.dest. The file is named after the student's account.

As described in the information for students, turnin only stores one file per student. It is recommended that instructors setup the "bundle" mechanism in cases where a multifile capability is required. Alternatively, but with more complexity for students, they can use tar to create a tar archive and submit that with turnin.

Tar archives submitted by students may be examined using the "tv" options:

tar tvf jsmith

Before unpacking a tar archive it probably would be wise to create an empty directory and unpack the archive there to avoid name conflicts with files from other students.

mkdir from.jsmith
mv jsmith from.jsmith
cd from.jsmith
tar xvf jsmith

The sequence shown above creates a new directory "from.jsmith"; moves the "jsmith" tar archive into the new directory; does a change directory (cd) to the new directory; unpacks the archive (actually extracts copies of the contents leaving the archive intact).

Enforcing deadlines

Some classes require that an assignment be handed in by a specific time after which homework is not accepted. The deadline can be rigidly enforced by simply renaming the turnin.dest directory to something else at the deadline. Since "turnin" won't be able to find the turnin.dest directory, files cannot be handed in.

To rename the directory to, say, "hwk1-files", use the "mv" command as follows:

cd ~/..
mv turnin.dest hwk1-files

The directory will be renamed to "hwk1-files" and students will be unable to turn in assignments.

If it is inconvenient to be logged on at the time of the deadline, use of the "at" command can allow you to rename the directory at the specified time even if you are not around to do it. Here's an example.

Let's say the deadline is Friday, January 25, at 9:00pm. You can use the "at" command to rename the turnin.dest directory to something else at exactly that moment.

cd ~/..
at 9pm jan 25

"at" will then prompt for the commands to be executed until you press CTRL-D. So, to rename the directory, continue by typing

mv turnin.dest hkw4-files

This will set up a job that will be run at exactly 9:00pm on January 25 to rename the turnin.dest directory. See man at for more information about the format and usage of the "at" command.

An alternative to enforcing a rigid deadline by changing the directory name is simply to look at the timestamp on the turned-in file. If the date on the file is prior to the dealine, then the user was able to turn in their assignment before the deadline. It is not possible for the student to change the date on the turnin file.

Turnin command line options (and running silently)

Turnin command line options (and running silently)

-c courseid
Specify the identifier (e.g. ec170f) for the course to which the assignment is being turned in.

The following two options are designed to support the "bundle" utility; they are not intended for direct use by students. The bundle Perl script illustrates how these options are employed.

Run in query-only mode. No file is turned in. Query-mode reports parameters that the instructor may have configured for a project. Parameters include: start date and end date defining the period during which turnin is allowed, limit on maximum size of turned in file.

See "man turnin" for details about the format of project configuration files.

-p projectid
Specify a two character project identifier.

If the student already has a file in the turnin.dest directory, turnin normally will ask the student to confirm before overwriting the previously turned in file. If turnin is reading the assignment file from a pipe, then the request for confirmation is suppressed. This can be used to advantage in scripted applications of turnin where you do not want the student to be asked questions.

cat homework2 | turnin -c ec170f

If you also want to suppress turnin messages, use:

cat homework2 | turnin -c ec170f > /dev/null

Resolving problems

While the error messages returned by turnin are generally descriptive enough to figure out what went wrong, some may need some further expanation. IMMEDIATELY after running turnin, type

echo $status

and match the number printed with the number in the left column here.

These error messages are numbered in chronological order -- that is, error 22 will occur later than error 21 would have. This may be useful for determining how far into the program the user got before it crashed.

Additionally, the error codes are grouped by severity: 0-19 represent general usage errors; 20-49 represent errors which likely point to incorrect "turnin" setup; and those above 50 represent internal errors which should be reported to ACMS.

No error -- normal program exit status.
Error in usage. Make sure user is using the correct command line arguments.
No courseid was specified, nor was one available via PREPLABEL variable. Use the -c option to specify a courseid.
Unknown project name supplied on command line. Confirm that a valid project name was given.
If the "REQUIREPROJECTCONFIG" option has been set within the master CONFIG file, confirm that a CONFIG.<projname> file exists which corresponds to the supplied project name.
Turnin for this project (or for all projects) has been disabled via a CONFIG option. Check with your professor or TA.
User attempted to turn in a file larger than the MAXFILESIZE as configured in CONFIG and/or CONFIG.<projname>.
getpwnam(courseid) failed. Courseid was not found in the passwd file. You should verify that the supplied courseid is correct. Contact ACMS if you can't resolve the problem.
UID for courseid less than 500. This should not happen when a valid courseid is supplied. Contact ACMS if the problem persists.
Couldn't start the turnin.dest directory. Directory probably doesn't exist. This could happen if the user tries to submit a file after the deadline when, perhaps, the turnin.dest directory name has been changed to prevent further turnins.
Turnin.dest directory is not owned by courseid. Make sure the directory is owned by the instructor's account, not a TA's account.
Turnin.dest is not writable by courseid. Permissions on turnin.dest should be 770 (ie, fully accessible to instructor and TA, and not accessible to student).
Illegal project name supplied with "-p" option. Project names are limited to 10 characters from the set: A-Z, a-z, 0-9, and "-".
STDIN a TTY, yet no source filename supplied. Specify a filename on the turnin command line or use shell redirection. See the turnin documentation for more detailed instructions.
Unable to stat() the source file. Probably due to an invalid filename supplied on the command line.
Unable to open() the source file. File is probably unreadable by the calling user. See the message returned by perror() to determine the exact nature of the error.
Unable to open the destination file. Probably insufficient disk space or the course account has exceeded its quota. See the message returned by perror() to determine the exact nature of the error. Make sure the instructor's account has ample disk space for the turned-in files.
An error occurred trying to write the destination file. Probably a) exceeded quota, b) insufficient disk space. See the message returned by perror() to determine the exact nature of the error. Make sure the instructor's account has ample disk space for the turned-in files.
A syntax error was discovered in the master CONFIG file. The instructor or TA should check the reported filename/ line number and correct any errors.
A syntax error was discovered in the CONFIG.<projname> file. The instructor or TA should check the reported filename/ line number and correct any errors.
Failed in attempt to seteuid to root (uid 0). This can happen if the program is not setuid root. Contact ACMS.
Failed in attempt to setegid to course GID. This can happen if the program is not setuid root. Contact ACMS.
Failed in attempt to seteuid to course UID. This can happen if the program is not setuid root. Contact ACMS.
Failed in attempt to setegid to caller's GID. This can happen if the program is not setuid root. Contact ACMS.
Failed in attempt to seteuid to caller's UID. This can happen if the program is not setuid root. Contact ACMS.
An error occurred trying to read the source file. See the message returned by perror() to determine the exact nature of the error. Contact ACMS if source of the error isn't evident.
Umbrella directory name does not match courseid. Contact ACMS.
Failed in attempt to seteuid to callerid. This can happen if the program is not setuid root. Contact ACMS.</dd></dl>