home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 11 / AACD11.ISO / AACD / System / xfd / autodoc / xfdmaster.doc < prev    next >
Text File  |  2000-06-27  |  32KB  |  887 lines
  1. TABLE OF CONTENTS
  2.  
  3. xfdmaster.library/xfdAllocBufferInfo
  4. xfdmaster.library/xfdAllocObject
  5. xfdmaster.library/xfdAllocSegmentInfo
  6. xfdmaster.library/xfdDecrunchBuffer
  7. xfdmaster.library/xfdDecrunchSegment
  8. xfdmaster.library/xfdFreeBufferInfo
  9. xfdmaster.library/xfdFreeObject
  10. xfdmaster.library/xfdFreeScanList
  11. xfdmaster.library/xfdFreeSegmentInfo
  12. xfdmaster.library/xfdGetErrorText
  13. xfdmaster.library/xfdInitScanHook
  14. xfdmaster.library/xfdObjectType
  15. xfdmaster.library/xfdRecogBuffer
  16. xfdmaster.library/xfdRecogLinker
  17. xfdmaster.library/xfdRecogSegment
  18. xfdmaster.library/xfdRelocate
  19. xfdmaster.library/xfdScanData
  20. xfdmaster.library/xfdStripHunks
  21. xfdmaster.library/xfdTestHunkStructure
  22. xfdmaster.library/xfdTestHunkStructureFlags
  23. xfdmaster.library/xfdTestHunkStructureNew
  24. xfdmaster.library/xfdUnlink
  25.  
  26. xfdmaster.library/xfdAllocBufferInfo     xfdmaster.library/xfdAllocBufferInfo
  27.  
  28.    NAME
  29.         xfdAllocBufferInfo -- Allocate memory for BufferInfo structure.
  30.  
  31.    SYNOPSIS
  32.         bufferinfo = xfdAllocBufferInfo()
  33.             D0              -30
  34.  
  35.         struct xfdBufferInfo *xfdAllocBufferInfo(void);
  36.  
  37.    FUNCTION
  38.         Allocates a memory block large enough to hold all information of
  39.         the xfdBufferInfo structure.
  40.  
  41.         (V36) This function is obsolete and shouldn't be used with new
  42.         code any longer. Use xfdAllocObject() instead.
  43.  
  44.    INPUTS
  45.         None.
  46.  
  47.    RESULT
  48.         bufferinfo - Pointer to the xfdBufferInfo structure or NULL if
  49.                      there occured an error.
  50.  
  51.    SEE ALSO
  52.         xfdFreeBufferInfo(), xfdFreeObject()
  53.  
  54. xfdmaster.library/xfdAllocObject             xfdmaster.library/xfdAllocObject
  55.  
  56.    NAME
  57.         xfdAllocObject -- Allocate memory for specified object. (V36)
  58.  
  59.    SYNOPSIS
  60.         object = xfdAllocObject(objecttype)
  61.           D0          -114          D0
  62.  
  63.         APTR xfdAllocObject(ULONG);
  64.  
  65.    FUNCTION
  66.         Allocates a memory block for the specified object. Never do this in
  67.         any other way for compatibility with library updates.
  68.  
  69.         Objecttype can be one of these:
  70.         XFDOBJ_BUFFERINFO     - allocate a xfdBufferInfo structure.
  71.         XFDOBJ_SEGMENTINFO    - allocate a xfdSegmentInfo structure.
  72.         XFDOBJ_LINKERINFO     - allocate a xfdLinkerInfo structure.
  73.         XFDOBJ_SCANNODE (V37) - allocate a xfdScanNode structure.
  74.  
  75.    INPUTS
  76.         objecttype - One of the XFDOBJ_#? values.
  77.  
  78.    RESULT
  79.         object - Pointer to the object or NULL if there occured an error.
  80.  
  81.    SEE ALSO
  82.         xfdFreeObject()
  83.  
  84. xfdmaster.library/xfdAllocSegmentInfo   xfdmaster.library/xfdAllocSegmentInfo
  85.  
  86.    NAME
  87.         xfdAllocSegmentInfo -- Allocate memory for SegmentInfo structure.
  88.  
  89.    SYNOPSIS
  90.         segmentinfo = xfdAllocSegmentInfo()
  91.             D0                -42
  92.  
  93.         struct xfdSegmentInfo *xfdAllocSegmentInfo(void);
  94.  
  95.    FUNCTION
  96.         Allocates a memory block large enough to hold all information of
  97.         the xfdSegmentInfo structure.
  98.  
  99.         (V36) This function is obsolete and shouldn't be used with new
  100.         code any longer. Use xfdAllocObject() instead.
  101.  
  102.    INPUTS
  103.         None.
  104.  
  105.    RESULT
  106.         segmentinfo - Pointer to the xfdSegmentInfo structure or NULL if
  107.                       there occured an error.
  108.  
  109.    SEE ALSO
  110.         xfdFreeSegmentInfo(), xfdFreeObject()
  111.  
  112. xfdmaster.library/xfdDecrunchBuffer       xfdmaster.library/xfdDecrunchBuffer
  113.  
  114.    NAME
  115.         xfdDecrunchBuffer -- Decrunch a file from buffer.
  116.  
  117.    SYNOPSIS
  118.         success = xfdDecrunchBuffer(bufferinfo)
  119.           D0             -60            A0
  120.  
  121.         BOOL xfdDecrunchBuffer(struct xfdBufferInfo *);
  122.  
  123.    FUNCTION
  124.         Decrunches a file to a separate buffer. You have to call
  125.         xfdRecogBuffer() first, only if this call was successful,
  126.         you may call xfdDecrunchBuffer().
  127.  
  128.         You have to pass the type of memory that should be used for
  129.         the target buffer in xfdbi_TargetBufMemType.
  130.  
  131.         (V38) You can submit your own allocated target buffer instead
  132.         in xfdbi_UserTargetBuf and its length in xfdbi_UserTargetBufLen.
  133.         This is only supported if XFDPFB_USERTARGET in xfdbi_PackerFlags
  134.         is set. Make sure to allocate a buffer that is at least as large
  135.         as xfdbi_MinTargetLen.
  136.  
  137.         Additionally you have to init the xfdbi_Special field with
  138.         a pointer to a special info buffer if any special flags are
  139.         set in the xfdbi_PackerFlags field:
  140.         XFDPFB_PASSWORD    - Buffer contains password (max. length of
  141.                              password is stored in xfdbi_MaxSpecialLen,
  142.                              if this is -1, password is not limited).
  143.         XFDPFB_KEY16 (V35) - xfdbi_Special points to an UWORD that holds
  144.                              a 16 bit key.
  145.         XFDPFB_KEY32 (V35) - xfdbi_Special points to an ULONG that holds
  146.                              a 32 bit key.
  147.  
  148.         If the decrunching was successful, the following fields in
  149.         the xfdBufferInfo structure will be initialized:
  150.  
  151.         xfdbi_TargetBuffer     - Pointer to decrunched file buffer.
  152.         xfdbi_TargetBufSaveLen - Length of decrunched file (for saving etc.).
  153.         xfdbi_TargetBufLen     - Total length of allocated buffer.
  154.         xfdbi_DecrAddress      - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  155.                                  this contains the address where the crunched
  156.                                  file has been relocated to.
  157.         xfdbi_JmpAddress       - If XFDPFB_ADDR is set in xfdbi_PackerFlags,
  158.                                  this contains the address where to jump at
  159.                                  in order to run the file.
  160.  
  161.         (V38) If the xfdbi_UserTargetBuf field is used, xfdbi_TargetBuffer
  162.         and xfdbi_TargetBufSaveLen should nevertheless be used for further
  163.         work with the decrunched file, while the buffer itself should be
  164.         released afterwards with the values from xfdbi_UserTargetBuf and
  165.         xfdbi_UserTargetBufLen. This ensures total compatibility with all
  166.         weird slaves.
  167.  
  168.    INPUTS
  169.         bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  170.            xfdbi_TargetBufMemType - Type of memory for target buffer.
  171.            xfdbi_Special          - Pointer to special info if required.
  172.            xfdbi_UserTargetBuf    - Pointer to own target buffer.
  173.            xfdbi_UserTargetBufLen - Length of own target buffer.
  174.  
  175.    RESULT
  176.         success - TRUE if decrunching was successful, FALSE if
  177.                   anything went wrong.
  178.  
  179.    NOTE
  180.         The following two passages are only valid for the standard
  181.         method of decrunching files (without user target buffer):
  182.  
  183.         xfdDecrunchBuffer() allocates a buffer for the decrunched file,
  184.         but it doesn't release this memory afterwards. That is because
  185.         you first have to work with the decrunched file (what else?).
  186.         Therefore you have to do a call to exec.library/FreeMem() after
  187.         you finished work. Use the following parameters:
  188.         xfdbi_TargetBufLen - Lenght of buffer.
  189.         xfdbi_TargetBuffer - Pointer to buffer.
  190.  
  191.         Don't forget:
  192.         xfdbi_TargetBufLen contains the length of the allocated memory
  193.         area, xfdbi_TargetBufSaveLen the length of the decrunched file
  194.         in that buffer.
  195.  
  196.         xfdDecrunchBuffer() never touches the buffer that contains the
  197.         crunched file. It's again your task to release this after
  198.         decrunching.
  199.  
  200.    SEE ALSO
  201.         xfdRecogBuffer(), exec.library/FreeMem()
  202.  
  203. xfdmaster.library/xfdDecrunchSegment     xfdmaster.library/xfdDecrunchSegment
  204.  
  205.    NAME
  206.         xfdDecrunchSegment -- Decrunch a file from its segment list.
  207.  
  208.    SYNOPSIS
  209.         success = xfdDecrunchSegment(segmentinfo)
  210.           D0             -72             A0
  211.  
  212.         BOOL xfdDecrunchSegment(struct xfdSegmentInfo *);
  213.  
  214.    FUNCTION
  215.         Decrunches a segment list. You have to call xfdRecogSegment()
  216.         first, only if this call was successful, you may call
  217.         xfdDecrunchSegment().
  218.  
  219.         You have to init the xfdsi_Special field with a pointer to a
  220.         special info buffer if any special flags are set in the
  221.         xfdsi_PackerFlags field:
  222.         XFDPFB_PASSWORD    - Buffer contains password (max. length of
  223.                              password is stored in xfdsi_MaxSpecialLen,
  224.                              if this is -1, password is not limited).
  225.         XFDPFB_KEY16 (V35) - xfdsi_Special points to an UWORD that holds
  226.                              a 16 bit key.
  227.         XFDPFB_KEY32 (V35) - xfdsi_Special points to an ULONG that holds
  228.                              a 32 bit key.
  229.  
  230.         (V34) Check xfdsi_Packerflags for XFDPFB_RELMODE. If set,
  231.         initialize xfdsi_RelMode with the desired XFDREL_#? value.
  232.  
  233.         If decrunching was successful, xfdsi_SegList holds a BPTR to
  234.         the decrunched segment list. The old segment list has been
  235.         released and/or replaced by the new one (depends on cruncher).
  236.  
  237.         If decrunching failed, xfdsi_SegList may be NULL. This happens
  238.         if an error occured after the seglist has already been changed
  239.         in any way. It then will be released.
  240.         Otherwise, if xfdsi_SegList is not NULL, it still contains a
  241.         valid BPTR to the crunched segment list.
  242.  
  243.    INPUTS
  244.         segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  245.            xfdsi_Special - Pointer to special info if required.
  246.            xfdsi_RelMode - (V34) XFDREL_#? value if required.
  247.  
  248.    RESULT
  249.         success - TRUE if decrunching was successful, FALSE if
  250.                   anything went wrong.
  251.  
  252.    NOTE
  253.         If you no longer need the decrunched segment list, you may
  254.         release it by simply calling dos.library/UnloadSeg().
  255.  
  256.    SEE ALSO
  257.         xfdRecogSegment(), dos.library/UnloadSeg()
  258.  
  259. xfdmaster.library/xfdFreeBufferInfo       xfdmaster.library/xfdFreeBufferInfo
  260.  
  261.    NAME
  262.         xfdFreeBufferInfo -- Free memory of xfdBufferInfo structure.
  263.  
  264.    SYNOPSIS
  265.         xfdFreeBufferInfo(bufferinfo)
  266.                -36            A1
  267.  
  268.         void xfdFreeBufferInfo(struct xfdBufferInfo *);
  269.  
  270.    FUNCTION
  271.         Deallocates the memory reserved via xfdAllocBufferInfo().
  272.  
  273.         (V36) This function is obsolete and shouldn't be used with new
  274.         code any longer. Use xfdFreeObject() instead.
  275.  
  276.    INPUTS
  277.         bufferinfo - Pointer to xfdBufferInfo structure.
  278.  
  279.    RESULT
  280.         None.
  281.  
  282.    SEE ALSO
  283.         xfdAllocBufferInfo(), xfdAllocObject()
  284.  
  285. xfdmaster.library/xfdFreeObject               xfdmaster.library/xfdFreeObject
  286.  
  287.    NAME
  288.         xfdFreeObject -- Free memory of object. (V36)
  289.  
  290.    SYNOPSIS
  291.         xfdFreeObject(object)
  292.             -120        A1
  293.  
  294.         void xfdFreeObject(APTR);
  295.  
  296.    FUNCTION
  297.         Deallocates the memory reserved via xfdAllocObject().
  298.  
  299.    INPUTS
  300.         object - Pointer to object.
  301.  
  302.    RESULT
  303.         None.
  304.  
  305.    SEE ALSO
  306.         xfdAllocObject()
  307.  
  308. xfdmaster.library/xfdFreeScanList           xfdmaster.library/xfdFreeScanList
  309.  
  310.    NAME
  311.         xfdFreeScanList -- Free linked list of xfdScanNode structures. (V37)
  312.  
  313.    SYNOPSIS
  314.         xfdFreeScanList(scannode)
  315.              -144          A1
  316.  
  317.         void xfdFreeScanList(struct xfdScanNode *);
  318.  
  319.    FUNCTION
  320.         Deallocates the memory of all xfdScanNode structures that have been
  321.         returned as result by xfdScanData().
  322.  
  323.    INPUTS
  324.         scannode - Pointer to the first xfdScanNode structure.
  325.  
  326.    RESULT
  327.         None.
  328.  
  329. xfdmaster.library/xfdFreeSegmentInfo     xfdmaster.library/xfdFreeSegmentInfo
  330.  
  331.    NAME
  332.         xfdFreeSegmentInfo -- Free memory of xfdSegmentInfo structure.
  333.  
  334.    SYNOPSIS
  335.         xfdFreeSegmentInfo(segmentinfo)
  336.                -48             A1
  337.  
  338.         void xfdFreeSegmentInfo(struct xfdSegmentInfo *);
  339.  
  340.    FUNCTION
  341.         Deallocates the memory reserved via xfdAllocSegmentInfo().
  342.  
  343.         (V36) This function is obsolete and shouldn't be used with new
  344.         code any longer. Use xfdFreeObject() instead.
  345.  
  346.    INPUTS
  347.         segmentinfo - Pointer to xfdSegmentInfo structure.
  348.  
  349.    RESULT
  350.         None.
  351.  
  352.    SEE ALSO
  353.         xfdAllocSegmentInfo(), xfdAllocObject()
  354.  
  355. xfdmaster.library/xfdGetErrorText           xfdmaster.library/xfdGetErrorText
  356.  
  357.    NAME
  358.         xfdGetErrorText -- Get an ascii string from an error number.
  359.  
  360.    SYNOPSIS
  361.         string = xfdGetErrorText(error)
  362.           D0           -78        D0.w
  363.  
  364.         STRPTR xfdGetErrorText(UWORD);
  365.  
  366.    FUNCTION
  367.         Whenever a library call fails, you receive an error number either
  368.         in the xfd#?_Error field or directly as a returncode. This function
  369.         gets the corresponding ascii string to the occured error.
  370.  
  371.    INPUTS
  372.         error - Error number from xfd#?_Error or returncode.
  373.  
  374.    RESULT
  375.         string - Pointer to an ascii string that describes the error.
  376.  
  377. xfdmaster.library/xfdInitScanHook           xfdmaster.library/xfdInitScanHook
  378.  
  379.    NAME
  380.         xfdInitScanHook -- Allocate and init xfdScanHook structure. (V37)
  381.  
  382.    SYNOPSIS
  383.         scanhook = xfdInitScanHook(entry, data)
  384.            D0           -156         A0    A1
  385.  
  386.         struct xfdScanHook *xfdInitScanHook(BOOL (*)(), APTR);
  387.  
  388.    FUNCTION
  389.         Allocates a xfdScanHook structure and fills the xfdsh_Entry and
  390.         xfdsh_Data fields with the given arguments.
  391.         You may do these two steps by yourself using xfdAllocObject(), but
  392.         this method is just easier.
  393.  
  394.    INPUTS
  395.         entry - The entrypoint of your hook code. Note that only registers
  396.                 D0/D1/A0/A1 may be scratched, all others have to be saved.
  397.         data  - Pointer to some data that might be useful for the execution
  398.                 of your hook code.
  399.  
  400.    RESULT
  401.         scanhook - Pointer to the xfdScanHook structure or NULL if there
  402.                    occured an error.
  403.  
  404.    NOTE
  405.         You have to release the memory of this structure if you don't
  406.         need it any longer with xfdFreeObject().
  407.  
  408.    SEE ALSO
  409.         xfdAllocObject(), xfdFreeObject(), xfdScanData()
  410.  
  411. xfdmaster.library/xfdObjectType               xfdmaster.library/xfdObjectType
  412.  
  413.    NAME
  414.         xfdObjectType -- Determine type of object. (V37)
  415.  
  416.    SYNOPSIS
  417.         objecttype = xfdObjectType(object)
  418.             D0            -150       A1
  419.  
  420.         ULONG xfdObjectType(APTR);
  421.  
  422.    FUNCTION
  423.         Checks if object points to a XFDOBJ_#? object and returns the type
  424.         of this object if possible.
  425.  
  426.    INPUTS
  427.         object - Pointer to a possible XFDOBJ_#? object.
  428.  
  429.    RESULT
  430.         objecttype - One of the XFDOBJ_#? values or NULL if not an object.
  431.  
  432.    SEE ALSO
  433.         xfdAllocObject()
  434.  
  435. xfdmaster.library/xfdRecogBuffer             xfdmaster.library/xfdRecogBuffer
  436.  
  437.    NAME
  438.         xfdRecogBuffer -- Examine buffer for crunched file.
  439.  
  440.    SYNOPSIS
  441.         success = xfdRecogBuffer(bufferinfo)
  442.           D0             -54         A0
  443.  
  444.         BOOL xfdRecogBuffer(struct xfdBufferInfo *);
  445.  
  446.    FUNCTION
  447.         Examines a file for known crunchers. You pass a pointer to
  448.         the file buffer in xfdbi_SourceBuffer and the length of the
  449.         buffer in xfdbi_SourceBufLen.
  450.  
  451.         (V37) You may additionally set some flags in xfdbi_Flags:
  452.         XFDFB_RECOGEXTERN     - If this flag is set, the external slaves
  453.                                 will be used for recognition, otherwise
  454.                                 they will be ignored.
  455.         XFDFB_RECOGTARGETLEN  - (V38) If this flag is set, only slaves
  456.                                 that support XFDPFB_RECOGLEN will be
  457.                                 used for recognition.
  458.         XFDFB_RECOGUSERTARGET - (V38) If this flag is set, only slaves
  459.                                 that support XFDPFB_USERTARGET will be
  460.                                 used for recognition.
  461.  
  462.         If a crunched file has been recognized, the following fields
  463.         in the xfdBufferInfo structure will be initialized:
  464.  
  465.         xfdbi_PackerName     - Pointer to the name of the cruncher.
  466.         xfdbi_PackerFlags    - Contains the packer type and additional
  467.                                information (eg. password).
  468.         xfdbi_MaxSpecialLen  - Only used if any special flags are set.
  469.         xfdbi_MinTargetLen   - (V38) If XFDPFB_RECOGLEN is supported,
  470.                                this field holds the memory required to
  471.                                decrunch this file (or -1 if length
  472.                                couldn't be recognized correctly).
  473.         xfdbi_FinalTargetLen - (V38) If XFDPFB_RECOGLEN is supported,
  474.                                this field holds the final length of the
  475.                                file after decrunching (or -1 if length
  476.                                couldn't be recognized correctly).
  477.  
  478.    INPUTS
  479.         bufferinfo - Pointer to an initialized xfdBufferInfo structure:
  480.            xfdbi_SourceBuffer - Pointer to file buffer.
  481.            xfdbi_SourceBufLen - Length of file buffer.
  482.            (V37) xfdbi_Flags  - Flags for recognition.
  483.  
  484.    RESULT
  485.         success - TRUE if a cruncher has been recognized, FALSE if
  486.                   file is unknown.
  487.  
  488.    SEE ALSO
  489.         xfdDecrunchBuffer()
  490.  
  491.    NOTE
  492.         The behaviour concerning external slaves has changed for V37.
  493.         This was neccessary as there exist a lot of external slaves that
  494.         are not coded properly. The XFDFB_RECOGEXTERN flag has been
  495.         introduced to avoid problems unless the user really wants to use
  496.         external recognition.
  497.  
  498. xfdmaster.library/xfdRecogLinker             xfdmaster.library/xfdRecogLinker
  499.  
  500.    NAME
  501.         xfdRecogLinker -- Examine buffer for linked file. (V36)
  502.  
  503.    SYNOPSIS
  504.         success = xfdRecogLinker(linkerinfo)
  505.           D0           -126          A0
  506.  
  507.         BOOL xfdRecogLinker(struct xfdLinkerInfo *);
  508.  
  509.    FUNCTION
  510.         Examines a file for known link mechanisms. You pass a pointer to
  511.         the file buffer in xfdli_Buffer and the length of the buffer in
  512.         xfdli_BufLen.
  513.  
  514.         If a linked file has been recognized, the following fields
  515.         in the xfdLinkerInfo structure will be initialized:
  516.  
  517.         xfdli_LinkerName - Pointer to the name of the linker.
  518.  
  519.    INPUTS
  520.         linkerinfo - Pointer to an initialized xfdLinkerInfo structure:
  521.            xfdli_Buffer - Pointer to file buffer.
  522.            xfdli_BufLen - Length of file buffer.
  523.  
  524.    RESULT
  525.         success - TRUE if a linker has been recognized, FALSE if
  526.                   file is unknown.
  527.  
  528.    SEE ALSO
  529.         xfdUnlink()
  530.  
  531. xfdmaster.library/xfdRecogSegment           xfdmaster.library/xfdRecogSegment
  532.  
  533.    NAME
  534.         xfdRecogSegment -- Examine segment list for crunched file.
  535.  
  536.    SYNOPSIS
  537.         success = xfdRecogSegment(segmentinfo)
  538.           D0             -66          A0
  539.  
  540.         BOOL xfdRecogSegment(struct xfdSegmentInfo *);
  541.  
  542.    FUNCTION
  543.         Examines a segment list for known crunchers. You pass a BPTR
  544.         to the segment list in xfdsi_SegList.
  545.  
  546.         (V37) You may additionally set some flags in xfdsi_Flags:
  547.         XFDFB_RECOGEXTERN   - If this flag is set, the external slaves
  548.                               will be used for recognition, otherwise
  549.                               they will be ignored.
  550.  
  551.         If a crunched segment list has been recognized, the following
  552.         fields in the xfdSegmentInfo structure will be initialized:
  553.  
  554.         xfdsi_PackerName    - Pointer to the name of the cruncher.
  555.         xfdsi_PackerFlags   - Contains the packer type and additional
  556.                               information (eg. password).
  557.         xfdsi_MaxSpecialLen - Only used if any special flags are set.
  558.  
  559.    INPUTS
  560.         segmentinfo - Pointer to an initialized xfdSegmentInfo structure:
  561.            xfdsi_SegList     - BPTR to segment list.
  562.            (V37) xfdsi_Flags - Flags for recognition.
  563.  
  564.    RESULT
  565.         success - TRUE if a cruncher has been recognized, FALSE if
  566.                   segment list is unknown.
  567.  
  568.    SEE ALSO
  569.         xfdDecrunchSegment()
  570.  
  571. xfdmaster.library/xfdRelocate                   xfdmaster.library/xfdRelocate
  572.  
  573.    NAME
  574.         xfdRelocate -- Create segment list from file buffer. (V34)
  575.  
  576.    SYNOPSIS
  577.         error = xfdRelocate(buffer, length, result, mode)
  578.          D0.w       -96       A0      D0      A1    D1.w
  579.  
  580.         UWORD xfdRelocate(APTR, ULONG, ULONG *, UWORD);
  581.  
  582.    FUNCTION
  583.         Creates a relocated and fully executable segment list from
  584.         a file buffer. The result is a BPTR to the first segment,
  585.         similar to the result of a call to dos.library/LoadSeg().
  586.  
  587.    INPUTS
  588.         buffer - Pointer to the file buffer that should be relocated.
  589.         length - Length of the file buffer.
  590.         result - Pointer to the longword that should hold the result.
  591.         mode   - Any XFDREL_#? relocation mode.
  592.  
  593.    RESULT
  594.         error  - XFDERR_OK if no error occured, else XFDERR_#?.
  595.         result - Holds a BPTR to the first segment if error = XFDERR_OK.
  596.  
  597.    NOTE
  598.         There is no need to call xfdTestHunkStructure[New|Flags]() before
  599.         relocation because xfdRelocate() does this already.
  600.  
  601.         This routine supports the following hunk types:
  602.         - hunk_name         ($3e8) -> Skipped.
  603.         - hunk_code         ($3e9) -> Creates new code segment.
  604.         - hunk_data         ($3ea) -> Creates new data segment.
  605.         - hunk_bss          ($3eb) -> Creates new bss segment.
  606.         - hunk_reloc32      ($3ec) -> Used for relocation.
  607.         - hunk_symbol       ($3f0) -> Skipped.
  608.         - hunk_debug        ($3f1) -> Skipped.
  609.         - hunk_end          ($3f2) -> May be left out.
  610.         - hunk_header       ($3f3) -> Only at top of file.
  611.         - hunk_reloc32short ($3f7/$3fc) -> Used for relocation.
  612.         Any other hunk types create an error. There is no support for
  613.         hunk_overlay, because the main purpose of this routine is to
  614.         be called from xfds_DecrunchSegment. And in that case, the real
  615.         dos.library/LoadSeg() has already initialized the overlay header.
  616.  
  617. xfdmaster.library/xfdScanData                   xfdmaster.library/xfdScanData
  618.  
  619.    NAME
  620.         xfdScanData -- Scan buffer for crunched data areas. (V37)
  621.  
  622.    SYNOPSIS
  623.         error = xfdScanData(buffer, length, result, flags, scanhook)
  624.          D0.w      -138       A0      D0      A1     D1.w     A2
  625.  
  626.         UWORD xfdScanData(APTR, ULONG, ULONG *, UWORD, struct xfdScanHook *);
  627.  
  628.    FUNCTION
  629.         Scans the buffer for any crunched data and returns a linked list
  630.         of xfdScanNode structures if one or more data files have been found.
  631.  
  632.         Flags can be one or more of these:
  633.         XFDSDF_USEEXTERN - Use external slaves for scanning.
  634.         XFDSDF_SCANODD   - Scan at odd addresses (only if CPU = 68020+)
  635.  
  636.         If you submit a xfdScanHook structure, you should initialize it
  637.         using xfdInitScanHook(). After every scanned byte (or word if
  638.         odd scanning is not used) your hook function will be called and
  639.         given an APTR to its own xfdScanHook structure in register A0.
  640.         You may or may not use any information from the structure in your
  641.         hook code and then set a returncode in D0 (TRUE to continue
  642.         scanning or FALSE to abort).
  643.         The xfdsh_ToDo field contains the amount of bytes that still have
  644.         to be scanned. The value is taken after a scan attempt has been
  645.         performed. Additionally, if the last scan attempt leaded to a
  646.         result, xfdsh_ScanNode contains a pointer to the respective
  647.         xfdScanNode structure.
  648.  
  649.         You may use the hook for several things, eg. just to test for a
  650.         break signal or a pressed gadget, as a progress indicator or to
  651.         print detected data immediately instead of waiting until the end
  652.         of the scan.
  653.  
  654.    INPUTS
  655.         buffer   - Pointer to the buffer that should be scanned.
  656.         length   - Length of the buffer.
  657.         result   - Pointer to the longword that should hold the pointer
  658.                    to the first xfdScanNode structure.
  659.         flags    - One or more XFDSDB_#? scan flags.
  660.         scanhook - Pointer to initialized xfdScanHook structure or NULL.
  661.  
  662.    RESULT
  663.         error  - XFDERR_OK if no error occured,
  664.                  XFDERR_HOOKBREAK if hook returned FALSE,
  665.                  else XFDERR_#?.
  666.         result - Holds pointer to the first xfdScanNode structure or NULL
  667.                  if nothing was found. This is only valid if error is either
  668.                  XFDERR_OK or XFDERR_HOOKBREAK.
  669.  
  670.    SEE ALSO
  671.         xfdInitScanHook()
  672.  
  673. xfdmaster.library/xfdStripHunks               xfdmaster.library/xfdStripHunks
  674.  
  675.    NAME
  676.         xfdStripHunks -- Remove annoying hunks from file buffer. (V36)
  677.  
  678.    SYNOPSIS
  679.         error = xfdStripHunks(buffer, length, result, flags)
  680.          D0.w       -108        A0      D0      A1    D1.w
  681.  
  682.         UWORD xfdStripHunks(APTR, ULONG, ULONG *, UWORD);
  683.  
  684.    FUNCTION
  685.         Strips hunk_name, hunk_symbol and hunk_debug from file buffer.
  686.         This might be useful to shorten executables, but the main
  687.         purpose is to remove decrunch protections based on modified
  688.         hunk structures.
  689.  
  690.    INPUTS
  691.         buffer - Pointer to the file buffer that should be stripped.
  692.         length - Length of the file buffer.
  693.         result - Pointer to the longword that should hold the new
  694.                  file length after stripping.
  695.         flags  - One or more XFDSHB_#? strip flags.
  696.  
  697.    RESULT
  698.         error  - XFDERR_OK if no error occured, else XFDERR_#?.
  699.         result - Holds new length of file if error = XFDERR_OK.
  700.  
  701.    NOTE
  702.         There is no need to call xfdTestHunkStructure[New|Flags]() before
  703.         stripping because xfdStripHunks() does this already.
  704.  
  705.         Attention! The new file length given as a result may be used
  706.         to save the modified file to disk, but the length of the
  707.         buffer itself is still the same as it was before the call.
  708.  
  709.         This routine supports the following hunk types:
  710.         - hunk_name         ($3e8) -> Stripped on XFDSHB_NAME.
  711.         - hunk_code         ($3e9) -> Skipped.
  712.         - hunk_data         ($3ea) -> Skipped.
  713.         - hunk_bss          ($3eb) -> Skipped.
  714.         - hunk_reloc32      ($3ec) -> Skipped.
  715.         - hunk_symbol       ($3f0) -> Stripped on XFDSHB_SYMBOL.
  716.         - hunk_debug        ($3f1) -> Stripped on XFDSHB_DEBUG.
  717.         - hunk_end          ($3f2) -> Skipped.
  718.         - hunk_header       ($3f3) -> Only at top of file.
  719.         - hunk_reloc32short ($3f7/$3fc) -> Skipped.
  720.         Any other hunk types create an error.
  721.  
  722. xfdmaster.library/xfdTestHunkStructure xfdmaster.library/xfdTestHunkStructure
  723.  
  724.    NAME
  725.         xfdTestHunkStructure -- Test hunks of executable file.
  726.  
  727.    SYNOPSIS
  728.         success = xfdTestHunkStructure(buffer, length)
  729.           D0              -84            A0      D0
  730.  
  731.         BOOL xfdTestHunkStructure(APTR, ULONG);
  732.  
  733.    FUNCTION
  734.         Checks an executable file for a valid hunk structure.
  735.         This is important for decrunching files, because an incomplete
  736.         or damaged file may cause a system crash.
  737.  
  738.    INPUTS
  739.         buffer - Pointer to the file buffer that should be checked.
  740.         length - Length of the file buffer.
  741.  
  742.    RESULT
  743.         success - TRUE if file is ok, FALSE if file is damaged.
  744.  
  745.    NOTE
  746.         It is recommended to use xfdTestHunkStructureNew() instead of
  747.         this routine for a more detailed error description. Internally
  748.         both calls use the same routines, this one is only left here
  749.         for downward compatibility.
  750.  
  751.    SEE ALSO
  752.         xfdTestHunkStructureNew(), xfdTestHunkStructureFlags()
  753.  
  754. xfdmaster.l/xfdTestHunkStructureFlags   xfdmaster.l/xfdTestHunkStructureFlags
  755.  
  756.    NAME
  757.         xfdTestHunkStructureFlags -- Test hunks of executable file. (V36)
  758.  
  759.    SYNOPSIS
  760.         error = xfdTestHunkStructureFlags(buffer, length, flags)
  761.          D0.w            -102               A0      D0     D1.w
  762.  
  763.         UWORD xfdTestHunkStructureFlags(APTR, ULONG, UWORD);
  764.  
  765.    FUNCTION
  766.         Checks an executable file for a valid hunk structure and reacts
  767.         on certain hunk types if special flags are given.
  768.         This is important for decrunching files, because an incomplete
  769.         or damaged file may cause a system crash.
  770.  
  771.    INPUTS
  772.         buffer - Pointer to the file buffer that should be checked.
  773.         length - Length of the file buffer.
  774.         flags  - Flags to cause special actions on certain hunk types.
  775.                  These are:
  776.                  XFDTHB_NOOVERLAYS - forces error on hunk_overlay.
  777.  
  778.    RESULT
  779.         error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged
  780.                 or special flags got activated.
  781.  
  782.    NOTE
  783.         You don't have to call this function before trying to decrunch
  784.         a file, because xfdDecrunchBuffer() does this already.
  785.  
  786.         This hunk checker supports the following hunk types:
  787.         - hunk_name         ($3e8)
  788.         - hunk_code         ($3e9)
  789.         - hunk_data         ($3ea)
  790.         - hunk_bss          ($3eb)
  791.         - hunk_reloc32      ($3ec)
  792.         - hunk_symbol       ($3f0)
  793.         - hunk_debug        ($3f1)
  794.         - hunk_end          ($3f2)
  795.         - hunk_header       ($3f3)
  796.         - hunk_overlay      ($3f5) -> forces error on XFDTHB_NOOVERLAYS
  797.         - hunk_break        ($3f6)
  798.         - hunk_reloc32short ($3f7/$3fc)
  799.         It recognizes the standard hunk_overlay ($3f5) format and some
  800.         user-defined overlay types too. Anyway, it may happen that some
  801.         weird overlay hunk causes problems because there isn't any real
  802.         definition for overlays.
  803.         The hunk structure of a non-overlayed file will nevertheless
  804.         be checked 100% correctly.
  805.  
  806.    SEE ALSO
  807.         xfdTestHunkStructureNew()
  808.  
  809. xfdmaster.lib/xfdTestHunkStructureNew   xfdmaster.lib/xfdTestHunkStructureNew
  810.  
  811.    NAME
  812.         xfdTestHunkStructureNew -- Test hunks of executable file. (V34)
  813.  
  814.    SYNOPSIS
  815.         error = xfdTestHunkStructureNew(buffer, length)
  816.          D0.w           -90               A0      D0
  817.  
  818.         UWORD xfdTestHunkStructureNew(APTR, ULONG);
  819.  
  820.    FUNCTION
  821.         Checks an executable file for a valid hunk structure.
  822.         This is important for decrunching files, because an incomplete
  823.         or damaged file may cause a system crash.
  824.  
  825.    INPUTS
  826.         buffer - Pointer to the file buffer that should be checked.
  827.         length - Length of the file buffer.
  828.  
  829.    RESULT
  830.         error - XFDERR_OK if file is ok, XFDERR_#? if file is damaged.
  831.  
  832.    NOTE
  833.         This is actually just a call to xfdTestHunkStructureFlags()
  834.         with no flags set.
  835.  
  836.    SEE ALSO
  837.         xfdTestHunkStructureFlags()
  838.  
  839. xfdmaster.library/xfdUnlink                       xfdmaster.library/xfdUnlink
  840.  
  841.    NAME
  842.         xfdUnlink -- Unlink two files inside the same buffer. (V36)
  843.  
  844.    SYNOPSIS
  845.         success = xfdUnlink(linkerinfo)
  846.           D0        -132        A0
  847.  
  848.         BOOL xfdUnlink(struct xfdLinkerInfo *);
  849.  
  850.    FUNCTION
  851.         Unlinks two files that have been joined by some so-called
  852.         4EB9-Linkers or any other recogniced linker type. No new buffers are
  853.         created, unlinked files are both located inside source buffer. You
  854.         have to call xfdRecogLinker() first, only if this call was
  855.         successful, you may call xfdUnlink().
  856.  
  857.         If unlinking was successful, the following fields in the
  858.         xfdLinkerInfo structure will be initialized:
  859.  
  860.         xfdli_Save1    - Pointer to first unlinked file.
  861.         xfdli_Save2    - Pointer to second unlinked file.
  862.         xfdli_SaveLen1 - Length of first unlinked file.
  863.         xfdli_SaveLen2 - Length of second unlinked file.
  864.  
  865.    INPUTS
  866.         linkerinfo - Pointer to an initialized xfdLinkerInfo structure
  867.                      as received by xfdRecogLinker().
  868.  
  869.    RESULT
  870.         success - TRUE if unlinking was successful, FALSE if
  871.                   anything went wrong.
  872.  
  873.    NOTE
  874.         After a call to xfdUnlink(), the contents of xfdli_Buffer are
  875.         under no circumstances valid any longer. The only way to make use
  876.         of the buffer contents is via xfdli_Save1 and xfdli_Save2.
  877.         But if you have finished work with the splitted files, you have
  878.         to release exactly the memory you have allocated for xfdli_Buffer.
  879.  
  880.         There exist several programs that produce the same linker output.
  881.         Some of them are very badly programmed, so if unlinking fails or
  882.         produces non-executable files, don't blame xfdmaster.library.
  883.  
  884.    SEE ALSO
  885.         xfdRecogLinker()
  886.  
  887.