1N/A.TH SHELL 3 "28 Feb 2003" AST
1N/A\fBshell\fR \- a \f5ksh\fP library interface
1N/A.ta .8i 1.6i 2.4i 3.2i 4.0i 4.8i 5.6i
1N/Aint sh_main(int \fIargc\fP, char *\fIargv\fP[], Sh_init \fIfn\fP);
1N/AShell_t *sh_init(int \fIargc\fP, char *\fIargv\fP[]);
1N/AShell_t *sh_getinterp(void);
1N/ANamval_t *sh_addbuiltin(const char *\fIname\fP,Sh_bltin_f \fIfn\fP,void *\fIarg\fP);
1N/Aunsigned int sh_isoption(int \fIoption\fP);
1N/Aunsigned int sh_onoption(int \fIoption\fP);
1N/Aunsigned int sh_offoption(int \fIoption\fP);
1N/Avoid *sh_parse(Shell_t *\fIshp\fP, Sfio_t *\fIsp\fP, int \fIflags\fP);
1N/Aint sh_trap(const char *\fIstring\fP, int \fImode\fP);
1N/Aint sh_run(int \fIargc\fP, char *\fIargv\fP[]);
1N/Aint sh_eval(Sfio_t *\fIsp\fP,int \fImode\fP);
1N/Aint sh_fun(Namval_t *\fIfunnode\fP, Namval_t *\fIvarnode\fP, char *\fIargv\fP[]);
1N/Aint sh_funscope(int \fIargc\fP,char *\fIargv\fP[],int(*\fIfn\fP)(void*),void *\fIarg\fP,int \fIflags\fP);
1N/AShscope_t *sh_getscope(int \fIindex\fP,int \fIwhence\fP);
1N/AShscope_t *sh_setscope(Shscope_t *\fIscope\fP);
1N/Aint (*sh_fdnotify(int(*\fIfn\fP)(int,int)))(int,int);
1N/Achar *sh_fmtq(const char *\fIstring\fP);
1N/Avoid *sh_waitnotify(Shwait_f \fIfn\fP);
1N/Avoid sh_delay(double \fIsec\fP);
1N/ASfio_t *sh_iogetiop(int \fIfd\fP, int \fImode\fP);
1N/Aint sh_sigcheck(void);
1N/AThe \fIShell\fP library is a set of functions used for
1N/Awriting extensions to \f5ksh\fP or writing commands
1N/Athat embed shell command processing.
1N/AThe include file \f5<
shell.h>\fP contains the type definitions,
1N/Afunction prototypes and symbolic constants defined by
1N/Athis interface. It also defines replacement definitions for
1N/Athe standard library functions
1N/Aintended to be compiled as built-in commands.
1N/Ain turn includes the standard include files, \f5<
stddef.h>\fP,
1N/AThe \f5<
shell.h>\fP header also includes the headers
1N/Aso that in most cases, programs only require the single
1N/APrograms can use this library in one of the following ways:
1N/ATo write builtin commands
and/or other code that will be loaded
1N/Ainto the shell by loading dynamic libraries
1N/Aat run time using the \f5builtin\fP(1) command.
1N/AIn this case the shell will look for a function named \f5lib_init\fP
1N/Ain your library and, if found, will execute this function with
1N/Atwo arguments. The first
1N/Aargument will be an \f5int\fP with value \f50\fP when the library is loaded.
1N/AThe second argument will contain a pointer to a structure of type
1N/AIn addition, for each argument named on the \f5builtin\fP
1N/Acommand line, it will look for a function named \f5b_\fP\fIname\fP\f5()\fP
1N/Ain your library and will \fIname\fP as a built-in.
1N/ATo build separate a separate command that uses the shell as a
1N/Alibrary at compile or run time.
1N/AIn this case the \f5sh_init()\fP function must be called to
1N/Ainitialize this library before any other commands in this library
1N/AThe arguments \fIargc\fP and \fIargv\fP are the number
1N/Aof arguments and the vector of arguments as supplied by the shell.
1N/AIt returns a pointer the \f5Shell_t\fP.
1N/ATo build a new version of \f5ksh\fP with extended capabilities,
1N/Afor example \f5tksh\fP(1).
1N/AIn this case, the user writes a \f5main()\fP function that
1N/Acalls \f5sh_main()\fP with the \fIargc\fP and \fIargv\fP arguments
1N/Afrom \f5main\fP and pointer to function, \fIfn\fP as a third
1N/Aargument.. The function \fIfn\fP will
1N/Abe invoked with argument \f50\fP after \f5ksh\fP has done initialization,
1N/Abut before \f5ksh\fP has processed any start up files or executed
1N/Aany commands. The function \fIfn\fP
1N/Awill be invoked with an argument of \f51\fP before \f5ksh\fP
1N/Abegins to execute a script that has been invoked by name
1N/Asince \f5ksh\fP cleans up memory and long jumps back to
1N/Athe beginning of the shell in this case.
1N/AThe function \fIfn\fP will be called with argument \f5-1\fP before
1N/AThe \f5Shell_t\fP structure contains the following fields:
1N/A Shopt_t \fIoptions\fP; \fR/* set -o options */\fP
1N/A Dt_t *\fIvar_tree\fP; \fR/* shell variable dictionary */\fP
1N/A Dt_t *\fIfun_tree\fP; \fR/* shell function dictionary */\fP
1N/A Dt_t *\fIalias_tree\fP; \fR/* shell alias dictionary */\fP
1N/A Dt_t *\fIbltin_tree\fP; \fR/* shell built-in dictionary */\fP
1N/A Shscope_t *\fItopscope\fP; \fR/* pointer to top-level scope */\fP
1N/A char *\fIinfile_name\fP; \fR/* path name of current input file*/\fP
1N/A int \fIinlineno\fP; \fR/* line number of current input file*/\fP
1N/A int \fIexitval\fP; \fR/* most recent exit value*/\fP
1N/AThis structure is returned by \f5sh_init()\fP but can also be retrieved
1N/Aby a call to \f5sh_getinterp()\fP.
1N/AAll built-in commands to the shell are invoked with
1N/Athree arguments. The first two arguments give the
1N/Anumber of arguments and the argument list
1N/Aand uses the same conventions as the \f5main()\fP function
1N/Aof a program. The third argument is a pointer to a structure
1N/Aof type \f5Shbltin_t\fP. This structure contains \f5shp\fP which is a pointer
1N/Ato the shell interpreter, and \f5ptr\fP which is a pointer that
1N/Acan be associated with each built-in.
1N/AThe \f5sh_addbuiltin()\fP function is used to add, replace or delete
1N/AIt takes the name of the built-in, \fIname\fP, a pointer
1N/Ato the function that implements the built-in, \fIfn\fP, and
1N/Aa pointer that will be passed to the function in the \f5ptr\fP field when
1N/AIf, \fIfn\fP is non-\f5NULL\fP the built-in command
1N/Ais added or replaced. Otherwise, \f5sh_addbuiltin()\fP will
1N/Areturn a pointer to the built-in if it exists or \f5NULL\fP otherwise.
1N/AIf \fIarg\fP is \f5(void*)1\fP the built-in will be deleted.
1N/AThe \fIname\fP argument can be in the format of a pathname.
1N/AIt cannot be the name of any of the special built-in commands.
1N/AIf \fIname\fP contains a \f5/\fP, the built-in is the basename of
1N/Athe pathname and the built-in will only be executed
1N/Aif the given pathname is encountered when performing
1N/AWhen adding or replacing a built-in,
1N/A\f5sh_addbuiltin()\fP function returns a pointer to
1N/Athe name-value pair corresponding to the built-in on success and \f5NULL\fP
1N/Aif it is unable to add or replace the built-in.
1N/AWhen deleting a built-in, \f5NULL\fP is returned on success or
1N/Aif not found, and the name-value pair pointer is returned if the built-in
1N/AThe functions \f5sh_onoption()\fP, \f5sh_offoption()\fP, \f5sh_isoption()\fP
1N/Aare used to set, unset, and test for shell options respectively.
1N/AThe \fIoption\fP argument can be any one of the following:
1N/AThe \f5NV_EXPORT\fP attribute is given to each variable whose
1N/Aname is an identifier when a value is assigned.
1N/AEach background process is run at a lower priority.
1N/ACauses a non-interactive shell to exit when a command,
1N/Aother than a conditional command, returns non-zero.
1N/AThe emacs editing mode.
1N/ASame as the emacs editing mode except for the behavior of CONTROL-T.
1N/AIndicates that the history file has been created and that
1N/Acommands can be logged.
1N/ADo not treat end-of-file as exit.
1N/A\f5SH_INTERACTIVE\fP:
1N/ASet for interactive shells.
1N/ADo not set or unset this option.
1N/AA \fB/\fP is added to the end of each directory generated by pathname
1N/AIndicates that the monitor option is enabled for job control.
1N/AThe \fB>\fP redirection will fail if the file exists. Each file
1N/Acreated with \fB>\fP will have the \f5O_EXCL\fP bit set as described
1N/ADo not perform pathname expansion.
1N/ADo not save function definitions in the history file.
1N/ACause a message to be generated as soon as each background job completes.
1N/ACause the shell to fail with an error of an unset variable is
1N/ACause each line to be echoed as it is read by the parser.
1N/ACause each command to be displayed after all expansions, but
1N/ARead character at a time rather than line at a time when
1N/AThe \f5sh_trap()\fP function can be used to compile and execute
1N/AA value of \f50\fP for \fImode\fP indicates that \fIname\fP
1N/Arefers to a string. A value of \f51\fP for \fImode\fP
1N/Aindicates that \fIname\fP is an \f5Sfio_t*\fP to an open stream.
1N/AA value of \f52\fP for \fImode\fP indicates that \fIname\fP
1N/Apoints to a parse tree that has been returned by \f5sh_parse()\fP.
1N/AThe complete file associated with the string or file
1N/Ais compiled and then executed so that aliases defined
1N/Awithin the string or file will not take effect until
1N/Athe next command is executed.
1N/AThe \f5sh_run()\fP function will run the command given by
1N/Aby the argument list \fIargv\fP containing \fIargc\fP elements.
1N/AIf \fIargv\fP\f5[0]\fP does not contain a \f5/\fP, it will
1N/Abe checked to see if it is a built-in or function before
1N/Aperforming a path search.
1N/AThe \f5sh_eval()\fP function executes a string or file
1N/AIf \fImode\fP is non-zero and the history file has
1N/Abeen created, the stream defined by \fIsp\fP
1N/Awill be appended to the history file as a command.
1N/AThe \f5sh_parse()\fP function takes a pointer to the
1N/Ashell interpreter \fIshp\fP, a pointer to a string or file stream
1N/A\fIsp\fP, and compilation flags, and returns a pointer
1N/Ato a parse tree of the compiled stream. This pointer can
1N/Abe used in subsequent calls to \f5sh_trap()\fP.
1N/AThe compilation flags can be zero or more of the following:
1N/ATreat new-lines as \fB;\fP.
1N/AAn end of file causes syntax error. By default it will
1N/Abe treated as a new-line.
1N/A\f5ksh\fP executes each function defined with the \f5function\fP
1N/Areserved word in a separate scope. The \f5Shscope_t\fP type
1N/Aprovides an interface to some of the information that
1N/Ais available on each scope. The structure contains
1N/Athe following public members:
1N/A \f5Sh_scope_t *par_scope;\fP
1N/A \f5char *cmdname;\fP
1N/A \f5Dt_t *var_tree;\fP
1N/AThe \f5sh_getscope()\fP function can be used to the the
1N/Ascope information associated with existing scope.
1N/AScopes are numbered from \f50\fP for the global scope
1N/Aup to the current scope level. The \fIwhence\fP
1N/Aargument uses the symbolic constants associated with \f5lseek()\fP
1N/Ato indicate whether the \f5Iscope\fP argument is absolute,
1N/Arelative to the current scope, or relative to the topmost scope.
1N/AThe\f5sh_setscope()\fP function can be used to make a
1N/Aa known scope the current scope. It returns a pointer to the
1N/AThe \f5sh_funscope()\fP function can be used to run a function
1N/Ain a new scope. The arguments \fIargc\fP and \fIargv\fP
1N/Aare the number of arguments and the list of arguments
1N/Arespectively. If \fIfn\fP is non-\f5NULL\fP, then
1N/Athis function is invoked with \fIargc\fP, \fIargv\fP, and \fIarg\fP
1N/AThe \f5sh_fun()\fP function can be called within a
1N/Adiscipline function or built-in extension to execute a
1N/Adiscipline function script.
1N/AThe argument \fIfunnode\fP is a pointer to the shell function
1N/Aor built-in to execute.
1N/AThe argument \fIvarnode\fP is a pointer to the name
1N/Avalue pair that has defined this discipline.
1N/AThe array \fIargv\fP is a \f5NULL\fP terminated list of
1N/Aarguments that are passed to the function.
1N/ABy default, \f5ksh\fP only records but does not act
1N/Aon signals when running a built-in command.
1N/AIf a built-in takes a substantial amount of time
1N/Ato execute, then it should check for interrupts
1N/Aperiodically by calling \f5sh_sigcheck()\fP.
1N/AIf a signal is pending, \f5sh_sigcheck()\fP will exit
1N/Athe function you are calling and return to the point
1N/Awhere the most recent built-in was invoked, or where
1N/A\f5sh_eval()\fP or \f5sh_trap()\fP was called.
1N/AThe \f5sh_delay()\fP function is used to cause the
1N/Ashell to sleep for a period of time defined by \fIsec\fP.
1N/AThe \f5sh_fmtq()\fP function can be used to convert a string
1N/Ainto a string that is quoted so that it can be reinput
1N/Ato the shell. The quoted string returned by \f5sh_fmtq\fP
1N/Amay be returned on the current stack, so that it
1N/Amust be saved or copied.
1N/AThe \f5sh_fdnotify()\fP function causes the function \fIfn\fP
1N/Ato be called whenever the shell duplicates or closes a file.
1N/AIt is provided for extensions that need to keep track of
1N/Afile descriptors that could be changed by shell commands.
1N/AThe function \fIfn\fP is called with two arguments.
1N/AThe first argument is the original file descriptor. The
1N/Asecond argument is the new file descriptor for duplicating
1N/Afiles, and \f5SH_FDCLOSE\fP when a file has been closed.
1N/AThe previously installed \f5sh_fdnotify()\fP function pointer
1N/AThe \f5sh_waitnotify()\fP function causes the function \fIfn\fP
1N/Ato be called whenever the shell is waiting for input from
1N/Aa slow device or waiting for a process to complete.
1N/AThis function can process events and run shell commands
1N/Auntil there is input, the timer is reached or a signal arises.
1N/AIt is called with three arguments. The first is the file
1N/Adescriptor from which the shell trying to read or \f5\-1\fP
1N/Aif the shell is waiting for a process to complete.
1N/AThe second is a timeout in milliseconds.
1N/AA value of \f5\-1\fP for the timeout means that
1N/Ano timeout should be set.
1N/AThe third argument is 0 for input file descriptors
1N/Aand 1 for output file descriptor.
1N/AThe function needs to return a value \f5>0\fP if there
1N/Ais input on the file descriptor, and a value \f5<0\fP
1N/Aif the timeout is reached or a signal has occurred.
1N/AA value of \f50\fP indicates
1N/Athat the function has returned without processing and that the shell
1N/Ashould wait for input or process completion.
1N/AThe previous installed \f5sh_waitnotify()\fP function pointer is returned.
1N/AThe \f5sh_iogetiop()\fP function returns a pointer to the
1N/ASfio stream corresponding to file descriptor number \fIfd\fP
1N/Aand the given mode \fImode\fP. The mode can be either
1N/A\f5SF_READ\fP or \f5SF_WRITE\fP.
1N/AThe \fIfd\fP argument can the number of an open file descriptor or
1N/Aone of the following symbolic constants:
1N/A\f5SH_IOCOPROCESS\fP:
1N/AThe stream corresponding to the most recent co-process.
1N/AThe stream corresponding to the history file.
1N/AIf no stream exists corresponding to \fIfd\fP or the stream
1N/Acan not be accessed in the specified mode, \f5NULL\fP is returned.
1N/ADavid G. Korn (dgk@research.att.com).