.\" 
.\" Copyright 2003 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH sho 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
sho \- Execute programs from a shell in a pseudo terminal programmatically.
.SH SYNOPSIS
.nf
.B #include <mba/shellout.h>
.sp

.B SHO_FLAGS_INTERACT
.B SHO_FLAGS_ISATTY
.sp
.B struct sho {
.B 	char ps1[32];
.B 	int flags;
.B 	pid_t pid;
.B 	int ptym;
.B 	struct termios t0;
.B };
.B 
.sp
.BI "struct sho *sho_open(const char *" sh ", const char *" ps1 ", int " flags ");
.br
.BI "int sho_close(struct sho *" sh ");
.br
.BI "int sho_expect(struct sho *" sh ", const char *" pv "[], int " pn ", char *" dst ", size_t dn, int " timeout ");
.br
.BI "int sho_loop(struct sho *" sh ", const char *" pv "[], int " pn ", int " timeout ");
.br

.fi
.SH DESCRIPTION
The
.BR "shellout" (3m)
module provides a robust interface to a UNIX shell such as sh or bash. Spawned programs may be controlled interactively from a terminal (i.e. "shell out") or entirely in the background (i.e. cron, network daemon, etc). For most purposes this functionality is identical to that of the popular
.BR "expect" (1)
program.
.sp
The
.BR "svcond" (3m)
module is not available in the Win32 environment. This module also does not work on HP-UX because it does not support the
.BR "forkpty" (3)
function.
.PP
.TP
.B open
The
.B sho_open
function uses
.BR "forkpty" (3)
and
.BR "execvp" (3)
to execute a UNIX shell in a pseudo terminial. The
.I struct sho *
object returned may be used with
.IR "sho_expect" ,
.IR "writen" ,
etc to interact with the shell. Writing characters to the
.I sh->ptym
(PTY master) descriptor will be read by the shell as if they had been typed at a terminal. A
.I struct sho *
must be closed with
.IR "sho_close" .
.TP
.B close
The
.B sho_close
function calls
.IR "wait" (2)
to wait for the shell process to exit. The shell will not exit until it is instructed to. This can be occomplished by writing "exit $?\\n" or if the program spawned within the shell is taking too long, a Ctrl-C may be written by sending "\\x03\\n". Or, as a last resort,
.I SIGKILL
may be sent to
.I sh->pid
with
.IR "kill" (2).
.TP
.B expect
The
.B sho_expect
function accepts a "pattern vector" of
.I pn
strings to match and reads characters from the shell represented by
.I sh
copying each into
.I dst
for no more than
.I dn
bytes and returns either;
.sp
.br
the index of the matching pattern + 1,
.br
zero if EOF was read from
.IR "sh->ptym" ,
.br
or -1 if
.I timeout
was exceeded or another error occured.
.sp
Tips: It is very easy to be confused about what you think the shell is doing and what it is really doing. It is important to emulate what happens when you type the equivalent input in a shell in a terminal window but consider that the shell does not echo your commands. The shell will just write the output of the program followed by the shell prompt (whatever you defined that to be). If you are issueing multiple commands or the "exit $?\\n" command take care not to write the commands before the shell is ready (receive the shell prompt). Finally, the buffer passed to
.I sho_expect
will only contain the characters up to and including the pattern that matched. If the pattern matched is not the shell prompt it will be necessary to call
.I sho_expect
again to match the prompt before another command may be issued.
.TP
.B loop
The
.B sho_loop
function uses the
.BR "select" (2)
system call to read from the shell and write to
.I stdout
at the same time. The loop will exit when either one of
.I pn
patterns at the beginning of the pattern vector
.I pv
is encountered or the
.I timeout
period has expired.
.sp
When combined with the
.I SHO_FLAGS_INTERACT
flag passed to
.I sho_open
this will effectively create a shell within a shell. Note, currently some programs will not operate correctly (e.g. vi) because certain
.I termios
flags are not optimal for interactive sessions. This would need futher study.
.SH RETURNS
.TP
.B open
The
.B sho_open
function returns the new shell instance or NULL if an error occured in which case errno will be set appropriately.
.TP
.B close
The
.B sho_close
function returns the exit status of the shell. However, normally it is desireable to return the exit status of the last program to run within that shell. In this case the special shell variable "$?" which evaluates to the exit status of the last program to run may passed to the exit command such as "exit $?\\n".
.TP
.B expect
The
.B sho_expect
function returns the index of the matching pattern + 1, 0 if EOF was read, or -1 if an error occured in which case errno will be set appropriately. If the
.I timeout
period is exceeded
.B sho_expect
will return -1 and set errno to EINTR.
.TP
.B loop
The
.B sho_loop
function returns the index of the matching pattern + 1, 0 if EOF was read, or -1 if an error occured in which case errno will be set appropriately. If the
.I timeout
period is exceeded
.B sho_expect
will return -1 and set errno to EINTR.