TABLE OF CONTENTS patch.library/FindPatch patch.library/FindPatchTagsA patch.library/GetPatchA patch.library/InstallPatch patch.library/InstallPatchTagsA patch.library/PatchFreeVec patch.library/RemovePatch patch.library/RemovePatchTagsA patch.library/SetPatchA patch.library/WaitRemovePatch patch.library/FindPatch patch.library/FindPatch NAME FindPatch -- find a patch structure with a given name. SYNOPSIS patch = FindPatch( Name ) D0 A0 struct Patch *FindPatch( STRPTR ); FUNCTION This function will search the patch.library lists for a patch structure with the given name. The first patch matching this name will be returned. This function exists only for historic reasons. It will internally be routed back to FindPatchTags(). INPUTS Name = Name of the patch structure to find RESULT patch = a pointer to the patch structure with the same name else zero to indicate that the string was not found. NOTES If your task is not the owner of the patch, the pointer is only valid as long as the system is in forbid(). From V2 on you may also lock the patch.library semaphore before calling this function. In this case a pointer to a patch structure is guranteed to be valid, until you release the semaphore. The semaphore, however, should be kept locked only for short periods of time in order not to block other tasks. BUGS SEE ALSO InstallPatch(), RemovePatch(), Patch.h patch.library/FindPatchTagsA patch.library/FindPatchTagsA NAME FindPatchTagsA -- find a patch structure with certain criteria. (V3) FindPatchTags -- varargs stub for FindPatchTagsA(). (V3) SYNOPSIS patch = FindPatchTagsA( taglist ) D0 A0 struct Patch *FindPatchTagsA( struct TagItem *); patch = FindPatchTags( firsttag, ...) struct Patch *FindPatchTags( Tag, ...); FUNCTION This function will search the patch.library lists for a patch structure, that matches the criteria specified in the taglist. The first matching patch will be returned. INPUTS taglist = pointer to array of tags TAGS PATT_PatchName (STRPTR) - Specifies that patch.library should search for the first occurrance of a patch of the given name. RESULT patch = a pointer to the patch structure or zero to indicate that no matching structure was found. NOTES If your task is not the owner of the patch, the pointer is only valid as long as the system is in forbid(). You may also lock the patch.library semaphore before calling this function. In this case a pointer to a patch structure is guranteed to be valid, until you release the semaphore. The semaphore, however, should be kept locked only for short periods of time in order not to block other tasks. BUGS Currently (V3) there is only one public tag available. SEE ALSO InstallPatchTags(), RemovePatchTags(), PatchTags.h patch.library/GetPatchA patch.library/GetPatchA NAME GetPatchA -- Changes certain attributes of a patch. (V3) GetPatch -- varargs stub for GetPatchA(). (V3) SYNOPSIS Result = GetPatchA( patch, taglist ) D0 A0 A1 ULONG Result GetPatchA( struct Patch *, struct TagItem *); Result = GetPatch( patch, firsttag, ...) ULONG Result GetPatch( struct Patch *, Tag, ...); FUNCTION Returns certain attributes and lists connected to a patch (see TAGS). INPUTS patch = pointer to a patch structure or NULL for no action taglist = pointer to array of tags TAGS PATT_Result2 (APTR) - An optional pointer to a longword, which will contain an errorcode as defined patch.h, when the function returns. Assembler programmers can get the same value from d1. Only one of the following tags may be specified at a time: PATT_PatchName (BOOL) - Return a pointer to a copy of the name of the patch in a null-terminated string. This pointer must be passed to PatchFreeVec(), if the string is no longer needed. Type of Result is STRPTR. PATT_TaskListType (BOOL) - Return the type of the internal TaskList Possible results: TL_TYPE_INCLUDE: all specified tasks will use the patchroutine, all others will ignore it. TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine, all others will use it. NULL: An error occured (this includes the absense of a TaskList). Check the secondary errorcode for more information. Type of Result is ULONG. PATT_TaskList (BOOL) - Return a pointer to a taglist containing all tasknames and taskids attached to patch. The tagitems are either PATT_AddTaskName or PATT_AddTaskID. This pointer must be passed to PatchFreeVec(), if the tasklist is no longer needed. Type of Result is taglist. RESULT Result = Pointer or longword depending on specified tags. A result of zero indicates an error. Errorcodes returned with PATT_Result2 or in register d1: PATERR_Ok Indicates success of the operation. PATERR_OutOfMem Indicates that there was not enough memory to complete the operation. PATERR_InvalidHandle Indicates that the pointer to the patch passed to the function was not or is no longer valid. This might happen, if you pass a wrong pointer or you got the pointer via FindPatch() and another task has removed the patch before this task called RemovePatchTags(). PATERR_NoTaskList No valid TaskList is attached to the patch. The SetPatchA() function with the PATT_CreateTaskList tag specified, must be called to allocate a TaskList. PATERR_PatchUnnamed The patch has no identification string attached to it. NOTES BUGS SEE ALSO InstallPatchTags(), PatchFreeVec(), Patch.h, PatchTags.h patch.library/InstallPatch patch.library/InstallPatch NAME InstallPatch -- Installs a patchroutine for library functions. SYNOPSIS patch = InstallPatch( newPatch ) D0 A0 struct Patch *InstallPatch( struct NewPatch * ); FUNCTION Opens a library and installs a user provided routine to a library function. Before you call InstallPatch(), you must initialize an instance of a NewPatch structure. NewPatch is a structure that contains all of the arguments needed to install a patch. The NewPatch structure may be discarded immediately after it is used to install the patch. This function exists only for historic reasons. It will internally routed back to InstallPatchTags(). Because InstallPatchTags() has advanced features there is definitely no need to call this function at all. INPUTS NewPatch = pointer to an instance of a NewPatch structure containing the following fields NPAT_NewCode: Pointer to the patch code to be installed. If NPAT_PRI is >= 0 then your patch code gets all registers set to the same values as the program that called the function. If NPAT_PRI is < 0 then your patch code gets all registers set to the same values as the library function returned them. It is up to the patch code to keep the registers intact, when it returns with 'rts'. Due to the internal implementation of the patches, library functions patched with patch.library require four bytes more stack. This might cause in very rare cases crashes due to stack overflow. NPAT_NewCodeSize: Optional length of the patch code to be installed. If this field is set to the correct value the PC-RELATIVE patch code starting at NPAT_NewCode will be copied to an internal Buffer. So it is possible to deallocate the patch code after InstallPatch returns. NPAT_LibraryName: Pointer to the name of the library, which contains the function to patch. ( as in exec.library/OpenLibrary() ) NPAT_LibVersion: version of the Library to open should be specified, if a function is available only from a certain library version on. ( as in exec.library/OpenLibrary() ) NPAT_LVO: Library Offset Vector (LVO) of the function to patch NPAT_Priority: Priority of the patch valid range: -127...+126 It indicates the sequence of patches, if more than one patch for a function is installed. The original code has a priority of 0. Priority: Meaning: >0: patch will be executed before the original <0: patch will be executed after the original =0: patch will be executed instead of the original NPAT_Flags: No flags are used and this field will be ignored ( keep zero ) NPAT_PatchName: An optional pointer to a string, which can be used to search for a patch with FindPatch(). The null-terminated string will be copied, so you may free its memory when InstallPatch() returns. The string should identify the program that installed the patch. NPAT_Result2: An optional pointer to a longword, which will contain an errorcode as defined later. Assembler programmers can always find this in d1, too. RESULT patch = pointer to a Patch structure or NULL on failure for informations about the errorcodes see RemovePatchTags() NOTES BUGS SEE ALSO InstallPatchTags() patch.library/InstallPatchTagsA patch.library/InstallPatchTagsA NAME InstallPatchTagsA -- Installs a patchcode for library functions. (V2) InstallPatchTags -- varargs stub for InstallPatchTagsA(). (V2) SYNOPSIS patch = InstallPatchTagsA( funcEntry, funcOffset, tagList ) D0 A0 D0 A1 struct Patch *InstallPatchTagsA( APTR, UWORD, struct TagItem * ); patch = InstallPatchTags( funcEntry, funcOffset, firsttag, ...) struct Patch *InstallPatchTags( APTR, UWORD, Tag, ...); FUNCTION Adds a user provided routine to a library function. NEW for V3: An internal call to SetPatch() will be made. So all tags which are valid with SetPatch() may be specified in the taglist. INPUTS funcEntry = pointer to the entry of the function to add funcOffset = Library Offset Vector (LVO) of the function to patch taglist = pointer to array of tags TAGS PATT_LibraryName (STRPTR) - Specifies that you want to patch a library of the given name ( as in exec.library/OpenLibrary() ). Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be specified. PATT_DeviceName (STRPTR) - Specifies that you want to patch a device of the given name ( as in exec.library/OpenDevice() ). Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be specified. PATT_LibraryBase (struct Library *) Specifies that you want to patch a library, device or resource with the given base. You may get such a pointer by calling one of the following exec functions: OpenLibrary(), OpenDevice(), OpenResource() You may safely close this library, if InstallPatchTags() returns, because patch.library will increase the OpenCount to make sure, that the library won't be removed from the system as long as there are patches installed. Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be specified. PATT_LibVersion (ULONG) - Versionnumber for exec.library/OpenLibrary. Optional in conjunction with PATT_LibraryName. Should be specified, if a function is available only from a certain library version on. Default is NULL (any version). PATT_DevFlags (ULONG) - Flags for exec.library/OpenDevice(). Optional in conjunction with PATT_DeviceName. Default is NULL. PATT_DevUnit (ULONG) - Unit for exec.library/OpenDevice(). Optional in conjunction with PATT_DeviceName. Default is NULL. PATT_PatchName (STRPTR) - An optional pointer to a string, which can be used to search for a patch with FindPatch() or FindPatchTags(). The null-terminated string will be copied, so you may free its memory when InstallPatchTags() returns. The string should identify the program that installed the patch. Even though this tag is optional, the use of it is strongly encouraged, because without it certain future enhancements of the patch.library may not work (e.g.: saving of user-settings). PATT_Priority (BYTE) - Priority of the patch valid range: -127...+126 It indicates the sequence of patches, if more than one patch for a function is to be installed. The original code has a priority of 0. Priority: Meaning: >0: patch will be executed before the original <0: patch will be executed after the original =0: patch will be executed instead of the original (default) Normally only the priorities +5, 0, -5 should be used. PATT_NewCodeSize (ULONG) - Optional length of the patch code to be installed. If this field is set to the correct value the PC-RELATIVE patch code starting at funcEntry will be copied into an internal Buffer. So it is possible to deallocate the patch code after InstallPatchTags() returned. PATT_Result2 (APTR) - An optional pointer to a longword, which will contain an errorcode as defined patch.h, when the function returns. Assembler programmers can get the same value from d1. For more tags see the description of SetPatch(). RESULT patch = pointer to a Patch structure or NULL on failure Errorcodes returned with PATT_Result2, NPAT_Result2 or in register d1: Note that from V3 on errorcodes may be returned, even if patch is a valid pointer, indicating a failure in the internal SetPatch() call. Previous versions always set PATERR_Ok, if patch is a valid pointer. PATERR_Ok Indicates success of the operation. PATERR_OutOfMem Indicates that there was not enough memory to complete the operation. PATERR_OpenLib The operation failed, because the exec.library function OpenLibrary() failed. Check the Autodocs for more informations about OpenLibrary(). PATERR_OpenDev The operation failed, because the exec.library function OpenDevice() failed. Check the Autodocs for more informations about OpenDevice(). PATERR_FuncNotStd The library offset vector of the function to patch was not in format that patch-library can accept. Patch.library can handle the following formats: jmp xxxxxx moveq.l #xx,Dx bra.l xxxx moveq.l #xx,Dx bra.s xx Note that this is the type of error returned, if you are trying to patch a function that uses inline code such as the exec.library/GetCC() function. PATERR_InvalidTags An error occured while parsing the specified Tags (e.g.: EITHER PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be used with InstallPatchTags() ) For more errorcodes see the description of SetPatch(). NOTES BUGS SEE ALSO RemovePatchTags(), SetPatch(), Patch.h, PatchTags.h, exec.library/OpenLibrary(), exec.library/OpenDevice() patch.library/PatchFreeVec patch.library/PatchFreeVec NAME PatchFreeVec -- free memory allocated by GetPatch() (V3) SYNOPSIS PatchFreeVec(memoryBlock) A1 void PatchFreeVec(void *); FUNCTION Free a memory allocation made by the GetPatch() call. The memory will be returned to the system pool from which it came. NOTE INPUTS memoryBlock - pointer to the memory block to free, or NULL. SEE ALSO GetPatch(), exec.library/FreeVec patch.library/RemovePatch patch.library/RemovePatch NAME RemovePatch -- Removes a patch installed by InstallPatch(). SYNOPSIS Error = RemovePatch( patch ) D0 A0 ULONG Error RemovePatch( struct Patch * ); FUNCTION This function is obsolete from V2 on, use RemovePatchTags() instead. It effectively calls the new function RemovePatchTags(patch, PATT_DelayedExpunge, FALSE) INPUTS patch = pointer to the patch structure or NULL for no action RESULT Error = Errorcodes as defined in Patch.h. (for more information see RemovePatchTags() ) NOTES Removing a patch routine can never be made absolutely save. Although patch.library does anything possible to provide methods to minimize the chance of a crash, there will always be a slight chance. So minimize the number of install and remove operations. BUGS SEE ALSO RemovePatchTags(), Patch.h patch.library/RemovePatchTagsA patch.library/RemovePatchTagsA NAME RemovePatchTagsA -- Removes an installed patch. (V2) RemovePatchTags -- varargs stub for RemovePatchTagsA(). (V2) SYNOPSIS Error = RemovePatchTagsA( patch, taglist ) D0 A0 A1 ULONG Error RemovePatchTagsA( struct Patch *, struct TagItem *); Error = RemovePatchTags( patch, firsttag, ...) ULONG Error RemovePatchTags( struct Patch *, Tag, ...); FUNCTION Removes a patch from a library function. All allocated resources for that specific patch will be deallocated. INPUTS patch = pointer to a patch structure or NULL for no action taglist = pointer to array of tags TAGS PATT_TimeOut (ULONG) - The number of ticks (1/50 seconds) the function keeps trying to remove the patch, if another task is running in the patchcode. If the patch.library does not succeed in the given time the function will return PATERR_PatchInUse. Defaults to NULL, which means no retry. PATT_DelayedExpunge (BOOL) - If this tag is not set to FALSE and a non-patch.library patch was installed after the patch.library patch for a specific library function the specified patch will nevertheless be removed. BUT some resources will be kept allocated by patch.library (e.g.: the Library Offset Vector will not be restored to its old state). Patch.library will try to deallocate these resources automatically, if the system is getting low on memory or if a call to a patch.library function that removes or installs patches is made. The default is TRUE !!! RESULT Error = Errorcodes as defined in Patch.h. PATERR_Ok Indicates success of the operation. PATERR_PatchInUse Indicates that some other task is using the installed function and the patch can't be removed now. Your task may wait and try again later. PATERR_PatchInstalled Indicates that a patchcode has been installed for that function after your patch.library patch has been installed and your patch is the only patch.library patch for that function. If patch.library would remove your patch tasks would jump into deallocated memory Result: blinking borders. Never occurs, if you pass in the tag PATT_DelayedExpunge with TRUE. PATERR_InvalidHandle Indicates that the pointer to the patch passed to the function was not or is no longer valid. This might happen, if you pass a wrong pointer or you got the pointer via FindPatch() and another task has removed the patch before this task called RemovePatchTags(). Also keep in mind that ln_Type must be PS_TYPE_USER. NOTES Removing a patch routine can never be made absolutely save. Although patch.library does anything possible to provide methods to minimize the chance of a crash, there will always be a slight chance. So minimize the number of install and remove operations. BUGS SEE ALSO InstallPatchTags(), Patch.h, PatchTags.h patch.library/SetPatchA patch.library/SetPatchA NAME SetPatchA -- Changes certain attributes of a patch. (V3) SetPatch -- varargs stub for SetPatchA(). (V3) SYNOPSIS Error = SetPatchA( patch, taglist ) D0 A0 A1 ULONG Error SetPatchA( struct Patch *, struct TagItem *); Error = SetPatch( patch, firsttag, ...) ULONG Error SetPatch( struct Patch *, Tag, ...); FUNCTION Changes certain attributes of a patch (see TAGS). INPUTS patch = pointer to a patch structure or NULL for no action taglist = pointer to array of tags TAGS PATT_CreateTaskList (ULONG) - Create a TaskList of the given type: TL_TYPE_INCLUDE: all specified tasks will use the patchroutine, all others will ignore it. So if no Task is specified via PATT_AddTask... tags, the patchroutine will be used for NO tasks! TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine, all others will use it. So if no Task is specified via PATT_AddTask... tags, the patchroutine will be used for ALL tasks! PATT_DeleteTaskList (BOOL) - Delete any exisiting TaskList This will return the patch to its default behaviour, which is to call the patchroutine for any task. It is not required to remove the TaskList, before you remove a patch, (via RemovePatchTags()) because this will automatically be done by patch.library. PATT_AddTaskID (struct Task *) - Add a task address to the patch TaskList. Patch.library takes care that one TaskID appears only once in the TaskList. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_AddTaskName (STRPTR) - Add a task of the given name to address to the patch TaskList. The string will be copied into an internal buffer. Patch.library takes care that one TaskName appears only once in the TaskList. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_RemTaskID (struct Task *) - Remove a task address from the patch TaskList Unlike many tags, you may specify this tag more than once in one taglist to remove multiple tasks to the list. PATT_RemTaskName (APTR) - Remove a task of the given name to address from the patch TaskList. Unlike many tags, you may specify this tag more than once in one taglist to remove multiple tasks to the list. RESULT Error = Errorcodes as defined in Patch.h. PATERR_Ok Indicates success of the operation. PATERR_OutOfMem Indicates that there was not enough memory to complete the operation. PATERR_InvalidHandle Indicates that the pointer to the patch passed to the function was not or is no longer valid. This might happen, if you pass a wrong pointer or you got the pointer via FindPatch() and another task has removed the patch before this task called RemovePatchTags(). PATERR_NoTaskList No valid TaskList is attached to the patch. The SetPatchA() function with the PATT_CreateTaskList tag specified, must be called to allocate a TaskList. PATERR_TaskListExists PATT_CreateTaskList was specified, but there already exists a TaskList. PATERR_InvalidTaskList PATT_CreateTaskList was specified with a wrong parameter NOTES Using the TaskList feature provided by this function will increase the stackusage of the patched function. BUGS SEE ALSO InstallPatchTags(), Patch.h, PatchTags.h patch.library/WaitRemovePatch patch.library/WaitRemovePatch NAME WaitRemovePatch -- Waits until it is possible to remove a patch. SYNOPSIS Error = WaitRemovePatch( patch ) D0 A0 ULONG Error WaitRemovePatch( struct Patch * ); FUNCTION This function is obsolete from V2 on, use RemovePatchTags() instead. It effectively calls the new function RemovePatchTags(patch, PATT_TimeOut, 0x7fffffff, PATT_DelayedExpunge, FALSE) INPUTS patch = pointer to the patch structure or NULL for no action RESULT Error = Errorcodes as defined in Patch.h. (for more information see RemovePatchTags() ) NOTES Removing a patch routine can never be made absolutely save. Although patch.library does anything possible to provide methods to minimize the chance of a crash, there will always be a slight chance. So minimize the number of install and remove operations. BUGS (?) This function will never return, if the patched library function crashed for some reason. SEE ALSO RemovePatchTags()