Introduction to Library Functions SHELL(3)
NAME
shell - a ksh library interface
SYNOPSIS
HEADERS/LIBRARIES
#include <shell.h>
libshell.a -lshell
DATA TYPES
Shell_t;
Shopt_t;
Shscope_t;
Shbltin_f;
Shinit_f;
Shwait_f;
FUNCTIONS
int sh_main(int argc, char *argv[], Sh_init fn);
Shell_t *sh_init(int argc, char *argv);
Shell_t *sh_getinterp(void);
Namval_t *sh_addbuiltin(const char *name,Sh_bltin_f fn,void *arg);
unsigned int sh_isoption(int option);
unsigned int sh_onoption(int option);
unsigned int sh_offoption(int option);
void *sh_parse(Shell_t *shp, Sfio_t *sp, int flags);
int sh_trap(const char *string, int mode);
int sh_eval(Sfio_t *sp,int mode);
int sh_fun(Namval_t *funnode, Namval_t *varnode, char *argv[]);
int sh_funscope(int argc,char *argv[],int(*fn)(void*),void *arg,int flags);
Shscope_t *sh_getscope(int index,int whence);
Shscope_t *sh_setscope(Shscope_t *scope);
int (*sh_fdnotify(int(*fn)(int,int)))(int,int);
char *sh_fmtq(const char *string);
void *sh_waitnotify(Shwait_f fn);
void sh_delay(double sec);
Sfio_t *sh_iogetiop(int fd, int mode);
int sh_sigcheck(void);
DESCRIPTION
The Shell library is a set of functions used for writing
extensions to ksh or writing commands that embed shell com-
mand processing. The include file <shell.h> contains the
type definitions, function prototypes and symbolic constants
defined by this interface. It also defines replacement
definitions for the standard library functions access(),
close(), dup(), exit(), fcntl(), lseek(), open(), pipe(),
read(), and write() that must be used with all code intended
to be compiled as built-in commands.
SunOS 5.10 Last change: 28 Feb 2003 1
Introduction to Library Functions SHELL(3)
The <shell.h> header includes <ast.h> which in turn includes
the standard include files, <stddef.h>, <stdlib.h>,
<stdarg.h>, <limits.h>, <stdio.h>, <string.h>, <unistd.h>,
<sys/types.h>, <fcntl.h>, and <locale.h>. The <shell.h>
header also includes the headers <cdt.h>, <cmd.h>, <sfio.h>,
<nval.h>, <stk.h>, and <error.h> so that in most cases, pro-
grams only require the single header <shell.h>.
Programs can use this library in one of the following ways:
1 To write builtin commands and/or other code that will
be loaded into the shell by loading dynamic libraries
at run time using the builtin(1) command. In this case
the shell will look for a function named lib_init in
your library and, if found, will execute this function
with argument 0 when the library is loaded. In addi-
tion, for each argument named on the builtin command
line, it will look for a function named b_name() in
your library and will name as a built-in.
2 To build separate a separate command that uses the
shell as a library at compile or run time. In this
case the sh_init() function must be called to initial-
ize this library before any other commands in this
library are invoked. The arguments argc and argv are
the number of arguments and the vector of arguments as
supplied by the shell. It returns a pointer the
Shell_t.
3 To build a new version of ksh with extended capabili-
ties, for example tksh(1). In this case, the user
writes a main() function that calls sh_main() with the
argc and argv arguments from main and pointer to func-
tion, fn as a third argument.. The function fn will be
invoked with argument 0 after ksh has done initializa-
tion, but before ksh has processed any start up files
or executed any commands. The function fn will be
invoked with an argument of 1 before ksh begins to exe-
cute a script that has been invoked by name since ksh
cleans up memory and long jumps back to the beginning
of the shell in this case. The function fn will be
called with argument -1 before the shell exits.
The Shell_t structure contains the following fields:
Shopt_t options; /* set -o options */
Dt_t *var_tree; /* shell variable dictionary */
Dt_t *fun_tree; /* shell function dictionary */
Dt_t *alias_tree; /* shell alias dictionary */
Dt_t *bltin_tree; /* shell built-in dictionary */
Shscope_t *topscope; /* pointer to top-level scope */
char *infile_name; /* path name of current input file*/
int inlineno; /* line number of current input file*/
int exitval; /* most recent exit value*/
This structure is returned by sh_init() but can also be
retrieved by a call to sh_getinterp().
SunOS 5.10 Last change: 28 Feb 2003 2
Introduction to Library Functions SHELL(3)
All built-in commands to the shell are invoked with three
arguments. The first two arguments give the number of argu-
ments and the argument list and uses the same conventions as
the main() function of a program. The third argument is a
pointer that can be associated with each built-in. The
sh_addbuiltin() function is used to add, replace or delete
built-in commands. It takes the name of the built-in, name,
a pointer to the function that implements the built-in, fn,
and a pointer that will be passed to the function when it is
invoked. If, fn is non-NULL the built-in command is added
or replaced. Otherwise, the given built-in command will be
deleted. The name argument can be in the format of a path-
name. It cannot be the name of any of the special built-in
commands. If name contains a /, the built-in is the
basename of the pathname and the built-in will only be exe-
cuted if the given pathname is encountered when performing a
path search. When adding or replacing a built-in,
sh_addbuiltin() function returns a pointer to the name-value
pair corresponding to the built-in on success and NULL if it
is unable to add or replace the built-in. When deleting a
built-in, NULL is returned on success or if not found, and
the name-value pair pointer is returned if the built-in can-
not be deleted.
The functions sh_onoption(), sh_offoption(), sh_isoption()
are used to set, unset, and test for shell options respec-
tively. The option argument can be any one of the follow-
ing:
SH_ALLEXPORT: The NV_EXPORT attribute is given to each
variable whose name is an identifier when a value is
assigned.
SH_BGNICE: Each background process is run at a lower
priority.
SH_ERREXIT: Causes a non-interactive shell to exit
when a command, other than a conditional command,
returns non-zero.
SH_EMACS: The emacs editing mode.
SH_GMACS: Same as the emacs editing mode except for
the behavior of CONTROL-T.
SH_HISTORY: Indicates that the history file has been
created and that commands can be logged.
SH_IGNOREEOF: Do not treat end-of-file as exit.
SH_INTERACTIVE:
SunOS 5.10 Last change: 28 Feb 2003 3
Introduction to Library Functions SHELL(3)
Set for interactive shells. Do not set or unset this
option. SH_MARKDIRS: A / is added to the end of each
directory generated by pathname expansion.
SH_MONITOR: Indicates that the monitor option is
enabled for job control.
SH_NOCLOBBER: The > redirection will fail if the file
exists. Each file created with > will have the O_EXCL
bit set as described in <fcntl.h>
SH_NOGLOB: Do not perform pathname expansion.
SH_NOLOG: Do not save function definitions in the his-
tory file.
SH_NOTIFY: Cause a message to be generated as soon as
each background job completes.
SH_NOUNSET: Cause the shell to fail with an error of
an unset variable is referenced.
SH_PRIVILEGED:
SH_VERBOSE: Cause each line to be echoed as it is read
by the parser.
SH_XTRACE: Cause each command to be displayed after
all expansions, but before execution.
SH_VI: The vi edit mode.
SH_VIRAW: Read character at a time rather than line at
a time when in vi edit mode.
The sh_trap() function can be used to compile and execute a
string or file. A value of 0 for mode indicates that name
refers to a string. A value of 1 for mode indicates that
name is an Sfio_t* to an open stream. A value of 2 for mode
indicates that name points to a parse tree that has been
returned by sh_parse(). The complete file associated with
the string or file is compiled and then executed so that
aliases defined within the string or file will not take
effect until the next command is executed.
The sh_eval() function executes a string or file stream sp.
If mode is non-zero and the history file has been created,
the stream defined by sp will be appended to the history
file as a command.
SunOS 5.10 Last change: 28 Feb 2003 4
Introduction to Library Functions SHELL(3)
The sh_parse() function takes a pointer to the shell inter-
preter shp, a pointer to a string or file stream sp, and
compilation flags, and returns a pointer to a parse tree of
the compiled stream. This pointer can be used in subsequent
calls to sh_trap(). The compilation flags can be zero or
more of the following:
SH_NL: Treat new-lines as ;.
SH_EOF: An end of file causes syntax error. By
default it will be treated as a new-line.
ksh executes each function defined with the function
reserved word in a separate scope. The Shscope_t type pro-
vides an interface to some of the information that is avail-
able on each scope. The structure contains the following
public members:
Sh_scope_t *par_scope;
int argc;
char **argv;
char *cmdname;
Dt_t *var_tree;
The sh_getscope() function can be used to the the scope
information associated with existing scope. Scopes are num-
bered from 0 for the global scope up to the current scope
level. The whence argument uses the symbolic constants
associated with lseek() to indicate whether the Iscope argu-
ment is absolute, relative to the current scope, or relative
to the topmost scope. Thesh_setscope() function can be used
to make a a known scope the current scope. It returns a
pointer to the old current scope.
The sh_funscope() function can be used to run a function in
a new scope. The arguments argc and argv are the number of
arguments and the list of arguments respectively. If fn is
non-NULL, then this function is invoked with argc, argv, and
arg as arguments.
The sh_fun() function can be called within a discipline
function or built-in extension to execute a discipline func-
tion script. The argument funnode is a pointer to the shell
function or built-in to execute. The argument varnode is a
pointer to the name value pair that has defined this discip-
line. The array argv is a NULL terminated list of arguments
that are passed to the function.
By default, ksh only records but does not act on signals
when running a built-in command. If a built-in takes a sub-
stantial amount of time to execute, then it should check for
interrupts periodically by calling sh_sigcheck(). If a sig-
nal is pending, sh_sigcheck() will exit the function you are
calling and return to the point where the most recent
SunOS 5.10 Last change: 28 Feb 2003 5
Introduction to Library Functions SHELL(3)
built-in was invoked, or where sh_eval() or sh_trap() was
called.
The sh_delay() function is used to cause the shell to sleep
for a period of time defined by sec.
The sh_fmtq() function can be used to convert a string into
a string that is quoted so that it can be reinput to the
shell. The quoted string returned by sh_fmtq may be returned
on the current stack, so that it must be saved or copied.
The sh_fdnotify() function causes the function fn to be
called whenever the shell duplicates or closes a file. It
is provided for extensions that need to keep track of file
descriptors that could be changed by shell commands. The
function fn is called with two arguments. The first argu-
ment is the original file descriptor. The second argument
is the new file descriptor for duplicating files, and
SH_FDCLOSE when a file has been closed. The previously
installed sh_fdnotify() function pointer is returned.
The sh_waitnotify() function causes the function fn to be
called whenever the shell is waiting for input from a slow
device or waiting for a process to complete. This function
can process events and run shell commands until there is
input, the timer is reached or a signal arises. It is
called with three arguments. The first is the file descrip-
tor from which the shell trying to read or -1 if the shell
is waiting for a process to complete. The second is a
timeout in milliseconds. A value of -1 for the timeout
means that no timeout should be set. The third argument is
0 for input file descriptors and 1 for output file descrip-
tor. The function needs to return a value >0 if there is
input on the file descriptor, and a value <0 if the timeout
is reached or a signal has occurred. A value of 0 indicates
that the function has returned without processing and that
the shell should wait for input or process completion. The
previous installed sh_waitnotify() function pointer is
returned.
The sh_iogetiop() function returns a pointer to the Sfio
stream corresponding to file descriptor number fd and the
given mode mode. The mode can be either SF_READ or
SF_WRITE. The fd argument can the number of an open file
descriptor or one of the following symbolic constants:
SH_IOCOPROCESS: The stream corresponding to the most
recent co-process.
SH_IOHISTFILE: The stream corresponding to the history
file. If no stream exists corresponding to fd or the
stream can not be accessed in the specified mode, NULL
SunOS 5.10 Last change: 28 Feb 2003 6
Introduction to Library Functions SHELL(3)
is returned.
SEE ALSO
builtin(1) cdt(3) error(3) nval(3) sfio(3) stk(3) tksh(1)
AUTHOR
David G. Korn (dgk@research.att.com).
SunOS 5.10 Last change: 28 Feb 2003 7
Generated by GNU enscript 1.6.4.
on 2009/10/26 12:14