|SHELL(3)||C LIBRARY FUNCTIONS||SHELL(3)|
#include <shell.h> libshell.a -lshell
Shell_t; Shopt_t; Shscope_t; Shbltin_t; Shbltin_f; Shinit_f; Shwait_f;
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_run(int argc, char *argv); 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);
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, programs only require the single header <shell.h>.
Programs can use this library in one of the following ways:
The Shell_t structure contains the following fields:
This structure is returned by sh_init() but can also be retrieved by a call to sh_getinterp().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*/
All built-in commands to the shell are invoked with three arguments. The first two arguments give the number of arguments and the argument list and uses the same conventions as the main() function of a program. The third argument is a pointer to a structure of type Shbltin_t. This structure contains shp which is a pointer to the shell interpreter, and ptr which 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 in the ptr field when it is invoked. If, fn is non-NULL the built-in command is added or replaced. Otherwise, sh_addbuiltin() will return a pointer to the built-in if it exists or NULL otherwise. If arg is (void*)1 the built-in will be deleted. The name argument can be in the format of a pathname. 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 executed 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 cannot be deleted.
The functions sh_onoption(), sh_offoption(), sh_isoption() are used to set, unset, and test for shell options respectively. The option argument can be any one of the following:
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_run() function will run the command given by by the argument list argv containing argc elements. If argv does not contain a /, it will be checked to see if it is a built-in or function before performing a path search.
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.
The sh_parse() function takes a pointer to the shell interpreter 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:
ksh executes each function defined with the function reserved word in a separate scope. The Shscope_t type provides an interface to some of the information that is available on each scope. The structure contains the following public members:
The sh_getscope() function can be used to the the scope information associated with existing scope. Scopes are numbered 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 argument 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.Sh_scope_t *par_scope; int argc; char **argv; char *cmdname; Dt_t *var_tree;
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 function 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 discipline. 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 substantial amount of time to execute, then it should check for interrupts periodically by calling sh_sigcheck(). If a signal is pending, sh_sigcheck() will exit the function you are calling and return to the point where the most recent 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 argument 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 descriptor 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 descriptor. 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:
|AST||28 Feb 2003||December 28, 2011|