Update the changelog

[opencv] / apps / Hawk / CVEiCL / EiC / eic.man

.TH EiC 1 "25 March 1999"\r
.SH NAME\r
\r
eic - An embeddable/extensible interactive bytecode C interpreter\r
\r
\r
.SH SYNOPSIS\r
\r
\fB eic [-Ipath] [-Dname[=var]] -[hHvVcCrR] [file] [fileargs] \fP\r
\r
.SS Options\r
\r
C preprocessor directives:\r
   -Ipath      search for include files in path\r
   -Dname      define a symbolic name to the value 1\r
   -Dname=var  define a symbolic name to the value var\r
                    Note, there is no spaces allowed\r
EiC directives:\r
   -h -H       causes this usage to be displayed\r
   -v -V       print EiC's Log information\r
   -p          showline\r
   -P          show path of include files\r
   -t -T       turns trace on\r
   -c -C       turns timer on\r
   -e          echo HTML mode\r
   -r          restart EiC. Causes EiC to be re initiated\r
                       from the contents of EiChist.lst file\r
  -R          same as `r', but prompts the user to accept\r
                       or reject each input line first\r
  -s -S       run silently\r
  -f          run in script mode\r
  -n          no history file\r
  -N          don't use any startup.h files\r
  -A          Non-interactive-mode\r
  file        EiC will execute `file' and then stop; for example:\r
                      % eic foo.c \r
  fileargs    command line arguments, which get passed onto file\r
\r
\r
.SH BASICS\r
\r
To exit EiC enter `:exit', that is:\r
\r
  EiC >  :exit\r
\r
\r
.SH DESCRITION\r
\r
EiC can be run in several different modes: (1) interactively, (2)\r
non-interactively (3) in scripting mode and (4) it can be embedded in other\r
systems.\r
\r
.SH EiC's INTERACTIVE MODE\r
\r
In interactive mode, the user enters commands, or immediate commands, at the\r
EiC prompt. Each immediate instruction produces a type, even if the type is\r
void; as for example, C statements, declarations etc. All resulting type\r
values are displayed:\r
\r
.Sx 3\r
  EiC 1> 3*55.5;\r
          166.5\r
  EiC 2> "hello, world!";\r
          hello, world!\r
  EiC 3> int i;\r
          (void)\r
  EiC 4> for(i=0;i<10;i++);\r
          (void)\r
  EiC 5> i;\r
          10\r
  EiC 6> struct {int a; double b[3];} ab = { 5,{0,1,2}};\r
          (void)\r
  EiC 7> ab;\r
          {5,Array}\r
  EiC 8> ab.a = 3;\r
          3\r
  EiC 9> ab.b[2];\r
          2\r
  EiC 10> #include <stdio.h>\r
          (void)\r
  EiC 11> printf("hello\\n");\r
  hello\r
          6\r
.Ex\r
\r
.SH EiC IS POINTER SAFE\r
\r
EiC is also pointer safe. This means EiC catches most types of array bound\r
violations; for example (for brevity, some output has been deleted):\r
\r
.Sx 3\r
   EiC 1> int a[10], *p, i;\r
   EiC 2> a[10];\r
   READ: attempted beyond allowed access area\r
\r
   EiC 3> p = &a[5];\r
   EiC 4> p[-5];\r
   EiC 5> p[-6];\r
   READ: attempted before allowed access area\r
 \r
   EiC 6> p[4];\r
   EiC 7> p[5];\r
   READ: attempted beyond allowed access area\r
 \r
   EiC 8> *(p+100);\r
   READ: attempted beyond allowed access area\r
 \r
   EiC 9> p = malloc(5*sizeof(int));\r
   EiC 10> *(p+100);\r
   READ: attempted beyond allowed access area\r
 \r
   EiC 11> for(i=0;i<100;i++) *p++ = i;\r
   WRITE: attempted beyond allowed access area\r
.Ex\r
\r
\r
To detect array bound violations as efficiently as possible, EiC does not\r
concern it self with the values held or produced by pointers, it only\r
worries about address values when they are either referenced or\r
dereferenced:\r
\r
.Sx 3\r
    EiC 1> int a, *p;\r
    EiC 2> p = &a;\r
    EiC 3> p+10;    // okay, no problems\r
    EiC 4> *(p+10); // try to read or write to the address\r
    READ: attempted beyond allowed access area\r
.Ex\r
\r
.SH EiC HOUSE KEEPING COMMANDS\r
\r
Besides parsing C or C preprocessor commands, EiC has it\r
own house keeping commands. House keeping commands are communicated\r
via lines beginning with a colon:\r
\r
 EiC 1> :help\r
\r
.SH  EiC INTERACTIVE COMMAND SUMMARY\r
\r
.TP \r
\fB:-I path\fP       \r
Append path to the include-file search list.\r
.TP\r
\fB:-L\fP\r
List search paths.\r
.TP\r
\fB:-R path \fP\r
Remove path from the include-file search list.\r
.TP\r
\fB:clear fname\fP\r
Removes the contents of file fname from EiC.\r
.TP\r
\fB :exit\fP\r
Terminates an EiC session.\r
.TP\r
\fB :files\fP\r
Display the names of all included files.\r
.TP\r
\fB :files fname\fP\r
Summarize the contents of the included file `fname'.\r
.TP\r
\fB :help\fP\r
Display summary of EiC commands.\r
.TP\r
\fB :history\fP\r
List the history of all input commands.\r
.TP\r
\fB :includes\fP\r
Display path of include files when loaded.\r
.TP\r
\fB :interpreter\fP\r
Execute input commands. By default it is on.\r
.TP\r
\fB :listcode\fP\r
List stack code.\r
.TP\r
\fB :listcode <linenums>\fP\r
List stack code with associated line numbers.\r
.TP\r
\fB :memdump\fP\r
Show potential memory leaks.\r
.TP\r
\fB :rm dddd\fP\r
Remove memory item dddd, which is a constant integer value.\r
.TP\r
\fB :rm f\fP\r
Removes f's definition from the symbol tables.\r
.TP\r
\fB :show f\fP\r
Shows type or  macro definition of `f'.\r
.TP\r
\fB :showline\fP\r
Show input line after macro expansion.\r
.TP\r
\fB :status\fP\r
Display the status of the toggle switches.\r
.TP\r
\fB :timer\fP\r
Time in seconds of execution.\r
.TP\r
\fB :trace\fP\r
Trace function calls and line numbers during code execution.\r
.TP\r
\fB :trace funcs\fP\r
Trace function calls only during code execution.\r
.TP\r
\fB :variables\fP\r
Display declared variables and interpreter-ed function names.\r
.TP\r
\fB :variables tags\fP\r
Display the tag identifiers.\r
.TP\r
\fB :variables <type-name>\fP\r
Display variables of type `type-name'. For example,\r
\r
        EiC > :show float []\r
\r
 will show all the variables that are declared to be an\r
array of floats\r
.TP\r
\fB :verbose\fP\r
Suppresses EiC's copyright and warning messages on start up.\r
\r
 \r
\r
\r
.SH RUNNING EiC NON-INTERACTIVELY\r
\r
EiC can also be run non-interactively or in batch mode, where it is possible\r
to run C programs in a typical interpreter style. It can also handle\r
programs that accept command line arguments, as seen from the toy example in\r
main2.c:\r
\r
.Sx 3\r
     #include <stdio.h>\r
     int main(int argc, char **argv)\r
     {\r
         while(argc--)\r
             printf("%s\n",*argv++);\r
         return 0;\r
     }\r
.Ex\r
\r
The first parameter, argc, holds the number of argument strings passed to\r
the program and is always at least one. The second parameter, argv, is an\r
array of unspecified size of pointers to the input strings, which the first\r
one will be the name of the program being executed:\r
\r
.Sx 3\r
     % eic main2.c 123 hello -Dworld this.and.that\r
     main2.c\r
     123\r
     hello\r
     -Dworld\r
     this.and.that\r
\r
.Ex\r
.SH EiC's SCRIPTING LANGUAGE\r
\r
In non-interactive mode, EiC runs generally like a typical interpreter,\r
accepting input from a complete C program. However, EiC is also a scripting\r
language. Below is an example of an EiC script, called hello.eic:\r
\r
.Sx 3\r
     #!/usr/local/bin/eic -f\r
\r
     #include <stdio.h>\r
     printf(" ** Hello from EiC's script mode. **\n");\r
.Ex\r
\r
The -f command-line switch, informs EiC to run in script mode. In script\r
mode, EiC will treat all lines beginning with `#' and which cannot be\r
interpreted as a preprocessor directive as a comment. To run the above\r
script and assuming that it's executable (chmod +x hello.eic):\r
.Sx 3\r
     % hello.eic\r
      ** Hello from EiC's script mode. **\r
     %\r
.Ex\r
\r
Another example of a more extensive EiC script is given in script1.eic:\r
\r
.Sx 3\r
  1  #!/usr/local/bin/eic -f\r
  2  #include <stdio.h>\r
  3\r
  4  // example of control of flow\r
  5  int i;\r
  6  int isqr(int x) { return x*x; }\r
  7  for(i=0;i<4;i++)\r
  8     printf("%d^2 =  %d\n",i,isqr(i));\r
  9  switch(i) {\r
 10     case 4: printf(" good\n\n"); break;\r
 11     default: printf(" bad\n\n");\r
 12  }\r
 13  // example of some file stuff;\r
 14  // read in some tools\r
 15  #include "tools/nxtString.c"\r
 16  FILE *fp = fopen(_Argv[0],"r");\r
 17  char *p;\r
 18  while((p=nxtString(fp)))\r
 19          printf("%s ",p);\r
 20  fclose(fp);\r
 21  printf("\n\n");\r
 22  // further example of using command line args\r
 23  if(_Argc) { // this is always true\r
 24     int k=0;\r
 25     printf("Processing command line arguments\n");\r
 26     for(k=0;k<_Argc;k++) {\r
 27        printf("%s\n",_Argv[k]);\r
 28     }\r
 29  } else\r
 30     printf("OOPS, an internal error has occurred\n");\r
.Ex\r
 \r
An EiC shell script is interpreted from the top to the bottom. First the\r
code is compiled to bytecode, in its entirety, and then run. After this,\r
control will be parsed to the main function if it exists. However, it is not\r
illegal to have a script that does not include the definition of a main\r
function. If the EiC directive :exit, which is the directive that terminates\r
an EiC interactive session, is present, it will cause the interpretation of\r
the script to halt at the position :exit is encounted, and nothing will have\r
happened other than having the code up to :exit operator compiled and parsed\r
- but it will not have been executed. Generally, the code for a function is\r
not executed until it is called, see line 8. Command line arguments are\r
passed into to the global variables _Argc and _Argv, see lines 16 and 23 to\r
30. For example:\r
\r
.Sx 3\r
     % script1.eic  abc 123 -DHELP\r
.Ex\r
\r
Implies that:\r
\r
.Sx 3     _Argc = 4,                 _Argv[0] = "sript1.eic"\r
     _Argv[1] = "abc"           _Argv[2] = "123"\r
     _Argv[3] = "-DHELP"        _Argv[4] = NULL\r
\r
.Ex 3\r
\r
.SH EMBEDDING OR LINKING TO EiC\r
\r
To Link against EiC you first need to build the source distribution. Then\r
linking to EiC from aother programs is done by linking against the EiC\r
libraries (libeic and libstdClib) in EiC/lib. In the directory\r
EiC/main/examples there is an example program called embedEiC.c that links\r
to EiC. Build and run it from the EiC/main/examples directory by entering\r
(assuming EiC has been installed in /usr/local/EiC):\r
\r
.Sx 3\r
     % gcc embedEiC.c -L/usr/local/EiC/lib -leic -lstdClib -lm\r
     % a.out\r
.Ex 3\r
\r
For communicating commands to EiC from another program there are two\r
functions supplied:\r
\r
     int EiC_run(int argc, char **argv);\r
\r
and\r
\r
     void EiC_parseString(char *command, ...);\r
\r
The EiC_run function is used to run C source files. The EiC_parseString\r
function is used to pass C or preprocessor commands to EiC via a string,\r
such as:\r
\r
.Sx 3\r
     EiC_parseString("#include <stdio.h>");\r
     EiC_parseString("int a = 10,i;");\r
     EiC_parseString("for(i=0;i<a;i++)"\r
                     "       printf(\\"%%d\\\\n\\",i);");\r
.Ex\r
\r
At present the main facility for sharing data between EiC and other\r
applications is via the address operator @:\r
\r
     int a @ dddd;\r
\r
The above defines a to be an integer and is stored at address dddd, which\r
must be an integral constant. The constant address dddd is not simply an\r
address conjured up. Its purpose is to enable access to data, or even\r
functions, defined in compiled code.\r
\r
When applied to function definitions, the limitation at this stage is that\r
the function must take void arguments and return void:\r
\r
          void foo(void) @ dddd;\r
\r
The above defines foo to be a builtin function located at address dddd. For\r
example:\r
\r
.Sx 3\r
  int foo[5] = {1,2,3,4,5};\r
  void fooey(void) {printf("fooey called\n");}\r
          ....\r
  EiC_parseString("int foo[5] @ %ld;",(long)foo);\r
  EiC_parseString("void fooey(void) @ %ld;",(long)fooey);\r
.Ex\r
\r
Further, int foo[5] @ 1256; defines foo to be an array of 5 ints mapped at\r
the specified virtual address and the usual pointer safety rules apply; that\r
is, foo[5]; will be caught as an illegal operation.\r
\r
Also, you can pass in data to EiC via setting variables and you can get EiC\r
to output data to a file. In a future release of EiC, more facilities are\r
expected to be added for sharing data between EiC and its embedding system.\r
\r
With respect to EiC_run, to run the file "myfile.c" and pass it the command\r
line arguments "hello" and "world", the following sequence of commands would\r
be used.\r
\r
.Sx 3\r
     char *argv[] = {"myfile.c", "hello", "world"};\r
     int  argc = sizeof(argv)/sizeof(char*);\r
     EiC_run(argc, argv);\r
.Ex\r
.SH EiC vs C\r
\r
Because EiC can be run interactively, it differs from C in several ways. In\r
this section I will outline what is currently missing from EiC and how EiC\r
differs from ISO C.\r
\r
Although, EiC can parse almost all of the C programming language, right up\r
front it is best to mention what is currently lacking or different:\r
\r
.TP\r
\fB1.\fP   \r
EiC is pointer safe. It detects many classes of memory read and write\r
violations. Also, to help in interfacing compiled library code to EiC,\r
EiC uses the optional pointer-qualifiers safe and unsafe.\r
\r
.TP\r
\fB4.\fP   \r
Structure  bit fields are not supported.\r
\r
.TP\r
\fB5.\fP   \r
While structures and unions can be returned from and passed by value to\r
functions, it is illegal in EiC to pass a structure or a union to a\r
variadic function (that is, a function that takes a variable number of\r
arguments):\r
\r
.Sx 3\r
 EiC 1> struct stag {int x; double y[5];} ss;\r
 EiC 2> void foo(const char *fmt, ...);\r
 EiC 3> foo("",ss);\r
 Error: passing a struct/union to variadic function foo\r
.Ex\r
\r
.TP\r
\fB6.\fP \r
The C concept of linkage is not supported. This is because, EiC does\r
not export identifiers to a linker - as does a true C compiler. EiC\r
works from the concept of a single translation unit.\r
\r
.TP\r
\fB7.\fP   \r
EiC does not parse preprocessor numbers , which aren't valid numeric\r
constants; for example, 155.6.8, which is an extended floating point\r
constants, will cause an error.\r
\r
.TP\r
\fB8.\fP   \r
EiC supports both standard C like comments /* ... */ and C++ style\r
comments. Also, when EiC is run in script mode, it treats all lines\r
that start with `#' and which can't be interpreted as a preprocessor\r
directive as a comment.\r
\r
.TP\r
\fB9.\fP   \r
There are no default type specifiers for function return values. In EiC\r
it is illegal to not explicitly state the return type of a function:\r
\r
.Sx 3\r
 foo() { ... } // error: missing return type \r
 int foo() { ... } // correct, \r
.Ex\r
\r
.TP\r
\fB10.\fP  \r
In addition to function definitions and declarations with an empty\r
parameter list, EiC only supports prototype declarations and\r
definitions:\r
\r
.Sx 3\r
 // Empty parameter list allowed \r
 int foo(); \r
\r
 // Illegal: old style C declaration\r
 int f(value) int value { ... } \r
\r
 // Allowed, prototype declaration\r
 int f(int); \r
\r
 // Allowed, full prototype declaration\r
 int f(int value); \r
.Ex\r
\r
.TP\r
\fB11.\fP  \r
EiC does not support trigraph sequences, wide characters or wide\r
strings: nor does it support the standard header <locale.h>.\r
\r
.TP\r
\fB12.\fP  \r
EiC's preprocessor lacks the #line directive.\r
\r
.TP\r
\fB13.\fP  \r
For convenience, EiC allows the #include directive to have an extra\r
form, which permits the parsing of a token-sequence in the form\r
#include filename; that is, without enclosing double quotes or angled\r
brackets.\r
\r
.TP\r
\fB14.\fP  \r
Besides parsing preprocessor directives or C statements, EiC also\r
parses its own internal house keeping language. House keeping commands\r
are communicated to EiC via lines that begin with a colon.\r
\r
\r
\r
.SH SEE ALSO\r
\r
        http://www.anarchos.com/eic\r
\r
\r
\r
\r
\r
\r
\r
\r
\r