home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ida35bc.zip / IDC.TXT < prev    next >
Text File  |  1996-01-29  |  18KB  |  456 lines
  1.  
  2. IDC language is a C-like language. It has the same lexical tokens as C does:
  3. character set,constants,identifiers,keywords, etc. All variables in IDC are
  4. automatic local variables (sic!). A variable can contain:
  5.   - a 32-bit signed long integer
  6.   - a character string (max 255 characters long)
  7. A program in IDC consists of function declarations. A function in IDC returns
  8. a value. There are 2 kinds of functions:
  9.   - built-in functions
  10.   - user-defined functions
  11.  
  12. A function is declared in this way:
  13.  
  14.   static func(arg1,arg2,arg3) {
  15.     ...
  16.   }
  17.  
  18. where arg1,arg2,arg3 are the function parameters,'func' is the function name.
  19. It is not nesessary to specify the types of the parameters because any variable
  20. can contain a string or a number.
  21.  
  22. A variable is declared in this way:
  23.  
  24.   auto var;
  25.  
  26. This declaration introduces a variable named 'var'. It can contain a string
  27. or a number. All C and C++ keywords are reserved and cannot be used as
  28. a variable name. The variable is defined up to end of function.
  29.  
  30. In IDC there are the following statements:
  31.   if (expression) statement
  32.   if (expression) statement else statement
  33.   for ( expr1; expr2; expr3 ) statement
  34.   while (expression) statement
  35.   do statement while (expression);
  36.   break;
  37.   continue;
  38.   return <expr>;
  39.   return;                    the same as 'return 0;'
  40.   { statements... }
  41.   expression;                     (expression-statement)
  42.   ;                         (empty statement)
  43.  
  44. In expressions you can use almost all C operations except:
  45.   ++,--
  46.   complex assigment operations as '+='
  47.   , (comma operation)
  48.  
  49. You can use the following construct in the expressions:
  50.  
  51.   [ s, o ]
  52.  
  53. This means to calculate linear (effective) address for segment 's' offset 'o'.
  54. The calculation is made using the following formula:
  55.  
  56.   (s << 4) + o
  57.  
  58. If a string constant is specified as 's', it denotes a segment by its name.
  59.  
  60. There are 2 type conversion operations:
  61.  
  62.   long( expr )
  63.   char( expr )
  64.  
  65. However, all type conversions are made automatically:
  66.   - operand(s) are converted to 'long'
  67.   - the operation is performed.
  68.  
  69. Exceptions:
  70.  1. binary '+' operation. If the first operand is string type, the second
  71.     operand is converted to a string and the operands are concatenated.
  72.  2. relational operations (such as ==,!=, etc.) If both operands are strings,
  73.     the string comparision is performed, otherwise - they are converted to
  74.     numbers.
  75.  
  76. Built-in functions
  77. ------------------
  78.  
  79. The following conventions are used in this list:
  80.   'ea' is a linear address
  81.   'success' is 0 if a function failed, 1 otherwise
  82.   'void' means that function returns no meaningful value (always 0)
  83.  
  84.  All function parameter conversions are made automatically.
  85.  
  86. A. Utility functions
  87. --------------------
  88. long    MK_FP        (long seg,long off);    // the same as [ seg, off ]
  89. long    _lpoke        (long RAMea,long value); // poke a long integer into RAM
  90.                         // returns old value
  91. long    _poke        (long RAMea,long value);// poke a byte into RAM
  92.                         // returns old value
  93. long    _peek        (long RAMea);        // get a byte from RAM
  94. char    form        (char format,long value); // works as sprintf, takes only
  95.                         // 1 parameter. Specifying %f as a parameter
  96.                         // will lead to abnormal program termination
  97.                         // with bad consequences.
  98.                         // The resulting string should
  99.                         // be less than 255 characters.
  100. char    substr        (char str,long x1,long x2); // substring [x1..x2-1]
  101.                         // if x2 == -1, then till end of line
  102. long    strstr        (char str,char substr);    // find a substring, -1 - not found
  103. long    strlen        (char str);        // calculate length
  104. long    xtol        (char str);        // ascii hex -> number
  105.                         // (use long() for atol)
  106. success    AssignKey    (char action,long key);    // assign a key to an action
  107.                         // meaningful only before the main
  108.                         // menu is constructed
  109. success    Jump        (long ea);        // move cursor to ea
  110.                         // screen is refreshed at the end
  111.                         // of IDC execution
  112. void    Wait        ();            // Wait for the end of
  113.                         // autoanalysis
  114. void    Exit        (long code);        // Exit to DOS
  115.  
  116. B. Functions that change program representation
  117. -----------------------------------------------
  118. void    DeleteAll    ();            // delete ALL information
  119.                         // about the program
  120. long    MakeCode    (long ea);        // convert to instruction
  121.                         // returns number of bytes
  122.                         // occupied by the instruction
  123. long    AnalyseArea    (long sEA,long eEA);    // analyse area and try to
  124.                         // convert to code all bytes
  125.                         // Returns 1-ok,0-CtrlBreak pressed
  126. success    MakeName    (long ea,char name);    // assign a name to a location
  127. success    MakeComm    (long ea,char comment);    // give a comment
  128. success    MakeRptCmt    (long ea,char comment);    // give a repeatable comment
  129. success    MakeArray    (long ea,long nitems);    // convert to an array
  130. success    MakeStr        (long ea,long size);    // convert to ASCII string
  131. success    MakeByte    (long ea);        // convert to byte
  132. success    MakeWord    (long ea);        // convert to word
  133. success    MakeDword    (long ea);        // convert to double-word
  134. success    MakeQword    (long ea);        // convert to quadro-word
  135. success    MakeTbyte    (long ea);        // convert to 10 bytes (tbyte)
  136. void    MakeUnkn    (long ea,long expand);    // convert to 'unknown'
  137.                         // expand==1 => undefine consequent
  138.                         // instructions too
  139. success    OpDec        (long ea);        // operands are decimal
  140. success    OpChar        (long ea);        // operands are characters
  141. success    OpOffset    (long ea,long segbase);    // operands are offsets
  142.                         // if segbase==-1, then operands aren't offsets
  143. success    OpSegment    (long ea);        // operands are segments
  144. success    OpNum        (long ea);        // operands are numbers
  145. success    OpAlt1        (long ea,char opnd);    // manually enter 1st operand
  146. success    OpAlt2        (long ea,char opnd);    // manually enter 2nd operand
  147. void    MakeVar        (long ea);        // the location is 'variable'
  148. success    MakeProc    (long ea,long fl);    // fl=0: no proc, fl=1: near proc, fl=2: far proc
  149. success    MakeEndp    (long ea,long fl);    // fl=0: no endp,1: endp
  150. void    ExtLinA        (long ea,long n,char line); // insert an additional line before the generated ones
  151. void    ExtLinB        (long ea,long n,char line); // insert an additional line after the generated ones
  152. void    DelExtLnA    (long ea,long n);    // delete an additional line before the generated ones
  153. void    DelExtLnB    (long ea,long n);    // delete an additional line aftr  the generated ones
  154. success    JmpTable    (long jmpea,long tableea,long nitems);    // define a jump table
  155. void    PatchByte    (long ea,long value);    // change a byte
  156. void    SetFlags    (long ea,long flags);    // change internal flags for ea
  157. success    SetReg        (long ea,char reg,long value); // set value of segment register
  158.  
  159. C. Functions that produce output files
  160. --------------------------------------
  161. void    WriteMap    (char file);        // produce a .map file
  162. void    WriteTxt    (char file,long ea1,long ea2); // produce an .asm file
  163. void    WriteExe    (char file);        // produce an executable file
  164.  
  165. D. Informational functions
  166. --------------------------
  167. long    GetFlags    (long ea);        // get internal flags for ea
  168. long    Byte        (long ea);        // get a byte at ea
  169. long    Word        (long ea);        // get a word at ea
  170. long    Dword        (long ea);        // get a double-word at ea
  171. long    LocByName    (char name);        // -1 - no such name
  172. long    SegByBase    (long base);        // -1 - no such segment
  173. long    MinEA        ();            // the minimal address defined in the program
  174. long    MaxEA        ();            // the maximal address defined in the program
  175. long    BeginEA        ();            // where execution starts
  176. long    ScreenEA    ();            // the current screen ea
  177. long    SelStart    ();            // the selected area start ea
  178.                         // -1 - no selected area
  179. long    SelEnd        ();            // the selected area end ea
  180.                         // -1 - no selected area
  181. long    GetReg        (long ea,char reg);    // get segment register value
  182.                         // -1 - undefined or error
  183. long    FirstSeg    ();            // returns start of the first
  184.                         // segment, -1 - no segments
  185. long    NextSeg        (long ea);        // returns start of the next
  186.                         // segment, -1 - no more segs
  187. long    SegStart    (long ea);        // returns start of the segment
  188.                         // -1 if bad address passed
  189. long    SegEnd        (long ea);        // return end of the segment
  190.                         // this address doesn't belong
  191.                         // to the segment
  192.                         // -1 if bad address passed
  193. char    SegName        (long ea);        // returns name of the segment
  194.                         // "" if bad address passed
  195. long    NextAddr    (long ea);        // returns next defined address
  196.                         // -1 if no such address exists
  197. long    PrevAddr    (long ea);        // returns prev defined address
  198.                         // -1 if no such address exists
  199. long    NextHead    (long ea);        // returns next defined item address
  200.                         // -1 if no such address exists
  201. long    PrevHead    (long ea);        // returns prev defined item address
  202.                         // -1 if no such address exists
  203. long    NextNotTail    (long ea);        // returns next not tail address
  204.                         // -1 if no such address exists
  205. long    PrevNotTail    (long ea);        // returns prev not tail address
  206.                         // -1 if no such address exists
  207. long    ItemEnd        (long ea);        // returns address past end of
  208.                         // the item
  209. long    ItemSize    (long ea);        // returns item size, min answer=1
  210. char    Name        (long ea);        // get name of the byte
  211. char    GetMnem        (long ea);        // get instruction name
  212. char    GetOpnd        (long ea,long n);    // get instruction operand
  213.                         // n=0 - first operand
  214. long    GetOpType    (long ea,long n);    // get operand type
  215.                         // n=0 - first operand
  216.                         // Returns:
  217.                         // -1    bad operand number passed
  218.                         // 0    None
  219.                         // 1    General Register (al,ax,es,ds...)
  220.                         // 2    Memory Reference
  221.                         // 3    Base + Index
  222.                         // 4    Base + Index + Displacement
  223.                         // 5    Immediate
  224.                         // 6    Immediate Far Address
  225.                         // 7    Immediate Near Address
  226.                         // 8    FPP register
  227.                         // 9    386 control register
  228.                         // 10    386 debug register
  229.                         // 11    386 trace register
  230.                         // 12    Condition (for Z80)
  231.                         // 13    bit (8051)
  232.                         // 14    bitnot (8051)
  233. char    LineA        (long ea,long num);    // get additional line before generated ones
  234. char    LineB        (long ea,long num);    // get additional line after generated ones
  235. char    Comment        (long ea);        // get comment
  236. char    RptCmt        (long ea);        // get repeatable comment
  237. char    AltOp1        (long ea);        // get manually entered 1st operand
  238. char    AltOp2        (long ea);        // get manually entered 2nd operand
  239.  
  240. E. Functions that change global settings
  241. ----------------------------------------
  242. long    StringEnd    (long asciiendchar);    // set current ASCII end character
  243.                         // returns old value
  244. long    StringStp    (long asciistopchar);    // set current ASCII break character
  245.                         // returns old value
  246. long    LowVoids    (long lowlimit);    // set current low limit for voids
  247.                         // returns old value
  248. long    HighVoids    (long highlimit);    // set current high limit for voids
  249.                         // returns old value
  250. long    TailDepth    (long taildepth);    // set current tail depth
  251.                         // returns old value
  252. long    Direction    (long direction);    // set current search direction
  253.                         // returns old value
  254. long    Analysis    (long analysis);    // enable/disable auto analysis
  255.                         // returns old value
  256. long    Tabs        (long tabulations);    // enable/disable tabulations in output file
  257.                         // returns old value
  258. long    Comments    (long comments);    // enable/disable automatic comments
  259.                         // returns old value
  260. long    Voids        (long voids);        // enable/disable void marks display
  261.                         // returns old value
  262. long    XrefShow    (long xrefshow);    // enable/disable cross-references display
  263.                         // returns old value
  264. long    Indent        (long indent);        // set indention for instruntions
  265.                         // returns old value
  266. long    CmtIndent    (long cmtindent);    // set indention for comments
  267.                         // returns old value
  268. long    AutoShow    (long autoshow);    // enable/disable autoanalysis display
  269.                         // returns old value
  270. success    SetPrcsr    (char processor);    // set processor type
  271.  
  272. F. Functions that interact with the user
  273. ----------------------------------------
  274. char    AskStr        (char defval,char prompt); // ask a string
  275. long    AskAddr        (long defval,char prompt); // -1 - no or bad input
  276. long    AskSeg        (long defval,char prompt); // -1 - no or bad input
  277. char    AskIdent    (char defval,char prompt);
  278. void    Message        (char str);        // show a message in messages window
  279. void    Warning        (char str);        // show a warning a dialog box
  280. void    Fatal        (char str);        // exit IDA immediately
  281.  
  282. G. Functions that work with segments
  283. ------------------------------------
  284. success    SegCreate    (long startea,long endea,long base,long use32,long alignment,long combination);
  285. success    SegDelete    (long segea,long disable);    // disable=1: exclude all bytes of the segment
  286.                             // from the disassembled text.
  287. success    SegBounds    (long segea,long startea,long endea);
  288. success    SegRename    (long segea,char name);
  289. success    SegClass    (long segea,char class);
  290. success    SegAlign    (long segea,long alignment);
  291.     #define saAbs       0    // Absolute segment.
  292.     #define saRelByte  1    // Relocatable, byte aligned.
  293.     #define saRelWord  2    // Relocatable, word (2-byte, 16-bit) aligned.
  294.     #define saRelPara  3    // Relocatable, paragraph (16-byte) aligned.
  295.     #define saRelPage  4    // Relocatable, aligned on 256-byte boundary (a "page"
  296.                         // in the original Intel specification).
  297.     #define saRelDble  5    // Relocatable, aligned on a double word (4-byte)
  298.                         // boundary. This value is used by the PharLap OMF for
  299.                         // the same alignment.
  300.     #define saRel4K    6    // This value is used by the PharLap OMF for page (4K)
  301.                         // alignment. It is not supported by LINK.
  302. success    SegComb        (long segea,long combination);
  303.     #define scPriv     0    // Private. Do not combine with any other program
  304.                             // segment.
  305.     #define scPub      2    // Public. Combine by appending at an offset that meets
  306.                         // the alignment requirement.
  307.     #define scPub2     4    // As defined by Microsoft, same as C=2 (public).
  308.     #define scStack    5    // Stack. Combine as for C=2. This combine type forces
  309.                         // byte alignment.
  310.     #define scCommon   6    // Common. Combine by overlay using maximum size.
  311.     #define scPub3     7    // As defined by Microsoft, same as C=2 (public).
  312. success    SegAddrng    (long segea,long addrng);
  313. long    SegByName    (char segname);        // returns segment base
  314. success    SegDefRef    (long segea,char reg,long value);
  315.                         // set default value for segment reg
  316.  
  317. H. Functions that work with files
  318. ---------------------------------
  319.  
  320. ***********************************************
  321. ** open a file
  322.     arguments: similiar to C fopen()
  323.     returns:    0 -error
  324.             otherwise a file handle
  325.  
  326. long    fopen        (char file,char mode);
  327.  
  328. ***********************************************
  329. ** close a file
  330.     arguments:    file handle
  331.     returns:    nothing
  332.  
  333. void    fclose        (long handle);
  334.  
  335. ***********************************************
  336. ** get file length
  337.     arguments:    file handle
  338.     returns:    -1 - error
  339.             otherwise file length in bytes
  340.  
  341. long    filelength    (long handle);
  342.  
  343. ***********************************************
  344. ** set cursor position in the file
  345.     arguments:    handle    - file handle
  346.             offset    - offset from origin
  347.             origin    - 0 = from start of file
  348.                   1 = from current cursor position
  349.                   2 = from end of file
  350.     returns:    -1 - error
  351.             otherwise cursor position
  352.  
  353. long    fseek        (long handle,long offset,long origin);
  354.  
  355. ***********************************************
  356. ** get cursor position in the file
  357.     arguments:    file handle
  358.     returns:    -1 - error
  359.             otherwise current cursor position
  360.  
  361. long    ftell        (long handle);
  362.  
  363. ***********************************************
  364. ** load file into IDA database
  365.     arguments:    handle    - file handle
  366.             pos    - position in the file
  367.             ea    - linear address to load
  368.             size    - number of bytes to load
  369.     returns:    0 - error
  370.             1 - ok
  371.  
  372. success    loadfile    (long handle,long pos,long ea,long size);
  373.  
  374. ***********************************************
  375. ** save from IDA database to file
  376.     arguments:    handle    - file handle
  377.             pos    - position in the file
  378.             ea    - linear address to save from
  379.             size    - number of bytes to save
  380.     returns:    0 - error
  381.             1 - ok
  382.  
  383. success    savefile    (long handle,long pos,long ea,long size);
  384.  
  385. ***********************************************
  386. ** read one byte from file
  387.     arguments:    handle    - file handle
  388.     returns:    -1 - error
  389.             otherwise a byte read.
  390.  
  391. long    fgetc        (long handle);
  392.  
  393. ***********************************************
  394. ** write one byte to file
  395.     arguments:    handle    - file handle
  396.             byte    - byte to write
  397.     returns:    0 - ok
  398.             -1 - error
  399.  
  400. long    fputc        (long byte,long handle);
  401.  
  402. ***********************************************
  403. ** read 2 bytes from file
  404.     arguments:    handle    - file hanlde
  405.             mostfirst 0 - least significant byte is first (intel)
  406.                   1 - most  significant byte is first
  407.     returns:    -1 - error
  408.             otherwise: a 16-bit value
  409.  
  410. long    readshort    (long handle,long mostfirst);
  411.  
  412. ***********************************************
  413. ** read 4 bytes from file
  414.     arguments:    handle    - file hanlde
  415.             mostfirst 0 - least significant byte is first (intel)
  416.                   1 - most  significant byte is first
  417.     returns:    a 32-bit value
  418.  
  419. long    readlong    (long handle,long mostfirst);
  420.  
  421. ***********************************************
  422. ** write 2 bytes to file
  423.     arguments:    handle    - file hanlde
  424.             word    - a 16-bit value to write
  425.             mostfirst 0 - least significant byte is first (intel)
  426.                   1 - most  significant byte is first
  427.     returns:    0 - ok
  428.  
  429. long    writeshort    (long handle,long word,long mostfirst);
  430.  
  431. ***********************************************
  432. ** write 4 bytes to file
  433.     arguments:    handle    - file hanlde
  434.             dword    - a 32-bit value to write
  435.             mostfirst 0 - least significant byte is first (intel)
  436.                   1 - most  significant byte is first
  437.     returns:    0 - ok
  438.  
  439. long    writelong    (long handle,long dword,long mostfirst);
  440.  
  441. ***********************************************
  442. ** read a string from file
  443.     arguments:    handle    - file hanlde
  444.     returns:    a string
  445.             on EOF, returns -1
  446.  
  447. char    readstr        (long handle);
  448.  
  449. ***********************************************
  450. ** write a string to file
  451.     arguments:    handle    - file hanlde
  452.             str    - string to write
  453.     returns:    0 - ok
  454.  
  455. long    writestr    (long handle,char str);
  456.