home *** CD-ROM | disk | FTP | other *** search
/ The Unsorted BBS Collection / thegreatunsorted.tar / thegreatunsorted / misc / idc.doc < prev    next >
Text File  |  1994-12-26  |  13KB  |  281 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.  
  113. B. Functions that change program representation
  114. -----------------------------------------------
  115. void    DeleteAll    ();            // delete ALL information
  116.                         // about the program
  117. long    MakeCode    (long ea);        // convert to instruction
  118.                         // returns number of bytes
  119.                         // occupied by the instruuction
  120. success    MakeName    (long ea,char name);    // assign a name to a location
  121. success    MakeComm    (long ea,char comment);    // give a comment
  122. success    MakeRptCmt    (long ea,char comment);    // give a repeatable comment
  123. success    MakeArray    (long ea,long nitems);    // convert to an array
  124. success    MakeStr        (long ea,long size);    // convert to ASCII string
  125. success    MakeByte    (long ea);        // convert to byte
  126. success    MakeWord    (long ea);        // convert to word
  127. success    MakeDword    (long ea);        // convert to double-word
  128. success    MakeQword    (long ea);        // convert to quadro-word
  129. success    MakeTbyte    (long ea);        // convert to 10 bytes (tbyte)
  130. void    MakeUnkn    (long ea);        // convert to 'unknown'
  131. success    OpDec        (long ea);        // operands are decimal
  132. success    OpChar        (long ea);        // operands are characters
  133. success    OpOffset    (long ea,long segbase);    // operands are offsets
  134.                         // if segbase==-1, then operands aren't offsets
  135. success    OpSegment    (long ea);        // operands are segments
  136. success    OpNum        (long ea);        // operands are numbers
  137. success    OpAlt1        (long ea,char opnd);    // manually enter 1st operand
  138. success    OpAlt2        (long ea,char opnd);    // manually enter 2nd operand
  139. void    MakeVar        (long ea);        // the location is 'variable'
  140. success    MakeProc    (long ea,long fl);    // fl=0: no proc, fl=1: near proc, fl=2: far proc
  141. success    MakeEndp    (long ea,long fl);    // fl=0: no endp,1: endp
  142. void    ExtLinA        (long ea,long n,char line); // insert an additional line before the generated ones
  143. void    ExtLinB        (long ea,long n,char line); // insert an additional line after the generated ones
  144. void    DelExtLnA    (long ea,long n);    // delete an additional line before the generated ones
  145. void    DelExtLnB    (long ea,long n);    // delete an additional line aftr  the generated ones
  146. success    JmpTable    (long jmpea,long tableea,long nitems);    // define a jump table
  147. void    PatchByte    (long ea,long value);    // change a byte
  148. void    SetFlags    (long ea,long flags);    // change internal flags for ea
  149. success    SetReg        (long ea,char reg,long value); // set value of segment register
  150.  
  151. C. Functions that produce output files
  152. --------------------------------------
  153. void    WriteMap    (char file);        // produce a .map file
  154. void    WriteTxt    (char file,long ea1,long ea2); // produce an .asm file
  155. void    WriteExe    (char file);        // produce an executable file
  156.  
  157. D. Informational functions
  158. --------------------------
  159. long    GetFlags    (long ea);        // get internal flags for ea
  160. long    Byte        (long ea);        // get a byte at ea
  161. long    Word        (long ea);        // get a word at ea
  162. long    Dword        (long ea);        // get a double-word at ea
  163. long    LocByName    (char name);        // -1 - no such name
  164. long    SegByBase    (long base);        // -1 - no such segment
  165. long    MinEA        ();            // the minimal address defined in the program
  166. long    MaxEA        ();            // the maximal address defined in the program
  167. long    ScreenEA    ();            // the current screen ea
  168. long    BeginEA        ();            // where execution starts
  169. long    GetReg        (long ea,char reg);    // get segment register value
  170.                         // -1 - undefined or error
  171. long    FirstSeg    ();            // returns start of the first
  172.                         // segment, -1 - no segments
  173. long    NextSeg        (long ea);        // returns start of the next
  174.                         // segment, -1 - no more segs
  175. long    SegStart    (long ea);        // returns start of the segment
  176.                         // -1 if bad address passed
  177. long    SegEnd        (long ea);        // return end of the segment
  178.                         // this address doesn't belong
  179.                         // to the segment
  180.                         // -1 if bad address passed
  181. char    SegName        (long ea);        // returns name of the segment
  182.                         // "" if bad address passed
  183. long    NextAddr    (long ea);        // returns next defined address
  184.                         // -1 if no such address exists
  185. long    PrevAddr    (long ea);        // returns prev defined address
  186.                         // -1 if no such address exists
  187. long    NextHead    (long ea);        // returns next defined item address
  188.                         // -1 if no such address exists
  189. long    PrevHead    (long ea);        // returns prev defined item address
  190.                         // -1 if no such address exists
  191. long    NextNotTail    (long ea);        // returns next not tail address
  192.                         // -1 if no such address exists
  193. long    PrevNotTail    (long ea);        // returns prev not tail address
  194.                         // -1 if no such address exists
  195. long    ItemEnd        (long ea);        // returns address past end of
  196.                         // the item
  197. long    ItemSize    (long ea);        // returns item size, min answer=1
  198. char    LineA        (long ea,long num);    // get additional line before generated ones
  199. char    LineB        (long ea,long num);    // get additional line after generated ones
  200. char    Comment        (long ea);        // get comment
  201. char    RptCmt        (long ea);        // get repeatable comment
  202. char    AltOp1        (long ea);        // get manually entered 1st operand
  203. char    AltOp2        (long ea);        // get manually entered 2nd operand
  204.  
  205. E. Functions that change global settings
  206. ----------------------------------------
  207. long    StringEnd    (long asciiendchar);    // set current ASCII end character
  208.                         // returns old value
  209. long    StringStp    (long asciistopchar);    // set current ASCII break character
  210.                         // returns old value
  211. long    LowVoids    (long lowlimit);    // set current low limit for voids
  212.                         // returns old value
  213. long    HighVoids    (long highlimit);    // set current high limit for voids
  214.                         // returns old value
  215. long    TailDepth    (long taildepth);    // set current tail depth
  216.                         // returns old value
  217. long    Direction    (long direction);    // set current search direction
  218.                         // returns old value
  219. long    Analysis    (long analysis);    // enable/disable auto analysis
  220.                         // returns old value
  221. long    Tabs        (long tabulations);    // enable/disable tabulations in output file
  222.                         // returns old value
  223. long    Comments    (long comments);    // enable/disable automatic comments
  224.                         // returns old value
  225. long    Voids        (long voids);        // enable/disable void marks display
  226.                         // returns old value
  227. long    XrefShow    (long xrefshow);    // enable/disable cross-references display
  228.                         // returns old value
  229. long    Indent        (long indent);        // set indention for instruntions
  230.                         // returns old value
  231. long    CmtIndent    (long cmtindent);    // set indention for comments
  232.                         // returns old value
  233. long    AutoShow    (long autoshow);    // enable/disable autoanalysis display
  234.                         // returns old value
  235. success    SetPrcsr    (char processor);    // set processor type
  236.                         
  237. F. Functions that interact with the user
  238. ----------------------------------------
  239. char    AskStr        (char defval,char prompt); // ask a string
  240. long    AskAddr        (long defval,char prompt); // -1 - no or bad input
  241. long    AskSeg        (long defval,char prompt); // -1 - no or bad input
  242. char    AskIdent    (char defval,char prompt);
  243. void    Message        (char str);        // show a message in messages window
  244. void    Warning        (char str);        // show a warning a dialog box
  245. void    Fatal        (char str);        // exit IDA immediately
  246.  
  247. G. Functions that work with segments
  248. ------------------------------------
  249. success    SegCreate    (long startea,long endea,long base,long use32,long alignment,long combination);
  250. success    SegDelete    (long segea,long disable);    // disable=1: exclude all bytes of the segment
  251.                             // from the disassembled text.
  252. success    SegBounds    (long segea,long startea,long endea);
  253. success    SegRename    (long segea,char name);
  254. success    SegClass    (long segea,char class);
  255. success    SegAlign    (long segea,long alignment);
  256.     #define saAbs       0    // Absolute segment.
  257.     #define saRelByte  1    // Relocatable, byte aligned.
  258.     #define saRelWord  2    // Relocatable, word (2-byte, 16-bit) aligned.
  259.     #define saRelPara  3    // Relocatable, paragraph (16-byte) aligned.
  260.     #define saRelPage  4    // Relocatable, aligned on 256-byte boundary (a "page"
  261.                         // in the original Intel specification).
  262.     #define saRelDble  5    // Relocatable, aligned on a double word (4-byte)
  263.                         // boundary. This value is used by the PharLap OMF for
  264.                         // the same alignment.
  265.     #define saRel4K    6    // This value is used by the PharLap OMF for page (4K)
  266.                         // alignment. It is not supported by LINK.
  267. success    SegComb        (long segea,long combination);
  268.     #define scPriv     0    // Private. Do not combine with any other program
  269.                             // segment.
  270.     #define scPub      2    // Public. Combine by appending at an offset that meets
  271.                         // the alignment requirement.
  272.     #define scPub2     4    // As defined by Microsoft, same as C=2 (public).
  273.     #define scStack    5    // Stack. Combine as for C=2. This combine type forces
  274.                         // byte alignment.
  275.     #define scCommon   6    // Common. Combine by overlay using maximum size.
  276.     #define scPub3     7    // As defined by Microsoft, same as C=2 (public).
  277. success    SegAddrng    (long segea,long addrng);
  278. long    SegByName    (char segname);        // returns segment base
  279. success    SegDefRef    (long segea,char reg,long value);
  280.                         // set default value for segment reg
  281.