man_1_simple_shell

.\" Copyright (c) 2024 by Jose N. Olmos (jose.n.olmos@outlook.com) and Nathan Wilson
.TH ASH 0  2024-07-24 "CHEPE, NATHAN" "Atlas Programmer's Manual"

.SH Simple Shell
ash \- a minimal re-implementation of shell

.SH SYNOPSIS
.nf
.B $ ash [cmd] [options] [arguments]
.fi

.SH DESCRIPTION
This is a simple emulation of the classic UNIX shell. It can run in both interactive and non-interactive modes depending on whether or not arguments were passed during initiation. Our shell is primarily designed to handle simple singular commands. Along with these, options and arguments may be given as well.

.SS Operation
If no arguments were passed at initiation, then Ash sets its mode into interactive. In this state it displays a prompt in stdout for the user and then it awaits for input coming from stdin. Once input has been received, it is interpreted and executed (if a matching command is found) along with its options and arguments, and once all subprocess created in response conclude, it will repeat the entire described series of steps again until an `exit` command is detected -- upon which our shell program terminates safely.
If a no matching command is found within the /bin/ directory then an error message is output.

.SS Limitations
Our simple shell (ash) connot handle special characters nor any dynamic movement of the cursor. This also means unfortunately that neither auto-complete nor shell history are implemented. furthermore, most all of the popular advanced features such as chaining, piping, and redirections are not implemented as well.

.SS Environment
Environment variables may be accessed if needed but there's no true integration of the environment into our shell's functioning. In particular there's no changing pwd from within our shell.

.SS Sub-processes
In order to execute commands our shell creates a copy of itself (fork) upon which it has permissions over. It will then replace this sub-shell's resources (execve) with a given command and wait for its termination before regaining control and resuming its own operation.

.SH RETURN VALUE
0 upon success, 1 upon common failure, and some other integer upon some special case failures.

.SH CONFORMING TO
Betty Style, Nicole Standards, the Checker's whims

.SH NOTES
This program was created as a class assignment for T1 students at Tulsa Atlas School

.SH BUGS
Since our implementation is very minimal by comparison to any of the broadly distributed shells, and because our approach may not have been conventional, there may be some unexpected behaviour somewhere amongst the edge cases. it is also possible that standard shell bugs may have been inadvertently duplicated as well. These all remain to be discovered

.SH EXAMPLES
The following is an example of ash running in interactive mode

.EX
	user@this_machine:~/path$ ./ash
	(ง'̀-'́)ง echo Wello, Horld!
	Wello, Horld!
	(ง'̀-'́)ง pwd
	~/path
	(ง'̀-'́)ง exit
	user@this_machine:~/path$ 
.EE

Here it is running in non-interactive mode

.EX
	user@this_machine:~/path$ ./ash cat somefile.txt
	Hello, World!
	user@this_machine:~/path$ 
.EE


.SH SEE ALSO
.BR sh (1), csh (1), ksh (1), fork (2), execve (2), environ (7)