Contents of the SHELL.DOC file

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

NAME NAME

pc-shell - pc command processor

SYNOPSIS SYNOPSIS

pc shell pc-shell [-s] [-v] [arg1 ... argn]

DESCRIPTION DESCRIPTION

pc-shell is a command processor for IBM-PC's and compatibles that emulates some of the more desirable functions of the Berkeley UNIX* C-shell. In addition, it implements PC-DOS versions of some of the common UNIX* commands - ls, mv, cp, etc.

s The -s option causes the program execute a file called "shell.rc" in the current directory (if it exists) before passing control to the user.

v The -v option (verbose) causes the program to echo all commands to the standard error stream before executing them.

arg1 argn arg1 ... argn (the command line arguments) are put into the shell's environment as the variables $1 through $n.

Wild Card Substitution Wild Card Substitution

Ambiguous file names are expanded to a list of matching file names on the command line. This can be defeated by quoting, and by setting the NOGLOB environment variable to '1'.

History substitution is a powerful means to save retyping of long command lines.It allows you to do things like re-execute the last command, re-execute the last command but redirect output to a file, or execute a new command with arguments from previous command lines. The last 20 commands are saved, and can be reviewed by typing the 'history' command.

Previous commands can be referred to by their number, or relative to the current command's number. Parameters from previous commands can be seperated out and used individually.

History substitutions specifications come in two parts - the command number specifier and the argument specifier, seperated by a colon. The argument specifier is optional; if it is omitted, the entire command line is specified.

::= !! | !n | !-n !! = last command !n = nth command

-1-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

!-n = command n commands before current command number !# = the current command line

There are a some shell variables that have special meanings for set the shell. They can be given values with the set command. They are

NOCLOBBER NOCLOBBER

NOCLOBBER If NOCLOBBER is equal to '1', then existing files may not be destroyed by output redirection, and output files to be appended to by >> must exist.

PROMPT PROMPT

PROMPT The PROMPT environment string is handled the same way as it COMMAND COM is by COMMAND.COM. There is one pc-shell-specific prompt string character ! that specifies the current command index. If no PROMPT environment string is defined, then the default is '$!% '.

NOGLOB NOGLOB

NOGLOB The NOGLOB environment string, if set to '1', will suppress file name expansion.

Multiple commands on one command line Multiple commands on one command line

Command lines are split at semicolons. This can be defeated by quoting or escaping.

EXAMPLE

%0 ls -l *.c ; make shell.exe ; exit

Conditional command execution Conditional command execution

If two commands are seperated by '&&', then the second will be executed only if the first returns 0 as an exit code. If two commands are seperated by '||', then the second will be executed only the first command returns non-zero as an exit code.

Example

make shell.exe && chmod +w /bin/shell.exe && mv shell.exe /bin

-3-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

If the make operation fails, then the chmod and the mv will not be executed.

make shell.exe || echo You blew it bub!

If the make operation fails, then the echo operation will be executed.

Any character preceded by a \ (backslash) is copied unmodified to the command buffer. This allows you to suppress the special meanings of shell command characters, such as '|', ';', and '* '.

# is the shell comment character. Anything on a line after a # character is ignored.

String surrounded by single or double quotes are stripped of the quotes, and passed without wild-card expansion to the invoked program.

Startup and Script Files Startup and Script Files

If '-s' is specified on the command line the program will look for a file called SHELL.RC in the current directory, and execute it before passing control to the console. This allows you to set up all your alias commands. It isn't a good idea to put an 'exit' command in your SHELL.RC file, as the shell will terminate.

sh Any file whose extension is .sh is run as a command file. There sh is also a command sh, into which shell scripts whose extension is not .sh can be redirected as standard input.

EXAMPLE

%0 sh %1 shell

INPUT OUTPUT INPUT/OUTPUT

COMMAND COM I/O redirection operates as it does under COMMAND.COM with some additional options:

name name Opens the file name as the standard input.

word < word reads the shell input up to a line which is identical to word. The resulting text is put into an anonymous temporary file, which is given to the command as standard input.

-4-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

name >name name >!name name >&name name >&!name

name The file name is used as standard output. If it doesn't exist, it's created; if it exists, it is truncated, and its previous contents are lost.

NOCLOBBER If the variable NOCLOBBER is set, the file must not already exist, or an error results. The forms using an exclamation point override the NOCLOBBER variable's action.

name The form >&name routes standard error along with standard name output to name.

name >>name name >>!name name >>&name name >>&!name

name Uses the file name as standard output, like >, but places NOCLOBBER output at the end of file. If the variable NOCLOBBER is set, it is an error if the file doesn't already exist. The forms using an exclamation point override the NOCLOBBER variable's action.

BUILT IN COMMANDS BUILT-IN COMMANDS

Some of the internal commands are UNIX* style replacements for COMMAND.COM internal commands, and some are included for convenience.

There are many that are simply aliases, e.g. 'copy' and 'cp' invoke the same program.

COMMAND DESCRIPTION SYNTAX COMMAND DESCRIPTION SYNTAX

terms used in syntax explanations :

-5-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

fname ::= PC-DOS ambiguous or unambiguous file or directory name.

uname ::= unambiguous PC-DOS file or directory name

string ::= any string of printable characters of arbitrary(<512) length.

filelist ::= filename [filename .. filename]

noargs ::= no arguments at all

space ::= any white space characters

[arg] ::= term is optional

envstring ::== | = |

COMMANDS COMMANDS

drive drive

a: | b: | c: | d: | e: | f: | g: | h: | i: | j:

changes default drive. If you don't have such a drive, nothing happens.

alias alias

alias

assigns cmdstring to name. name can now be used just as if it were a built-in or external command. cmdstring may contain history expressions or variable substitutions.

The syntax of this command is flexible - you can specify alii (?) in the form 'name=subst','name subst','name = subst', or 'name =subst.' However you need a space before character before a single quote in order to specify an alias that contains blanks.

alias set The alias and set commands are case sensitive, unlike COMMAND COM their analogs in COMMAND.COM.

+r, -r turn on or off read permission - i.e. hide the file. +w, -w turn on or off write permission. +h, -h turn on or off hidden attribute - converse of r +a, -a turn on or off archive attribute

Note that '-r' or '+rwh' are both valid syntax for switches. Also new permission switches are permissable between file names with the following warning: I don't reset the masks between file names - if you have a second batch of attribute changes on the command line, the effect is additive. If you're not careful, you could make a mess of a files attributes.

If you don't specify any attribute switches, file attributes will be set to 0, which means read,write,not hidden,not system, not modified since last backup.

cls cls

cls

clears the screen and homes the cursor.

commands commands

commands

prints a table of available built-in commands. (see above)

del del

del

synonym for rm.

dir dir

dir

synonym for ls.

dump dump

-7-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

dump filespec [block [page]] | [segment:[offset]] [count]

Where a block is 64K bytes and a page is 256 bytes Segment:offset are standard 8086 notation in hexadecimal Count is the number of bytes to dump in decimal

This came from some anonymous public domain source, ported by me

echo echo

echo

echo on echos argument list to screen. echo on causes all commands to be echoed before execution (i.e. sets the echo off verbose flag). echo off turns off the verbose flag.

era era

era

synonym for rm.

error error

error

prints returned value of last command to the screen.

exit exit

exit

terminates execution of the shell.

fgrep fgrep

fgrep

looks for unambiguous pattern in . echos lines matching to the screen.

history history

history [size]

size prints history list to standard output. If size is given, the number of commands history remembers is set to size size. If you change the size, history 'forgets' all previous commands and resets its counters to 0.

ls ls

ls | dir [-[alqctrR]]

Lists files that match

-a all files, including system files are listed. '.' and '..' are suppressed, but you know they're there if you

-8-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

need them, don't you? -l prints out file times, permissions, etc -q suppresses header line from display - useful when you want to pipe stuff into another program. -c print as one column. -t sort by time, most recent last -R recurse through all encountered subdirectories. -r reverses sort order.

md md

md | mkdir

make a directory. Prints an error if it can't be done

more more

more [-[0-9]*] []

List file to screen with pauses

-n specify tab width when expanding tabs, where n is an integer. more acts like 'cat' when redirected - you can concatenate files in this manner. If no files are specifed, standard input is 'mored.'

mv mv

mv [-v]

moves specified file or files to target specifed by. If there is more than one file in list, must be a directory

v -v will print out a message saying how it is accomplishing the move, which is probably more interesting to me than you.

popd popd

popd

returns to directory at top of directory stack.

pushd pushd

pushd

save current working directory on directory stack, and changes current working directory to .

pwd pwd

pwd

prints current working directory to standard output.

rd rd

-9-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

rd | rmdir

remove specified directory if possible.

rm rm

rm [-q]

blows away all files in . If -q is specified, will ask if they should be removed.

set set

set []

sets a string in the environment. If you specify 'name=' with no string after, it will remove it from the environment. If you don't specify a string, set prints out current environment.

The syntax of this command is flexible - you can specify set in the form 'set name=subst','set name subst','set name = subst', or 'set name =subst.' However you need a before space character before a single quote in order to specify a substitution string that contains blanks.

sh sh

sh [ .. ] forks a 'local' shell - i.e. saves all pertinent information about the shell you're currently in and invokes the command processor function recursively, with scriptfile scriptfile as input. The arguments are copied to $1 through $N environment strings, overwriting the startup arguments.

sh sh gives you a way to run scripts, without loading an extra copy of shell.com or small.com.

switchar switchar

switchar [schar]

schar schar sets the DOS switch character to schar. If schar is not given, the current switch character is echoed.

tee tee

tee

Copies standard input to standard output, depositing a copy in

touch touch

touch

-10-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

Makes the modification time of specified files the current date and time.

unalias unalias

unalias aliasname

remove alias name from the alias list.

y y

y

copies standard input to standard output, and then copies the specified files to standard output. Sort of the opposite of tee, in other words.

The Small Shell The Small Shell

Included in release 2.0 or later is a 'small' version of the shell. This version will take up less than 30K of memory at runtime (as verified by chkdsk). What's the catch? Well, ls, cp, mv, more, fgrep, and dump become external commands. I am not going to distribute these commands; you can either make them yourself, or you can use whatever you have on hand. If you need to use the COMMAND.COM copy facility, try putting these commands in your SHELL.RC file

alias cp 'command -c copy' alias ls 'command -c dir -w | sort'

The removed commands accounted for over 10K of the shell.com.

Helpful hints Helpful hints

Use forward slashes in all path names. (See note below on switch characters) If you use DOS 3.0 or higher, this includes paths to transient programs.

put single quotes around arguments with semicolons in them, so they don't turn into command delimiters.

The set command affects only the local shell's environment. You can 'exit' to command.com and the original environment is intact. The local environment is 2K large - which is useful.

When using the Microsoft C compiler under pc-shell, the compiler has a bad habit of look for parameters beginning with forward slashes in the environment. If you get their famous 'P0 : bad option' message, try revising the environment.

-11-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

Implementation notes Implementation notes

DOS doesn't acknowledge a 'change default drive' command until you issue a 'get current directory' call. Why? The only way I figured this out is by disassembling command.com.

PC|MS-DOS has a limit of 20 file handles. If you add a command that opens files, make sure you catch the ctrl-break signal and close them. Look at CAT.C or Y.C for examples.

DON'T REDIRECT INPUT INTO PRINT. Print gets all hosed up. Print has lots of trouble in general with the pc-shell, and should be avoided.

BUGS BUGS

Due to the way that environment strings are expanded on the command line, semicolons inside shell variables look like command seperators. This is not so much a bug as a gotcha.

I have noticed intermittent problems running on an AT, with DOS 3.0, but have been unable to reproduce them on a PC. I suspect bugs in DOS 3.0 that are absent in 3.1. If you notice

any consistent problems, send me a bug report.

DON'T REDIRECT INPUT INTO PRINT. It gets mighty confused and goes into an endless loop. Don't blame me, call MICROSOFT/IBM, and ask them where the heck they look for their command line!!!

Fixed the bug that made "mv foo .." throw away the source file and move it to "..foo", (i.e. nowhere). Added the sh command, that allows you to run scripts without re-invoking the shell.

V 2 2 V 2.2

Fixed the bug that locked pc up when a command line with a leading ; was entered. Changed fork code so that files with the extension .sh are run as scripts. The equals sign in alias and set is now optional.

V 2 3 V 2.3

-12-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

Removed information about versions 1.0 through 1.6 from documentation, adding any relevant material to the tips or implementation notes sections. Added redirection of standard error, and checking for NOCLOBBER. Implemented execution of the prompt string.

The switch character is now changed back to '/' before executing external commands. This should make some Microsoft programs happier. The environment with its forward slashes in the path are left intact. We'll see how that goes.

V 2 4 V 2.4

The problem running external programs written by IBM and Microsoft has finally been traced to Aztecs fexecv function. When is an ASCIIZ string not an ASCIIZ string? When you need to put a single carriage return on the end of it. THANKS to Programmers Journal. NOTE WELL that needing a carriage return in your command tail for EXEC calls is note documented in the IBM PC-DOS technical reference.

All references to the Aztec screen library have been removed, so this should work on Rainbows, Compupros, AMPROs etc. etc. etc. ls is slower, but its a small price to pay. If you want a fast version, one can be created for you if you mail a contribution (hint,hint).

mv now will do the right thing when you try to move to a drive that has been joined to a directory (DOS 3.1). It also now has a verbose switch, which tells you what exactly its doing. When I started writing a mv, I had no idea how many special cases I would have to take care of.

V 2 5 V 2.5

Problem with using the wrong path to search for external programs solved. Main command line parsing changed so that NOGLOB could be used to suppress file name expansion. The program now provides the same function in 1K less code, and seems to run faster to boot.

DONATIONS REQUESTED DONATIONS REQUESTED

The shell seems to have generated an incredible amount of interest, all around the country - someone apparently put this code out over the usenet and arpanet, in addition to its original FIDOnet roots.

I would like to keep working on it, but for it to progress further, it can no longer be a 'lunch hour hack.' I am therefore requesting that those who feel that this is a useful piece of software send me a donation to further my efforts towards purchasing a machine for home use.

-13-

PC-SHELL (1) PC-DOS C Shell PC-SHELL (1)

Anyone sending more that 25$ will recieve: 1. a PC-DOS disk with most recent release full source and executable image. 2. Source and executable for various other public domain *nix programs (tail, nroff, cut, paste, diff, grep)

If you use this every day, or if you are giving everyone in your place of employment a copy, value it accordingly.

This does not constitute a licensing agreement of any sort, nor is any warranty implied. Once you have a copy of this program or its source, it's yours to hack to pieces, use, revere, revile, or whatever. I like the anarchic aspects of the various public domain networks.