da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.TH SHELL 3 "28 Feb 2003"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fBshell\fR \- a \f5ksh\fP library interface
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SYNOPSIS
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.ta .8i 1.6i 2.4i 3.2i 4.0i 4.8i 5.6i
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "DATA TYPES"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SS "FUNCTIONS"
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint sh_main(int \fIargc\fP, char *\fIargv\fP[], Sh_init \fIfn\fP);
7c2fbfb345896881c631598ee3852ce9ce33fb07April ChinShell_t *sh_init(int \fIargc\fP, char *\fIargv\fP[]);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinShell_t *sh_getinterp(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinNamval_t *sh_addbuiltin(const char *\fIname\fP,Sh_bltin_f \fIfn\fP,void *\fIarg\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinunsigned int sh_isoption(int \fIoption\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinunsigned int sh_onoption(int \fIoption\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinunsigned int sh_offoption(int \fIoption\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinvoid *sh_parse(Shell_t *\fIshp\fP, Sfio_t *\fIsp\fP, int \fIflags\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint sh_trap(const char *\fIstring\fP, int \fImode\fP);
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinint sh_run(int \fIargc\fP, char *\fIargv\fP[]);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint sh_eval(Sfio_t *\fIsp\fP,int \fImode\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint sh_fun(Namval_t *\fIfunnode\fP, Namval_t *\fIvarnode\fP, char *\fIargv\fP[]);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint sh_funscope(int \fIargc\fP,char *\fIargv\fP[],int(*\fIfn\fP)(void*),void *\fIarg\fP,int \fIflags\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinShscope_t *sh_getscope(int \fIindex\fP,int \fIwhence\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinShscope_t *sh_setscope(Shscope_t *\fIscope\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint (*sh_fdnotify(int(*\fIfn\fP)(int,int)))(int,int);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinchar *sh_fmtq(const char *\fIstring\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinvoid *sh_waitnotify(Shwait_f \fIfn\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinvoid sh_delay(double \fIsec\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSfio_t *sh_iogetiop(int \fIfd\fP, int \fImode\fP);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinint sh_sigcheck(void);
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH DESCRIPTION
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIShell\fP library is a set of functions used for
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwriting extensions to \f5ksh\fP or writing commands
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthat embed shell command processing.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe include file \f5<shell.h>\fP contains the type definitions,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfunction prototypes and symbolic constants defined by
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthis interface. It also defines replacement definitions for
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe standard library functions
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5access()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5close()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5dup()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5exit()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5fcntl()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5lseek()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5open()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5pipe()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5read()\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5write()\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthat must be used
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwith all code
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinintended to be compiled as built-in commands.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin turn includes the standard include files, \f5<stddef.h>\fP,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5<sys/types.h>\fP, \f5<fcntl.h>\fP, and \f5<locale.h>\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5<shell.h>\fP header also includes the headers
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinso that in most cases, programs only require the single
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinheader \f5<shell.h>\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinPrograms can use this library in one of the following ways:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTo write builtin commands and/or other code that will be loaded
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininto the shell by loading dynamic libraries
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinat run time using the \f5builtin\fP(1) command.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn this case the shell will look for a function named \f5lib_init\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin your library and, if found, will execute this function with
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chintwo arguments. The first
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinargument will be an \f5int\P with value \f50\fP when the library is loaded.
7c2fbfb345896881c631598ee3852ce9ce33fb07April ChinThe second argument will contain a pointer to a structure of type
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chin\f5Shbltin_t\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn addition, for each argument named on the \f5builtin\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincommand line, it will look for a function named \f5b_\fP\fIname\fP\f5()\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin your library and will \fIname\fP as a built-in.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTo build separate a separate command that uses the shell as a
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinlibrary at compile or run time.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn this case the \f5sh_init()\fP function must be called to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininitialize this library before any other commands in this library
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinare invoked.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe arguments \fIargc\fP and \fIargv\fP are the number
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinof arguments and the vector of arguments as supplied by the shell.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt returns a pointer the \f5Shell_t\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTo build a new version of \f5ksh\fP with extended capabilities,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfor example \f5tksh\fP(1).
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIn this case, the user writes a \f5main()\fP function that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincalls \f5sh_main()\fP with the \fIargc\fP and \fIargv\fP arguments
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfrom \f5main\fP and pointer to function, \fIfn\fP as a third
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinargument.. The function \fIfn\fP will
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbe invoked with argument \f50\fP after \f5ksh\fP has done initialization,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbut before \f5ksh\fP has processed any start up files or executed
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinany commands. The function \fIfn\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwill be invoked with an argument of \f51\fP before \f5ksh\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbegins to execute a script that has been invoked by name
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinsince \f5ksh\fP cleans up memory and long jumps back to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe beginning of the shell in this case.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe function \fIfn\fP will be called with argument \f5-1\fP before
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe shell exits.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5Shell_t\fP structure contains the following fields:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin Shopt_t \fIoptions\fP; \fR/* set -o options */\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin Dt_t *\fIvar_tree\fP; \fR/* shell variable dictionary */\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin Dt_t *\fIfun_tree\fP; \fR/* shell function dictionary */\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin Dt_t *\fIalias_tree\fP; \fR/* shell alias dictionary */\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin Dt_t *\fIbltin_tree\fP; \fR/* shell built-in dictionary */\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin Shscope_t *\fItopscope\fP; \fR/* pointer to top-level scope */\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin char *\fIinfile_name\fP; \fR/* path name of current input file*/\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin int \fIinlineno\fP; \fR/* line number of current input file*/\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin int \fIexitval\fP; \fR/* most recent exit value*/\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis structure is returned by \f5sh_init()\fP but can also be retrieved
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinby a call to \f5sh_getinterp()\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAll built-in commands to the shell are invoked with
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthree arguments. The first two arguments give the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinnumber of arguments and the argument list
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand uses the same conventions as the \f5main()\fP function
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinof a program. The third argument is a pointer to a structure
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinof type \f5Shbltin_t\fP. This structure contains \f5shp\P which is a pointer
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinto the shell interpreter, and \f5ptr\fP which is a pointer that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincan be associated with each built-in.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_addbuiltin()\fP function is used to add, replace or delete
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbuilt-in commands.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt takes the name of the built-in, \fIname\fP, a pointer
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto the function that implements the built-in, \fIfn\fP, and
7c2fbfb345896881c631598ee3852ce9ce33fb07April China pointer that will be passed to the function in the \f5ptr\fP field when
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinit is invoked.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf, \fIfn\fP is non-\f5NULL\fP the built-in command
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinis added or replaced. Otherwise, \f5sh_addbuiltin()\fP will
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinreturn a pointer to the built-in if it exists or \f5NULL\fP otherwise.
7c2fbfb345896881c631598ee3852ce9ce33fb07April ChinIf \fIarg\fP is \f5(void*)1\fP the built-in will be deleted.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIname\fP argument can be in the format of a pathname.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt cannot be the name of any of the special built-in commands.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fIname\fP contains a \f5/\fP, the built-in is the basename of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe pathname and the built-in will only be executed
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif the given pathname is encountered when performing
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china path search.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhen adding or replacing a built-in,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5sh_addbuiltin()\fP function returns a pointer to
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe name-value pair corresponding to the built-in on success and \f5NULL\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif it is unable to add or replace the built-in.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinWhen deleting a built-in, \f5NULL\fP is returned on success or
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif not found, and the name-value pair pointer is returned if the built-in
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincannot be deleted.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe functions \f5sh_onoption()\fP, \f5sh_offoption()\fP, \f5sh_isoption()\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinare used to set, unset, and test for shell options respectively.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIoption\fP argument can be any one of the following:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_ALLEXPORT\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5NV_EXPORT\fP attribute is given to each variable whose
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinname is an identifier when a value is assigned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_BGNICE\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinEach background process is run at a lower priority.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_ERREXIT\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinCauses a non-interactive shell to exit when a command,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinother than a conditional command, returns non-zero.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_EMACS\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe emacs editing mode.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_GMACS\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSame as the emacs editing mode except for the behavior of CONTROL-T.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_HISTORY\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIndicates that the history file has been created and that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincommands can be logged.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_IGNOREEOF\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinDo not treat end-of-file as exit.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_INTERACTIVE\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSet for interactive shells.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinDo not set or unset this option.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_MARKDIRS\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA \fB/\fP is added to the end of each directory generated by pathname
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_MONITOR\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIndicates that the monitor option is enabled for job control.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_NOCLOBBER\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fB>\fP redirection will fail if the file exists. Each file
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincreated with \fB>\fP will have the \f5O_EXCL\fP bit set as described
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_NOGLOB\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinDo not perform pathname expansion.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_NOLOG\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinDo not save function definitions in the history file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_NOTIFY\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinCause a message to be generated as soon as each background job completes.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_NOUNSET\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinCause the shell to fail with an error of an unset variable is
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreferenced.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_PRIVILEGED\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_VERBOSE\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinCause each line to be echoed as it is read by the parser.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_XTRACE\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinCause each command to be displayed after all expansions, but
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbefore execution.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_VI\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe vi edit mode.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_VIRAW\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinRead character at a time rather than line at a time when
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin vi edit mode.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_trap()\fP function can be used to compile and execute
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china string or file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA value of \f50\fP for \fImode\fP indicates that \fIname\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinrefers to a string. A value of \f51\fP for \fImode\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinindicates that \fIname\fP is an \f5Sfio_t*\fP to an open stream.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA value of \f52\fP for \fImode\fP indicates that \fIname\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinpoints to a parse tree that has been returned by \f5sh_parse()\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe complete file associated with the string or file
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis compiled and then executed so that aliases defined
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwithin the string or file will not take effect until
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe next command is executed.
7c2fbfb345896881c631598ee3852ce9ce33fb07April ChinThe \f5sh_run()\fP function will run the command given by
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinby the argument list \fIargv\fP containing \fIargc\fP elements.
7c2fbfb345896881c631598ee3852ce9ce33fb07April ChinIf \fIargv\fP\f5[0]\fP does not contain a \f5/\fP, it will
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinbe checked to see if it is a built-in or function before
7c2fbfb345896881c631598ee3852ce9ce33fb07April Chinperforming a path search.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_eval()\fP function executes a string or file
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinstream \fIsp\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf \fImode\fP is non-zero and the history file has
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbeen created, the stream defined by \fIsp\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwill be appended to the history file as a command.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_parse()\fP function takes a pointer to the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinshell interpreter \fIshp\fP, a pointer to a string or file stream
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\fIsp\fP, and compilation flags, and returns a pointer
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto a parse tree of the compiled stream. This pointer can
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbe used in subsequent calls to \f5sh_trap()\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe compilation flags can be zero or more of the following:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_NL\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinTreat new-lines as \fB;\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_EOF\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinAn end of file causes syntax error. By default it will
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinbe treated as a new-line.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5ksh\fP executes each function defined with the \f5function\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinreserved word in a separate scope. The \f5Shscope_t\fP type
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinprovides an interface to some of the information that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis available on each scope. The structure contains
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe following public members:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin \f5Sh_scope_t *par_scope;\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin \f5int argc;\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin \f5char **argv;\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin \f5char *cmdname;\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin \f5Dt_t *var_tree;\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_getscope()\fP function can be used to the the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinscope information associated with existing scope.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinScopes are numbered from \f50\fP for the global scope
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinup to the current scope level. The \fIwhence\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinargument uses the symbolic constants associated with \f5lseek()\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto indicate whether the \f5Iscope\fP argument is absolute,
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinrelative to the current scope, or relative to the topmost scope.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe\f5sh_setscope()\fP function can be used to make a
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china known scope the current scope. It returns a pointer to the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinold current scope.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_funscope()\fP function can be used to run a function
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinin a new scope. The arguments \fIargc\fP and \fIargv\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinare the number of arguments and the list of arguments
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinrespectively. If \fIfn\fP is non-\f5NULL\fP, then
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthis function is invoked with \fIargc\fP, \fIargv\fP, and \fIarg\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinas arguments.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_fun()\fP function can be called within a
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindiscipline function or built-in extension to execute a
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindiscipline function script.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe argument \fIfunnode\fP is a pointer to the shell function
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinor built-in to execute.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe argument \fIvarnode\fP is a pointer to the name
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinvalue pair that has defined this discipline.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe array \fIargv\fP is a \f5NULL\fP terminated list of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinarguments that are passed to the function.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinBy default, \f5ksh\fP only records but does not act
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinon signals when running a built-in command.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf a built-in takes a substantial amount of time
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto execute, then it should check for interrupts
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinperiodically by calling \f5sh_sigcheck()\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf a signal is pending, \f5sh_sigcheck()\fP will exit
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthe function you are calling and return to the point
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinwhere the most recent built-in was invoked, or where
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5sh_eval()\fP or \f5sh_trap()\fP was called.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_delay()\fP function is used to cause the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinshell to sleep for a period of time defined by \fIsec\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_fmtq()\fP function can be used to convert a string
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chininto a string that is quoted so that it can be reinput
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto the shell. The quoted string returned by \f5sh_fmtq\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmay be returned on the current stack, so that it
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinmust be saved or copied.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_fdnotify()\fP function causes the function \fIfn\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto be called whenever the shell duplicates or closes a file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt is provided for extensions that need to keep track of
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfile descriptors that could be changed by shell commands.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe function \fIfn\fP is called with two arguments.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe first argument is the original file descriptor. The
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinsecond argument is the new file descriptor for duplicating
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinfiles, and \f5SH_FDCLOSE\fP when a file has been closed.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe previously installed \f5sh_fdnotify()\fP function pointer
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_waitnotify()\fP function causes the function \fIfn\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinto be called whenever the shell is waiting for input from
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968china slow device or waiting for a process to complete.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThis function can process events and run shell commands
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinuntil there is input, the timer is reached or a signal arises.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIt is called with three arguments. The first is the file
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chindescriptor from which the shell trying to read or \f5\-1\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif the shell is waiting for a process to complete.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe second is a timeout in milliseconds.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA value of \f5\-1\fP for the timeout means that
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinno timeout should be set.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe third argument is 0 for input file descriptors
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand 1 for output file descriptor.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe function needs to return a value \f5>0\fP if there
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinis input on the file descriptor, and a value \f5<0\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinif the timeout is reached or a signal has occurred.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinA value of \f50\fP indicates
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinthat the function has returned without processing and that the shell
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinshould wait for input or process completion.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe previous installed \f5sh_waitnotify()\fP function pointer is returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \f5sh_iogetiop()\fP function returns a pointer to the
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinSfio stream corresponding to file descriptor number \fIfd\fP
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinand the given mode \fImode\fP. The mode can be either
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SF_READ\fP or \f5SF_WRITE\fP.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe \fIfd\fP argument can the number of an open file descriptor or
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinone of the following symbolic constants:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_IOCOPROCESS\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe stream corresponding to the most recent co-process.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin\f5SH_IOHISTFILE\fP:
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinThe stream corresponding to the history file.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinIf no stream exists corresponding to \fIfd\fP or the stream
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chincan not be accessed in the specified mode, \f5NULL\fP is returned.
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chin.SH SEE ALSO
da2e3ebdc1edfbc5028edf1354e7dd2fa69a7968chinDavid G. Korn (dgk@research.att.com).