






             [1mGuidelines for writing ksh‐93 built‐in commands[0m
                              [4mDavid[24m [4mG.[24m [4mKorn[0m





       [4m1.[24m  [4mINTRODUCTION[0m

       A  built‐in  command is executed without creating a separate
       process.  Instead, the command is invoked as a C function by
       [1mksh[22m.   If  this  function  has  no side effects in the shell
       process, then the behavior of this built‐in is identical  to
       that  of  the  equivalent  stand‐alone command.  The primary
       difference in this case is  performance.   The  overhead  of
       process  creation  is  eliminated.   For  commands  of short
       duration, the effect can be dramatic.  For example,  on  SUN
       OS  4.1,  the  time  to run [1mwc [22mon a small file of about 1000
       bytes, runs about 50 times faster as a built‐in command.

       In addition, built‐in commands may have side effects on  the
       shell  environment.   This  is  usually  done  to extend the
       application domain  for  shell  programming.   For  example,
       there  is a group of X‐windows extension built‐ins that make
       heavy use of the shell variable namespace.  These  built‐ins
       are  added  at run time and result in a windowing shell that
       can be used to write X‐windows applications.

       While there  are  definite  advantages  to  adding  built‐in
       commands,  there  are some disadvantages as well.  Since the
       built‐in command and [1mksh [22mshare the  same  address  space,  a
       coding error in the built‐in program may affect the behavior
       of [1mksh[22m; perhaps causing it to core dump or hang.   Debugging
       is  also  more  complex  since  your code is now a part of a
       larger entity.  The isolation provided by a separate process
       guarantees  that  all  resources used by the command will be
       freed when the  command  completes.   Resources  used  by  a
       built‐in  must  be meticulously maintained and freed.  Also,
       since the address space of [1mksh [22mwill be larger when  built‐in
       are  loaded, it may increase the time it takes [1mksh [22mto fork()
       and exec() non‐built‐in commands.  It makes no sense to  add
       a  built‐in command that takes a long time to run or that is
       run only  once,  since  the  performance  benefits  will  be
       negligible.  Built‐ins that have side effects in the current
       shell environment have the disadvantage  of  increasing  the
       coupling  between  the  built‐in and [1mksh[22m, making the overall
       system less modular and more monolithic.

       Despite these drawbacks, in  many  cases  extending  [1mksh  [22mby
       adding built‐in commands makes sense and allows reuse of the
       shell scripting ability in an application  specific  domain.
       This memo describes how to write [1mksh [22mextensions.







       [4m2.[24m  [4mWRITING[24m [4mBUILT‐IN[24m [4mCOMMANDS[0m

       There  is a development kit available for writing [1mksh [22mbuilt‐
       ins as part of the AST (AT&T Software  Technology)  Toolkit.
       The development kit has three directories, [1minclude[22m, [1mlib[22m, and
       [1mbin[22m.  It is  best  to  set  the  value  of  the  environment
       variable  [1mPACKAGE_ast  [22mto  the  pathname  of  the  directory
       containing  the  development  kit.   The  [1minclude  [22mdirectory
       contains  a  sub‐directory named [1mast [22mthat contains interface
       prototypes for functions that you can call  from  built‐ins.
       The  [1mlib  [22mdirectory  contains  the [1mast [22mlibrary and a library
       named [1mcmd [22mthat contains a version of several of the standard
       POSIX[1] utilities that can be made run time built‐ins.  The
       [1mlib/ksh [22mdirectory contains shared libraries  that  implement
       other [1mksh [22mbuilt‐ins.  The [1mbin [22mdirectory contains build tools
       such as [1mnmake[22m[2].   To  add  built‐ins  at  runtime,  it  is
       necessary  to  build a shared library containing one or more
       built‐ins that you wish to  add.   The  built‐ins  are  then
       added by running [1mbuiltin −f [4m[22mshared_lib[24m.  Since the procedure
       for building share libraries is system dependent, it is best
       to  use  [1mnmake  [22musing  the  sample nmake makefile below as a
       prototype.  The AST Toolkit also contains some  examples  of
       built‐in libraries under the [1msrc/cmd/kshlib [22mdirectory.

       There  are two ways to code adding built‐ins.  One method is
       to replace the function [1mmain [22mwith a function  [1mb_[4m[22mname[24m,  where
       [4mname[24m  is  the  name  of  the built‐in you wish to define.  A
       built‐in command has a calling  convention  similar  to  the
       [1mmain   [22mfunction  of  a  program,  [1mint  main(int  argc,  char[0m
       [1m*argv[])[22m.  except that it takes a  third  argument  of  type
       [1mShbltin_t*  [22mwhich  can  be passed as [1mNULL [22mif it is not used.
       The definition for [1mShbltin_t* [22mis in [1m<ast/shcmd.h>[22m.   Instead
       of  [1mexit[22m,  you need to use [1mreturn [22mto terminate your command.
       The return value will become the exit status of the command.
       The  [1mopen [22mbuilt‐in, installed in [1mlib/ksh [22min the AST Toolkit,
       uses this method.  The [1mShbltin_t [22mstructure contains a  field
       named  [1mshp  [22mwhich  is  a  pointer the the shell data that is
       needed for [1mshell [22mlibrary callbacks.  It  also  contains  the
       fields, [1mshrun[22m, [1mshtrap[22m, [1mshexit[22m, and [1mshbltin [22mthat are function
       pointers to the  [1mshell  [22mlibrary  functions  [1msh_run[22m,  [1msh_trap[0m
       [1msh_exit[22m,  and  [1msh_addbuiltin[22m,  respectively. These functions
       can be invoked without the need for  runtime  symbol  lookup
       when the shell is statically linked with [1mlibshell[22m.

       The  alternative method is to create a function [1mlib_init [22mand
       use the [1mShbltin_t.shbltin() [22mfunction  to  add  one  or  more
       built‐ins.   The  [1mlib_init  [22mfunction will be called with two
       arguments.  The first argument will be 0 when the library is
       loaded  and  the second argument will be of type [1mShbltin_t*[22m.
       The [1mdbm_t [22mand [1mdss [22mshell built‐ins use this method.

       No matter which way you add built‐ins  you  should  add  the
       line [1mSHLIB([4m[22midentifier[24m[1m) [22mas the last line of one of the built‐
       in source file, where [4midentifier[24m is any C identifier.   This
       line  provides  version  information  to  the  shell [1mbuiltin[0m
       command that it uses to  verify  compatibility  between  the
       built‐in and [1mksh [22mimplementation versions. [1mbuiltin [22mfails with
       a diagnostic  on  version  mismatch.  The  diagnostic  helps
       determine whether [1mksh [22mis out of date and requires an upgrade
       or the built‐in is out of date and requires recompilation.






       The steps necessary to create and add a  run  time  built‐in
       are  illustrated  in  the following simple example.  Suppose
       you wish  to  add  a  built‐in  command  named  [1mhello  [22mwhich
       requires  one argument and prints the word hello followed by
       its argument.  First, write the  following  program  in  the
       file [1mhello.c[22m:

                               [1mExhibit 1.[0m
       #include      <stdio.h>  int b_hello(int argc, char *argv[],
       void *context) {
               if(argc != 2)
               {
                       fprintf(stderr,"Usage: hello arg\n");
                       return(2);
               }
               printf("hello %s\n",argv[1]);
               return(0); } SHLIB(hello)

       Next, the program needs to be compiled.  If you are building
       with AT&T [1mnmake [22muse the following [1mMakefile[22m:

                               [1mExhibit 2.[0m
       :PACKAGE:  ‐‐shared  ast  hello plugin=ksh :LIBRARY: hello.c
       and run [1mnmake install [22mto  compile,  link,  and  install  the
       built‐in  shared  library in [1mlib/ksh/ [22munder [1mPACKAGE_ast[22m.  If
       the built‐in extension uses several [1m.c [22mfiles,  list  all  of
       these on the [1m:LIBRARY: [22mline.

       Otherwise you will have to compile [1mhello.c [22mwith an option to
       pick up the AST include directory (since the  AST  [1m<stdio.h>[0m
       is  required for [1mksh [22mcompatibility) and options required for
       generating shared libraries.  For example, on Linux use this
       to compile:

                               [1mExhibit 3.[0m
       cc  ‐fpic  ‐I$PACKAGE_ast/include/ast ‐c hello.c and use the
       appropriate link line.  It  really  is  best  to  use  [1mnmake[0m
       because  the  2 line Makefile above will work on all systems
       that have [1mksh [22minstalled.

       If you have several built‐ins, it is desirable  to  build  a
       shared library that contains them all.

       The final step is using the built‐in.  This can be done with
       the  [1mksh  [22mcommand  [1mbuiltin[22m.   To  load  the  shared  library
       [1mlibhello.so  [22mfrom the current directory and add the built‐in
       [1mhello[22m, invoke the command,

                               [1mExhibit 4.[0m
       builtin ‐f ./libhello.so hello  The  shared  library  prefix
       ([1mlib  [22mhere) and suffix ([1m.so [22mhere) be omitted; the shell will
       add an appropriate suffix for the system that it is  loading
       from.   If you install the shared library in [1mlib/ksh/[22m, where
       [1m../lib/ksh/ [22mis a directory on [1m$PATH[22m, the command

                               [1mExhibit 5.[0m
       builtin ‐f hello hello will  automatically  find,  load  and
       install  the  built‐in on any system.  Once this command has
       been invoked, you can invoke  [1mhello  [22mas  you  do  any  other
       command.   If you are using [1mlib_init [22mmethod to add built‐ins
       then no arguments follow the [1m−f [22moption.






       It is often desirable to make a command [4mbuilt‐in[24m  the  first
       time  that  it  is  referenced.   The  first  time  [1mhello [22mis
       invoked,  [1mksh  [22mshould  load  and  execute  it,  whereas  for
       subsequent invocations [1mksh [22mshould just execute the built‐in.
       This can be done by creating a file  named  [1mhello  [22mwith  the
       following contents:

                               [1mExhibit 6.[0m
       function hello {
               unset ‐f hello
               builtin ‐f hello hello
               hello "$@" } This file [1mhello [22mneeds to be placed in a
       directory that is in your [1mFPATH [22mvariable, and  the  built‐in
       shared library should be installed in [1mlib/ksh/[22m, as described
       above.


       [4m3.[24m  [4mCODING[24m [4mREQUIREMENTS[24m [4mAND[24m [4mCONVENTIONS[0m

       As mentioned above,  the  entry  point  for  built‐ins  must
       either  be  of  the  form  [1mb_[4m[22mname[24m  or  else be loaded from a
       function named [1mlib_init[22m.  Your built‐ins can call  functions
       from  the  standard  C  library,  the [1mast [22mlibrary, interface
       functions provided by [1mksh[22m,  and  your  own  functions.   You
       should  avoid  using  any global symbols beginning with [1msh_[22m,
       [1mnv_[22m, and [1med_ [22msince these are used by  [1mksh  [22mitself.   [1m#define[0m
       constants  in [1mksh [22minterface files use symbols beginning with
       [1mSH_ [22mand [1mNV_[22m, so avoid using names beginning with these too.

       [4m3.1[24m  [4mHeader[24m [4mFiles[0m

       The development kit provides a portable interface to  the  C
       library  and to libast.  The header files in the development
       kit are compatible with K&R C[3], ANSI‐C[4], and C++[5].

       The  best  thing  to  do  is  to  include  the  header  file
       [1m<shell.h>[22m.   This header file causes the [1m<ast.h> [22mheader, the
       [1m<error.h> [22mheader and the [1m<stak.h> [22mheader to be  included  as
       well  as defining prototypes for functions that you can call
       to get shell services for your builtins.   The  header  file
       [1m<ast.h>  [22mprovides  prototypes  for many [1mlibast [22mfunctions and
       all the symbol and  function  definitions  from  the  ANSI‐C
       headers, [1m<stddef.h>[22m, [1m<stdlib.h>[22m, [1m<stdarg.h>[22m, [1m<limits.h>[22m, and
       [1m<string.h>[22m.   It  also  provides   all   the   symbols   and
       definitions   for   the   POSIX[6]   headers  [1m<sys/types.h>[22m,
       [1m<fcntl.h>[22m,  and  [1m<unistd.h>[22m.   You  should  include  [1m<ast.h>[0m
       instead  of  one  or  more  of these headers.  The [1m<error.h>[0m
       header provides  the  interface  to  the  error  and  option
       parsing   routines   defined  below.   The  [1m<stak.h>  [22mheader
       provides the interface to  the  memory  allocation  routines
       described below.

       Programs  that  want  to use the information in [1m<sys/stat.h>[0m
       should include the file [1m<ls.h> [22minstead.  This  provides  the
       complete POSIX interface to [1mstat() [22mrelated functions even on
       non‐POSIX systems.

       [4m3.2[24m  [4mInput/Output[0m

       [1mksh [22muses [1msfio[22m, the Safe/Fast I/O library[7], to perform  all





       I/O  operations.  The [1msfio [22mlibrary, which is part of [1mlibast[22m,
       provides a superset of the  functionality  provided  by  the
       standard  I/O  library  defined  in  ANSI‐C.  If none of the
       additional functionality is required, and  if  you  are  not
       familiar  with  [1msfio  [22mand  you do not want to spend the time
       learning it, then you can use [1msfio  [22mvia  the  [1mstdio  [22mlibrary
       interface.    The   development   kit  contains  the  header
       [1m<stdio.h> [22mwhich maps [1mstdio [22mcalls to  [1msfio  [22mcalls.   In  most
       instances  the mapping is done by macros or inline functions
       so that there is no overhead.  The man  page  for  the  [1msfio[0m
       library is in an Appendix.

       However, there are some very nice extensions and performance
       improvements in [1msfio [22mand if you plan any major extensions  I
       recommend that you use it natively.

       [4m3.3[24m  [4mError[24m [4mHandling[0m

       For  error  messages  it  is  best  to  use  the [1mast [22mlibrary
       function [1merrormsg() [22mrather that sending output to [1mstderr  [22mor
       the  equivalent  [1msfstderr  [22mdirectly.   Using [1merrormsg() [22mwill
       make  error  message  appear  more  uniform  to  the   user.
       Furthermore,  using  [1merrormsg()  [22mshould make it easier to do
       error  message  translation  for  other  locales  in  future
       versions of [1mksh[22m.

       The first argument to [1merrormsg() [22mspecifies the dictionary in
       which the string will  be  searched  for  translation.   The
       second  argument  to [1merrormsg() [22mcontains that error type and
       value.  The third argument is a [4mprintf[24m style format and  the
       remaining  arguments  are arguments to be printed as part of
       the message.  A new‐line is inserted  at  the  end  of  each
       message  and  therefore,  should  not  appear as part of the
       format string.  The second argument should  be  one  of  the
       following:

       [1mERROR_exit([4m[22mn[24m[1m)[22m: If [4mn[24m is not‐zero, the builtin will exit value
            [4mn[24m after printing the message.

       [1mERROR_system([4m[22mn[24m[1m)[22m: Exit  builtin  with  exit  value  [4mn[24m   after
            printing  the  message.   The  message will display the
            message corresponding to [1merrno [22menclosed within  [1m[ ]  [22mat
            the end of the message.

       [1mERROR_usage([4m[22mn[24m[1m)[22m: Will  generate a usage message and exit.  If
            [4mn[24m is non‐zero, the exit value will be 2.  Otherwise the
            exit value will be 0.

       [1mERROR_debug([4m[22mn[24m[1m)[22m: Will  print  a level [4mn[24m debugging message and
            will then continue.

       [1mERROR_warn([4m[22mn[24m[1m)[22m: Prints a warning message. [4mn[24m is ignored.

       [4m3.4[24m  [4mOption[24m [4mParsing[0m

       The first thing that a built‐in should do is  to  check  the
       arguments for correctness and to print any usage messages on
       standard error.  For consistency with the rest of [1mksh[22m, it is
       best  to use the [1mlibast [22mfunctions [1moptget() [22mand [1moptusage()[22mfor
       this purpose.  The header [1m<error.h> [22mincludes prototypes  for
       these  functions.   The  [1moptget() [22mfunction is similar to the





       System V C library  function  [1mgetopt()[22m,  but  provides  some
       additional   capabilities.    Built‐ins  that  use  [1moptget()[0m
       provide a more consistent user interface.

       The [1moptget() [22mfunction is invoked as

                               [1mExhibit 7.[0m
       int optget(char *[4margv[24m[], const char *[4moptstring[24m)  where  [1margv[0m
       is  the  argument  list  and  [1moptstring  [22mis  a  string  that
       specifies the allowable arguments and additional information
       that  is  used to format [4musage[24m messages.  In fact a complete
       man page in [1mtroff [22mor [1mhtml [22mcan  be  generated  by  passing  a
       usage  string  as  described  by  the [1mgetopts [22mcommand.  Like
       [1mgetopt()[22m, single  letter  options  are  represented  by  the
       letter  itself,  and options that take a string argument are
       followed by  the  [1m:  [22mcharacter.   Option  strings  have  the
       following special characters:

       [1m:    [22mUsed  after a letter option to indicate that the option
            takes an option argument.   The  variable  [1mopt_info.arg[0m
            will  point  to  this value after the given argument is
            encountered.

       [1m#    [22mUsed after a letter option to indicate that the  option
            can   only   take  a  numerical  value.   The  variable
            [1mopt_info.num [22mwill contain this value  after  the  given
            argument is encountered.

       [1m?    [22mUsed  after  a  [1m:  [22mor  [1m# [22m(and after the optional [1m?[22m)  to
            indicate the  the  preceding  option  argument  is  not
            required.

       [1m[[22m...[1m] [22mAfter  a  [1m:  [22mor [1m#[22m, the characters contained inside the
            brackets are used to identify the option argument  when
            generating a [4musage[24m message.

       [4mspace[24m The  remainder  of  the  string will only be used when
            generating usage messages.

       The [1moptget() [22mfunction returns the matching option letter  if
       one  of  the  legal  option is matched.  Otherwise, [1moptget()[0m
       returns

       [1m’:’  [22mIf there is  an  error.   In  this  case  the  variable
            [1mopt_info.arg [22mcontains the error string.

       [1m0    [22mIndicates   the   end   of   options.    The   variable
            [1mopt_info.index  [22mcontains  the   number   of   arguments
            processed.

       [1m’?’  [22mA  usage  message has been required.  You normally call
            [1moptusage() [22mto generate and display the usage message.

       The following is an example of the option parsing portion of
       the [1mwc [22mutility.

                               [1mExhibit 8.[0m
       #include                  <shell.h>                 while(1)
       switch(n=optget(argv,"xf:[file]"))   {           case   ’f’:
                       file  = opt_info.arg;                 break;
               case    ’:’:                    error(ERROR_exit(0),





       opt_info.arg);                   break;           case  ’?’:
                       error(ERROR_usage(2),         opt_info.arg);
                       break; }

       [4m3.5[24m  [4mStorage[24m [4mManagement[0m

       It  is  important  that  any memory used by your built‐in be
       returned.  Otherwise, if your built‐in is called frequently,
       [1mksh  [22mwill  eventually  run  out of memory.  You should avoid
       using  [1mmalloc()  [22mfor  memory  that  must  be  freed   before
       returning  from  you  built‐in, because by default, [1mksh [22mwill
       terminate you built‐in in the event of an interrupt and  the
       memory will not be freed.

       The  best  way  to  to  allocate  variable  sized storage is
       through calls to the  [1mstak  [22mlibrary  which  is  included  in
       [1mlibast [22mand which is used extensively by [1mksh [22mitself.  Objects
       allocated with the [1mstakalloc() [22mfunction are freed  when  you
       function  completes  or aborts.  The [1mstak [22mlibrary provides a
       convenient way to build variable length  strings  and  other
       objects  dynamically.   The man page for the [1mstak [22mlibrary is
       contained in the Appendix.

       Before [1mksh [22mcalls each built‐in command, it saves the current
       stack  location and restores it after it returns.  It is not
       necessary to save and restore the stack location in  the  [1mb_[0m
       entry function, but you may want to write functions that use
       this stack are restore it when leaving  the  function.   The
       following  coding  convention  will  do this in an efficient
       manner:

                               [1mExhibit 9.[0m
       [4myourfunction[24m() {
               char    *savebase;
               int     saveoffset;
               if(saveoffset=staktell())
                       savebase = stakfreeze(0);
               ...
               if(saveoffset)
                       stakset(savebase,saveoffset);
               else
                       stakseek(0); }


       [4m4.[24m  [4mCALLING[24m [1mksh [4m[22mSERVICES[0m

       Some of the more interesting  applications  are  those  that
       extend  the  functionality  of  [1mksh  [22min application specific
       directions.  A  prime  example  of  this  is  the  X‐windows
       extension  which adds builtins to create and delete widgets.
       The [1mnval [22mlibrary is used to interface with  the  shell  name
       space.   The  [1mshell  [22mlibrary  is  used to access other shell
       services.

       [4m4.1[24m  [4mThe[24m [4mnval[24m [4mlibrary[0m

       A great deal of power is derived from  the  ability  to  use
       portions  of  the  hierarchal variable namespace provided by
       [1mksh‐93 [22mand turn these names into active objects.

       The [1mnval [22mlibrary is used to interface with shell  variables.





       A  man  page  for this file is provided in an Appendix.  You
       need to include the header [1m<nval.h> [22mto access the  functions
       defined  in the [1mnval [22mlibrary.  All the functions provided by
       the [1mnval [22mlibrary begin with  the  prefix  [1mnv_[22m.   Each  shell
       variable  is  an  object  in  an  associative  table that is
       referenced by name.  The type  [1mNamval_t*  [22mis  pointer  to  a
       shell  variable.   To operate on a shell variable, you first
       get a handle to the variable with the [1mnv_open() [22mfunction and
       then supply the handle returned as the first argument of the
       function that provides an operation on  the  variable.   You
       must call [1mnv_close() [22mwhen you are finished using this handle
       so that the space can be freed once the value is unset.  The
       two  most  frequent  operations  are to get the value of the
       variable,  and  to  assign  value  to  the  variable.    The
       [1mnv_getval() [22mreturns a pointer the the value of the variable.
       In some cases the pointer returned is to a region that  will
       be  overwritten  by the next [1mnv_getval() [22mcall so that if the
       value isn’t used immediately, it  should  be  copied.   Many
       variables   can   also   generate   a  numeric  value.   The
       [1mnv_getnum() [22mfunction returns a numeric value for  the  given
       variable   pointer,  calling  the  arithmetic  evaluator  if
       necessary.

       The [1mnv_putval() [22mfunction is used to assign a new value to  a
       given  variable.   The  second  argument  to [1mputval() [22mis the
       value to be assigned and the third argument is a [4mflag[24m  which
       is used in interpreting the second argument.

       Each  shell  variable  can have one or more attributes.  The
       [1mnv_isattr() [22mis used to test for the existence of one or more
       attributes.   See  the  appendix  for  a  complete  list  of
       attributes.

       By default, each shell variable passively stores the  string
       you  give  with with [1mnv_putval()[22m, and returns the value with
       [1mgetval()[22m.  However, it is possible to turn any node into  an
       active  entity  by  assigning  functions  to it that will be
       called whenever [1mnv_putval() [22mand/or  [1mnv_getval()  [22mis  called.
       In  fact  there are up to five functions that can associated
       with each variable to override  the  default  actions.   The
       type [1mNamfun_t [22mis used to define these functions.  Only those
       that are non‐[1mNULL [22moverride the default actions.  To override
       the  default  actions,  you  must  allocate  an  instance of
       [1mNamfun_t[22m, and then assign the functions  that  you  wish  to
       override.    The   [1mputval()   [22mfunction   is  called  by  the
       [1mnv_putval()  [22mfunction.   A  [1mNULL  [22mfor  the  [4mvalue[24m   argument
       indicates  a  request  to  unset  the  variable.   The  [4mtype[0m
       argument might contain the [1mNV_INTEGER [22mbit so you  should  be
       prepared  to  do  a  conversion  if necessary.  The [1mgetval()[0m
       function is called by [1mnv_getval() [22mvalue and  must  return  a
       string.    The   [1mgetnum()  [22mfunction  is  called  by  by  the
       arithmetic evaluator and must return  double.   If  omitted,
       then  it  will  call [1mnv_getval() [22mand convert the result to a
       number.

       The functionality of a variable can further be increased  by
       adding  discipline functions that can be associated with the
       variable.  A discipline function allows a script  that  uses
       your   variable   to   define   functions   whose   name  is
       [4mvarname[24m[1m.[4m[22mdiscname[24m where [4mvarname[24m is the name of the  variable,
       and  [4mdiscname[24m  is the name of the discipline.  When the user





       defines such a function,  the  [1msettrap()  [22mfunction  will  be
       called  with the name of the discipline and a pointer to the
       parse tree corresponding to the  discipline  function.   The
       application  determines  when  these  functions are actually
       executed.  By default, [1mksh [22mdefines [1mget[22m, [1mset[22m,  and  [1munset  [22mas
       discipline functions.

       In addition, it is possible to provide a data area that will
       be passed as an argument to each of these functions whenever
       any  of  these  functions are called.  To have private data,
       you need to define and allocate a structure that looks like

                              [1mExhibit 10.[0m
       struct [4myours[24m {
               Namfun_t        fun;         [4myour_data_fields[24m; };

       [4m4.2[24m  [4mThe[24m [4mshell[24m [4mlibrary[0m

       There are several functions that are used by [1mksh [22mitself that
       can also be called from built‐in commands.  The man page for
       these routines are in the Appendix.

       The [1msh_addbuiltin() [22mfunction can be used to  add  or  delete
       builtin  commands.   It  takes the name of the built‐in, the
       address of the function that implements the built‐in, and  a
       [1mvoid*  [22mpointer  that  will be passed to this function as the
       third agument whenever  it  is  invoked.   If  the  function
       address  is  [1mNULL[22m,  the  specified built‐in will be deleted.
       However, special built‐in functions  cannot  be  deleted  or
       modified.

       The  [1msh_fmtq()  [22mfunction takes a string and returns a string
       that is quoted as necessary so that it can be used as  shell
       input.   This function is used to implement the [1m%q [22moption of
       the shell built‐in [1mprintf [22mcommand.

       The [1msh_parse() [22mfunction returns a parse  tree  corresponding
       to  a  give  file  stream.   The  tree  can  be  executed by
       supplying it as the first argument to the [1msh_trap() [22mfunction
       and   giving   a   value   of  [1m1  [22mas  the  second  argument.
       Alternatively, the [1msh_trap() [22mfunction can parse and  execute
       a  string  by  passing  the string as the first argument and
       giving [1m0 [22mas the second argument.

       The [1msh_isoption() [22mfunction can be used to set to see whether
       one or more of the option settings is enabled.




















                                [4mREFERENCES[0m

         1. [4mPOSIX[24m   [4m−[24m   [4mPart[24m  [4m2:[24m  [4mShell[24m  [4mand[24m  [4mUtilities,[24m  IEEE  Std
            1003.2‐1992, ISO/IEC 9945‐2:1993.

         2. Glenn Fowler, [4mA[24m [4mCase[24m [4mfor[24m [4mmake[24m, Software ‐ Practice  and
            Experience, Vol. 20 No. S1, pp. 30‐46, June 1990.

         3. Brian  W.  Kernighan  and Dennis M. Ritchie, [4mThe[24m [4mC[24m [4mPro-[0m
            [4mgramming[24m [4mLanguage[24m, Prentice Hall, 1978.

         4. American National Standard for  Information  Systems  −
            Programming Language − C, ANSI X3.159‐1989.

         5. Bjarne Stroustroup, [4mC++[24m, Addison Wesley, xxxx

         6. [4mPOSIX[24m  [4m−[24m  [4mPart[24m [4m1:[24m [4mSystem[24m [4mApplication[24m [4mProgram[24m [4mInterface,[0m
            IEEE Std 1003.1‐1990, ISO/IEC 9945‐1:1990.

         7. David Korn and Kiem‐Phong Vo, [4mSFIO[24m [4m‐[24m  [4mA[24m  [4mSafe/Fast[24m  [4mIn-[0m
            [4mput/Output[24m  [4mlibrary,[24m  Proceedings of the Summer Usenix,
            pp. , 1991.












































