Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 534.lha / vmalloc_v1.2 / libs / track.doc.pp / track.doc

Wrap

Text File | 1991-08-08 | 58.9 KB | 2,424 lines

TABLE OF CONTENTS track.library/AbsChk track.library/AbsChkWord track.library/AddProcess track.library/Atol track.library/CheckPacket track.library/ChkBound track.library/ChkRange track.library/CreateExtIO track.library/CreatePacket track.library/CreatePort track.library/DeleteExtIO track.library/DeletePacket track.library/DeletePort track.library/DoPacket track.library/ExceptCall track.library/ExceptCode track.library/ExceptEnter track.library/ExceptInit track.library/ExceptLeave track.library/ExceptRaise track.library/FPrintf track.library/FreeTrackedItem track.library/FreeTrackList track.library/GetTrap track.library/LongJmp track.library/MakeBStr track.library/MemAlloc track.library/MemFree track.library/NewList track.library/OnSignal track.library/Printf track.library/Reads track.library/RemoveProcess track.library/SendPacket track.library/SetJmp track.library/SetTrap track.library/SPrintf track.library/Strcat track.library/Strchr track.library/TCreateExtIO track.library/TCreatePacket track.library/TCreatePort track.library/TLock track.library/TMemAlloc track.library/TOpen track.library/TOpenDevice track.library/TOpenLibrary track.library/TOpenScreen track.library/TOpenWindow track.library/TrackItem track.library/TrapMsg track.library/TSetDMRequest track.library/TSetMenuStrip track.library/WaitPacket track.library/AbsChk track.library/AbsChk NAME AbsChk -- Compare a 32bit value against an absolute maximum. SYNOPSIS AbsChk( var, max ) D0 D1 long int var ; long int max ; FUNCTION Compares a 32bit value such as a pointer, against a maximum possible value. If the value is less than or equal to the maximum, this function returns. Otherwise an exception EX_CHK is generated. INPUTS var should be an unsigned 32bit quantity. I don't think it will handle signed comparisons properly, if at all. max should again be an unsigned 32bit quantity. RESULTS It either returns or it doesn't. Excellent for applications where if the value is out of range, then the logic is broken. Better to cause an exception than possibly bring the machine down. NOTES This was designed to be used while the trap handling is enabled, to enable you to capture the exception. If the trap handling is not enabled, you will get a 'SOFTWARE FAILURE - Task Help' requester. SEE ALSO libraries/track.h (for EX_CHK), SetTrap(), AbsChkWord() BUGS none known. track.library/AbsChkWord track.library/AbsChkWord NAME AbsChkWord -- Compare a 16bit value against an absolute maximum. SYNOPSIS AbsChkWord( var, max ) D0 D1 short int var ; short int max ; FUNCTION Compares a 16bit value such as a short int, against a maximum possible value. If the value is less than or equal to the maximum, this function returns. Otherwise an exception EX_CHK is generated. INPUTS var should be an unsigned 16bit quantity. I don't think it will handle signed comparisons properly, if at all. max should again be an unsigned 16bit quantity. RESULTS It either returns or it doesn't. Excellent for applications where if the value is out of range, then the logic is broken. Better to cause an exception than possibly bring the machine down. NOTES This is an entrypoint *WITHIN* AbsChk() that shortcuts the high word comparison. Hence, if the inputs are 32bits, only the lower words make any difference. SEE ALSO AbsChk() BUGS none known. track.library/AddProcess track.library/AddProcess NAME AddProcess -- Setup a process node for the current process SYNOPSIS ProcessList = AddProcess() D0 struct ProcessList *ProcessList ; FUNCTION This allocates an area of memory using AllocMem(), sets it up for the current task/process, and links it to an internal list. INPUTS RESULTS A pointer to the process node is returned, or NULL if memory was not available. EG. struct ProcessList *pl = AddProcess() ; . . During this space, the SetTrap(), Exception handling functions . and the Resource Tracking functions are valid. . RemoveProcess() ; NOTES This should never need to be called since it is already called for each process when the library is opened. Note that RemoveProcess() will reset the Trap/Exception handler, free *ALL* tracked items (and is called automatically when you close the library). One use for these is if you CreateProc() a process, and wish the process to use the libraries tracking/excepion handling functions. EG Global TrackBase ; blah = CreateProc(...) ; if (blah) { . . Just sort of do things... . } -- Proc -- AddProcess() ; /* This process how has Resource tracking etc */ . . Things to be done. . RemoveProcess(); /* Free all tracked items, and reset handlers */ Note the lack of parameters. The process node is identified by the unique number returned by FindTask(0). SEE ALSO RemoveProcess(), AllocMem() BUGS The return value IS NOT THE PROCESS LIST POINTER as documented. The function works fine, but the return value is gibberish. (not that it is needed right? It is a private structure anyway.) track.library/Atol track.library/Atol NAME Atol -- Convert an ASCII string to a 32bit long int. (unsigned) SYNOPSIS result = Atol( str ) D0 A0 char *str ; FUNCTION The string 'str' is scanned to skip spaces, then converted to a 32bit unsigned long. Note that leading signs are not accepted nor processed. Conversion stops immediately a non-numeric character is located. INPUTS str A pointer to a terminated string. Spaces at the beginning of the string are automatically skipped. RESULTS result A 32bit unsigned long. Note that a value of zero can be either a numeric zero, or that no numeric characters were found. NOTES Since only one return code is generally accepted when using 'C', it is difficult to gain access to A0 *after* the call to Atol(). If you can, via lattice's getreg() for example, then A0 contains a pointer to the string *AFTER* the number. SEE ALSO getreg(), atol() BUGS A0 is ALWAYS advanced by a minimum of one character. If no numeric input is found, it should not be advanced. (but that isn't a real problem is it..) track.library/CheckPacket track.library/CheckPacket NAME CheckPacket -- Check to see if a DOS packet submitted with SendPacket() has been finished with. SYNOPSIS result = CheckPacket( packet ) D0 A1 struct StandardPacket *packet ; struct StandardPacket *result ; FUNCTION Check the packets' reply port message list to see if this packet is in its reply queue. This only works if the packet has been initialised such that : packet->sp_Msg.mn_ReplyPort = packet->sp_Pkt.dp_Reply This is done automatically by the function CreatePacket() INPUTS packet A pointer to a DOS StandardPacket structure. RESULTS result A pointer to the returned packet. By all coincidence, this is the same as the pointer you gave it. UNLESS the packet was not finished with, in which case NULL is returned. NOTES The packet should be created with 'CreatePacket()'. You may then fill in the dp_Arg's and Action's and Type's, then submit the packet do DOS using the 'SendPacket()' call. IMPORTANT. DOS is *documented* to corrupt dp_Reply in the DOS packet. That does not mean it *WILL* change it, just that it is allowed to. To overcome this, the contents of dp_Reply is duplicated into mn_ReplyPort in the exec message section of the StandardPacket. The CheckPacket() and WaitPacket() rely on the mn_ReplyPort, and SendPacket() sets the dp_Reply to the contents of mn_ReplyPort before submitting the packet to DOS. As long as mn_ReplyPort is not modified, this clearly solves one of the more annoying aspects of dealing with DOS packets. (Not BCPL though!!) CheckPacket() does only that, *CHECK*. You must call WaitPacket() to actually remove the packet from the reply Queue, or if you want to, do the following. if (CheckPacket(packet)) Remove(packet) ; Since WaitPacket() will actually call CheckPacket() again to check if the packet is finished with. To find the packet, it scan's the ReplyPort list for the Message. This can be inefficient if called in a busy/wait loop. Hence it is best to check if a *new* message was received in the reply queue (with, SetSignal()) before calling CheckPacket() again. However, since generally only one packet will ever exists on the reply queue, a : packet = GetMsg(packet->sp_Msg.mn_ReplyPort) ; will generally give the same result more efficiently. IE, returns NULL if the reply is not yet available. However, if *MANY* DOS packets are outstanding on a particular port, CheckPacket() can be used to check for a particular DOS packet. SEE ALSO SendPacket(), WaitPacket(), DoPacket(), CreatePacket(), DeletePacket(), SetSignal() BUGS None known. It is guaranteed that dp_Reply is corrupted by DOS, but it is *NOT* guaranteed that the mn_ReplyPort is not corrupted. I am relying on the Message structure *NOT* being modified by DOS, which may change as commodore see fit. Use at own risk. Apart from that, it works fine under 2.0!! track.library/ChkBound track.library/ChkBound NAME ChkBound -- Compare a 32bit value against low/high bounds. SYNOPSIS ChkBound( var, min, max ) D0 D2 D1 long int var ; long int min ; long int max ; FUNCTION Compares a 32bit value such as a pointer, against a minimum and a maximum possible value. If the value is outside of either bound then an exception EX_CHK is generated. Otherwise it returns normally. INPUTS var should be an unsigned 32bit quantity. I don't think it will handle signed comparisons properly, if at all. min and max should again be a unsigned 32bit quantities. RESULTS It either returns or it doesnt. Excellent for applications where if the value is out of range, then the logic is broken. Better to cause an exception than possibly bring the machine down. NOTES This was designed to be used while the trap handling is enabled, to enable you to capture the exception. If the trap handling is not enabled, you will get a 'SOFTWARE FAILURE - Task Help' requester. SEE ALSO libraries/track.h (for EX_CHK), SetTrap(), AbsChkWord() AbsChk() BUGS none known. track.library/ChkRange track.library/ChkRange NAME ChkRange -- Compare a 32bit value against start and size bounds. SYNOPSIS ChkRange( var, min, size ) D0 D2 D1 long int var ; long int min ; long int size ; FUNCTION Compares a 32bit value such as a pointer, against a minimum value and a range value. If the value is out of range then an exception EX_CHK is generated. Otherwise it returns normally. INPUTS var should be an unsigned 32bit quantity. I don't think it will handle signed comparisons properly, if at all. min and size should again be a unsigned 32bit quantities. RESULTS It either returns or it doesnt. Excellent for applications where if the value is out of range, then the logic is broken. Better to cause an exception than possibly bring the machine down. NOTES This is most useful for string manipulation. For example, if you do the following : char buf[LENGTH] ; ptr = strchr(buf,':') ; /* * Check that ptr is within reason. This could only * fail if * a) ':' not found * b) The search went passed the 80 character boundary. * * You say LENGTH-1, since ptr can only be from * buf+0 to buf+79. */ ChkRange(ptr,buf,LENGTH-1) ; This was designed to be used while the trap handling is enabled, to enable you to capture the exception. If the trap handling is not enabled, you will get a 'SOFTWARE FAILURE - Task Help' requester. SEE ALSO libraries/track.h (for EX_CHK), SetTrap(), AbsChkWord() AbsChk(), ChkBound() BUGS none known. track.library/CreateExtIO track.library/CreateExtIO NAME CreateExtIO -- Create an Extended IO Request. SYNOPSIS IORequest = CreateExtIO( reply, size ) D0 A0 D0 struct IORequest *IORequest ; struct MsgPort *reply ; size = size of Request structure. FUNCTION This allocates memory for an IORequest structure, filling in the exec Message information, and linking in the replyport specified. INPUTS reply A pointer to the replyport for the IORequest. size The size of the IORequest. Since difference devices use different size custom request structures, it is important that you specify the correct size. RESULTS Returns a pointer to the allocated memory for the IORequest. If the allocation failed, then a NULL is returned. The memory for the IORequest is cleared when allocated. NOTES It is currently illegal to ask for an IORequest structure, with a NULL reply port. The IORequests message type is set to NT_MESSAGE. SEE ALSO DeleteExtIO(), CreatePort() BUGS none known. track.library/CreatePacket track.library/CreatePacket NAME CreatePacket -- Create and initialise a StandardPacket structure. SYNOPSIS packet = CreatePacket( reply ) D0 A0 struct StandardPacket *packet; struct MsgPort *reply; FUNCTION This function allocates and clears a DOS StandardPacket structure, filling in the strange DOS links, and storing the reply port address in the Message structure's ReplyPort pointer. If the reply argument is NULL, a new MsgPort is created via CreatePort(). INPUTS reply A pointer to a standard MsgPort structure as returned by CreatePort() RESULTS A Pointer to a partially initialised DOS StandardPacket structure. NOTES See CheckPacket() for important information about the *Packet() command set. SEE ALSO CheckPacket(), WaitPacket(), DoPacket(), DeletePacket(), CreatePort() BUGS none known. track.library/CreatePort track.library/CreatePort NAME CreatePort -- Create an Exec MsgPort structure. SYNOPSIS msgport = CreatePort( name, pri ) D0 A0 D0 struct MsgPort *msgport; char *name; int pri; FUNCTION Allocates memory for a MsgPort structure, allocates a Signal, initialises the name, priority, size, sigbit, and other important information for the MsgPort to be immediately ready for use. INPUTS name A pointer to a string for the name. If no name (Ie NULL) is supplied, the port is assumed to be private, and is not added to the system MsgPort list. pri The MsgPort priority. This is generally zero. RESULTS Returns a pointer to a MsgPort structure, unless there was insufficient memory, or not enough signals, in which case NULL is returned. NOTES This is *VERY* similar to the CreatePort() function in amiga.lib SEE ALSO DeletePort() BUGS none known. track.library/DeleteExtIO track.library/DeleteExtIO NAME DeleteExtIO -- Delete an Extended IO Request structure. SYNOPSIS DeleteExtIO( request ) A1 struct IORequest *request ; FUNCTION Free's the memory associated with the IORequest structure. INPUTS request A pointer to an IORequest created with CreateExtIO() RESULTS NOTES Before freeing the memory, the IORequest is corrupted. Hence if you accidentally reuse the deleted IORequest, you will most likely crash the machine. Be Warned. (This is done on purpose) Note also that the replyport specified when you create the port is *NOT* free'd. You must DeletePort() it if you no longer need it. SEE ALSO CreateExtIO(), DeletePort() BUGS none known. track.library/DeletePacket track.library/DeletePacket NAME DeletePacket -- Delete a DOS StandardPacket structure. SYNOPSIS DeletePacket( packet, reply ) A0 D0 struct StandardPacket *packet ; Boolean reply; FUNCTION This function free's memory associated with a StandardPacket. It is *NOT* a good idea to free it while it is in use, but you know that don't you. INPUTS packet A pointer to the StandardPacket to free. reply A flag to indicating the status of the reply port. TRUE indicates that the port was specified in the CreatePacket() call. It is up to you to free it. FALSE indicates that the port was created automatically by CreatePacket(), and should be free'd by DeletePacket() RESULTS NOTES The reply port is an issue because you can either create one and share it, or create one for each DOS packet. If you let CreatePacket() create the reply port, you should indicate FALSE, and let DeletePacket() delete it. On the otherhand, if you created one for all packets, you must specifiy TRUE, and not let DeletePacket() free it. The reason it is this way, is so that if you specify a port for the CreatePacket(), then specify it for the DeletePacket() (hence TRUE), and the same works for CreatePacket(NULL) and DeletePacket(packet,NULL) (hence FALSE) You may perform trickery, such as creating a port, and many packets, then using DeletePacket(packet,TRUE) on the LAST DeletePacket() to remove the port automatically. *** Watchout if you track the CreatePort(), you must FreeTrackItem() it, rather than let DeletePacket() free it *** SEE ALSO CreatePacket(), CreatePort(), DeletePort() BUGS none known. track.library/DeletePort track.library/DeletePort NAME DeletePort -- free up an exec MsgPort structure. SYNOPSIS DeletePort( port ) A0 struct MsgPort *port ; FUNCTION This free's the signals and memory associated with a MsgPort structure. INPUTS port A pointer the a MsgPort created via CreatePort(). RESULTS NOTES If the port has a name, DeletePort() *WILL* attempt to remove it from the system ports list. HENCE, if you CreatePort() it without a name, and add a name later, then you *MUST* remove the name before calling DeletePort(). SEE ALSO CreatePort() BUGS none known. track.library/DoPacket track.library/DoPacket NAME DoPacket -- Sends a packet to a device port synchronously. SYNOPSIS result = DoPacket( Packet, Dest ) D0 A1 A0 long result; struct StandardPacket *Packet; struct MsgPort *Dest; FUNCTION Sends a DOS packet to the port specified, and waits until it has completed. (Hence 'synchronously') INPUTS Packet A pointer to a DOS StandardPacket structure. Dest A pointer to a device's message port as returned via Open() or DeviceProc(). RESULTS result The dp_Result field is extracted and returned as the result code. Hence if only a dp_Result is expected, you do not need to get it yourself. NOTES This is a synchronous method of DOS communication. In general you would do something like : struct StandardPacket *packet = CreatePacket(NULL); packet->sp_Pkt.dp_Action = ACTION_READ ; packet->sp_Pkt.dp_Arg1 = fh->fh_Arg1 ; packet->sp_Pkt.dp_Arg2 = buffer ; packet->sp_Pkt.dp_Arg3 = 1024 ; /* length */ length = DoPacket(packet,fh->fh_Type) ; Which would read from file handle 'fh', into buffer 'buffer' for 1024 bytes. The Actual length read would be returned in the variable length. DoPacket() is implemented along the following lines : SendPacket(packet,dest) ; WaitPacket(packet) ; return packet->sp_Pkt.dp_Res1 ; SEE ALSO CheckPacket(), WaitPacket(), CreatePacket(), DeletePacket() BUGS none known. track.library/ExceptCall track.library/ExceptCall NAME ExceptCall -- Break to a local exception handler. SYNOPSIS ExceptCall( code ) D0 int code ; FUNCTION This function switches from protected mode, to exception mode (do not confuse any of this with user/supervisor mode.) and resets control to the 'local' exception handler. NOTE: The alias for this function is CALLEXCEPTION(), and should be used instead of ExceptCall() for implementation reasons. INPUTS code An integer code, which can be retrieved from within the exception handler via the function 'ExceptCode()' RESULTS This function does not return, unless there are no active exception handlers. NOTES Given a program fragment : PROTECTED printf ("diff = %d\n",x/deltax) ; /* delta x = 0! */ printf ("This should not happen\n") ; EXCEPTION printf ("EXCEPTION : %d\n",LASTEXCEPTION()) ; NORMAL When the division by zero occurs, within x/deltax, then the default 'trap' handler, will call ExceptCall() with the trap number. This will cause execution to continue at the printf() after the statement 'EXCEPTION' You may of course call ExceptCall() yourself, but it is recommended that you use the higher level ExceptRaise() call. This is because calling ExceptCall() from within the exception handler will restart the hander, however ExceptRaise() will terminate the current exception handler and use ExceptCall() to fall to the next exception handler in the stack. This is the current default 'trap' handler. --------------------------------------------------------------- /* * Exception handler.. This gets the cause of the exception and * returns to the main program at the last exception entry point. */ #include <proto/track.h> #include <libraries/track.h> void _DefaultEHandler(void) { struct TrapInfo *codes = GetTrap() ; ExceptCall(codes->ti_TrapNO) ; } --------------------------------------------------------------- SEE ALSO ExceptCode() (LASTEXCEPTION()), ExceptRaise() (RAISEEXCEPTION()) BUGS The macro CALLEXCEPTION() is disabled by default, since you should have no reason to use it. track.library/ExceptCode track.library/ExceptCode NAME ExceptCode -- return the code used to raise the last exception. SYNOPSIS code = ExceptCode() int code ; FUNCTION Within an exception handler, ExceptCode() can be called to get the code passed via ExceptCall() or ExceptRaise(). NOTE: The alias for this function is LASTEXCEPTION(), and should be used instead of ExceptCode() for implementation reasons. INPUTS RESULTS code A long int, passed via ExceptRaise(). NOTES A code can either be a processor trap code, eg Division by zero, or a user code, such as a failed test. It is a good idea to keep all user codes greater than the processor trap codes, so that you don't confuse them. For this reason, all codes should be larger than EX_MC68000. SEE ALSO ExceptRaise() (RAISEEXCEPTION()) BUGS none known. track.library/ExceptEnter track.library/ExceptEnter NAME ExceptEnter -- Exception gateway. SYNOPSIS boolean = ExceptEnter( name ) D0 A0 char *name ; FUNCTION This function immediately returns FALSE. If an exception occurs, control is passed back to this function, and it return TRUE. NOTE: The alias for this function is PROTECTED or PROTECT(name), and should be used instead of ExceptEnter() for implementation reasons. INPUTS name A pointer to a name string. This is used if a nested function wants to break out to this exception handler. RESULTS boolean The first time this function is called, it return FALSE. It then returns TRUE if an exception is raised. NOTES This function may be a tad difficult to understand. Given the following code fragment. -------------------------------------------- if (ExceptEnter(NULL)) { ExceptLeave() ; exit(42) ; } <code fragment> ExceptLeave() ; -------------------------------------------- The first time ExceptEnter() is called, it returns FALSE, and execution continues to the <code fragment>. If during the code fragment, an exception occurs, (Say a BUS ERROR), then control is bounced back to the ExceptEnter() function, which will return TRUE, causing the 'ExceptLeave() ; exit(42)' to be executed. Because of the difficulty visualising the flow of control, (after all it does magically bounce around...) I have put some macros together to simplify the construction. The above code could be re-written as : -------------------------------------------- int code ; PROTECED <code fragment> code = 0 ; EXCEPTION code = 42 NORMAL return code ; -------------------------------------------- Here, the 'protected' code, and the 'exception' code are clearly separated, and the flow of control is easier to follow, if you can see where in the <code fragment> the exception was generated. Since exception information is stored 'stack' like, functions may each have a different exception handler, or even nested exception zones, within a function. SEE ALSO ExceptRaise(), ExceptLeave(). BUGS track.library/ExceptInit track.library/ExceptInit NAME ExceptInit -- Initialise the exception handler system. SYNOPSIS ExceptInit( func ) A0 void (*func)() FUNCTION This function starts the exception handler system, and sets the function to call if a processor exception is generated. NOTE: The alias for this function is EINIT(handler) or EHANDLERINIT(), and should be used instead of ExceptInit() for implementation reasons. INPUTS func A pointer to a processor exception handler. An example is given in the description of the ExceptCall() function. RESULTS NOTES The 'func' is only needed if you intend to trap processor exceptions. You can leave it NULL, and pass control around with the RaiseException() call. This MUST be called before the first ExceptEnter() call, or you may crash the system. SEE ALSO ExceptCall(), RaiseException() BUGS If you call this function a second time, deep within a nest of exception handlers, it will immediately flush all the current handlers, without passing control to any of them. However, it will not free the memory associated with them. It is not a good idea to call this function a second time. track.library/ExceptLeave track.library/ExceptLeave NAME ExceptLeave -- remove an exception handler from the top of the stack. SYNOPSIS ExceptLeave() FUNCTION This function undoes what ExceptEnter() does, removing the current execption handler from the top of the stack. NOTE: The alias for this function is NORMAL and should be used instead of ExceptLeave() for implementation reasons. INPUTS RESULTS NOTES Since any function can have an exception handler, and it may call a function that sets up its own handler, it is possible that an exception caused after the ExceptLeave() will be passed to the exception handler of the calling function. This feature is used by the ExceptRaise() function. If you are in an exception zone, ExceptRaise() will call ExceptLeave() once, and then jump to the next available exception handler. SEE ALSO ExceptRaise() BUGS If you return from a function without calling ExceptLeave(), there is no warning. However an exception will attempt to access an invalid stack frame, and very likely explode violently. track.library/ExceptRaise track.library/ExceptRaise NAME ExceptRaise -- Break to a local or external exception handler. SYNOPSIS ExceptRaise( code, name ) D0 A2 int code ; char *name ; FUNCTION This function breaks to the next available exception handler, leaving the current function if necessary. NOTE: The alias for this function is RAISEEXCEPTION() and should be used instead of ExceptRaise() for implementation reasons. INPUTS code An integer code, which will be passed to the exception code. name A name string. If this is specified, then ExceptRaise() will Attempt to break out as far as the last ExceptEnter() with the same name. RESULTS If all went well, this function should not return. NOTES If you are in a protected zone, then this function is identical to ExceptCall() (unless you specified a name). If you are in an exception zone, or specified a name, then ExceptLeave() will be called either once, or until the zone with the correct name is found. Then control will be passed to that new exception handler. SEE ALSO ExceptCall() BUGS If you specify a name, and that name is NOT found, this will jump to the next available handler, without generating an error. track.library/FPrintf track.library/FPrintf NAME FPrintf -- Formatted Printf to a File Handle. SYNOPSIS FPrintf( Handle, Fmt, Args ) A2 A0 A1 BPTR Handle; char *Fmt; long Args; FUNCTION Standard 'C' fprintf function to an AmigaDos file handle, as supplied by Open(), or TOpen(). INPUTS Handle A BCPL pointer to a file handle. Fmt A format string. Read the definition of printf() for the codes. Args Argument pointer for the format string. RESULTS NOTES This calls the Exec RawDoFmt() function with the format and args, and writes the result to the file handle specified. This function required a stub to work with 'C'. SEE ALSO printf(), Printf() BUGS If you compiler automatically promotes integers to 32bit longs, then all %d's and %u's must be written as %ld and %lu. track.library/FreeTrackedItem track.library/FreeTrackedItem NAME FreeTrackedItem -- Free a tracked resource item. SYNOPSIS FreeTrackedItem( Item ) A0 long Item ; FUNCTION This function frees the item pointed to by Item. INPUTS Item A pointer to value identifying the resource. RESULTS NOTES The Item is free'd by calling the 'Free' function in the items 'tn_drop' pointer. The item node is then unlinked and deallocated. Note that the register A4 is stored as part of the tracking environment, and is restored before calling the 'C' function. This is to aid 'C' programmer, who wish to use functions which are pre-compiled, such as the amiga.lib 'Close()' function. SEE ALSO TrackItem() BUGS none known. track.library/FreeTrackList track.library/FreeTrackList NAME FreeTrackList -- Free all tracked items. SYNOPSIS FreeTrackList() FUNCTION This free's all items currently tracked by this process. INPUTS RESULTS NOTES This function is called automatically when the library is closed. SEE ALSO FreeTrackedItem(),TrackItem() BUGS none known. track.library/GetTrap track.library/GetTrap NAME GetTrap -- Get information about last processor trap. SYNOPSIS info = GetTrap() struct TrapInfo *info FUNCTION This functions returns a pointer to a structure containing the PC of the last TRAP, the TRAP number, and a pointer to a NULL terminated string describing the TRAP. INPUTS RESULTS info A pointer to an instance of the TrapInfo structure. This is a pointer to an internal data structure, and its contents should not be altered. NOTES When a trap occurs, the lowlevel trap handler stores the trap number and trap address in a TrapInfo structure local to the current task or process. When GetTrap() is called, the trap number of used to calculate a pointer to a message, which is stored in the structure, before returning the address of the structure in memory. The possible messages include : Trap 1 Bus Error Address Error Illegal Instruction Divide by Zero CHK instruction TRAPV instruction Priviledge violation Trace Line 1010 emulation Line 1111 emulation An example of the use of GetTrap() : gurutrap( void ) { struct TrapInfo *codes = GetTrap() ; Printf ("SOFTWARE FAILURE : %s\n",codes->ti_TrapMsg) ; exit(1) ; } To use this, you would also use the command 'SetTrap(gurutrap).' SEE ALSO libraries/track.h for (struct TrapInfo), SetTrap() BUGS none known. track.library/LongJmp track.library/LongJmp NAME LongJump -- return to a previously saved context. SYNOPSIS LongJmp( save ) A0 jmpbuf save FUNCTION LongJmp() returns to the context contained within the variable 'save'. INPUTS save A context buffer. defined in the ansi include file setjmp.h RESULTS This function should not return. (It should return to where the context was saved) NOTES This is a duplication of the ANSI setjmp()/longjmp() commands, used in the exception handling code. (Now you know how it all magically jumps around!) SEE ALSO setjmp(), SetJmp(), longjmp() setjmp.h BUGS This only works if it is called directly via inline assembly, or #pragma's. The use of a C language stub will invalidate the function, and probably crash the machine. track.library/MakeBStr track.library/MakeBStr NAME MakeBStr -- Convert a string to a BSTR. SYNOPSIS bstr = MakeBStr( string ) D0 A0 BSTR bstr; char *string; FUNCTION This function creates a BSTR from the character string, and returns a BPTR to the BSTR. (Don't you hate BCPL..) INPUTS string A normal everyday NULL terminated string. RESULTS bstr A BPTR to a BSTR, or NULL if memory was unavailable. NOTES A BSTR is a string, where the first byte is the length, and the string does not need a terminator byte. (Since you know its length.) A BPTR is a pointer divided by 4. Hence the string begins in memory at (BPTR << 2) + 1. ALL DOS routines use BPTR's and some use BSTR's as well. IMPORTANT : The memory allocated for the BSTR is tracked, and should be free'd by passing the REAL ADDRESS to FreeTrackItem() not the BPTR. Eg, dev = MakeBStr("DF0") ; . . . FreeTrackedItem( dev << 2 ) ; Since it is tracked, it will be free'd when the program closes the track.library. SEE ALSO Dos functions, FreeTrackedItem(). BUGS A BSTR may be up to 255 bytes, but a normal C string can be infinitely long. This routine DOES NOT MAKE SURE that the initial string is short enough to be a BSTR. track.library/MemAlloc track.library/MemAlloc NAME MemAlloc -- Allocate memory. SYNOPSIS buffer = MemAlloc( Size, Type ) D0 D0 D1 void *buffer ; ULONG Size ; ULONG Type ; FUNCTION This function allocated Size bytes of type Type, returning the address of the allocated block. INPUTS Size The size of the block to allocate in bytes. Type The type of memory to allocate, ie CHIP, FAST or PUBLIC. RESULTS buffer A pointer to the allocated memory. NOTES This function allocates four extra bytes, using 'AllocMem()' and stores the length of the block in the first longword. The pointer returned is a pointer to the second longword. When MemFree(buffer) is called, it subtracts 4 bytes from buffer, and uses the contents of the first longword as the 'size' argument for 'FreeMem(buffer,size)' SEE ALSO MemFree(), AllocMem(), FreeMem() BUGS none known. track.library/MemFree track.library/MemFree NAME MemFree -- Free a memory block allocated with MemAlloc() SYNOPSIS MemFree( Block ) A1 void *Block; FUNCTION This function free's the memory block pointed to by Block. INPUTS Block A pointer to the memory allocated with MemAlloc() RESULTS NOTES MemFree() looks for the size of the allocated block at Block-4, and uses this size when calling FreeMem(Block-4,size); See MemAlloc() for more information. SEE ALSO MemAlloc(), AllocMem(), FreeMem() BUGS none known. track.library/NewList track.library/NewList NAME NewList -- Initialise an Exec list header. SYNOPSIS NewList( List ) A0 struct List *List ; FUNCTION This function initialises an exec list header for use. INPUTS List A pointer to a list header. RESULTS NOTES An EXEC list header must be initialised before use. The usual method is : List->lh_Head = & ( List->lh_Tail ) ; List->lh_Tail = NULL ; List->lh_TailPred = & ( List->lh_Head ) ; The NewList() function call will do this for you. SEE ALSO exec/lists.h (RKM/exec for List management) BUGS none known. track.library/OnSignal track.library/OnSignal NAME OnSignal -- Initialise signal handling, and set function pointer. SYNOPSIS OnSignal( sigmask ,func ) D0 A0 ULONG sigmask ; void (*func)(void) ; FUNCTION This function initialises the signal handling mechanism if it is the first call, and sets up to call 'func()' when a signal in 'sigmask' is generated. INPUTS sigmask A 32bit mask of which signals will cause function func() to be called. func A pointer to the function to be called when a signal is generated. RESULTS NOTES An array of 32 function pointers is allocated, with one entry per possible signal. Each call of OnSignal() will set the appropriate bits in the exception mask using 'SetExcept()', and place the function address in each array position indicated by the signal mask. When the signal occurs, program context switches to a software exception state, and execution continues with the signal handler. When the signal handler returns, execution is continued where it left off. A signal handler can be easily disabled by specifying the correct mask, and a NULL function. Example : setup to call 'windowhandler()' on intuition messages, and to call 'aborthandler()' in the event of a control C or control D. OnSignal ( 1 << window->UserPort . mp_SigBit, windowhandler ) ; OnSignal ( SIGBREAKF_CTRL_C | SIGBREAKF_CTRL_D, aborthandler ) ; Now turn off the control D signal handler. OnSignal ( SIGBREAKF_CTRL_D, NULL ) ; NOTE that this leave control C handling active. Ie it is not affected. SEE ALSO SetExcept() BUGS This is not a real bug, more of a restriction. I wrote a program that used 'Printf()' in a loop, and OnSignal(SIGBREAKF_CTRL_C,exit). If the control-C arrived, and the program exit()'ed while a DOS message (regarding the write to console) was active, the machine promply guru'ed. MOTTO : Dont let a signal interupt a DOS function, unless you are guaranteed to return to where you left off. track.library/Printf track.library/Printf NAME Printf -- Print formatted string to console. SYNOPSIS Printf( String, Args ) A0 A1 char *String ; Arguments Args ; FUNCTION This is a printf() compatible Printf() function, whose output goes to the file handle returned by the Output() function. INPUTS String A pointer to a printf() like format string. Note that floats are not supported. Args Standard C arguments. example 'Printf("%d = %x",42,blah) ;' RESULTS NOTES Since Output() and Write() are functions callable only from DOS processes, you MUST be a process to use this function! In C, a stub is required to get the address of the arguments which are on the stack. SEE ALSO printf(), Output(), Write() BUGS If your compiler promotes int's to 32bit, you must tell Printf() about it. Example, 'Printf ("%lx\n",42) ;'. The 'l' in '%lx' tells Printf() that the number is a 32bit LONG int. track.library/Reads track.library/Reads NAME Reads -- Read a string from a file handle. SYNOPSIS str = Reads( file, buf, len ) D0 D1 D2 D3 char *str ; BPTR file ; char *buf ; int len ; FUNCTION This function reads a carriage or EOF terminated string from the specified file. INPUTS file A BPTR to a file handle. buf Buffer space to place the input. len The LENGTH of the available buffer. RESULTS str A pointer to buf is returned, unless an error occurred, in which case a NULL is returned. NOTES This function reads a buffer full from the file, and scans for a linefeed. If a linefeed is found, then that linefeed is replaced with a string terminator (NULL), and the file is seeked back to the next character past the linefeed. If no linefeed was found, then the *buffer* is NULL terminated. If *NO* character were succesfully read. (Ie an error, or the file was at EOF), then a NULL is returned. SEE ALSO Read(), Seek() BUGS This uses DOS functions, and must only be called from a process. Due to the method of seeking used, the input file handle must not be a pipe. It will read the pipe a buffer full at a time, and discard the remainder. This can only be fixed via a buffering machanism as supplied in stdio. track.library/RemoveProcess track.library/RemoveProcess NAME RemoveProcess -- Remove a process from the resource list. SYNOPSIS RemoveProcess() FUNCTION This function removes a process from the resource list, disabling all signal handling, all exception handling, and freeing all tracked items. INPUTS RESULTS NOTES This function is called for each process automatically as it closes the library, hence there is no need to call it yourself. SEE ALSO AddProcess() BUGS none known. track.library/SendPacket track.library/SendPacket NAME SendPacket -- Send a DOS StandardPacket to a device. SYNOPSIS packet = SendPacket( packet, Dest ) D0 A1 A0 struct StandardPacket *packet ; struct MsgPort *Dest ; FUNCTION This fixes the packets 'dp_Reply' pointer, and then sends the packet to the destination port specified. INPUTS packet The StandardPacket to send to the device. Dest The destination MsgPort. RESULTS packet The original packet pointer is returned. NOTES DOS is documented to corrupt the dp_Reply pointer in its packets. Using the CreatePacket() call, the contents of dp_Reply are cached in the Message header, and copied back to dp_Reply whenever you call SendPacket(). At anytime, CheckPacket() will return the packet if it is finished with, and can be Remove()'ed. At anytime, WaitPacket() will pause until the packet IS finished with, and will Remove() it before returning. SEE ALSO DoPacket() BUGS none known. track.library/SetJmp track.library/SetJmp NAME SetJmp -- Save current context for a later LongJmp(). SYNOPSIS firstrun = SetJmp( save ) D0 A0 boolean firstrun ; jmpbuf save ; FUNCTION This function saves important processor information to enable the LongJmp() command to return to this point. INPUTS save An area to save the context to. Defined in the ANSI include file setjmp.h RESULTS firstrun FALSE if the SetJmp() saved the context, TRUE if a LongJmp() caused control to return to the SetJmp(). NOTES This is an implementation of the ANSI setjmp() command, for use with the exception handling functions. Read a manual on setjmp()/longjmp() for a proper discussion of its use. SEE ALSO LongJmp() BUGS This only works if it is called directly via inline assembly, or #pragma's. The use of a C language stub will invalidate the function, and probably crash the machine. track.library/SetTrap track.library/SetTrap NAME SetTrap -- Setup a process trap handler. SYNOPSIS SetTrap( vec ) A0 void (*vec)(void) ; FUNCTION This function tells the library internal trap handler to call function vec() before returning. INPUTS vec A pointer to a function. RESULTS NOTES Although the internal trap handler is executed in supervisor mode, the processor is switched to user mode before calling your handler code. The special compiler register A4 is setup before calling the function, in case your compiler does not have a keyword to automatically reload this register. If you do not know know why A4 is so important, then you need not worry. Trap handling can the stopped via the call SetTrap(NULL). Note that this does not turn off the internal handler, it just tells it to call the standard 'Software Failure -- Task Held' routine! SEE ALSO GetTrap() BUGS none known. track.library/SPrintf track.library/SPrintf NAME SPrintf -- Printf formatted output to a buffer. SYNOPSIS SPrintf( String, Fmt, Args ) A2 A0 A1 char *String ; char *Fmt ; Arguments Args ; FUNCTION This function performs 'C' string formatting on 'Fmt' and places the formatting string in 'String'. INPUTS String A pointer to a buffer. Fmt A pointer to a format string. Args C arguments for the Printf() formatting. RESULTS NOTES This function performs C like printf() formatting. Note that unlike Printf() and FPrintf(), no DOS functions are called, hence SPrintf() may be called from a task. SEE ALSO Printf(), printf(), FPrintf() BUGS If your compiler promotes int's to 32bit, you must tell Printf() about it. Example, 'Printf ("%lx\n",42) ;'. The 'l' in '%lx' tells Printf() that the number is a 32bit LONG int. track.library/Strcat track.library/Strcat NAME Strcat -- perform string concatenation. SYNOPSIS Strcat( str, data ) A0 A1 char *str, *data ; FUNCTION This function appends 'data' to the end of 'str'. The result is guaranteed to be NULL terminated. INPUTS str A pointer to a string. data A pointer to a second string. RESULTS NOTES str MUST be large enough to hold both strings. This function was implemented for internal use, however creating a library entry point was so trivial, I had to do it! SEE ALSO strcat() BUGS none known. track.library/Strchr track.library/Strchr NAME Strchr -- scan a string for a specific character. SYNOPSIS pos = Strchr( str, val ) D0 A0 D1 char *pos ; char *str ; int val ; FUNCTION This function searches the NULL terminated string 'str' for the first occurence of the character 'val' INPUTS str A pointer to a string to search. val A character to search for. RESULTS pos A pointer to the character within the string. NOTES This function was implemented for internal use, however creating a library entry point was so trivial, I had to do it! SEE ALSO strchr() BUGS none known. track.library/TCreateExtIO track.library/TCreateExtIO NAME TCreateExtIO -- Create Extended IO Request and track it. SYNOPSIS IORequest = TCreateExtIO( reply, size ) D0 A0 D0 struct IORequest *IORequest ; struct MsgPort *reply ; int size ; FUNCTION This function calls 'CreateExtIO()' with the arguments and tracks the result. INPUTS See CreateExtIO() RESULTS See CreateExtIO() NOTES Whereas for CreateExtIO() you call DeleteExtIO(), for this function you call FreeTrackedItem(). OR If you do not, it will be automatically freed when the track library is closed. SEE ALSO CreateExtIO(), TrackItem() BUGS none known. track.library/TCreatePacket track.library/TCreatePacket NAME TCreatePacket -- Create DOS StandardPacket and track it. SYNOPSIS struct StandardPacket = TCreatePacket( reply ) D0 A0 struct StandardPacket *StandardPacket ; struct MsgPort *reply ; FUNCTION This function calls 'CreatePacket()' with the arguments and tracks the result. INPUTS See CreatePacket() RESULTS See CreatePacket() NOTES Whereas for CreatePacket() you call DeletePacket(), for this function you call FreeTrackedItem(). OR If you do not, it will be automatically freed when the track library is closed. SEE ALSO CreatePacket(), TrackItem() BUGS none known. track.library/TCreatePort track.library/TCreatePort NAME TCreatePort -- Create a Message Port and track it. SYNOPSIS MsgsPort = TCreatePort( name, pri ) D0 A0 D0 struct MsgPort *MsgPort ; char *name ; int pri ; FUNCTION This function calls 'CreatePort()' with the arguments and tracks the result. INPUTS See CreatePort() RESULTS See CreatePort() NOTES Whereas for CreatePort() you call DeletePort(), for this function you call FreeTrackedItem(). OR If you do not, it will be automatically freed when the track library is closed. SEE ALSO CreatePort() BUGS none known. track.library/TLock track.library/TLock NAME TLock -- Create a lock and track it. SYNOPSIS lock = TLock( name, mode ) D0 D1 D2 FUNCTION This function calls 'CreatePort()' with the arguments and tracks the result. INPUTS See Lock() RESULTS See Lock() NOTES Whereas for Lock() you call UnLock(), for this function you call FreeTrackedItem(). OR If you do not, it will be automatically freed when the track library is closed. SEE ALSO Lock() BUGS Since Lock() returns a BPTR, this function is currently tracked on the BPTR. However is it possible that another pointer (to a MsgPort for example) may happen to be equal. (I.E. The address of the message port happens to be equal to the address of the lock divided by 4!) If this happens, a FreeTrackedItem(lock) may free the wrong item!! RSN I will change this to track the proper address, (not the BPTR) BUT I WILL NOT CHANGE THE NAME. USE AT OWN RISK. track.library/TMemAlloc track.library/TMemAlloc NAME TMemAlloc -- Allocate memory and track it. SYNOPSIS block = TMemAlloc( Size, Type ) D0 D0 D1 void *block ; int Size, Type ; FUNCTION This function calls 'CreatePort()' with the arguments and tracks the result. INPUTS See MemAlloc() RESULTS See MemAlloc() NOTES Whereas for MemAlloc() you call MemFree(), for this function you call FreeTrackedItem(). OR If you do not, it will be automatically freed when the track library is closed. (If you call MemFree(), the library will attempt to free it again when you close it, and the machine will guru.) SEE ALSO MemAlloc() BUGS none known. track.library/TOpen track.library/TOpen NAME TOpen -- Open a file and track it. SYNOPSIS fh = TOpen( file, mode ) D0 D1 D2 BPTR fh ; char *file ; int mode ; FUNCTION This function calls Open() with the arguments, and tracks the result. INPUTS See Open() RESULTS See Open() NOTES Whereas for Open() you call Close(), for this function you call FreeTrackedItem(). OR If you do not, it will be automatically freed when the track library is closed. SEE ALSO Open() BUGS Since Open() returns a BPTR, this function is currently tracked on the BPTR. However is it possible that another pointer (to a MsgPort for example) may happen to be equal. (I.E. The address of the message port happens to be equal to the address of the file handle divided by 4!) If this happens, a FreeTrackedItem(fh) may free the wrong item!! RSN I will change this to track the proper address, (not the BPTR) BUT I WILL NOT CHANGE THE NAME. USE AT OWN RISK. track.library/TOpenDevice track.library/TOpenDevice NAME SYNOPSIS error = TOpenDevice( devname, unit, ioRequest, flags ) D0 A0 D0 A1 D1 int error ; char *devname ; int unit ; struct IORequest *ioRequest ; int flags ; FUNCTION This calls 'OpenDevice()' with the arguments, and tracks the result. INPUTS See OpenDevice() RESULTS See OpenDevice() NOTES This function cannot track the return value of OpenDevice() since it returns a boolean. Hence, it tracks the address of the IORequest structure. This means the first call to FreeTrackItem(ioRequest) will close the device, and the next call will free the IORequest structure. This should pose no real problem, since you would not want to free an IO request without closing the device first. SEE ALSO OpenDevice() BUGS none known. track.library/TOpenLibrary track.library/TOpenLibrary NAME TOpenLibrary -- Open a system library and track it. SYNOPSIS library = TOpenLibrary( lib, rev ) D0 A1 D0 struct Library *library ; char *lib ; int rev ; FUNCTION This function calls 'OpenLibrary()' with the arguments, and tracks the result. INPUTS See OpenLibrary() RESULTS See OpenLibrary() NOTES This will track the open library, automatically closing it when you close 'track.library' if you do not FreeTrackItem() it first. WARNING : If you 'CloseLibrary()' a library, and FreeTrackedItem() closes it again, you may get a library with a negative use count. This means when the next program opens the library, and the counter increments to zero, any low memory situation can cause the library to be unloaded WHILE STILL IN USE. Hence BOOM. SEE ALSO OpenLibrary() BUGS none known. track.library/TOpenScreen track.library/TOpenScreen NAME TOpenScreen -- Open a screen and track it. SYNOPSIS TOpenScreen( newscrptr ) A0 FUNCTION The function calls OpenScreen(), and tracks the screen. INPUTS See OpenScreen() RESULTS See OpenScreen() NOTES The screen must be closed with FreeTrackedItem(). When using this, it is a good idea to track everything on the screen. That way if a guru is caught, and the library closed, everything will be free'd. If not, the screen may be free'd from under an open window! (See TOpenWindow()) SEE ALSO OpenScreen() BUGS none known. track.library/TOpenWindow track.library/TOpenWindow NAME TOpenWindow -- Open a window and track it. SYNOPSIS window *TOpenWindow( newwinptr ) D0 A0 struct Window *window ; struct NewWindow *newwinptr ; FUNCTION This function calls OpenWindow() and track the result. INPUTS See OpenWindow() RESULTS See OpenWindow() NOTES When tracking a window, it is a good idea to track everything you do to, or put in a window. Example : If you set a clip region, and then accidentaly do a division by zero, which causes the trap handler to close the library and exit gracefully, you may find the system does not like closing a window with custom clip regions and gadgets. If you had tracked the regions and gadget, they would have been clear away before the window was closed. SEE ALSO See OpenWindow() BUGS none known. track.library/TrackItem track.library/TrackItem NAME TrackItem -- Add an item description to the track list. SYNOPSIS TrackItem( Item, Code, Param ) D0 A0 D1 void *Item ; void (*Code)(void *item, void *Param) ; void Param ; FUNCTION This function creates and links in a new track node, filled in with the information about the item you gave it. INPUTS Item A pointer to an ITEM. This should be a unique pointer. Code A pointer to a function to free the ITEM. Param A parameter, incase the function pointed to by Code requires a second parameter. RESULTS NOTES This is the call to track an item. Tracking an item is done as follows 1) Prepare or find a routine to free the Item. For example, the Amige.lib 'Close()' stub. 2) Create the Item. Eg. item = Open("henry",MODE_OLDFILE) ; 3) Track the item. TrackItem(item,Close,NULL) ; /* Close does not need param */ To close the file, you call : FreeTrackedItem(item) ; Notice that the item is actually the pointer to the file handle. It does not need to be, but in this case it was important because the FreeTrackedItem(item) ; call, will do a 'Close(item)'. Items are tracked in a stack. If you track a screen, then track a window, and then track a gadget, then closing the library would cause the gadget to be freed, the window closed and the screen closed in that order. SEE ALSO FreeTrackedItem() ; BUGS none known. track.library/TrapMsg track.library/TrapMsg NAME TrapMsg -- Return a message describing a processor exception. SYNOPSIS msg = TrapMsg( code ) D0 D0 char *msg ; int code ; FUNCTION This function uses the exception code to look up a descriptive meaning in a table. INPUTS code The processor exception code. RESULTS msg A NULL terminate message. NOTES This function returns a Message describing an exception given an exception number. See GetTrap() to a description of the available messages. GetTrap() is similar, except it calls TrapMsg() with the last exception code storing in the internal process structure. SEE ALSO GetTrap() BUGS none known. track.library/TSetDMRequest track.library/TSetDMRequest NAME TSetDMRequest -- Request DM events, and track it. SYNOPSIS TSetDMRequest( win, request ) A0 A1 strict Window *win ; boolean request ; FUNCTION This function calls SetDMRequest() and tracks that it has been called. INPUTS See SetDMRequest() RESULTS See SetDMRequest() NOTES SEE ALSO SetDMRequest() BUGS none known. track.library/TSetMenuStrip track.library/TSetMenuStrip NAME TSetMenuStrip -- Set a window Menu, and Track it. SYNOPSIS TSetMenuStrip( win, menu ) A0 A1 struct Window *win ; struct Menu *menu ; FUNCTION This function attaches the menu to the window, and tracks the menu. INPUTS See SetMenuStrip() RESULTS See SetMenuStrip() NOTES When you use this, you MUST remember to FreeTrackedItem(menu) before freeing the window. When closing the track library, the menu will automatically be freed before the window is closed. SEE ALSO SetMenuStrip() BUGS none known. track.library/WaitPacket track.library/WaitPacket NAME WaitPacket -- Wait until a DOS request is complete. SYNOPSIS result = WaitPacket( packet ) D0 A1 long result ; struct StandardPacket *packet; FUNCTION This function waits until the packet is finished with, and Remove()'s it from the reply queue. It then returns the dp_Result code. INPUTS packet The StandardPacket to wait for. RESULTS result The result code from dp_Result in the packet. NOTES This is implemented as a loop doing the following : While (!CheckPacket(packet)) WaitPort(packet->sp_Msg.mn_ReplyPort); Remove(packet) ; return packet->sp_Pkt.dp_Result ; SEE ALSO CheckPacket(), Remove() BUGS none known.