man_1_simple_shell

.TH hsh 1 "2022-04-11" "V1.0" "simple shell man page"

.SH NAME
.B hsh simple shell

.SH SYNOPSIS (WAYS TO USE)
.B hsh [filename]

.B ./hsh

.B echo "command" | ./hsh

.B cat [bash_filename] | ./hsh

.SH DESCRIPTION
.B hsh is a simple UNIX command language interpreter that reads commands from either a file or standard input and executes them.

.B Invocation
.in +2n
hsh can be invoked both interactively and non-interactively.
If hsh is invoked with standard input not connected to a terminal, it reads and  executes received commands in order.
.in

.B Environment
.in +2n
Upon invocation, **hsh** receives and copies the environment of the parent process in which it was executed. This environment is an array of *name-value* strings describing variables in the format NAME=VALUE.
.in

.B Command Execution
.in +2n
After receiving a command, **hsh** tokenizes it into words using " " as a delimiter. The first word is considered the command and all remaining words are considered arguments to that command. **hsh** then proceeds with the following actions:

.RS
1. If the first character of the command is neither a slash (\\) nor dot (.), the shell searches for it in the list of shell builtins. If there exists a builtin by that name, the
builtin is invoked.
.RE

.RS
2. If the first character of the command is none of a slash (\\), dot (.), nor builtin, **hsh** searches each element of the **PATH** environmental variable for a directory containing an executable file by that name.
.RE

.RS
3. If the first character of the command is a slash (\\) or dot (.) or either of the above searches was successful, the shell executes the named program with any remaining given arguments in a separate execution environment.
.RE


.B Exit Status
.in +2n
**hsh** returns the exit status of the last command executed, with zero indicating success and non-zero indicating failure.

All builtins return zero on success and one or two on incorrect usage (indicated by a corresponding error message).
.in

.B Signals
.in +2n
While running in interactive mode, **hsh** ignores the keyboard input `Ctrl+c`. Alternatively, an input of end-of-file (`Ctrl+d`) will exit the program.
User hits `Ctrl+d` in the third line.
.in

.B Variable Replacement
.in +2n
**hsh** interprets the `$` character for variable replacement.
.in

.B Shell Builtin Commands
.in +2n

.RS
.B cd
.RS
Usage: cd [DIRECTORY]
.RE

.B exit
.RS
Usage: exit [STATUS]
.RE

.B env
.RS
Usage: env
.RE

.B cd
.RS
Usage: cd [PATH DIR]
.RE

.B setenv
.RS
Usage: setenv [KEY] [VALUE]
.RE

.B unsetenv
.RS
Usage: unsetenv [KEY]
.RE

.SH EXAMPLE
.nf

./hsh
$ echo Hello World
Hello World

$ pwd
/root

$ mkdir #CisFun

$ /bin/ls

#CisFun

$ exit 24

.ni

.SH FUTURE FEATURES

.B ";" Handle separator of commands.

.B "&& and ||" Handle the logical operators.

.B "alias" Allows use aliases.

.B "$$ $?" Variables replacement.

.B "#" Allow the comments.

.B "help" Display the help for the built-ins.

.B "history" Displays the history list.

.B "simple_shell [filename]" Can take a file as a command line argument.

.SH SEE ALSO
access(2), chdir(2), execve(2), _exit(2), exit(3), fflush(3), fork(2), free(3), isatty(3), getcwd(3), malloc(3), open(2), read(2), sh(1), signal(2), stat(2), wait(2), write(2)

.B hsh emulates basic functionality of the shell.

.SH AUTHOR
Diego Linares and Frank Quispe