home *** CD-ROM | disk | FTP | other *** search
/ Sauce 'n' Code 3 / sauce-n-code-03.adf / Articles / stcautodocs.txt / stcautodocs.txt
Text File  |  1996-01-21  |  29KB  |  793 lines
  1. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  2.                 stc.library v3.303+
  3.  
  4.  
  5. TABLE OF CONTENTS
  6.  
  7. stc.library/CrunchData      * Not documented here.. Use CrunchDataTags()
  8. stc.library/DeCrunchData
  9. stc.library/AllocBuffer
  10. stc.library/FreeBuffer
  11. stc.library/QuickSort
  12. stc.library/AllocFileBuffer * Not documented here.. Use NewAllocFileBuffer()
  13. stc.library/FreeFileBuffer
  14. stc.library/LoadFileBuffer
  15. stc.library/ProcessHunks
  16. stc.library/SaveExec        * Not documented here.. Use SaveExecTags()
  17. stc.library/LibDeCrunchPExec
  18. stc.library/CrunchDataTags
  19. stc.library/SaveExecTags
  20. stc.library/NewAllocFileBuffer
  21. stc.library/AllocMemBuffer
  22. stc.library/FileIs
  23.  
  24. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  25. stc.library/DeCrunchData
  26.  
  27.     NAME
  28.         DeCrunchData -- Decrunches data that was crunched with stc.library
  29.                         v2.0 -> 3.304 (S403 and S404)
  30.  
  31.     SYNOPSIS
  32.         success = DeCrunchData( destination, source )
  33.         D0        -36           A0           A1
  34.  
  35.         BOOL DeCrunchData( APTR destination, APTR source );
  36.  
  37.     FUNCTION
  38.         Decrunches stc.library crunched data (S403 and S404) from standard
  39.         sourcefile to destination buffer.
  40.  
  41.         If both destination and source has separate memory regions there
  42.         is no problem to decrunch data.
  43.  
  44.         If you need to save memory it's possible to decrunch over the source
  45.         file. Take care you do the following:
  46.             Decrunch memory buffer must be atleast file's original length +
  47.             security length. You get both values from the beginning of the
  48.             source file (the decrunch info header).
  49.  
  50.             Load source file to the beginning of the decrunch buffer and
  51.             define destination address "security length" bytes ahead from
  52.             the beginning of the decrunch buffer.
  53.  
  54.         Decrunch info header & decrunching:
  55.  
  56.         Every file crunched with stc.library v2.0+ has following header
  57.         (16 bytes) at the beginning of the crunched data:
  58.  
  59.             "S404" or "S403".L  ; cruncher version - string (four bytes)
  60.             Security length.L   ; overlap size - longword
  61.             Original length.L   ; decrunched length - longword
  62.             Crunched length.L   ; crunched length - longword
  63.                .                ; crunched data starts
  64.                .
  65.                .
  66.  
  67.         Security length is always 16 + something.
  68.  
  69.         There are also two control words at the end of crunched data. For
  70.         historical reasons it's quite wierd. I'll explain it with a 
  71.         following picture:
  72.  
  73.         <<- Lower memory                           Higher memory ->>
  74.  
  75.                   +------------ Crunched length ------------+
  76.                   |                                         |
  77.         InfoHeader|......................LastWord|BitCounter|MaxBits
  78.                             ^                 ^       ^         ^
  79.                             |                 |       |         |
  80.             Crunched data --+                 |       |         |
  81.                                               |       |         |
  82.                          Last crunched word --+       |         |
  83.                                                       |         |
  84.            How many used bits there are in LastWord --+         |
  85.                                                                 |
  86.                                      Efficiency (not in S403) --+
  87.  
  88.         If both crunched data and destination memory overlap there must
  89.         be atleast 'Security length' distance between the start of the
  90.         crunched data and the start of the destination memory:
  91.  
  92.         <<- Lower memory                               Higher memory ->>
  93.  
  94.                   <<<-------------- Decrunching direction --------------
  95.  
  96.         InfoHeader|......................LastWord|BitCounter|MaxBits
  97.         ^
  98.         |             |<------------ Destination memory starts here ....
  99.         |             |
  100.         +-- SecLen ---+
  101.         |
  102.         +---------------> Crunched data starts here..
  103.  
  104.     INPUTS
  105.         destination = pointer to the beginning of the memory you want to
  106.                       decrunch
  107.         source      = pointer to crunched data (must include the decrunch
  108.                       info header)
  109.  
  110.     RESULT
  111.         success     = TRUE if source was actually S403 or S404 crunched file
  112.                       FALSE if coulnd't find correct ID string
  113.  
  114.     SEE ALSO
  115.         CrunchDataTags()
  116.  
  117. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  118. stc.library/AllocBuffer
  119.  
  120.     NAME
  121.         AllocBuffer -- Alloc buffer for cruncher
  122.  
  123.     SYNOPSIS
  124.         buffer AllocBuffer( version )
  125.         D0     -42          D0
  126.  
  127.         BOOL AllocBuffer( ULONG version );
  128.  
  129.     FUNCTION
  130.         Allocates correct size of memory for cruncher's use. This buffer
  131.         includes hash table and lookahead buffer.
  132.  
  133.     INPUTS
  134.         version = current cruncher version. Use S404 at the moment.
  135.  
  136.     RESULT
  137.         buffer  = pointer to the buffer or NULL if allocation failed.
  138.  
  139.     SEE ALSO
  140.         FreeBuffer(), CrunchDataTags()
  141.  
  142. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  143. stc.library/FreeBuffer
  144.  
  145.     NAME
  146.         FreeBuffer -- Frees buffer allocated with AllocBuffer()
  147.  
  148.     SYNOPSIS
  149.         FreeBuffer( buffer )
  150.         -48         A1
  151.  
  152.         void FreeBuffer( APTR buffer );
  153.  
  154.     FUNCTION
  155.         Frees memory allocated with AllocBuffer().
  156.  
  157.     INPUTS
  158.         buffer = pointer to buffer
  159.  
  160.     SEE ALSO
  161.         AllocBuffer()
  162.  
  163. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  164. stc.library/QuickSort
  165.  
  166.     NAME
  167.         QuickSort -- Sort an array of numbers
  168.  
  169.     SYNOPSIS
  170.         QuickSort( amount, array )
  171.         -54        D0      A0
  172.  
  173.         void QuickSort( ULONG amount, ULONG *array );
  174.  
  175.     FUNCTION
  176.         Sorts an array of unsigned lonwords into ascending order. Uses
  177.         fast quicksort algorithm.
  178.  
  179.     INPUTS
  180.         amount = number of items in array
  181.         array  = pointer to the array of ULONGs
  182.  
  183.     NOTES
  184.         This function uses recursion and may need a lot of stack space.
  185.  
  186. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  187. stc.library/FreeFileBuffer
  188.  
  189.     NAME
  190.         FreeFileBuffer -- Frees memory allocated with AllocFileBuffer(),
  191.                        NewAllocFileBuffer() or AllocMemBuffer()
  192.  
  193.     SYNOPSIS
  194.         FreeFileBuffer( filebuffer )
  195.         -66             A1
  196.  
  197.         void FreeFileBuffer( APTR filebuffer );
  198.  
  199.     FUNCTION
  200.         Frees memory allocated with AllocFileBuffer(), NewAllocFileBuffer()
  201.         or AllocMemBuffer().
  202.  
  203.     INPUTS
  204.         filebuffer = pointer buffer
  205.  
  206.     SEE ALSO
  207.         AllocFileBuffer(), NewAllocFileBuffer(), AllocMemBuffer()
  208.  
  209. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  210. stc.library/LoadFileBuffer
  211.  
  212.     NAME
  213.         LoadFileBuffer -- Load file into filebuffer
  214.  
  215.     SYNOPSIS
  216.         length = LoadFileBuffer( filebuffer )
  217.         D0       -72             A0
  218.  
  219.         ULONG LoadFileBuffer( APTR filebuffer );
  220.  
  221.     FUNCTION
  222.         Loads a file into buffer. Buffer must have been allocated with
  223.         AllocFileBuffer() or NewAllocFileBuffer().
  224.         This function takes automatically care of placing data into
  225.         correct place inside buffer (security length).
  226.  
  227.     INPUTS
  228.         filebuffer = pointer to buffer allocated with AllocFilebuffer() or
  229.                      NewAllocFileBuffer()
  230.  
  231.     RESULT
  232.         length     = total bytes loaded or NULL if there was an error. In
  233.                      case of error read DOS errorcode from ErrorMsg.
  234.  
  235.     NOTES
  236.         There are few hypotical cases when this function may return error
  237.         without a reason. Firstly filebuffer includes information of the
  238.         file to be loaded: file size, security length and name (path).
  239.  
  240.         If file size changes between NewAllocFileBuffer() and
  241.         LoadFileBuffer() (some other task modifies the file) an error
  242.         will be returned. This is because file won't stay locked after
  243.         NewAllocFileBuffer().
  244.  
  245.         If you use file names (paths) longer than 108 characters the name
  246.         will be automatically truncated. So it's recommendent to change
  247.         work directory instead just adding it to filename.
  248.  
  249.     BUGS
  250.         Read also the note considering StcBase->ErrorMsg in
  251.         include/libraries/stc.h.
  252.  
  253.     SEE ALSO
  254.         AllocFileBuffer(), NewAllocFileBuffer()
  255.  
  256. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  257. stc.library/ProcessHunks
  258.  
  259.     NAME
  260.         ProcessHunks -- Preprocess hunks of command file
  261.  
  262.     SYNOPSIS
  263.         processedlength = ProcessHunks( length, filebuffer )
  264.         D0                -78           D0      A0
  265.  
  266.         ULONG ProcessHunks( ULONG length, APTR filebuffer );
  267.  
  268.     FUNCTION
  269.         Converts hunks of command file to StoneCracker's own and much
  270.         shorter form. Hunk_symbol, hunk_debug and hunk_ext will be
  271.         removed and there's no way to get them back.
  272.  
  273.         Hunk preprocessor does the following for hunks:
  274.  
  275.           · All debug hunks generated by compiler are deleted (no way to
  276.             get them back!).
  277.           · There are no Hunk_ends
  278.           · Hunk header info at the beginning of the file is modified to
  279.             a shorter form:
  280.                   1 longword = (total number of hunks)-1 (=n)
  281.                 n+1 longwords = hunksizes & memory type (as normally)
  282.           · Hunk_code is converted to %01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.L
  283.                                          +-------- datasize>>2 -------+
  284.           · Hunk_data is converted to %11xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.L
  285.                                          +-------- datasize>>2 -------+
  286.           · Hunk_bss is converted to %100000000000000000.W
  287.           · Hunk_reloc start with %000000000000000000.W and then
  288.             Repeat until (number of relocentries) = 0
  289.               1 word = number of relocentries (null if no relocs anymore)
  290.               1 word = relocate hunk number..
  291.               1 longword = %bbbbbbbbxxxxxxxxxxxxxxxxxxxxxxxx.L
  292.                             ^       +----- First reloc ----+
  293.                             |
  294.                             +--> Number of bytes to add to 'First reloc'
  295.                                    2       = 3 bytes per relocentry
  296.                                    4 or 6  = 2 bytes per relocentry
  297.                                    8 or 10 = 1 byte per relocentry
  298.                                    ?       = only one relocentry
  299.               followed by (number of relocentries) %bbbbbbbb reloc-
  300.               entries..
  301.           · End of processed hunks is %1111111111111111.W
  302.  
  303.     INPUTS
  304.         length     = size of file in filebuffer.
  305.         filebuffer = buffer allocated with AllocFileBuffer() or
  306.                      NewAllocFileBuffer().
  307.  
  308.     RESULT
  309.         processedlength = size of the file after preprocessing or NULL
  310.                           if it's not possible to convert all hunks
  311.                           correctly. Read ErrorMsg for errorcode.
  312.  
  313.                 Errorcodes are:
  314.  
  315.                 phNOHEADER = file wasn't a command file.
  316.                 phNOMATCH  = file is probably overlayed. Maximum number of
  317.                              hunks doesn't match to highest hunk.
  318.                 phUNIT     = there was a hunk_unit.
  319.                 phNAME     = there was a hunk_name (handled since v3.303)
  320.                 phREHEADER = there was hunk_header again.
  321.                 phOVERLAY  = file is overlayed.
  322.                 phBREAK    = file is overlayed.
  323.                 phHUNKID   = unknown hunk ID.
  324.  
  325.     NOTE
  326.         All command files _must_ be preprocessed if you want to decrunch
  327.         them with stc.library's executable decrunchers.
  328.  
  329.     BUGS
  330.         These are really not bugs but stc.library can't handle hunk_unit
  331.         and new hunk types that came with Kickstart 2.0 and higher. Also
  332.         it's not possible to preprocess overlayed files.
  333.  
  334.         Read also the note considering StcBase->ErrorMsg in
  335.         include/libraries/stc.h.
  336.  
  337.     SEE ALSO
  338.         AllocFileBuffer(), NewAllocFileBuffer(), LoadFileBuffer()
  339.  
  340. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  341. stc.library/LibDeCrunchPExec
  342.  
  343.     NAME
  344.         LibDeCrunchPExec -- decrunches crunched command file
  345.  
  346.     SYNOPSIS
  347.         LibDeCrunchPExec( hunk1, seglist )
  348.         -90               A3     A4
  349.  
  350.         void LibDeCrunchPExec( APTR hunk1, APTR seglist );
  351.  
  352.     FUNCTION
  353.         Decrunches and relocates crunched command file. Function also
  354.         takes care of hunk mess, memory managing and closing library.
  355.         If decrunching succees decrunched program will be runned.
  356.         Following assembly example (it's current library decruncher)
  357.         shows how to use LibDeCrunchPExec():
  358.  
  359.  
  360.     *
  361.     * First normal hunk stuff in front of command file..
  362.     *
  363.  
  364.         cnop    0,4
  365.         dc.l    HUNK_HEADER             ; It's command file
  366.         dc.l    0
  367.         dc.l    2                       ; Total number of hunks.
  368.         dc.l    0                       ; Lowest hunk
  369.         dc.l    1                       ; Highest hunk
  370.         dc.l    (ldH0End-ldH0Start)>>2    ; Size of the first code hunk
  371. ldH1MemSize:
  372.         dc.l    0                       ; Size of the second code hunk
  373.                                         ; Code size + original file size +
  374.                                         ; security length
  375.         dc.l    HUNK_CODE
  376.         dc.l    (ldH0End-ldH0Start)>>2  ; Size of the first code hunk
  377.  
  378.     *
  379.     * Code of the first code hunk starts..
  380.     *
  381.  
  382. ldH0Start:
  383.         pea     ldExit(pc)
  384.         movem.l d0-a6,-(sp)
  385.         lea     ldH0Start-4(pc),a4      ; Address of this code hunk (seglist)
  386.         move.l  (a4),a3
  387.         add.l   a3,a3
  388.         add.l   a3,a3                   ; Address of next code hunk
  389.         jsr     18(a3)                  ; Call it.. 18 = 4 bytes of link
  390.                                         ; to next hunk + 12 bytes of
  391.                                         ; library name + 2 bytes to make
  392.                                         ; code longword aligned..
  393.         movem.l (sp)+,d0-a6
  394. ldExit:
  395.         rts
  396.         cnop    0,4
  397. ldH0End:
  398.  
  399.     *
  400.     * Hunk stuff in front of next hunk (segment)
  401.     *
  402.  
  403.         dc.l    HUNK_CODE
  404. ldH1DataSize:
  405.         dc.l    0                       ; Size of code & crunched data
  406.  
  407.     *
  408.     * Code of the second code hunk & crunched data..
  409.     *
  410.  
  411. ldH1Start:
  412.         dc.b    "stc.library",0,0,0
  413.         lea     4(a3),a1                ; Here we actually start..
  414.         moveq   #STCVERSION,d0          ; = 3
  415.         move.l  $04.w,a6
  416.         jsr     _LVOOpenLibrary(a6)
  417.         tst.l   d0
  418.         bne.s   ldCont
  419.         rts
  420. ldCont: move.l  d0,a6
  421.         jsr     _LVOstcLibDeCrunchPExec(a6)
  422. ldH1End:
  423.         ; Crunched data starts here. Jsr passes address of the data
  424.         ; into the stack..
  425.         ;
  426.         ; Library function takes care of closing library..
  427.  
  428.  
  429.     INPUTS
  430.         hunk1   = pointer to next hunk in seglist
  431.         seglist = pointer to program's segment list
  432.  
  433.     NOTE
  434.         You really _must_ know what you are going to do because this
  435.         function causes easily those red boxes. There can't more than
  436.         two hunks in command file that includes this function and the
  437.         example above is the only way how to use function correctly.
  438.  
  439. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  440. stc.library/CrunchDataTags
  441.  
  442.     NAME
  443.         CrunchDataTags -- crunch data in buffer
  444.  
  445.     SYNOPSIS
  446.         crunchedlength = CrunchDataTags( taglist )
  447.         D0               -96             A0
  448.  
  449.         ULONG CrunchDataTags( struct TagItem * );
  450.  
  451.     FUNCTION
  452.         Crunches data in buffer with the latest algorithm or actually
  453.         with the algorithm you defined with AllocBuffer() (both S403 and
  454.         S404 algorithms default to S404).
  455.  
  456.         There are following tags for CrunchDataTags():
  457.  
  458.         cdDESTINATION - you must give filebuffer as a destination. See
  459.             AllocFileBuffer(), NewAllocFileBuffer(), AllocMemBuffer() and
  460.             LoadFileBuffer().
  461.  
  462.         cdLENGTH - size of file to be crunched.
  463.  
  464.         cdABORTFLAGS - there are three possibilities and only one of them
  465.             can be used at once. If cdABORTFLAGS == cdAbortNIL there's no
  466.             way to abort crunching process.
  467.             If cdABORTFLAGS == cdAbortGADGET function expects to find valid
  468.             pointer to a message structure in cdMSGPORT tag. This message
  469.             port is checked every now and then if a gadget event has
  470.             arrived. Note! The "abort gadget's" user data field must be
  471.             NULL. If your message port gets gadget events from several
  472.             gadgets take care that only "abort gadget's" user data field
  473.             is NULL.
  474.             If cdABORTFLAGS == cdAbortCTRLC ctrl-c signal is checked. This
  475.             works only when your program is running under CLI without own
  476.             window.
  477.  
  478.         cdOUTPUTFLAGS - there are three possibilities and only one of them
  479.             can be used at once. If cdOUTPUTFLAGS == cdOutPutNIL then no
  480.             output is done.
  481.             If cdABORTFLAGS == cdOutPutWIN function expects to find valid
  482.             pointer to your window's rastport in cdRASTPORT tag. Number of
  483.             bytes still remaining is written into your window. Position
  484.             must be defines with cdXPOS & cdYPOS tags.
  485.             If cdOutPutFLAGS == cdOutPutCLI function expects to find file
  486.             handle (use DOS Output() ) in cdRASTPORT tag. The counter is
  487.             written into CLI.
  488.  
  489.     cdXPOS - define relative x position for crunch counter in your window.
  490.             You need this tag only when cdOUTPUTFLAGS == cdOutPutWIN.
  491.  
  492.     cdYPOS - define relative y position for crunch counter in your window.
  493.             You need this tag only when cdOUTPUTFLAGS == cdOutPutWIN.
  494.  
  495.     cdRASTPORT - pointer to your window's raster port. You need this tag
  496.             only when cdOUTPUTFLAGS == cdOutPutWIN.
  497.             If cdOUTPUTFLAGS == cdOutPutCLI this tag must be CLI's file
  498.             handle (use DOS Output() ).
  499.  
  500.     cdMSGPORT - pointer to your window's message port. This tag is used
  501.             and needed only when cdABORTFLAGS == cdAbortGADGET.
  502.  
  503.     cdDISTBITS - define cruncher's efficiency. There are five possibilities:
  504.             cdDist1K  = the worst efficiency but the fastest
  505.             cdDist2K  =            .
  506.             cdDist4K  =            .
  507.             cdDist8K  =            .
  508.             cdDist16K = the best efficiency but the slowest
  509.  
  510.     cdBUFFER - pointer to buffer you have allocated with AllocBuffer().
  511.  
  512.     INPUTS
  513.         taglist = pointer to your taglist (an array of longwords). The
  514.                   taglist must end with TAG_DONE.
  515.  
  516.     RESULT
  517.         crunchedlength = new crunched length (includes 16 bytes of decrunch
  518.                          info header), NULL if crunching failed or -1L if
  519.                          user aborted crunching. (this value is always
  520.                          longword aligned)
  521.  
  522.     SEE ALSO
  523.         DeCrunchData(), LoadFileBuffer(), AllocFileBuffer(),
  524.         NewAllocFileBuffer(), AllocMemBuffer()
  525.  
  526. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  527. stc.library/SaveExecTags
  528.  
  529.     NAME
  530.         SaveExecTags -- saves crunched file with decruncher
  531.  
  532.     SYNOPSIS
  533.         savedlength = SaveExecTags( taglist )
  534.         D0            -102          A0
  535.  
  536.         ULONG SaveExecTags( struct TagItem *taglist );
  537.  
  538.     FUNCTION
  539.         Saves crunched file with wanted decruncher or without decruncher.
  540.  
  541.         There are following tags for SaveExecTags():
  542.  
  543.         sxSAVETYPE - define what kind of decruncher you want to attach to
  544.                 the crunched file. Stc.library v3.303 & v3.304 have six
  545.                 types:
  546.                 sxData          = no decruncher, just crunched data
  547.                 sxPExec         = normal decruncher for command files. All
  548.                                   needed hunks, memory handling and
  549.                                   relocation is included. Average speed.
  550.                 sxPExecLib      = same as above but needs stc.library for
  551.                                   decrunching. Fast & short decruncher!
  552.                 sxAbsNormal     = normal decruncher for absolute files. One
  553.                                   hunk and cache code. Average speed.
  554.                 sxAbsPlain      = decruncher included but without hunks so
  555.                                   it's not runable from CLI or workbench.
  556.                                   No cache code. Average speed.
  557.                 sxAbsKillSystem = special decruncher for absolute files. One
  558.                                   hunk, cache code, stack relocation, forces
  559.                                   VBR (=vector base register) to zero and SR
  560.                                   (=status register) is modified. Use only
  561.                                   if you need to overdrive OS. Average
  562.                                   speed.
  563.                     NOTE! Kill system decruncher returns processor type
  564.                           in A4 register. If A4 = $00000000 mc68000/010 is
  565.                           presented and if A4 = $ffffffff mc68020/030/040
  566.                           is presented!
  567.  
  568.         sxFILENAME - pointer NULL terminated filename.
  569.  
  570.         sxDATABUFFER - pointer to filebuffer that was allocated with
  571.                 AllocFileBuffer() or NewAllocFileBuffer().
  572.  
  573.         sxLENGTH - size of crunched file. CrunchDataTags() returns this
  574.                 value.
  575.  
  576.         sxLOAD - start address of absolute file. You need this with all
  577.                 absolute files.
  578.  
  579.         sxJUMP - run address of absolute file. You need this with all
  580.                 absolute files.
  581.  
  582.         sxDECR - memory location for decruncher code. You need this when
  583.                 sxSAVETYPE == sxAbsKillSystem.
  584.  
  585.         sxUSP - new memory location for user stackpointer. You need this
  586.                 when sxSAVETYPE == sxAbsKillSystem.
  587.  
  588.         sxSSP - new memory location for system stackpointer (=interrupt
  589.                 stackppointer). You need this when sxSAVETYPE ==
  590.                 sxAbsKillSystem.
  591.  
  592.         sxSR - define status register. The value is loaded into SR just
  593.                 before running your code so flags won't change during
  594.                 decrunching. You need this when sxSAVETYPE ==
  595.                 sxAbsKillSystem.
  596.  
  597.     INPUTS
  598.         taglist = pointer to your taglist (an array of longwords). The
  599.                   taglist must end with TAG_DONE.
  600.  
  601.     RESULT
  602.         savedlength = total bytes saved to the disk or NULL if an error
  603.                       occured. Read ErrorMsg for DOS errorcode.
  604.  
  605.     BUGS
  606.         Read also the note considering StcBase->ErrorMsg in
  607.         include/libraries/stc.h.
  608.  
  609.     SEE ALSO
  610.         CrunchDataTags()
  611.  
  612. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  613. stc.library/NewAllocFileBuffer
  614.  
  615.     NAME
  616.         NewAllocFileBuffer -- allocate memory for file
  617.  
  618.     SYNOPSIS
  619.  
  620.         filebuffer = NewAllocFileBUffer( securitylength, filename )
  621.         D0           -108                D0              A0
  622.  
  623.         APTR NewAllocFileBuffer( ULONG securitylength, char *filename );
  624.  
  625.     FUNCTION
  626.         Allocates memory for file to be crunched. This is the only way
  627.         to do it in future compatible way. Security length must be even
  628.         value (prefer longword alignment).
  629.  
  630.     INPUTS
  631.         securitylength = how many bytes source data and crunched data can
  632.                          overlap each other without confusing crunching or
  633.                          decrunching.
  634.  
  635.         filename       = pointer to NULL terminated filename. In maximum
  636.                          108 characters (including path if added).
  637.  
  638.     RESULT
  639.         filebuffer = pointer to filebuffer that is used with many other
  640.                      functions or NULL if an error occured. In case of
  641.                      error if:
  642.                         ErrorMsg = NULL then there wasn't enough memory,
  643.                         ErrorMsg <> NULL it's the DOS errorcode.
  644.  
  645.     BUGS
  646.         Read also the note considering StcBase->ErrorMsg in
  647.         include/libraries/stc.h.
  648.  
  649.     SEE ALSO
  650.         DeCrunchData(), LoadFileBuffer(), CrunchDataTags(), SaveExecTags()
  651.  
  652. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  653. stc.library/AllocMemBuffer
  654.  
  655.     NAME
  656.         AllocMemBuffer -- allocate memory for misc data
  657.  
  658.     SYNOPSIS
  659.         filebuffer = AllocMemBuffer( securitylength, memsize )
  660.         D0           -114            D0              D1
  661.  
  662.         APTR AllocMemBuffer( ULONG securitylength, ULONG memsize );
  663.  
  664.     FUNCTION
  665.         Allocates memory for "filebuffer" in future compatible way but you
  666.         can't use LoadFileBuffer() with this filebuffer pointer. This
  667.         function makes it possible to crunch anykind of data, not just
  668.         files.
  669.         You must take care of placing data into correct place in
  670.         filebuffer yourself. The data (..you want to crunch) must start
  671.         "security length" distance ahead from the start of the filebuffer!
  672.  
  673.         Like in this assembly example:
  674.  
  675.  
  676. myseclen    equ     4           ; security length we use in this example
  677.  
  678.             move.l  stcbase,a6
  679.             moveq   #myseclen,d0
  680.             move.l  #10240,d1       ; we want 10Kb buffer
  681.             move.l  d1,d2
  682.             jsr     _LVOAllocMemBuffer(a6)
  683.             move.l  d0,filebuffer   ; did we get memory
  684.             beq     nomemory
  685.  
  686.             lea     mydata,a0       ; start of data we want to crunch
  687.             move.l  d0,a1           * a1 = filebuffer     *
  688.             addq    #myseclen,a1    * add security length *
  689.  
  690.             lsr     #2,d2
  691.             subq    #1,d2           ; how many longwords to move
  692. loop:       move.l  (a0)+,(a1)+     ; zwing!
  693.             dbra    d2,loop
  694.             .
  695.             .
  696. *
  697. * And now we can go on crunching the contents of the filebuffer with
  698. * CrunchDataTags() and then save it with SaveExecTags(). And when we
  699. * don't need the buffer anymore it can be freed with FreeFileBuffer().
  700. *
  701.  
  702.     INPUTS
  703.         securitylength = how many bytes source data and crunched data can
  704.                          overlap each other without confusing crunching or
  705.                          decrunching.
  706.  
  707.         memsize        = size of the filebuffer.
  708.  
  709.     RESULT
  710.         filebuffer = pointer to filebuffer or NULL if no memory.
  711.  
  712.     SEE ALSO
  713.         FreeFileBuffer(), CrunchDataTags(), SaveExecTags()
  714.  
  715. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  716. stc.library/FileIs
  717.  
  718.     NAME
  719.         FileIs -- examine file if it's already crunched
  720.  
  721.     SYNOPSIS
  722.         fileinfo = FileIs( filename )
  723.         D0         -120    A0
  724.  
  725.         ULONG FileIs( char *filename );
  726.  
  727.     FUNCTION
  728.         Examines file if it's already crunched with any of stc.library
  729.         v2.0+ cruncher. This function finds and separates all decrunchers
  730.         and cruncher types used in stc.library v2.0+.
  731.         Returned fileinfo has a bit complicated layout. The fileinfo is
  732.         divided into two parts. Bits 31-24 include info about the file and
  733.         bits 23-0 include additional info (bytes to skip or DOS errorcode).
  734.  
  735.         IAAA.L = fileinfo
  736.         ^^-^
  737.         | \|
  738.         |  |
  739.         |  +-----> AAA, bits 23-0, additional info
  740.         |
  741.         |
  742.         +--> I = %aabbcccc, bits 31-24
  743.  
  744.         bits 31-30 %aa   = filetype:
  745.             isEXEC          %10 = exec (command file)
  746.             isDATA          %01 = data (can't be runned)
  747.                             %11 = reserved
  748.                             %00 = DOS error occured during examing!
  749.         bits 29-28 %bb   = cruncher type:
  750.                             %00 = not crunched
  751.             isS403          %10 = S403
  752.             isS404          %01 = S404
  753.                             %11 = reserved
  754.         bits 27-24 %cccc = decruncher type:
  755.                             %0000 = not crunched? (sxData?)
  756.             isNPEXEC        %0001 = exec, normal decruncher (sxPExec)
  757.             isLPEXEC        %0010 = exec, library decruncher (sxPExecLib)
  758.             isNABS          %0011 = absolute normal (sxAbsNormal)
  759.             isPABS          %0100 = absolute plain (sxPlain)
  760.             isKABS          %0101 = absolute kill system (sxKillSystem)
  761.                             rest are reserved..
  762.  
  763.         If %aa = %00 (DOS error occured during examing) AAA, bits 23-0,
  764.         include DOS errorcode.
  765.         Otherwise AAA, bits 23-0, include the number of bytes from the
  766.         beginning of the file to the "decrunch info header" (=size of
  767.         decruncher).
  768.  
  769.         Here are some examples of bitcombinations for different files
  770.         (bits 31-24):
  771.                                              aabbcccc
  772.             crunched absolute plain (S404): %01010100
  773.  
  774.                                              aabbcccc
  775.             normal command file:            %10000000
  776.  
  777.                                              aabbcccc
  778.             crunched libexecutable (S404):  %10010010
  779.  
  780.     INPUTS
  781.         filename = pointer to NULL terminated filename.
  782.  
  783.     RESULT
  784.         fileinfo = info about the file or DOS errorcode.
  785.  
  786.     SEE ALSO
  787.         SaveExecTags(), DeCrunchData()
  788.  
  789. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  790.  
  791. MOVEQ   #0,D0
  792. RTS                     ; succesful exit..
  793.