Series 300 Implementation

NAME

wsh − create new shells in new or existing windows

SYNOPSIS

wsh [-w type] [-kboitTMmnv] [-l x,y] [-s w,h] [-r w,h] [-gad] [-c cmdline] [window_spec...]
wsh -e [-gad] [-c cmdline] window_spec... 

DESCRIPTION

This command creates new windows with the given names, sets up reasonable environments in them (see below), and starts shells associated with them.  If you don’t give window_spec, wsh creates one window with a default name.  See windows(1) for an explanation of window_spec. 

The shell program used is defined by the $SHELL environment variable.  It can be a full pathname, or be relative to one of the directories in $PATH. If $SHELL is null or not defined, the default shell is /bin/sh. 

By default (no -e option), wsh creates all the needed windows at once, before creating any shells. 

The options for wsh are identical to those for wcreate, with the addition of:

-e Create shells and attach them to existing windows (or terminals...), which must not be already affiliated to any program(s).  With this option, none of the options normally passed to wcreate are allowed, and you must supply at least one window_spec.

-g Make the new shell for each window a login shell.  The literal effect is to prepend a "−" to the first argument (arg0, program basename) passed to the shell program.  This causes some programs to do extra initialization, e.g.  /bin/sh runs /etc/profile and $HOME/.profile. 

-c Give the new shell for each window a command line to execute.  This option and its argument are passed (as two separate arguments) to each new shell. 

-a Causes the window to be automatically destroyed when its device interface (special file) is closed by every process that has opened it.  See wdestroy(1) for details on the -a option. 

-d Causes the window to be automatically destroyed when its device interface (special file) is closed by every process and only when a new window has been created.  See wdestroy(1) for details on the -d option. 

WARNING: Don’t give the -c option unless the shell program recognizes it. 

If you do not give a window_spec, wsh calls the window manager to pick a name for you before calling wcreate.

wsh waits until each shell is successfully executed from a child process before starting the next one. 

Side Effects

wsh sets up a reasonable user environment for each shell.  It performs only those actions which most users need, leaving all other initialization under user control. 

wsh adds an entry to /etc/utmp for term0 windows.  This means that who(1) will show the user as being logged in on a pty for every window shell still active. 

Each new shell is a process group leader, affiliated to its window, with its standard input, output, and error connected to the window, opened for read/write, and with all other files closed.  wsh checks affiliation by opening (and closing) /dev/tty.  It refuses to start an unaffiliated shell, e.g., if there is already a shell connected to the window. 

wsh sets signals SIGHUP, SIGINT, and SIGQUIT to SIG_DFL (see signal(2)). The first is necessary in case the program was started with nohup(1); each new shell must be able to receive SIGHUP from its window’s server.  The latter two are necessary in case the program was started in the background with "&"; they are safe because each new shell is affiliated to a new window. 

wsh sets the window’s special file permissions to 0622.  (Ownership must already be set to the process’s userid for this to succeed.  Normally this is done automatically by wcreate.)

wsh calls ioctl(2) to set the line discipline for each window to the following (see tty(4) for details).

 /* iflag */     BRKINT | IGNPAR | ICRNL  | IXON,
/* oflag */     OPOST  | ONLCR  | TAB0,
/* cflag */     B9600  | CS8    | CREAD  | CLOCAL,
/* lflag */     ISIG   | ICANON | ECHO   | ECHOE  | ECHOK,
/* line  */     000,
 /* 0 INTR  */   003,  /* ^C */
/* 1 QUIT  */   034,  /* ^\ */
/* 2 ERASE */   010,  /* ^H */
/* 3 KILL  */   025,  /* ^U */
/* 4 EOF   */   004,  /* ^D */
/* 5 EOL   */   000,  /* ^@ */
/* 6 rsvd1 */   000,
/* 7 rsvd2 */   000,

wsh does not change environment variables, nor alarm(2) or nice(2) settings.

EXAMPLES

wsh Greg
Create a term0 window named "Greg" at the default screen location, and start a shell in it. 

SHELL=/usr/bin/vi wsh -kb -l100,200 -s80,20 termwin
Create an assigned (selected), bottom, term0 window named termwin in the directory $WMDIR, with a "shell" of type /bin/vi connected.  The upper left corner is at x = 100, y = 200 (pixels).  The window is 80 columns and 20 rows in size. 

wsh -wgraphics -gc’exec anvil’ win1 win2
Create graphics windows "win1" and "win2", start a login shell for each window, and have them execute the command "exec anvil".

wsh -ea uhoh
Connect a shell to window "uhoh", which was created with wcreate (or whose shell terminated).  In addition, automatically destroy the window when the new shell is terminated. 

To cause a term0 window to be destroyed when the connected shell exits, specify -a with the other wsh options. 

SEE ALSO

windows(1), wborder(1), wcreate(1), wdestroy(1), wdisp(1), wfont(1), wlist(1), wmove(1), wselect(1), wsize(1), ioctl(2), signal(2), utmp(4), tty(7). 

DIAGNOSTICS

wsh prints a message to standard error and returns non-zero if it detects any error. 

wsh uses a close-on-exec pipe from its child processes to gain information on any error which occurs up through successful exec(2) of each shell.

Return values and possible meanings:

 0  No errors detected.
 1  No windows or shells created, due to:
     bad invocation
     error before calling wcreate
     failure to call wcreate
     wcreate returned anything other than 2
     (including termination due to signal)
 1  Aborted after possibly creating windows, due to problems while
   expanding a window_spec pattern.
 2  Windows possibly created, but no shells (wcreate returned 2)
 3  All windows and one or more shells possibly created,
   but failed to:
     open pipe (with write file descriptor greater than 2)
     set pipe to close-on-exec
     fork
     open window as file descriptor 0
     affiliate to window
     dup 0 to file descriptors 1 and 2
     set window permissions (using chmod)
     set window line discipline (using ioctl)
     execute shell program

WARNINGS

If the process which calls wsh has SIGCLD set to SIG_IGN, wsh thinks wcreate fails because system(3) returns −1.

Hewlett-Packard Company  —  May 11, 2021