home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 6 / Sonderheft_6-96.iso / pd / libraries / patchlibv4 / autodocs / patch.doc
Text File  |  1996-11-03  |  26KB  |  756 lines
  1. TABLE OF CONTENTS
  2.  
  3. patch.library/CreatePatchProjectA
  4. patch.library/FindPatch
  5. patch.library/FindPatchTagsA
  6. patch.library/GetPatchA
  7. patch.library/InstallPatch
  8. patch.library/InstallPatchTagsA
  9. patch.library/PatchFreeVec
  10. patch.library/RemovePatch
  11. patch.library/RemovePatchProjectA
  12. patch.library/RemovePatchTagsA
  13. patch.library/SetPatchA
  14. patch.library/WaitRemovePatch
  15.  
  16. patch.library/CreatePatchProjectA           patch.library/CreatePatchProjectA
  17.  
  18.    NAME
  19.     CreatePatchProjectA -- Create an instance of a patch project. (V4)
  20.     CreatePatchProject -- varargs stub for CreatePatchProjectA(). (V4)
  21.  
  22.    SYNOPSIS
  23.     project = CreatePatchProjectA( projectname, taglist )
  24.     D0                           A0           A1
  25.  
  26.     APTR CreatePatchProjectA( STRPTR, struct TagItem *);
  27.  
  28.     project = CreatePatchProject( projectname, firsttag, ...)
  29.  
  30.     APTR CreatePatchProject( STRPTR, Tag, ...);
  31.  
  32.    FUNCTION
  33.     Create an instance of a patch project.
  34.  
  35.     This instance may be used to manipulate or remove patches belonging
  36.     to one project (or program) with one function call.
  37.  
  38.     The projectname will be copied into an internal buffer.
  39.  
  40.    INPUTS
  41.     projectname = pointer to name of the patch project
  42.     taglist     = pointer to array of tags
  43.  
  44.    TAGS
  45.     none defined yet
  46.  
  47.    RESULT
  48.     project = pointer to patch projects private structure or 
  49.           null on failure
  50.  
  51.    NOTES
  52.  
  53.    BUGS
  54.  
  55.    SEE ALSO
  56.     RemovePatchProject(), InstallPatchTags(), patch.h
  57.   patch.library/FindPatch                               patch.library/FindPatch
  58.  
  59.    NAME
  60.     FindPatch -- find a patch structure with a given name.
  61.  
  62.    SYNOPSIS
  63.     patch = FindPatch( Name )
  64.     D0               A0
  65.  
  66.     struct Patch *FindPatch( STRPTR );
  67.  
  68.    FUNCTION
  69.     This function will search the patch.library lists for a
  70.     patch structure with the given name. The first patch matching
  71.     this name will be returned.
  72.  
  73.     This function exists only for historic reasons.
  74.     It will internally be routed back to FindPatchTags().
  75.  
  76.    INPUTS
  77.     Name = Name of the patch structure to find
  78.  
  79.    RESULT
  80.     patch = a pointer to the patch structure with the same name else
  81.         zero to indicate that the string was not found.
  82.  
  83.    NOTES
  84.     If your task is not the owner of the patch, the
  85.     pointer is only valid as long as the system is in forbid().
  86.     From V2 on you may also lock the patch.library semaphore
  87.     before calling this function. In this case a pointer to
  88.     a patch structure is guaranteed to be valid, until you
  89.     release the semaphore. The semaphore, however, should be kept
  90.     locked only for short periods of time in order not to block
  91.     other tasks.
  92.  
  93.    BUGS
  94.  
  95.    SEE ALSO
  96.     InstallPatch(), RemovePatch(), Patch.h
  97.  patch.library/FindPatchTagsA                     patch.library/FindPatchTagsA
  98.  
  99.    NAME
  100.     FindPatchTagsA -- find a patch structure with certain criteria. (V3)
  101.     FindPatchTags -- varargs stub for FindPatchTagsA(). (V3)
  102.  
  103.    SYNOPSIS
  104.     object = FindPatchTagsA( taglist )
  105.     D0               A0
  106.  
  107.     APTR FindPatchTagsA( struct TagItem *);
  108.  
  109.     object = FindPatchTags( firsttag, ...)
  110.  
  111.     APTR FindPatchTags( Tag, ...);
  112.  
  113.    FUNCTION
  114.     This function will search the patch.library lists for a
  115.     patch structure, that matches the criteria specified in the taglist.
  116.     The first matching patch will be returned.
  117.  
  118.    INPUTS
  119.     taglist = pointer to array of tags
  120.  
  121.    TAGS
  122.     Specify only one of these at a time:
  123.     PATT_PatchName (STRPTR) - Specifies that patch.library should
  124.         search for the occurrence of a patch of the given name.
  125.     PATT_ProjectName (V4) (STRPTR) - Specifies that patch.library should
  126.         search for the occurrence of a project of the given name.
  127.  
  128.  
  129.     PATT_NoCase (V4) (BOOL) - If specified with PATT_PatchName or
  130.         PATT_ProjectID string-comparison will be case-independent.
  131.         International characters are not respected with this version
  132.         of patch.library.
  133.         This may or may not change in the future.
  134.     PATT_LastObject (V4) (APTR) - This tag allows to search for multiple
  135.         matching objects. Simply specify the result of an previous
  136.         call to FindPatchTags() to continue searching with this tag.
  137.         You may also specify NULL to start searching the lists from
  138.         the beginning. Keep in mind, that you must make sure, that
  139.         the pointer is valid (see notes).
  140.  
  141.    RESULT
  142.     object = a pointer to the object as requested within the taglist or
  143.         zero to indicate that no match was found.
  144.  
  145.    NOTES
  146.     If your task is not the owner of the patch, the
  147.     pointer is only valid as long as the system is in forbid().
  148.     You may also lock the patch.library semaphore
  149.     before calling this function. In this case a pointer to
  150.     a patch structure is guaranteed to be valid, until you
  151.     release the semaphore. The semaphore, however, should be kept
  152.     locked only for short periods of time in order not to block
  153.     other tasks.
  154.  
  155.    BUGS
  156.  
  157.    SEE ALSO
  158.     InstallPatchTags(), RemovePatchTags(), PatchTags.h
  159.  patch.library/GetPatchA                               patch.library/GetPatchA
  160.  
  161.    NAME
  162.     GetPatchA -- Returns certain attributes of a patch. (V3)
  163.     GetPatch -- varargs stub for GetPatchA(). (V3)
  164.  
  165.    SYNOPSIS
  166.     Result = GetPatchA( patch, taglist )
  167.     D0                A0     A1
  168.  
  169.     ULONG Result GetPatchA( struct Patch *, struct TagItem *);
  170.  
  171.     Result = GetPatch( patch, firsttag, ...)
  172.  
  173.     ULONG Result GetPatch( struct Patch *, Tag, ...);
  174.  
  175.    FUNCTION
  176.     Returns certain attributes and lists connected to a patch (see TAGS).
  177.  
  178.    INPUTS
  179.     patch = pointer to a patch structure or NULL for no action
  180.     taglist = pointer to array of tags
  181.  
  182.    TAGS
  183.     PATT_Result2 (APTR) - An optional pointer to a longword, which will
  184.         contain an errorcode as defined patch.h, when
  185.         the function returns.
  186.         Assembler programmers can get the same value from d1.
  187.  
  188.     Only one of the following tags may be specified at a time:
  189.  
  190.     PATT_PatchName (BOOL) - Return a pointer to a copy of the name of
  191.         the patch in a null-terminated string.
  192.         This pointer must be passed to PatchFreeVec(), if
  193.         the string is no longer needed.
  194.         Type of Result is STRPTR.
  195.     PATT_TaskListType (BOOL) - Return the type of the internal TaskList
  196.         Possible results:
  197.         TL_TYPE_INCLUDE: all specified tasks will use the patchroutine,
  198.                  all others will ignore it.
  199.         TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine,
  200.                  all others will use it.
  201.         NULL:         An error occurred (this includes the absence of
  202.                  a TaskList). Check the secondary errorcode for
  203.                  more information.
  204.         Type of Result is ULONG.
  205.     PATT_TaskList (BOOL) - Return a pointer to a taglist containing all
  206.         tasknames and taskids attached to patch. The tagitems are either
  207.         PATT_AddTaskName or PATT_AddTaskID.
  208.         This pointer must be passed to PatchFreeVec(), if
  209.         the tasklist is no longer needed.
  210.         Type of Result is taglist.
  211.     PATT_Disabled (V4) (BOOL) - Return a number representing the current
  212.         disable nesting counter of a patch. Null means the patch is
  213.         enabled and will be used, by any tasks using the
  214.         library function.
  215.  
  216.    RESULT
  217.     Result = Pointer or longword depending on specified tags.
  218.          A result of zero indicates an error.
  219.  
  220.     Errorcodes returned with PATT_Result2 or in register d1:
  221.         PATERR_Ok
  222.             Indicates success of the operation.
  223.         PATERR_OutOfMem
  224.             Indicates that there was not enough memory to
  225.             complete the operation.
  226.         PATERR_InvalidHandle
  227.             Indicates that the pointer to the patch passed
  228.             to the function was not or is no longer valid.
  229.             This might happen, if you pass a wrong pointer or
  230.             you got the pointer via FindPatch() and another
  231.             task has removed the patch before this task called
  232.             RemovePatchTags().
  233.         PATERR_NoTaskList
  234.             No valid TaskList is attached to the patch.
  235.             The SetPatchA() function with the PATT_CreateTaskList tag
  236.             specified, must be called to allocate a TaskList.
  237.         PATERR_PatchUnnamed
  238.             The patch has no identification string attached to it.
  239.  
  240.    NOTES
  241.  
  242.    BUGS
  243.  
  244.    SEE ALSO
  245.     InstallPatchTags(), PatchFreeVec(), Patch.h, PatchTags.h
  246.  patch.library/InstallPatch                         patch.library/InstallPatch
  247.  
  248.    NAME
  249.     InstallPatch -- Installs a patchroutine for library functions.
  250.  
  251.    SYNOPSIS
  252.     patch = InstallPatch( newPatch )
  253.     D0              A0
  254.  
  255.     struct Patch *InstallPatch( struct NewPatch * );
  256.  
  257.    FUNCTION
  258.     This function exists only for historic reasons. It will internally
  259.     routed back to InstallPatchTags(). Because InstallPatchTags()
  260.     has advanced features there is definitely no need to call this
  261.     function at all.
  262.  
  263.    INPUTS
  264.     NewPatch = pointer to an instance of a NewPatch structure
  265.  
  266.    RESULT
  267.     patch = pointer to a Patch structure or NULL on failure
  268.  
  269.    NOTES
  270.  
  271.    BUGS
  272.  
  273.    SEE ALSO
  274.     InstallPatchTags()
  275.  patch.library/InstallPatchTagsA               patch.library/InstallPatchTagsA
  276.  
  277.    NAME
  278.     InstallPatchTagsA -- Installs a patchcode for library functions. (V2)
  279.     InstallPatchTags -- varargs stub for InstallPatchTagsA(). (V2)
  280.  
  281.    SYNOPSIS
  282.     patch = InstallPatchTagsA( funcEntry, funcOffset, tagList )
  283.     D0                    A0         D0          A1
  284.  
  285.     struct Patch *InstallPatchTagsA( APTR, UWORD, struct TagItem * );
  286.  
  287.     patch = InstallPatchTags( funcEntry, funcOffset, firsttag, ...)
  288.  
  289.     struct Patch *InstallPatchTags( APTR, UWORD, Tag, ...);
  290.  
  291.    FUNCTION
  292.     Adds a user provided routine to a library function.
  293.  
  294.     NEW for V3: An internal call to SetPatch() will be made.
  295.     So all tags which are valid with SetPatch() may be specified in the
  296.     taglist.
  297.  
  298.    INPUTS
  299.     funcEntry = pointer to the entry of the function to add
  300.     funcOffset = Library Offset Vector (LVO) of the function to patch
  301.     taglist = pointer to array of tags
  302.  
  303.    TAGS
  304.     PATT_LibraryName (STRPTR) - Specifies that you want to patch a library
  305.         of the given name ( as in exec.library/OpenLibrary() ).
  306.         Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase
  307.         MUST be specified.
  308.     PATT_DeviceName (STRPTR) - Specifies that you want to patch a device
  309.         of the given name ( as in exec.library/OpenDevice() ).
  310.         Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase
  311.         MUST be specified.
  312.     PATT_LibraryBase (struct Library *) Specifies that you want to patch
  313.         a library, device or resource with the given base.
  314.         You may get such a pointer by calling one of the following
  315.         exec functions: OpenLibrary(), OpenDevice(), OpenResource()
  316.         You may safely close this library, if InstallPatchTags()
  317.         returns, because patch.library will increase the OpenCount
  318.         to make sure, that the library won't be removed from the
  319.         system as long as there are patches installed.
  320.         V4: The OpenCount will not be increased, if the PatchSupervisor
  321.         support program is active.
  322.         Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase
  323.         MUST be specified.
  324.     PATT_LibVersion (ULONG) - Versionnumber for exec.library/OpenLibrary.
  325.         Optional in conjunction with PATT_LibraryName.
  326.         Should be specified, if a function is available only
  327.         from a certain library version on.
  328.         Default is NULL (any version).
  329.     PATT_DevFlags (ULONG) - Flags for exec.library/OpenDevice().
  330.         Optional in conjunction with PATT_DeviceName. Default is NULL.
  331.     PATT_DevUnit (ULONG) - Unit for exec.library/OpenDevice().
  332.         Optional in conjunction with PATT_DeviceName. Default is NULL.
  333.     PATT_PatchName (STRPTR) - An optional pointer to a string, which can
  334.         be used to search for a patch with FindPatch() or FindPatchTags().
  335.         The null-terminated string will be copied, so you may free
  336.         its memory when InstallPatchTags() returns. The string should
  337.         identify the program that installed the patch.
  338.         Even though this tag is optional, the use of it is strongly
  339.         encouraged, because without it certain future enhancements
  340.         of the patch.library may not work (e.g.: saving of user-settings).
  341.     PATT_Priority (BYTE) - Priority of the patch
  342.         valid range: -127...+126
  343.         It indicates the sequence of patches, if more than one patch
  344.         for a function is to be installed.
  345.         The original code has a priority of 0.
  346.         Priority:    Meaning:
  347.         >0: patch will be executed before the original
  348.         <0: patch will be executed after the original
  349.         =0: patch will be executed instead of the original (default)
  350.         Normally only the priorities +5, 0, -5 should be used.
  351.     PATT_NewCodeSize (ULONG) - Optional length of the patch code to be
  352.         installed.
  353.         If this field is set to the correct value the PC-RELATIVE
  354.         patch code starting at funcEntry will be copied into an
  355.         internal buffer. So it is possible to deallocate the
  356.         patch code after InstallPatchTags() returned.
  357.     PATT_Result2 (APTR) - An optional pointer to a longword, which will
  358.         contain an errorcode as defined patch.h, when
  359.         the function returns.
  360.         Assembler programmers can get the same value from d1.
  361.     PATT_ProjectID (APTR) (V4) - Optional pointer to a PatchProject as
  362.         created by a CreatePatchProject() function call, indicating
  363.         that the newly installed patch belongs to one project or program.
  364.         If used together with the RemovePatchProject function
  365.         many patches can be removed with one function call.
  366.  
  367.  
  368.     For more tags see the description of SetPatch().
  369.  
  370.    RESULT
  371.     patch = pointer to a patch structure or NULL on failure
  372.  
  373.     Errorcodes returned with PATT_Result2, NPAT_Result2 or in register d1:
  374.     Note that from V3 on errorcodes may be returned, even if patch is a
  375.     valid pointer, indicating a failure in the internal SetPatch() call.
  376.     Previous versions always set PATERR_Ok, if patch was a valid pointer.
  377.         PATERR_Ok
  378.             Indicates success of the operation.
  379.         PATERR_OutOfMem
  380.             Indicates that there was not enough memory to
  381.             complete the operation.
  382.         PATERR_OpenLib
  383.             The operation failed, because the exec.library
  384.             function OpenLibrary() failed. Check the Autodocs
  385.             for more informations about OpenLibrary().
  386.         PATERR_OpenDev
  387.             The operation failed, because the exec.library
  388.             function OpenDevice() failed. Check the Autodocs
  389.             for more informations about OpenDevice().
  390.         PATERR_FuncNotStd
  391.             The library offset vector of the function to patch
  392.             was not in format that patch-library can accept.
  393.             Patch.library can handle the following formats:
  394.             jmp xxxxxx
  395.             moveq.l #xx,Dx    bra.l xxxx
  396.             moveq.l #xx,Dx    bra.s xx
  397.             Note that this is the type of error returned,
  398.             if you are trying to patch a function that uses
  399.             in-line code such as the exec.library/GetCC() function.
  400.         PATERR_InvalidTags
  401.             An error occurred while parsing the specified Tags
  402.             (e.g.: EITHER PATT_LibraryName, PATT_DeviceName or
  403.             PATT_LibraryBase MUST be used with InstallPatchTags() )
  404.     For more errorcodes see the description of SetPatch().
  405.  
  406.    NOTES
  407.     This function may implicitly call dos.library functions, so do not
  408.     call it from tasks.
  409.  
  410.    BUGS
  411.     Currently (V4) you may not pass pathnames with PATT_LibraryName or
  412.     PATT_DeviceName (e.g.: "Work:libs/foo.library"). This will be fixed
  413.     in the next release.
  414.  
  415.    SEE ALSO
  416.     RemovePatchTags(), RemovePatchProject(), SetPatch(), Patch.h,
  417.     PatchTags.h, exec.library/OpenLibrary(), exec.library/OpenDevice()
  418.  patch.library/PatchFreeVec                         patch.library/PatchFreeVec
  419.  
  420.    NAME
  421.     PatchFreeVec -- free memory allocated by GetPatch() (V3)
  422.  
  423.    SYNOPSIS
  424.     PatchFreeVec(memoryBlock)
  425.              A1
  426.  
  427.     void PatchFreeVec(void *);
  428.  
  429.    FUNCTION
  430.     Free a memory allocation made by the GetPatch() call. The memory will
  431.     be returned to the system pool from which it came.
  432.  
  433.    NOTE
  434.  
  435.    INPUTS
  436.     memoryBlock - pointer to the memory block to free, or NULL.
  437.  
  438.    SEE ALSO
  439.     GetPatch(), exec.library/FreeVec
  440.  patch.library/RemovePatch                           patch.library/RemovePatch
  441.  
  442.    NAME
  443.     RemovePatch -- Removes a patch installed by InstallPatch().
  444.  
  445.    SYNOPSIS
  446.     Error = RemovePatch( patch )
  447.     D0                 A0
  448.  
  449.     ULONG Error RemovePatch( struct Patch * );
  450.  
  451.    FUNCTION
  452.     This function is obsolete from V2 on, use RemovePatchTags() instead.
  453.     It effectively calls the new function
  454.     RemovePatchTags(patch, PATT_DelayedExpunge, FALSE, TAG_DONE)
  455.  
  456.    INPUTS
  457.     patch = pointer to the patch structure or NULL for no action
  458.  
  459.    RESULT
  460.     Error = Errorcodes as defined in Patch.h.
  461.         (for more information see RemovePatchTags() )
  462.  
  463.    NOTES
  464.  
  465.    BUGS
  466.  
  467.    SEE ALSO
  468.     RemovePatchTags(), Patch.h
  469.  patch.library/RemovePatchProjectA           patch.library/RemovePatchProjectA
  470.  
  471.    NAME
  472.     RemovePatchProjectA -- Remove all patches from the same project. (V4)
  473.     RemovePatchProject -- varargs stub for RemovePatchProjectA(). (V4)
  474.  
  475.    SYNOPSIS
  476.     Error = RemovePatchProjectA( project, taglist )
  477.     D0                         A0       A1
  478.  
  479.     ULONG Error RemovePatchProjectA( ULONG, struct TagItem *);
  480.  
  481.     Error = RemovePatchProject( project, firsttag, ...)
  482.  
  483.     ULONG Error RemovePatchProject( ULONG, Tag, ...);
  484.  
  485.    FUNCTION
  486.     Remove all patches from the given project.
  487.  
  488.     This function simplifies the way, patches can be removed:
  489.     - All patches belonging to one project will be disabled
  490.     - The function then waits (depending on PATT_Timeout) until
  491.       the usagecounter of all patches becomes zero
  492.     - Now all patches will be removed via RemovePatchTags()
  493.     - If all patches are removed resources connected to the
  494.       project will be deallocted
  495.  
  496.     You may call this function to cleanup a project, even if no
  497.     patch was successfully installed for this project.
  498.  
  499.    INPUTS
  500.     project = pointer to a patch project obtained via CreatePatchProject()
  501.     taglist = pointer to array of tags
  502.  
  503.    TAGS
  504.     same as RemovePatchTags()
  505.  
  506.    RESULT
  507.     Error = Errorcodes as defined in Patch.h.
  508.         same as RemovePatchTags()
  509.  
  510.    NOTES
  511.     Removing a patch routine can never be made absolutely safe.
  512.     Although patch.library does anything possible to provide methods
  513.     to minimize the chance of a crash, there will always be a
  514.     slight chance.
  515.     So minimize the number of install and remove operations.
  516.  
  517.    BUGS
  518.  
  519.    SEE ALSO
  520.     CreatePatchProject(), InstallPatchTags(), RemovePatchTags(),
  521.     Patch.h, PatchTags.h
  522.  patch.library/RemovePatchTagsA                 patch.library/RemovePatchTagsA
  523.  
  524.    NAME
  525.     RemovePatchTagsA -- Removes an installed patch. (V2)
  526.     RemovePatchTags -- varargs stub for RemovePatchTagsA(). (V2)
  527.  
  528.    SYNOPSIS
  529.     Error = RemovePatchTagsA( patch, taglist )
  530.     D0                      A0     A1
  531.  
  532.     ULONG Error RemovePatchTagsA( struct Patch *, struct TagItem *);
  533.  
  534.     Error = RemovePatchTags( patch, firsttag, ...)
  535.  
  536.     ULONG Error RemovePatchTags( struct Patch *, Tag, ...);
  537.  
  538.    FUNCTION
  539.     Removes a patch from a library function.
  540.  
  541.     All allocated resources for that specific patch will
  542.     be deallocated.
  543.  
  544.    INPUTS
  545.     patch = pointer to a patch structure or NULL for no action
  546.     taglist = pointer to array of tags
  547.  
  548.    TAGS
  549.     PATT_TimeOut (ULONG) - The number of ticks (1/50 seconds) the
  550.         function keeps trying to remove the patch, if another task
  551.         is running in the patchcode.
  552.         If the patch.library does not succeed in the given time the
  553.         function will return PATERR_PatchInUse.
  554.         Defaults to NULL, which means no retry.
  555.     PATT_DelayedExpunge (BOOL) - If this tag is not set to FALSE and a
  556.         non-patch.library patch was installed after the patch.library
  557.         patch for a specific library function the specified patch
  558.         will nevertheless be removed.
  559.         BUT some resources will be kept allocated by patch.library
  560.         (e.g.: the Library Offset Vector will not be restored to its
  561.         old state). Patch.library will try to deallocate these
  562.         resources automatically, if the system is getting low on
  563.         memory or if a call to a patch.library function that
  564.         removes or installs patches is made.
  565.         The default is TRUE !!!
  566.  
  567.    RESULT
  568.     Error = Errorcodes as defined in Patch.h.
  569.         PATERR_Ok
  570.             Indicates success of the operation.
  571.         PATERR_PatchInUse
  572.             Indicates that some other task is using the
  573.             installed function and the patch can't be removed now.
  574.             Your task may wait and try again later.
  575.         PATERR_PatchInstalled
  576.             Indicates that a patchcode has been installed for
  577.             that function after your patch.library patch has
  578.             been installed and your patch is the only
  579.             patch.library patch for that function.
  580.             If patch.library would remove your patch
  581.             tasks would jump into deallocated memory
  582.             Result:  blinking borders.
  583.             Never occurs, if you pass in the tag
  584.             PATT_DelayedExpunge with TRUE.
  585.         PATERR_InvalidHandle
  586.             Indicates that the pointer to the patch passed
  587.             to the function was not or is no longer valid.
  588.             This might happen, if you pass a wrong pointer or
  589.             you got the pointer via FindPatch() and another
  590.             task has removed the patch before this task called
  591.             RemovePatchTags().
  592.             Also keep in mind that ln_Type must be PS_TYPE_USER.
  593.  
  594.    NOTES
  595.     Removing a patch routine can never be made absolutely safe.
  596.     Although patch.library does anything possible to provide methods
  597.     to minimize the chance of a crash, there will always be a
  598.     slight chance.
  599.     So minimize the number of install and remove operations.
  600.  
  601.     This function may implicitly call dos.library functions, so do not
  602.     call it from tasks.
  603.  
  604.    BUGS
  605.  
  606.    SEE ALSO
  607.     InstallPatchTags(), RemovePatchProject(), Patch.h, PatchTags.h
  608.  patch.library/SetPatchA                               patch.library/SetPatchA
  609.  
  610.    NAME
  611.     SetPatchA -- Changes certain attributes of a patch. (V3)
  612.     SetPatch -- varargs stub for SetPatchA(). (V3)
  613.  
  614.    SYNOPSIS
  615.     Error = SetPatchA( patch, taglist )
  616.     D0               A0     A1
  617.  
  618.     ULONG Error SetPatchA( struct Patch *, struct TagItem *);
  619.  
  620.     Error = SetPatch( patch, firsttag, ...)
  621.  
  622.     ULONG Error SetPatch( struct Patch *, Tag, ...);
  623.  
  624.    FUNCTION
  625.     Changes certain attributes of a patch (see TAGS).
  626.  
  627.    INPUTS
  628.     patch = pointer to a patch structure or NULL for no action
  629.     taglist = pointer to array of tags
  630.  
  631.    TAGS
  632.     PATT_CreateTaskList (ULONG) - Create a TaskList of the given type:
  633.         TL_TYPE_INCLUDE: all specified tasks will use the patchroutine,
  634.                  all others will ignore it.
  635.                  So if no Task is specified via PATT_AddTask... tags,
  636.                  the patchroutine will be used for NO tasks!
  637.         TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine,
  638.                  all others will use it.
  639.                  So if no Task is specified via PATT_AddTask... tags,
  640.                  the patchroutine will be used for ALL tasks!
  641.     PATT_DeleteTaskList (BOOL) - Delete any existing TaskList
  642.         This will return the patch to its default behavior, which is to call
  643.         the patchroutine for any task.
  644.         It is not required to remove the TaskList, before you remove a patch,
  645.         (via RemovePatchTags()) because this will automatically be done
  646.         by patch.library.
  647.     PATT_AddTaskID (struct Task *) - Add a task address to the patch TaskList.
  648.         Patch.library takes care that one TaskID appears only once in the
  649.         TaskList.
  650.         Unlike many tags, you may specify this tag more than once in one
  651.         taglist to add multiple tasks to the list.
  652.     PATT_AddTaskName (STRPTR) - Add a task of the given name to address to 
  653.         the patch TaskList. The string will be copied into an
  654.         internal buffer.
  655.         Patch.library takes care that one TaskName appears only once in the
  656.         TaskList.
  657.         Unlike many tags, you may specify this tag more than once in one
  658.         taglist to add multiple tasks to the list.
  659.     PATT_RemTaskID (struct Task *) - Remove a task address from the TaskList
  660.         Unlike many tags, you may specify this tag more than once in one
  661.         taglist to remove multiple tasks from the list.
  662.     PATT_RemTaskName (APTR) - Remove a task of the given name from the
  663.         TaskList.
  664.         Unlike many tags, you may specify this tag more than once in one
  665.         taglist to remove multiple tasks from the list.
  666.     PATT_Disabled (V4) (BOOL) - Enable (False) or disable (True) a patch.
  667.         For disabling a patch a nesting counter is provided.
  668.         In order to restore normal patch execution, the programmer must
  669.         provide exactly one call to 'enable' for every 'disable'.
  670.         If a patch is disabled this does not mean, that no task continues to
  671.         use the patched code. It only makes sure, that no further tasks enter
  672.         the patch code.
  673.         If PATT_Disabled,TRUE is set with InstallPatchTags() the patch will
  674.         not be called until explicitly enabled by a call to SetPatchTags().
  675.     PATT_AddRemoveHook (V4) (struct Hook *) - Add a Hook, which is called by
  676.         patch.library whenever a patch is removed from memory. Neither
  677.         the Hook structure nor the hookfunction are copied into internal
  678.         memory. So freeing these structures must be accomplished by the
  679.         hookfunction itself. It must also preserve all registers.
  680.         The hookobject (Register A2) for this hook is the patch structure.
  681.         For more information about hooks see utility/hooks.h,
  682.         utility.library/CallHook() or the RKMs.
  683.         Unlike many tags, you may specify this tag more than once in one
  684.         taglist to add multiple hooks.
  685.     PATT_RemRemoveHook (V4)    (struct Hook *) - Remove a Hook installed 
  686.         with PATT_AddRemoveHook.
  687.         Unlike many tags, you may specify this tag more than once in one
  688.         taglist to remove multiple hooks.
  689.  
  690.  
  691.    RESULT
  692.     Error = Errorcodes as defined in Patch.h.
  693.         PATERR_Ok
  694.             Indicates success of the operation.
  695.         PATERR_OutOfMem
  696.             Indicates that there was not enough memory to
  697.             complete the operation.
  698.         PATERR_InvalidHandle
  699.             Indicates that the pointer to the patch passed
  700.             to the function was not or is no longer valid.
  701.             This might happen, if you pass a wrong pointer or
  702.             you got the pointer via FindPatch() and another
  703.             task has removed the patch before this task called
  704.             RemovePatchTags().
  705.         PATERR_NoTaskList
  706.             No valid TaskList is attached to the patch.
  707.             The SetPatchA() function with the PATT_CreateTaskList tag
  708.             specified, must be called to allocate a TaskList.
  709.         PATERR_TaskListExists
  710.             PATT_CreateTaskList was specified, but there already
  711.             exists a TaskList.
  712.         PATERR_InvalidTaskList
  713.             PATT_CreateTaskList was specified with a wrong parameter
  714.  
  715.    NOTES
  716.     Using the TaskList feature provided by this function will increase
  717.     the stackusage of the patched function.
  718.  
  719.    BUGS
  720.  
  721.    SEE ALSO
  722.     InstallPatchTags(), Patch.h, PatchTags.h
  723.  patch.library/WaitRemovePatch                   patch.library/WaitRemovePatch
  724.  
  725.    NAME
  726.     WaitRemovePatch -- Waits until it is possible to remove a patch.
  727.  
  728.    SYNOPSIS
  729.     Error = WaitRemovePatch( patch )
  730.     D0                 A0
  731.  
  732.     ULONG Error WaitRemovePatch( struct Patch * );
  733.  
  734.    FUNCTION
  735.     This function is obsolete from V2 on, use RemovePatchTags() instead.
  736.     It effectively calls the new function
  737.     RemovePatchTags(patch,  PATT_TimeOut, 0x7fffffff,
  738.                 PATT_DelayedExpunge, FALSE,
  739.                 TAG_DONE)
  740.  
  741.    INPUTS
  742.     patch = pointer to the patch structure or NULL for no action
  743.  
  744.    RESULT
  745.     Error = Errorcodes as defined in Patch.h.
  746.         (for more information see RemovePatchTags() )
  747.  
  748.    NOTES
  749.  
  750.    BUGS (?)
  751.     This function will never return, if the patched library function
  752.     crashed for some reason.
  753.  
  754.    SEE ALSO
  755.     RemovePatchTags()
  756.