man_1_simple_shell

./"This is the manpage of the SHELLY project at Holberton School

.TH SHELLY "May 10th 2022" "SHELLY man page"

.SH SYNOPSIS

.B #include \fB"main.h"
.B int main(void);

.SH NAME

.B SHELLY
- Command line interpreter (Shell).

.SH DESCRIPTION

.B \fBSHELLY\fR

The \fBSHELLY\fR utility is a command line interpreter that shall execute commands read from a command line string, the standard input.

The shell is a command that reads lines from either a file or the terminal, interprets them, and generally executes other commands. The shell is a command that reads lines from either a file or the terminal, interprets them, and generally executes other commands.

The interactive mode,the prompt, ($), which is called the command prompt, is issued by the shell. While the prompt is displayed, the user can type a command. Shell reads the input after the user press Enter. It determines the command the user wants executed by looking at the first word of the input. The first word can refer to a command built in, a command with or without the path, or an executable file, while the rest of words means the command's arguments.
Shell takes the input and separates the words (taking account the spaces and tabs like delimiters) into tokens.

With the command and arguments tokenized, the shell verifies that the commands exist and executes it. For this, it creates a child process with the system call fork to execute the process, while the parent process waits. At the end of the execution of the command by the child process, it terminates, returns to the parent process and continues the cycle generating a new prompt and waiting for another input.

.SH BUILTIN COMMANDS
These are the \fBBuiltin\fR commands of the SHELLY:

\fBExit\fR	-Exits the shell.
\fBEnv\fR	-Prints the environment variable.

.SH LEXICAL STRUCTURE

SHELLY reads input taking account the special characters to break it into words like whitespaces (tabs and spaces), and ignores the following characters:

\fBQuotation marks\fR
These are used to ignore the special meaning of some characters such as whitespaces.

\fBBackslash\fR
A backslash keeps the literal meaning of some special characters, with the exception of \n that means new line.

\fBAlias\fR
An alias is a name used to call an executable file with a shorter name (Some times is called a command with specific parameters). SHELLY checks the word to see if it matches an alias. If it does, it replaces it in the input with its meaning.

\fBPath Search\fR
When locating a command, the shell first looks to see if it has a builtin function by that name. If a builtin command is not found, one of two things happen:
1. Command names containing a slash are simply executed without performing any searches.
2. The shell searches each entry in PATH in turn for the command.  The value of the PATH variable should be a series of entries separated by colons.  Each entry consists of a directory name. 


.SH BRETURN VALUE

\fBCommand Exit Status\fR
Each command has an exit status that can influence the behavior of other shell commands.  The paradigm is that a command exits with zero for normal or success, and non-zero for failure, error, or a false indication. The man page for each command should indicate the various exit codes and what they mean. Additionally, the builtin commands return exit codes, as does an executed shell function.

.SH EXAMPLES

\fBOutput:\fR
$ echo "qwerty" | ./hsh
./hsh: 1: qwerty: not found

\fBInteractive mode:\fR
$ ./hsh
($) /bin/ls
hsh main.c shell.c
($)
($) exit
$

\fBNon-interactive mode:\fR
$ echo "/bin/ls" | ./hsh
hsh main.c shell.c test_ls_2
$
$ cat test_ls_2 | ./hsh
hsh main.c shell.c test_ls_2
hsh main.c shell.c test_ls_2
$

\fBCommands with the path:\fR
($) /bin/ls
barbie_j       env-main.c  exec.c  fork.c  pid.c  ppid.c    prompt   prompt.c  shell_0.3

\fBCommands without the path - no arguments:\fR
($) ls
barbie_j       env-main.c  exec.c  fork.c  pid.c  ppid.c    prompt   prompt.c  shell_0.3  

\fBCommands without the path - with arguments:\fR
($) ls -l /tmp 
total 20
-rw------- 1 ernestwambua ernestwambua   0 Dec  5 12:09 config-err-aAMZrR
drwx------ 3 root   root   4096 Dec  5 12:09 systemd-private-062a0eca7f2a44349733e78cb4abdff4-colord.service-V7DUzr
drwx------ 3 root   root   4096 Dec  5 12:09 systemd-private-062a0eca7f2a44349733e78cb4abdff4-rtkit-daemon.service-ANGvoV
drwx------ 3 root   root   4096 Dec  5 12:07 systemd-private-062a0eca7f2a44349733e78cb4abdff4-systemd-timesyncd.service-CdXUtH
-rw-rw-r-- 1 kinyarasam kinyarasam   0 Dec  5 12:09 unity_support_test.0

\fBBuiltin:\fR
($) exit
$

.SH AUTHORS
Written by Ernest Wambua and Kinyara Samuel.