man_1_simple_shell

.TH man 1 "25 August 2021" "Gsh man page"
.SH NAME
.B Gsh
 - Gsh stands for Giant shell, though ironical name...but that is how it was to me when ALX released the first trimester final project called simple_shell. Sorry for the verbosity.
.SH SYNOPSIS
.B ./Gsh
.PP
-------------------------------
.PP
$ [command] [options] [FILE]
.SH DESCRIPTION
.B Gsh is an end of the first trimester project for ALX students where we explore, understand, and build a working functional simple shell program.
.PP
This is a very simplified version of a shell, similar to bash or dash. We put to practice the knowledge learnt so far - on C - into a real world scenario.
.SH OPTIONS
.B Gsh
operates in two modes which are
.I interactive
and
.I non-interactive
modes.
.SH INVOCATION
.PP
In the 
.I interactive 
mode, the user runs the program according to the SYNOPSIS above and starts slotting in commands that needs be executed.
.PP
In the
.I non-interactive
mode, the user types in command to the terminal and then pipes it with 
.B ./Gsh.
Once that command is executed or not, it returns back to the default shell your terminal started up with.
.SH EXIT VALUES
Not specific.
.PP
It returns the exit code of the last command inside it or that provided by user.
.SH EXAMPLES
.IP

$ ./hsh

Once it becomes a process, a prompt will be displayed. It depends on your system configurations. I will use
.B $
here.

$ pwd

.B /root/simple_shell

$ /bin/pwd

.B /root/simple_shell

$ ls -la

.B Expect to see something
.SH BUILTINS
There are some built-in commands which are few for now. They are:
.PP
.I env
 - prints the environmental variables
.PP
.I exit
 - quits the program.
.SH BUGS
No Known bugs at present. Report if any is discovered to
.I https://github.com/Thrinkxs/simple_shell/issues.
.SH AUTHORS
.B Thrinkxs

.B Thrinkxs
.SH COPYRIGHT
.B Gsh
is Copyright (C) free.

//OTHER VERSION
.TH SHELLBY 1 "August 2022" "ALX School" "0x16. C - Simple Shell"
.SH NAME
.B shellby\fR \- simple UNIX command interpreter
.SH SYNOPSIS
.B shellby\fR [\fIfilename\fR]
.SH DESCRIPTION
.B Shellby\fR is a simple UNIX command language interpreter that reads commands from either a file or standard input and executes them.

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

If \fBshellby\fR is invoked with standard input connected to a terminal (determined by \fIisatty(3)\fR), an \fIinteractive\fR shell is opened.
When executing interactively, \fBshellby\fR displays the prompt \fI$ \fR when it is ready to read a command.

Alternatively, if command line arguments are supplied upon invocation, \fBshellby\fR treats the first argument as a file from which to read commands.
The supplied file should contain one command per line.
.B Shellby\fR runs each of the commands contained in the file in order before exiting.
.in

.B Environment
.in +2n
Upon invocation, \fBshellby\fR receives and copies the environment of the parent process in which it was exeucted.
This \fBenvironment\fR is an array of \fIname-value\fR strings describing variables in the format \fINAME=VALUE\fR.
.in

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

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

.RS
2. If the first character of the command is none of a slash (\fI\\\fR), dot (\fI.\fR), nor builtin, \fBshellby\fR searches each element of the
\fBPATH\fR 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 (\fI\\\fR) or dot (\fI.\fR) or either of the above searches was successful,
the shell executes the named program with any remaining arguments given in a separate execution environment.
.RE

.B Exit Status
.in +2n
.B Shellby\fR returns the exit status of the last command executed, unless a syntax error occurs, with zero indicating success and non-zero indicating failure.

If a command is not found, the return status is 127; if a command is found but is not executable, the return status is 126.

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, \fBshellby\fR ignores the keyboard input \fBCtrl+c\fR.
Alternatively, an input of end-of-file (\fBCtrl+d\fR) will exit the program.
.in

.B Variable Replacement
.in +2n
.B Shellby\fR inerprets the \fI$\fR character for variable replacement:

.RS
.B $ENV_VARIABLE\fR	\fIENV_VARIABLE\fR is subsituted with its value.
.RE

.RS
.B $?\fR			\fI?\fR is substituted with the return value of the last program executed.
.RE

.RS
.B $$\FR			The second \fI$\fR is substituted with the current process ID.
.RE

.B Comments
.in +2n
.B Shellby\fR ignores all words and characters preceeded by a \fI#\fR character on a line.
.in

.B Operators
.in +2n

.RS
.B ;\fR - Command separator
.RS
Commands separated by a \fI;\fR are executed sequentially.
.RE

.B &&\fR - AND logical operator
.RS
.I command1\fR && \fIcommand2\fR: \fIcommand2\fR is executed if, and only if, \fIcommand1\fR returns an exit status of zero.
.RE

.B ||\fR - OR logical operator
.RS
.I command1\fR || \fIcommand2\fR: \fIcommand2\fR is executed if, and only if, \fIcommand1\fR returns a non-zero exit status.
.RE

The operators \fI&&\fR and \fI||\fR have equal precedence, followed by \fI;\fR.
.RE

.B Shellby Builtin Commands
.in +2n

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

Changes the current directory of the process to \fBDIRECTORY\fR.

If no argument is given, the command is interpreted as \fBcd $HOME\fR.

If the argument \fB-\fR is given, the command is interpreted as \fBcd $OLDPWD\fR.

The environment variables \fBPWD\fR and \fBOLDPWD\fR are updated after a change of directory.
.RE

.B alias
.RS
Usage: \fBalias [NAME[='VALUE'] ...]\fR

Handles aliases.

.I alias\fR: Prints a list of all aliases, one per line, in the form \fINAME='VALUE'\fR.

.I alias NAME [NAME2 ...]\fR: Prints the aliases \fINAME\fR, \fINAME2\fR, etc. one per line, in the form \fINAME='VALUE'\fR.

.I alias NAME='VALUE' [...]\fR: Defines an alias for each \fINAME\fR whose \fIVALUE\fR is given.
If \fIname\fR is already an alias, its value is replaced with \fIVALUE\fR.
.RE

.B exit
.RS
Usage: \fBexit [STATUS]\fR

Exits the shell.

The \fBSTATUS\fR argument is the integer used to exit the shell.

If no argument is given, the command is interpreted as \fBexit 0\fR.
.RE

.B env
.RS
Usage: \fBenv\fR

Prints the current environment.
.RE

.B setenv
.RS
Usage: \fBsetenv [VARIABLE] [VALUE]\fR

Initializes a new environment variable, or modifies an existing one.

Upon failure, prints a message to \fBstderr\fR
.RE

.B unsetenv
.RS
Usage: \fBunsetenv [VARIABLE]\fR

Removes an environmental variable.

Upon failure, prints a message to \fBstderr\fR.
.RE
.RE
.in

.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 Shellby\fR emulates basic functionality of the \fBsh\fR shell.
This man page borrows from the corresponding man pages sh(1) and dash(1).