man_1_simple_shell

.TH man 1 "18 May 2022" "ALX SE PROGRAM" "SIMPLE SHELL"
.SH NAME
.B Simple Shell
- command line interpreter
.SH SYNOPSIS
.B $ [command] -[options] [arguments]
.sp
.SH DESCRIPTION
Simple Shell is a replica of the Unix shell. It works the same way the
.B sh
program does. This program has been created in the context of a first-year project for ALX SE Program.
.sp
.B Run
.RS
The program is compiled with the following command:
.B gcc -Wall -Werror -Wextra -pedantic *.c -o hsh
, enter
.B ./hsh 
to execute Simple Shell.
.RE
.sp
.B Overview
.RS
Simple Shell interprets commands from the standard input. The process of the program is forked into a child process, 
in which the system call execve() will be called. The arguments for execve() are an array of strings formed from the input,
and the extern char **environ variable. The child process will be replaced by the execution of the command,
and the program will return to the parent process.
.RE
.sp
.B Invocation
.RS
Simple Shell accepts two modes: interactive and non-interactive. To enter the interactive mode, just execute ./hsh.
The parent process will print the prompt 
.B $ 
and wait for the user to input a command, that will be executed by execve().
To use the non-interactive mode, pipe
.I echo
followed by the command in double quotes into ./hsh. This mode doesn't print a prompt and executes the command directly.
.RE
.sp
.B Path search
.RS
The way Simple Shell works is that when it receives input from the command line,
it searches for a shell function by that name. If it doesn't find it, it searches for a builtin by that name.
If it's not a builtin, and the command is the full name of an executable, like /bin/ls, it will be executed. 
If the command doesn't include its full path, and the PATH environment variable has not been altered, then Simple Shell searches in the PATH for the command and its directory.
PATH is a colon-separated list of directories containing the executable programs corresponding to the commands.
If PATH has been altered, or emptied, Simple Shell will first look in the current working directory to see if the command corresponds to an executable.
If it finds it there, this executable will be executed, if not, it will go through the PATH to try to find the full path of the command.
.RE
.sp
.B Builtins
.RS
Simple Shell has a few builtins that replicate the real shell builtins.
.sp
.RE
.RS
.B - exit [status]
exits the program with an exit status of the value specified as an argument by the user.
.sp
.B - env
prints the environment variables list to the standard output.
.sp
.B - setenv [name] [value]
without arguments, prints the environment variables.
With [name], creates and exports an empty environment variable.
With [name] and [value], creates and exports an environment variable and sets its value.
.sp
.B - unsetenv [name]
Deletes the environment variable [name].
.sp
.B - cd [directory]
changes the working directory.
With no option, changes to the home directory.
With '-', changes to the previous directory and prints the current one.
This builtin changes the environment variables PWD and OLDPWD.
.RE
.sp
.SH EXAMPLES
.sp
.B $ ls -l 
.RS
will list all the files in the current working directory, in long format.
.RE
.B echo "pwd" | ./hsh
.RS
will show the entire path of the current working directory, in non-interactive mode.
.RE
.B $ baguette
.RS
will throw an error message if "baguette" is not an executable file the Simple Shell can find.
.RE
.B $ exit 98
.RS
will exit the Simple Shell with a status of 98.
.RE
.SH SEE ALSO
.I dash,
.I csh
.SH NOTES
Simple Shell is entirely coded in the C programming language. It does not entirely replicate the real shell, 
as some builtins and features are missing. Simple Shell only takes one command at a time for now.
.sp
.SH BUGS
As mentionned before, some regular shell builtins are not implemented in Simple Shell, and trying to execute them
will end up in unexpected behavior, or error message.
.SH AUTHORS
Juliana Sau & Andrew Mutunga, Cohort 5.