cwish(1)

NAME
cwish - curses window shell

SYNOPSIS
cwish [ [+|-] [acCdflnprsw] ] [-?]

DESCRIPTION
Cwish is a powerful fullscreen, menu-based, easy to use and user friendly interface to the UNIX (tm) filesystem. It can also be used as a shell replacement for interactive use. It is intended for character terminal environments where such tools are not available at all and where one needs a general purpose tool for easily walking through the filesystem.

OPTIONS
Cwish has several commandline options to change the runtime behaviour:

+a    Display the "attribute" line at the bottom of the screen.
If you don't like to continuously have the line showing the current file's attributes, you can switch this off by using the -a switch. As a side effect, you will be able to use two more screen lines for the file window display.

-a    Don't display the "attribute" line.

+C    On CDROM media, files containing data have often all execute
attributes set, so that cwish tries to execute the file as a shell script when selected for display. By specifying the +C option in conjunction with the +c option, cwish removes internally all execute permission from ordinary files.

-C    No execute permission removal is done on regular files.

+c    On CDROM's conforming to the
High Sierra or the ISO-9660 standard a version number is appended to a regular file's name delimited by a semicolon. This semicolon is interpreted by the shell as an end of line delimiter. To get around this behaviour, cwish escapes the semicolon by placing a backslash in front of the semicolon if this option is selected.

-c    Do not escape the semicolon in CDROM filenames.

+d    Try to preserve the current directory when walking through
the directory tree.

-d    Don't try to preserve the current directory.

+f    Display "virtual" function key labels.
Cwish detects the presence of a Hewlett-Packard-Terminal by the presence of the "xs"-flag in termcap or the "xhp"-flag in terminfo. If this flag is not present, cwish emulates the function key labels in the last line of the screen. If this behaviour is not desired, use the -f switch to run cwish without emulated function key labels.

-f    Don't display "virtual" function key labels.

+l    Enable the detection and display of symbolic links. This option
only makes sense if the "attributes" line is displayed.

-l    Disable the detection and display of symbolic links.

+n    Enable display of filenames starting with a dot.

-n    Disable display of filenames starting with a dot.

+p    Display the current directory as "." in the file window
of the screen. Usually the first file displayed in the file window is the "..", the directory above the current directory. This is convenient for easy walking through the directory tree. Although the current directory, ".", is not displayed, it is present and included in the entry count in the upper right corner of the file window. If you wish to display the current directory too, use the +p switch to turn this option on.

-p    Don't display the current directory as ".".

+r    Wait for pressing RETURN after executing an external
command.

-r    Don't wait for pressing RETURN after executing an external
command.

+s    Follow symbolic links to directories.

-s    Don't follow symbolic links to directories.

+w    Enable the processing of wildcard filenames for file display.
The wildcard specification must be entered using the .cwishrc file option "wildcard=" or by using cwish's configuration screen.

-w    Disable the processing of wildcard filenames.

-?    Displays current version of
cwish and copyright and usage information.

THE DISPLAY SCREEN
After starting cwish , the screen becomes divided into several "windows":

  Command Window
The command window consists of the uppermost two lines on screen, the first line is displaying the program's name, version and copyright information, the host name, the terminal type and the current time. In case that an error message has to be displayed, this line is used to display the error message until the next key is pressed.

The next line in this window is the the command line, displaying the current history line number as it's prompt. One can cycle through the command line history by using the popular emacs control sequences. Any alphanumeric input typed at the keyboard is displayed here and executed by the users shell (system(3) or, if configured, a local system()-call which uses a user configurable shell for command line execution) after pressing <return>.

  File Window
The middle part of the screen becomes your "window" into the currently selected directory - it's called the file window. The first line of the file window contains the full pathname of the current directory together with the number of files in this directory labeled Entries. If filename wildcarding is active, this label becomes Matches , when marking files, this label becomes Byte.

With the cursor keys, the user moves a "cursor" or "current file", which is a highlighted bar, over the filenames in the file window. If a file is made the current selected file by placing the cursor on it, various operations can be done on it, i.e. if the file is a directory, and the user hits return, a change to that directory is done. If the file is an executable file, it is either executed as a binary executable or as a shell script. If the file is a data file it is displayed by the selected pager program - more options are available. If there are more files in a directory than fitting into the file window, it can be paged through by using the page up/down function keys.

Files can be marked in the file window and expanded in the commandline by the special wildcard character "%" - so if you mark several files in the file window, and type "rm % <RETURN>" in the commandline, all selected files will be deleted.

The current selected filename can be echoed onto the commandline for further processing by some other commands.

If there are more files in the directory than will fit into the file window, one can move through file window "pages" by using the PAGE UP and PAGE DOWN terminal keys. There is an indicator available in the lower right corner of the file window for telling the user if there is page above "^", a page below "V" or pages above and below "*" available beside the current one.

  Attribute Window
If it was configured by either using the commandline switch -a or by using the configuration file option, the lower part of the screen becomes the attribute window which displays several attributes of the currently selected (highlighted) file. By using function key 7 you are able to switch between two types of attribute lines: normal - attributes displayed are permissions, date, time, size, no. of hardlinks, username and groupname; alternate - access date/time, modify date/time, status change date/time and inode.

  Function Key Label Window
If it was configured by either using the commandline switch f or by using the configuration file option, the last part of the screen becomes the virtual function key label window. Some cwish functionality is controllable by the terminals special function keys (f1....f8). Hewlett-Packard Terminals have special programmable function key labels; for terminals having function keys, but no labels, cwish simulates 8 function key labels in the last line of the terminal.

Command Window Keys

Backspace - Erases the character left of the cursor.

Delete - Erases the character under the cursor.

Insert - Toggles between insert and overwrite mode on the commandline.

Return - Return key handling is dependent of the status of the commandline:
Commandline contains characters:
The command string entered into the command line is terminated and executed by handing it to the system() call to execute it.
Commandline is empty:
While you are maneuvering with the highlighting bar through the file window, you are able to do the most natural commands depending on the type of file to the current selected (highlighted) file by just pressing <RETURN>. This means, that if your file is:
• a executable program, it is executed
• a data file, it is displayed using the pager program
• a directory, the current directory is changed to the highlighted one

Delete Char - Erases the character under the cursor.

Control-F - Forward one character on the commandline.

ESC f - Forward to the beginning of the next word.

Control-B - Backward one character on the commandline.

ESC b - Backward to the beginning of the previous word.

Control-P - Previous commandline from history buffer.

Control-N - Next commandline from history buffer.

Control-D - If the commandline is empty, exit cwish. If the commandline is not empty, delete the character under the cursor.

Control-K - Kill the line on the commandline from the cursor position to the end of the commandline and place the string into the kill-buffer. See also key Control-Y.

Control-Y - Yank text from the kill-buffer (if any) onto the commandline at the current cursor position. See also key Control-K.

Control-A - Position the cursor at the beginning of the commandline.

Control-E - Position the cursor at the end of the commandline.

Control-L - Refresh display

Alphanumeric Characters     Any alphanumeric, non-control character
typed on the keyboard is displayed on the commandline.

File Window Keys

Cursor Right - Move the current file one position to the right. If on the right margin, wrap onto the next line, first position. If on the lowest right position, wrap to the upper left position.

Cursor Left - Move the current file one position to the left. If on the left margin, wrap onto the previous line, last position. If on the upper left position, wrap to the lowest right position.

Cursor Up - Move the current file one position up in the same column.

Cursor Down - Move the current file one position down in the same column.

Cursor Home - Move the current file to the upper left position.

Cursor Home Down - Move the current file to the lower right position.

Next Page - Display the next file window screen (if any). This function is also executable by pressing "ESC N".

Previous Page - Display the previous file window screen (if any). This function is also executable by pressing "ESC P".

Function Keys

Function Key 1 - Edit the current file with your editor. This function is also executable by pressing "ESC 1".

Function Key 2 - Echo the current filename onto the commandline. This function is also executable by pressing "ESC 2".

Function Key 3 - Display the help screen. This function is also executable by pressing "ESC 3".

Function Key 4 - Enter the cwish runtime configuration menu screen. This function is also executable by pressing "ESC 4".

Function Key 5 - Mark the current filename. This function is also executable by pressing "ESC 5".

Function Key 6 - Unmark all marked filenames. This function is also executable by pressing "ESC 6".

Function Key 7 - If an attribute window is displayed, this key toggles between a normal and an alternate attribute line to show nearly all the current files attributes. If cwish was compiled with USE_STRDEV, there is a third attribute line available showing device major and minor numbers for device files. This function is also executable by pressing "ESC 7".

Function Key 8 - Close the current directory and open the the next upper directory (this has the same effect as executing "cd .." on the commandline. This function is also executable by pressing "ESC 8".

MARKING FILES
A special purpose wildcard character is recognized on the command line and is expanded after pressing <RETURN>, it is the character "%" (percent). This character expands to all marked files in the file window and gives the user a new powerful file handling functionality.

The behaviour of whether the current filename advances to the next position or stays at the current one is configurable in the runtime configuration menu and with an initfile variable. See also the Function Key 5 and Function Key 6 functions and the tagmove configuration file variable.

When making/tagging files, the Label Entries or Matches in the upper right corner of the file window is replaced by the label Byte and displays the sum of the sizes of all marked/tagged files.

CHANGE DIRECTORY COMMAND
The cd command is implemented in cwish itself. In case the command is typed without any parameters, a change directory to the users HOME directory is done. If a hyphen is typed after the cd command, a change directory to the previous working directory (if any) is executed. For using the cd command in conjunction with wildcards, see the following paragraph.

FILENAME COMPLETITION
There is a rather primitive filename completition available on the commandline, which is initiated by pressing the TAB key (compile time configurable) or the Escape key twice.

COMMANDLINE WILDCARD PROCESSING
It is possible to specify wildcard characters in a filename on the commandline. If the command to be performed is not a cd command, the wildcard matching rules of the shell used apply, if the command is a cd command (which is executed by itself), the wildcard string is interpreted according to the following rules:

\x  Turns off the special meaning of x and matches it directly; this is used mostly before a question mark or asterisk, and is not valid inside square brackets.

~   At the beginning of a pathname is replaced with the user's HOME directory

?   Matches any single character.

*   Matches any sequence of zero or more characters.

[x...y]
    Matches any single character specified by the set x...y, where any character other than minus sign or close bracket may appear in the set. A minus sign may be used to indicate a range of characters. That is, [0-5abc] is a shorthand for [012345abc]. More than one range may appear inside a character set; [0-9a-zA-Z._] matches almost all of the legal characters for a host name.

[!x...y]
    This matches any character not in the set x...y, which is interpreted as described above.
    There is no way to specify a minus sign in a character range.

FILE WINDOW WILDCARD PROCESSING
If the users wants to display just some files in the file window, he may do so by specifying a wildcard string in the configuration menu or with the configuration file variable wildcard. The rules for constructing such a string are the same as described in the above paragraph. Because there is a speed penalty in using this option, it has to be enabled in the configuration menu or file.

If wildcard processing is in effect, the label Entries in the upper right corner of the file window is replaced by the label Matches and displays the number of files matching the wildcard specification.

Filename wildcard processing affect all types of files with the exception of directories, which are always displayed.

THE ATTRIBUTE WINDOW
If an attribute window is displayed, (see command line options +a and -a ), some more information for the currently highlighted file in the file window is displayable, because there is more information available for a given file than will fit into 80 columns, there are two levels (switchable by using function key F7) available - normal and alternate attribute lines.

If cwish was compiled with the option USE_STRDEV defined, there is a third attribute line available showing device major and minor numbers for device files.

The normal (default after starting cwish ) attribute line displays:
• the file access permissions in a format as used by the "ls" utility
• the file modification date
• the file modification time
• the file size in bytes
• the number of hard links for the file
• the name of the owner of the file
• the name of the group of the file

The alternate attribute line displays:
• the file access date and time
• the file modification date and time
• the file last status change date and time
• the inode

The optional third alternate attribute line displays:
• the device major number in decimal (or 'void' if the current file is not a device specialfile).
• the device minor number in decimal, hexadecimal and binary (or 'void' if the current file is not a device specialfile).

CONFIGURATION FILE
On startup, cwish searches a startup configuration file named ".cwishrc" in the users HOME directory, and, if found, configures itself using the information in this file.
One can configure cwish by setting three types of Variables:

  Boolean Variables

Boolean Variables can be set/reset by using the stings "on" or "off" after the variable name and an equal sign.
attributes - Enable/disable attribute line display

preserve - Enable/disable preserve directory

fkeys - Enable/disable virtual function key label display

links - Enable/disable symbolic link detection and display

point - Enable/disable display of the current directory in the file window as "." (dot).

return - Enable/disable wait for pressing <RETURN> after a external command is executed.

wildenable - Enable/disable wildcard filename processing.

cdrom - Enable/disable CDROM semicolon in filename processing.

cdnoprog - Enable/disable CDROM removal of execute permissions.

dotnames - Enable/disable the display of filenames starting with a dot.

tagmove - Enable/disable moving to the next file after marking the current.

followsdir - Enable/disable follow symbolic linked directories.

autoexpand - Enable/disable expand command aliases immediately onto the commandline.

  String Variables

pager - the partial or full filename of the program to be used as the pager program.

editor - the partial or full filename of the program to be used as the editor program.

wildcard - specify a wildcard expression to be used for selecting filenames to be displayed in the file window.

shell - specify the shell used to execute the commandline. A complete pathname MUST (!!) be specified (i.e. "/bin/sh" or "/bin/csh") for this option to function properly.

This option is only effective if cwish was compiled with the USE_OWN_SYSTEM option defined.

tail - specify a "tail" to be used for special filename-ending processing. See below for details.

alias - specify a command alias. See below for details.

  Character Variables

delimiter - the delimiter character to be used to delimit the command and the the attribute window from the file window.

HANDLING OF FILES WITH SPECIAL ENDINGS (tail-command)
The handling of the special filename-ending processing is now configurable by the user in the .cwishrc - file.

The syntax of the "tail" command is:

"tail=<pattern> <command>"

A trailing "|" in the command string tells cwish to append the name of the pager to the command to pipe it through the pager.

The tail-lines in the configuration file are searched from the last entry to the first, so the order of tail - commands is IMPORTANT !

Examples:

    tail=<pattern>
         <command>
    ---------------
         -----------------------------------
    tail=*.[1-9]
         nroff -man|
    tail=*.tar.Z
         compress -dfc | tar tvf -|
    tail=*.tar.gz
         gzip -cdf | tar tvf -|
    tail=*.Z
         compress -dfc|
    tail=*.gz
         gzip -cdf|

HANDLING OF ALIASES (alias-command)
A user may specify shorthands for commands using the alias command in the .cwishrc - file.

The syntax of the "alias" command is:

"alias=<pattern> <command>"

If the aliased command is the first word on the commandline, it is expanded onto the commandline while the user (still) types (more).

The alias-lines in the configuration file are searched from the last entry to the first, so the order of alias - commands is IMPORTANT !

Examples:

    alias=<pattern>
         <command>
    ---------------
         -----------------------------------
    alias=md
         mkdir
    alias=l
         cd /usr/local/src
    alias=ll
         ls -l -a -g
    alias=pf
         ps -e -f
    alias=bdf
         df -k

STARTUP AND CONFIGURATION-FILE PROCESSING
When cwish is started, it runtime configures itself in the following order:

1.  it sets up defaults taken from the environment

2.  it (re-) configures itself by reading the .cwishrc configuration file from the users HOME directory

3.  the command line options (if any) are processed and used for (re-)configuration

RUNTIME CONFIGURATION
While running cwish the user is able to change several configuration variables on the fly by using the configuration menu which is entered by pressing Function Key 4.

You can leave the configuration menu by pressing CONTROL-D.

Pressing SPACE toggles a the value of a boolean variable.

A wildcard string can be entered by moving the cursor onto the Wildcard field and pressing <RETURN>, the only editing key available is <BACKSPACE>. Leave the field by pressing <RETURN> again - remember to enable the processing of wildcards by setting the boolean variable WildEnabl to YES.

The variables in the lower half of the screen are just displayed but cannot be changed here. Use the .cwishrc configuration file options to change these and restart cwish.

ENVIRONMENT
Cwish depends on some of the following environment variables:

HOME - mandatory, the users HOME directory

PAGER - optional, the pager program used to display text files, this defaults to using "more" (it is recommended to use "less" as the pager with cwish).

EDITOR - optional, the editor used for editing files, if this variable does not exist, the environment variable VISUAL is used, if it also does not exist, this defaults to "vi".

TERM - mandatory, the users termcap/terminfo entry

SEE ALSO
sh(1), system(3)

COPYRIGHT
Cwish is
Copyright (c) 1988 - 1996 by Hellmuth Michaelis
Eggerstedtstr. 28
22765 Hamburg
Europe
Tel: +49 40 384298 (private)
Tel: +49 40 55903-170 (at work)
e-mail: hm@hcs.de

All rights are reserved except as explicitly granted by written permission of the author.

Cwish is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See the file COPYING, distributed with cwish , for restriction and warranty information

The wildmat(3) library function used by cwish to perform all types of wildcard matching was written by Rich $alz <rsalz@bbn.com> in 1986, and posted to Usenet. The version used here was taken from volume 17 of comp.sources.misc.

The user_from_uid() and group_from_gid() user and group name cacheing functions used by cwish (see usrgrp.c) are from an unknown BSD distribution. The optional mysystem() function (see system.c) is derived from a recent NetBSD-current (pre 1.0) system() C-library source.

So i'd like to say that ``This product includes software developed by the University of California, Berkeley and its contributors'.

RETURN VALUES
The return value is 0 if cwish was exited normally by the user, any other return value signals that a fatal error has occurred.

FILES
$HOME/.cwishrc

DIAGNOSTICS
Cwish uses the first line (which under no error conditions contains a copyright message, version, terminal name and time) to tell the user in case of error what type of error has occurred. This error message is overwritten with the normal header when the next key is pressed.

HISTORY
Cwish was modeled after a utility called "PAM" (Personal Application Manager) which was distributed as part of Hewlett-Packards HP-UX (tm) Operating System.

In contrast to PAM, which runs only on HP's own terminals, cwish is curses based and should run on all sorts of terminals, although it was tested just with HP-terminals (HP2392A,HP700/9x) and DEC-terminals (VT100/VT220) and terminal emulators which come with X Windows (xterm, hpterm).

Cwish began as a termcap based program on a Microware OS-9/68k (tm) machine, moved over to the HP-UX environment to replace PAM (still termcap based) and was then rewritten to use curses.

In the meantime it compiles and runs on a wide range of architectures, see the various Makefiles that come with the source.