2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 1/8 Assignment 2: cowrie, A Simple Shell version: 1.2 last updated: 2019-11-10 08 00 00 Aims to explore Linux process manipulation system calls to further explore string manipulation in C to further experience data structures in C to build a very simple command-line interpreter to explore writing C code to manipulate processes to give you experience with interprocess communication (pipes) Introduction Your task in this assignment is to write cowrie a simple shell. Shells (e.g. bash) can provide very complex functionality. In this assignment you will implement a small but useful subset of the core functionality typical of a Unix/Linux shell. You will be given a number of simplifying assumptions which make your task easier. Getting Started Create a new directory for this assignment called cowrie, change to this directory, and fetch the provided code by running these commands: $ mkdir cowrie $ cd cowrie $ 1521 fetch cowrie cowrie.c contains code to start the assignment. It will compile and run, but the only functionality implemented is exit: $ dcc cowrie.c -o cowrie $ ./cowrie cowrie> exit $ cowrie.c does contain some functions that make your task much easier. For example, the function tokenizer breaks a string into words, using separators, making your task much simpler. Reference implementation There is a reference implementation available for this assignment which you use to clarify how your implementation should behave: $ 1521 cowrie cowrie> echo hello reference implementation hello reference implementation /bin/echo exit status = 0 cowrie> exit $ Cowrie Commands – Subset 0 – cd/pwd Your next task is to add code to the function execute_command to implement builtin commands cd (change directory) and pwd (print current directory). Your next task is to add code to the function execute_command: 2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 2/8 // // Execute a command, and wait until it finishes. // // * `words’: a NULL-terminated array of words from the input command line // * `path’: a NULL-terminated array of directories to search in; // * `environment’: a NULL-terminated array of environment variables. // static void execute_command(char **words, char **path, char **environment) { assert(words != NULL); assert(path != NULL); assert(environment != NULL); char *program = words[0]; if (program == NULL) { // nothing to do return; } if (strcmp(program, “exit”) == 0) { do_exit(words); // do_exit will only return if there is an error return; } // ADD CODE HERE TO IMPLEMENT SUBSET 0 // CHANGE CODE BELOW HERE TO IMPLEMENT SUBSET 1 if (strrchr(program, ‘/’) == NULL) { fprintf(stderr, “SEARCHING OF PATH FOR PROGRAM UNIMPLEMENTED\n”); } if (is_executable(program)) { fprintf(stderr, “RUNNING PROGRAM UNIMPLEMENTED\n”); } else { fprintf(stderr, “CHANGE ME TO AN ERROR MESSAGE\n”); } } $ 1521 cowrie cowrie> cd /tmp cowrie> pwd current directory is ‘/tmp’ cowrie> cd /home/cs1521/public_html cowrie> pwd current directory is ‘/home/cs1521/public_html’ If the cd command is given no argument it should change directory to the value specified in the HOME environment variable. $ 1521 cowrie cowrie> cd cowrie> pwd current directory is ‘/home/z555555’ HINT: The lecture example my_cd.c shows how to use chdir to change directory. The lecture example getcwd.c shows how to print your current directory. The lecture example getenv.c shows how to run a program using posix_spawn. Cowrie Commands – Subset 1 – running commands Your next task is to add code to the function execute_command to execute commands which are not builtin. execute_command is given the command that has been entered as an array of words. You need to find the executable_file corresponding to the command and execute it, for example: 2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 3/8 $ 1521 cowrie cowrie> date Fri 8 Nov 12:07:50 AEDT 2019 /bin/date exit status = 0 The first word of the command specifies a program to run. The parameter path specifies a list of directories to search for the corresponding executable file. // // Check whether this process can execute a file. // Use this function when searching through the directories // in the path for an executable file // static int is_executable(char *pathname) { struct stat s; return // does the file exist? stat(pathname, &s) == 0 && // is the file a regular file? S_ISREG(s.st_mode) && // can we execute it? faccessat(AT_FDCWD, pathname, X_OK, AT_EACCESS) == 0; } A command may have multiple words which should be passed as the program’s argv, for example: $ 1521 cowrie cowrie> file cowrie.c cowrie.c: C source, ASCII text /usr/bin/file exit status = 0 cowrie> echo this command has 4 arguments this command has 4 arguments /bin/echo exit status = 0 cowrie> echo this command has 4 arguments this command has 4 arguments /bin/echo exit status = 0 cowrie> cp cowrie.c cowrie.c.backup /bin/cp exit status = 0 cowrie> ls cowrie.c.backup cowrie.c.backup /bin/ls exit status = 0 cowrie> hdhhfdhjf hdhhfdhjf: command not found Note the exit status of a command is printed when it exits: $ 1521 cowrie cowrie> ls cow.c /bin/ls: cannot access ‘cow.c’: No such file or directory /bin/ls exit status = 2 If a full path is given to a command you don’t search for it in the path directories,for example: $ 1521 cowrie cowrie> /home/cs1521/bin/spim Loaded: /home/cs1521/share/spim/exceptions.s (spim) HINT: The lecture example spawn.c shows how to run a program using posix_spawn. Make sure you wait for the new process to finish. Cowrie Commands – Subset 2 – History Your next task is to add code which saves a numbered list of every command executed. Each command should be appended to the file $HOME/.cowrie_history You should add a built-in command history n which prints the last n commands. If n is not specified it should default to 10. You should add a built-in command ! n which prints command n and then executes it. If n is not specified the last command should be executed and printed. 2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 4/8 $ rm -f $HOME/.cowrie_history $ 1521 cowrie cowrie> echo hello hello /bin/echo exit status = 0 cowrie> echo cowrie cowrie /bin/echo exit status = 0 cowrie> history 0: echo hello 1: echo cowrie cowrie> !0 echo hello hello /bin/echo exit status = 0 cowrie> !1 echo cowrie cowrie /bin/echo exit status = 0 cowrie> ! echo cowrie cowrie /bin/echo exit status = 0 You can commands in-memory, e.g. in an array, but you should also append each command immediately to the file $HOME/.cowrie_history. When appending commands put a space between each word and a ‘\n’ after the command. This will often be different to the white- space the user actually entered. HINT: The tokenize function always returns ! as a separate word so !n will always be returned as two words ! and n Cowrie Commands – Subset 3 – Globbing If any of the characters ‘*’, ‘?’, ‘[‘, or ‘~’ appears in a word that word should be replaced by all of the words matching that word using the glob(3) library function. This may result in the words list becoming longer than initially. If there are no matches, use the word unchanged. This should be done before any of the actions described below. $ 1521 cowrie cowrie> cd /home/cs1521/public_html/19T3/code/mips_basics/ cowrie> echo *.c i_love_mips.c /bin/echo exit status = 0 cowrie> wc *mips* 6 11 82 i_love_mips.c 10 27 172 i_love_mips.s 16 38 254 total /usr/bin/wc exit status = 0 cowrie> ls *.[cs] add.s i_love_mips.c i_love_mips.s /bin/ls exit
status = 0 HINT: Use GLOB_NOCHECK|GLOB_TILDE as the second parameter of the glob(3) function) Cowrie Commands – Subset 4 – I/O Re-direction If the first two tokens of the command line are < and a filename, the command should be executed with its standard input connected to the specified file. If the file does not exist, or is not readable, an error message should be printed. Similarly the last two words of the command line are > and a filename, the command should be executed with its standard output connected to the specified file. If the file is not writeable, an error message should be printed. The file should be over-written if it exists. If the last three words of the command line are >, > and a filename, standard output should be appended to the file rater than the file being over-written. 2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 5/8 An error message should be printed if > or < appear anywhere elsewhere on the command-line. An error message should be printed if no command is specified to redirect. An error message should be printed if a builtin command is specified with I/O redirection. Commands with invalid I/O redirection should not be added to the history. $ 1521 cowrie cowrie> echo hello cowrie >hello.txt /bin/echo exit status = 0 cowrie> cat hello.txt hello cowrie /bin/cat exit status = 0 cowrie> echo hello again >>hello.txt /bin/echo exit status = 0 cowrie> cat hello.txt hello cowrie hello again /bin/cat exit status = 0 cowrie> echo good bye cowrie >hello.txt /bin/echo exit status = 0 cowrie> cat hello.txt good bye /bin/cat exit status = 0 cowrie> < cowrie.c wc -l 636 /usr/bin/wc exit status = 0 cowrie> wc -l cowrie.c >number_of_lines /usr/bin/wc exit status = 0 cowrie> cat number_of_lines 636 /bin/cat exit status = 0 HINT: The lecture examples spawn_read_pipe.c and spawn_read_pipe.c show use of posix_spawn_file_actions_adddup2 which you’ll need to use. The tokenize function always returns < and > as a separate words, for example >file will be returned as two words. Cowrie Commands – Subset 5 – Pipes If a | appears between commands the stdout of the first command should be connected to the stdin of the second command. For example: $ 1521 cowrie cowrie> cat cowrie.c | wc -l 636 /usr/bin/wc exit status = 0 cowrie> < cowrie.c cat | wc -l >number_of_lines /usr/bin/wc exit status = 0 cowrie> cat number_of_lines 636 /bin/cat exit status = 0 cowrie> < cowrie.c cat | grep include | wc -l >number_of_includes /usr/bin/wc exit status = 0 cowrie> cat number_of_includes 18 /bin/cat exit status = 0 HINT: The lecture examples spawn_read_pipe.c and spawn_read_pipe.c show use of the functions pipe, posix_spawn_file_actions_adddup2 and posix_spawn_file_actions_addclose which you’ll need to use. The tokenize function always returns | as a separate word. Tests 2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 6/8 As usual you are expected do your own testing but some autotests are available to help you get started: $ 1521 autotest cowrie … If you create extra .c or .h files, you will need to supply them explicitly to autotest; for example: $ 1521 autotest cowrie extra1.c extra2.c extra3.h … Assumptions and Clarifications Like all good programmers, you should make as few assumptions as possible. Your submitted code must be a single C program only. You may not submit code in other languages. You are only permitted to use the function posix_spawn to run processes. You are not permitted to use functions such as posix_spawnp, system, popen, fork, vfork, clone or any of the exec functions. You may not use functions from other libraries; in other words, you cannot use dcc’s -l flag. If you need clarification on what you can and cannot use or do for this assignment, ask in the class forum. You are required to submit intermediate versions of your assignment. See below for details. Your program must not require extra compile options. It must compile with dcc *.c -o cowrie, and it will be run with dcc when marking. Run-time errors from illegal C will cause your code to fail automarking. If your program writes out debugging output, it will fail automarking tests: make sure you disable debugging output before submission. Change Log When you think your program is working, you can use autotest to run some simple automated tests: $ 1521 autotest cowrie Assessment Submission When you are finished working on the assignment, you must submit your work by running give: $ give cs1521 ass2_cowrie cowrie.c You must run give before Monday 25 November 21 59 59 to obtain the marks for this assignment. Note that this is an individual exercise, the work you submit with give must be entirely your own. You can run give multiple times. Only your last submission will be marked. If you are working at home, you may find it more convenient to upload your work via give’s web interface. You cannot obtain marks by e-mailing your code to tutors or lecturers. You check the files you have submitted here. Automarking will be run by the lecturer after the submission deadline, using test cases different to those autotest runs for you. (Hint: do your own testing as well as running autotest.) Manual marking will be done by your tutor, who will mark for style and readability, as described in the Assessment section below. After your tutor has assessed your work, you can view your results here; The resulting mark will also be available via give’s web interface. Due Date This assignment is tentatively due Monday 25 November 21 59 59. Version 1.0 (2019-11-09 11 59 59) Initial release Version 1.1 (2019-11-09 15 00 00) Extra information added to spec Version 1.2 (2019-11-10 08 00 00) Supplied code changed to show use of strrchr to check for / Various typos fixed in spec Bugs in autotest fixed and more autotests added Bug fixed in reference implementation handling of / 2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 7/8 If your assignment is submitted after this date, each hour it is late reduces the maximum mark it can achieve by 4%. For example, if an assignment worth 74% was submitted 5 hours late, the late submission would have no effect. If the same assignment was submitted 10 hours late, it would be awarded 60%, the maximum mark it can achieve at that time. Assessment Scheme This assignment will contribute 13 marks to your final COMP1521 mark. 80% of the marks for assignment 2 will come from the performance of your code on a large series of tests. 20% of the marks for assignment 2 will come from hand marking. These marks will be awarded on the basis of clarity, commenting, elegance and style. In other words, you will be assessed on how easy it is for a human to read and understand your program. An indicative assessment scheme follows. The lecturer may vary the assessment scheme after inspecting the assignment submissions, but it is likely to be broadly similar to the following: HD (85+) subsets 0-5 work; beautiful code DN (75+) subsets 0-3 work; good, clear code CR (65+) subset 0 & 1 works PS (50-60) subset 0 works, subset 1 partly working 0% knowingly providing your work to anyone and it is subsequently submitted (by anyone). 0 FL for COMP1521 submitting any other person’s work; this includes joint work. academic misconduct submitting another person’s work without their consent; paying another person to do work for you. Intermediate Versions of Work You are required to submit intermediate versions of your assignment. Every time you work on the assignment and make some progress you should copy your work to your CSE account and submit it using the give command below. It is fine if intermediate versions do not compile or otherwise fail submission tests. Only the final submitted version of your assignment will be marked. All these intermediate versions of your work will be placed in a Git repository and made available to you via a web interface at https://gitlab.cse.unsw.edu.au/z555555
5/19T3-comp1521-ass2_cowrie (replacing z5555555 with your own zID). This will allow you to retrieve earlier versions of your code if needed. Attribution of Work This is an individual assignment. The work you submit must be entirely your own work, apart from any exceptions explicitly included in the assignment specification above. Submission of work partially or completely derived from any other person or jointly written with any other person is not permitted. You are only permitted to request help with the assignment in the course forum, help sessions, or from the teaching staff (the lecturer(s) and tutors) of COMP1521. Do not provide or show your assignment work to any other person (including by posting it on the forum), apart from the teaching staff of COMP1521. If you knowingly provide or show your assignment work to another person for any reason, and work derived from it is submitted, you may be penalized, even if that work was submitted without your knowledge or consent; this may apply even if your work is submitted by a third party unknown to you. You will not be penalized if your work is taken without your consent or knowledge. Submissions that violate these conditions will be penalised. Penalties may include negative marks, automatic failure of the course, and possibly other academic discipline. We are also required to report acts of plagiarism or other student misconduct: if students involved hold scholarships, this may result in a loss of the scholarship. This may also result in the loss of a student visa. Assignment submissions will be examined, both automatically and manually, for such submissions. COMP1521 19T3: Computer Systems Fundamentals is brought to you by the School of Computer Science and Engineering at the University of New South Wales, Sydney. 2019/11/10 COMP1521 19T3 – Assignment 2: cowrie, A Simple Shell https://cgi.cse.unsw.edu.au/~cs1521/19T3/assignments/ass2/index.html 8/8 For all enquiries, please email the class account at [email protected] CRICOS Provider 00098G
