Fresh Fish 2

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

/ Fresh Fish 2 / FFMCD02.bin / new / os20 / util / ssl / sslib.doc < prev next >

Wrap

Text File | 1993-12-21 | 42.5 KB | 1,655 lines

Special Support Library Version 3.0 (c) 1993 Martin Mares, MJSoft System Software ================================================================================ STARTUP, EXIT & ERROR HANDLING: StartupInit ExitCleanup ExitError DisplayError DosError ReportError TestBreak MISCELLANEOUS ROUTINES: ParseArgs Printf Puts PutsNL FormatStr StrCat StrToL SimpleRequest GENERAL TRACKING ROUTINES: CreateResList GetResList FreeResList FreeAllResLists TrackObject FreeObject TrackRoutine TrackExtd TrackSlave SPECIAL TRACKING ROUTINES: TrackAllocMem TrackAlloc TrackOpen TrackLock TrackPort TrackIoRq TrackSignal TrackDevice TrackLibrary TrackDosObject I/O FUNCTIONS: LoadFile ChkRead ChkWrite ChkDoIO HASHING FUNCTIONS: InitHashTree AddHashItem FindHashItem FILENAME FUNCTIONS: AddExtension SetExtension GetExtension RemExtension POOLED ALLOCATION: (similar to pool management in exec V39, but faster and V37) TrackPool PoolAlloc PoolFree LINEAR POOLED ALLOCATION: LinearAlloc LinearAllocN TrackLinPool ================================================================================ SYNOPSIS AddExtension(A0=Name,A1=Buffer,A2=Extension,D0=BufSize) FUNCTION Append filename extension if there isn't any. INPUTS Name = original file name Buffer = buffer to copy the name to (may be equal to Name) Extension = extension to be added BufSize = size of Buffer RESULT TRUE if successful, FALSE if buffer overflow. SEE ALSO SetExtension, GetExtension, RemExtension -------------------------------------------------------------------------------- SYNOPSIS AddHashItem(A0=Tree,A1=ItemName,D0=DataSize) FUNCTION Add an item to hashed tree performing no checking of duplicity (if you make duplicated entries, some of them will be lost = cannot be found by any method, but are correctly freed if you free the tree). The item contains your own data area of specified size. INPUTS Tree = hashed tree represented by its tracker ItemName = text key representing the item DataSize = the size of your data area for the item (0-32766, must be even!) RESULT Pointer to user data area of the item. This data area is preceeded by one word containing size of the area. The area is succeeded by key string. SEE ALSO InitHashTree, FindHashItem, FreeObject -------------------------------------------------------------------------------- SYNOPSIS ChkDoIO(A0=Message,A1=DeviceTracker) FUNCTION This function acts like DoIO in exec.library, but is a bit different (these differences make it easier-to-use in programs, which use simple I/O): - IO_FLAGS are NOT set to $01 (DoIO does it, but ChkDoIO sets only the IOB_QUICK bit). It makes ChkDoIO capable of handling I/O commands requiring special information in flags. - While waiting for finish of the operation, the user may hit CTRL-C and try to abort it. - If err_iofail and err_iofail2 bits are set, ChkDoIO does automatic processing of I/O errors. In this case, it uses the error table stored in DeviceTracker (see TrackDevice) and the custom error string: (1) If error string has been found - "<Message> - <error string>" err_iofail2 is used (2) In other cases - "<Message> - <xxx.device> error <errcode>" err_iofail is used INPUTS Message - optional error message (if NULL => "I/O error" will be used) !! it must contain reference to the error table (may be NULL) !! DeviceTracker - tracker of device the I/O operation is being done with (created by TrackDevice) RESULT Error code or 0 if successful. SEE ALSO TrackDevice, exec/DoIO -------------------------------------------------------------------------------- SYNOPSIS ChkRead(A0=Tracker,A1=Buffer,D0=Size) FUNCTION Read from file and report any errors. The file tracker is used instead of file handle, because it contains file name used for error report. The report is generated whenever the size of read data is not equal to the size specified as a parameter, therefore ChkRead cannot be used for reading from interactive files. Warning: file name specified by call to TrackFile must be still on its place and mustn't be changed in any way. INPUTS Tracker - tracker of source file RESULT Boolean value indicating success. SEE ALSO ChkWrite, TrackOpen, LoadFile -------------------------------------------------------------------------------- SYNOPSIS ChkWrite(A0=Tracker,A1=Buffer,D0=Size) FUNCTION Write to file and report any errors. The file tracker is used instead of file handle, because it contains file name used for error reports. Warning: file name specified by call to TrackFile must be still on its place and mustn't be changed in any way. INPUTS Tracker - tracker of destination file Buffer - buffer containing data block to be written Size - number of bytes (block size) RESULT Boolean value indicating success. SEE ALSO ChkRead, TrackOpen -------------------------------------------------------------------------------- SYNOPSIS CreateResList() FUNCTION Create local resource list. It can be useful if you need to have local resources allocated in some part of program and freed after leaving it and if you don't want to free them separately using FreeObject(). RESULT Pointer to created ResourceList structure. SEE ALSO FreeResList, FreeAllResLists -------------------------------------------------------------------------------- SYNOPSIS DisplayError(A0=Text,A1=Params) FUNCTION Display an error message using standard or user-supplied error displaying mechanism (it defaults to writing the message into standard output if it exists or to displaying a requester with it if started from WB with no console window). Using of requesters (equivalent to SimpleRequest(A0,A1,"Exit")) for the default error routine can be forced by the ssf_errorreq flag or the sst_errorreq tag. This function automatically adds an exclamation mark ('!') to the message and is able to process printf-style arguments. It's better if the error message isn't longer than one line. INPUTS Text - pointer to message you want to display (MUSTN'T EXCEED 200 BYTES!!!) Params - pointer to optional parameters used for printf-style formatting SEE ALSO ExitError, DosError, ReportError, SimpleRequest -------------------------------------------------------------------------------- SYNOPSIS DosError(A0=optional text,A1=Params) FUNCTION Display an error message followed by DOS fault string explaining why the error has happened. The DOS error number is determined using the dos/IoErr() function, therefore you must call it directly after the function, which caused the error, without calling any other DOS functions (directly or indirectly). The program is terminated via standard exit mechanism with return code according to sv_errrc. If IoErr()=0 and Text<>0, ExitError(Text,Params) is called. If IoErr()=0 and Text==0, ExitError("Unknown DOS Error") is called. INPUTS Text - message text, can be empty (in this case, only the fault string is shown) Params - pointer to optional parameters used for printf-style formatting NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO ExitCleanup, ExitError -------------------------------------------------------------------------------- SYNOPSIS ExitCleanup() FUNCTION This function performs standard cleanup actions and exit: - it tests, if A5 contains correct value. If it doesn't, the current task is searched in the caller table. If it isn't found, the alert AN_ExitCrash is displayed and the system is reset (this very fatal situation shouldn't occur). - the user's exit routine (sv_exitrout) is called. - all tracked resources are freed using FreeAllResLists(). - all arguments supplied by DOS are freed. - the A5-variables block is freed. - ... - program is terminated with return code sv_rc. RESULT Completely clean environment (all objects can be recycled now...) NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO StartupInit, ExitError -------------------------------------------------------------------------------- SYNOPSIS ExitError(A0=Text,A1=Params) FUNCTION Display an error message using DisplayError and exit the program with return code sv_errrc. It's better if the error message isn't longer than one line. INPUTS Text - pointer to error message (MUSTN'T EXCEED 200 BYTES!!!) Params - optional pointer for parameters used for printf-style formatting RESULT Horrified user. NOTE A5 may contain incorrect value on entry. SSLib is able to find the correct pointer automatically. SEE ALSO DisplayError, ExitCleanup -------------------------------------------------------------------------------- SYNOPSIS FindHashItem(A0=Tree,A1=ItemName) FUNCTION Find an item in hashed tree. It's able to find only one occurence of given string. INPUTS Tree = hashed tree represented by its tracker ItemName = text key to find RESULT Pointer to user data area of the item. (Additional fields reachable from this point are listed in AddHashItem doc). SEE ALSO InitHashTree, AddHashItem, FreeObject -------------------------------------------------------------------------------- SYNOPSIS FormatStr(A0=Format,A1=Data,A2=DestBuf) FUNCTION This function performs something like sprintf() in C. Calls exec/RawDoFmt with simple PutC routine, which stores all characters into supplied destination buffer. INPUTS Format - pointer to format string Data - pointer to parameters DestBuf - pointer to destination buffer -------------------------------------------------------------------------------- SYNOPSIS FreeAllResLists() FUNCTION Free all tracked resources in all resource lists. Used by ExitCleanup(). -------------------------------------------------------------------------------- SYNOPSIS FreeObject(A0=tracker) FUNCTION Free tracked object and remove the tracker. For master trackers, free all slave trackers. All trackers, which are not freed by calling of this service, will be freed during the ExitCleanup process. It will be done in reverse order that they have been tracked. Trackers connected as slaves will be handled as usually (see below). The freeing routines may fail. In this case, the resource freeing process will be started again and the tracker will be freed without calling the routine, which failed. The freeing routine for given tracker type is called only if the trk_data field is not 0. But the tracker itself is freed anyway. If you free a tracker, which is a slave of some other tracker, the tracked resource is correctly freed, but the tracker node remains in memory until freeing of master tracker. INPUTS Tracker - pointer to object tracker (may be zero -> nothing happens) SEE ALSO FreeResList, Track#?, FreeAllResLists, ExitCleanup -------------------------------------------------------------------------------- SYNOPSIS FreeResList() FUNCTION Free all tracked objects in the top-level resource list and remove the list. Used to free local resource lists. SEE ALSO CreateResList, FreeAllResLists, FreeObject, Track#?, ExitCleanup -------------------------------------------------------------------------------- SYNOPSIS GetExtension(A0=Name) FUNCTION Get filename extension. INPUTS Name = file name to get extension of RESULT Pointer to extension of given filename. If there's no extension in the name, the result will point to the trailing NULL character. NOTES A0=D0 on exit SEE ALSO AddExtension, GetExtension, RemExtension -------------------------------------------------------------------------------- SYNOPSIS GetResList() FUNCTION Get current top-level resource list. If there isn't any resource list, one is created. RESULT Pointer to the resl_list item of the top-level resource list. NOTE A0=D0 on exit SEE ALSO CreateResList, FreeResList, Track#? -------------------------------------------------------------------------------- SYNOPSIS InitHashTree(D0=TableSize,D1=Flags) FUNCTION Initialize a hashed tree. The hashed tree is a simple structure containing data items accessed using text key. SS Library allows to simply manage these trees with both case-dependent and case-independent key searching. INPUTS TableSize = number of entries in the hash table. Each entry occupies 4 bytes. Must be a power of 2 between 8 and 32768. Flags = some chacteristics of the tree htf_nocase = peform all comparisons in case-insensitive manner. It is significantly slower. RESULT Hashed tree tracker. (The tree is always referenced by this tracker) SEE ALSO AddHashItem, FindHashItem, FreeObject -------------------------------------------------------------------------------- SYNOPSIS LinearAlloc(A0=Pool,D1=Size) FUNCTION Allocates memory in given linear memory pool (created by TrackLinPool). If Size is less or equal to free space in current memory chunk, the memory is taken from it. In all other cases, new memory chunk is created. If Size>Quantum, the new chunk is expanded to satisfy the request. Allocation of 0 bytes is allowed. INPUTS Pool - tracker of linear memory pool you want to allocate the block in Size - requested size (!!! in D1 !!!) RESULT Pointer to allocated memory block. This result is always even. 0 if insufficient memory and err_memory disabled. SEE ALSO TrackLinPool, LinearAllocN -------------------------------------------------------------------------------- SYNOPSIS LinearAllocN(A0=Pool,D1=Size) FUNCTION Allocates memory in given linear memory pool (created by TrackLinPool). Doesn't word-align the allocation, therefore is usually used for allocation of strings. Slightly faster than LinearAlloc. If Size is less or equal to free space in current memory chunk, the memory is taken from it. In all other cases, new memory chunk is created. If Size>Quantum, the new chunk is expanded to satisfy the request. Allocation of 0 bytes is allowed. INPUTS Pool - tracker of linear memory pool you want to allocate the block in Size - requested size (!!! in D1 !!!) RESULT Pointer to allocated memory block. 0 if insufficient memory and err_memory disabled. SEE ALSO TrackLinPool, LinearAlloc -------------------------------------------------------------------------------- SYNOPSIS LoadFile(A0=FileName) FUNCTION Read file from disk to memory. Uses TrackOpen, TrackMem and ChkRead and reports their errors if enabled. This function is able to decrunch powerpacked files using powerpacker library. Encrypted files are not supported yet. Error processing mechanism is dependent on err_openread and err_read bits. RESULT Pointer to file in memory. The file is preceeded by one longword containing file size in bytes and is null-terminated (useful mostly for text files). Zero if unsuccessful. D1=tracker of memory area containing the file or 0 if unsuccessful BUGS Cannot load from interactive file handles, because it isn't possible. SEE ALSO ChkRead, TrackOpen -------------------------------------------------------------------------------- SYNOPSIS ParseArgs(A0=Source,A1=Template,A2=ExtraHelp,A3=Destination,D0=Flags) FUNCTION Parse arguments. This function does something similar to dos/ReadArgs, but there are some little enhancements: - Automatic processing of errors (the program is automatically halted after error if it isn't disabled by corresponding flag bit). - Ability to process non-decimal numbers in /N arguments (see StrToL). - Tracking functions are used for allocation of additional memory. - Provides mechanism for processing of default settings of non-/A arguments. - Arguments specified in default settings may be overriden or disabled by placing the minus ("-") sign before their keywords. For example: Let's have the template "NAME/K,SWITCH/S,ANOTHER/S" Default is "NAME Something ANOTHER" Parameters are "NAME Suspicious -ANOTHER SWITCH" Result is: NAME="Suspicious", ANOTHER=FALSE, SWITCH=TRUE The typical example of using ParseArgs with defaults is: if (! ParseArgs(Defaults,Template,&Vars,pafm_nofail | pafm_ignorea)) Report_Bad_Defaults; ParseArgs(Arguments,Template,&Vars,pafm_noclear); !! The /A arguments aren't taken from the defaults. INPUTS Source - string to parse (NULL means: fetch it from standard buffered input) Template - template ExtraHelp - string to be displayed after second "?" entered by the user Destination - array to store the arguments to Flags - some flags (see below) FLAGS pafb_nofail - disable automatic processing of errors pafb_noclear - don't clear the array pafb_ignorea - don't check presence of /A arguments RESULT Boolean value indicating success (always true if the automatic error processing is turned on. D1=object tracker SEE ALSO StartupInit, StrToL, dos/ReadArgs -------------------------------------------------------------------------------- SYNOPSIS PoolAlloc(A0=Pool,D0=Size) FUNCTION Allocates memory in given memory pool (created by TrackPool). If Size is less or equal to Threshold of memory pool, it's allocated inside some chunk. If there is no free chunk, new one is created. Large memory blocks are allocated separately and linked to the pool Attempt to allocate 0 bytes of memory results in alert AN_AllocZero and termination of your program. INPUTS Pool - tracker of memory pool you want to allocate the block in Size - requested size RESULT Pointer to allocated memory block. SEE ALSO TrackPool, PoolFree -------------------------------------------------------------------------------- SYNOPSIS PoolFree(A0=Pool,A1=Address,D0=Size) FUNCTION Frees memory allocated by PoolAlloc. Partial freeing is not allowed. INPUTS Pool - tracker of memory pool you have allocated the block in Address - address of memory block to be freed Size - size of memory block SEE ALSO TrackPool, PoolAlloc -------------------------------------------------------------------------------- SYNOPSIS Printf(A0=Text,A1=Params) FUNCTION This function sends a formatted text to standard output. Similar to C printf() with one exception: the size of INT defaults to 16 bits. INPUTS Text - pointer to message to be printed Params - pointer to optional parameters SEE ALSO Puts, PutsNL, FormatString -------------------------------------------------------------------------------- SYNOPSIS Puts(A0=Text) FUNCTION This function sends a non-formatted text to standard output. INPUTS Text - pointer to text to be printed SEE ALSO PutsNL, Printf, FormatString -------------------------------------------------------------------------------- SYNOPSIS PutsNL(A0=Text) FUNCTION This function sends a non-formatted text followed by the NL (new line) chara- cter to standard output. INPUTS Text - pointer to text to be printed SEE ALSO Puts, Printf, FormatString -------------------------------------------------------------------------------- SYNOPSIS RemExtension(A0=Name) FUNCTION Remove filename extension if there's any. INPUTS Name = filename to remove extension from. RESULT None SEE ALSO AddExtension, SetExtension, GetExtension -------------------------------------------------------------------------------- SYNOPSIS ReportError(D0=ErrCode,A1=Arg1,D2=Arg2,D3=Arg3) FUNCTION Write standard error message and terminate or simply return without any message (if the corresponding error bit is clear). INPUTS ErrCode = error code (see SS.i) Arg1,Arg2,Arg3 = optional arguments to be substituted in the message RESULT 0 in both D0 and D1 SEE ALSO ExitError, DisplayError -------------------------------------------------------------------------------- SYNOPSIS SetExtension(A0=Name,A1=Buffer,A2=Extension,D0=BufSize) FUNCTION Set filename extension or add it if there isn't any. INPUTS Name = original file name Buffer = buffer to copy the name to (may be equal to Name) Extension = extension to be used BufSize = size of Buffer RESULT TRUE if successful, FALSE if buffer overflow. SEE ALSO AddExtension, GetExtension, RemExtension -------------------------------------------------------------------------------- SYNOPSIS SimpleRequest(A0=Text,A1=Params,A2=Gadgets) FUNCTION Display a message using intuition/EasyRequest, but with significantly simpler arguments. For additional informations see EasyRequest. INPUTS Text - pointer to message you want to display Params - pointer to optional parameters used for printf-style formatting Gadgets - pointer to string containing texts to be used for requester gadgets RESULT See EasyRequest SEE ALSO DisplayError, intuition/EasyRequest -------------------------------------------------------------------------------- SYNOPSIS StartupInit(A0=StartupStruct,D7=WBMsg) FUNCTION Perform standard startup initialization which includes: - Checks ss.library version requested by your program. - Allocate space for system variables and your own variables. The A5 register points to this memory region directly on the ssbase item allowing simple determination of the library base using MOVE.L (A5),A6. The system variables are stored below A5 (as described in SS.i) and may grow in future releases. Your own variables are stored above A5. The amount of user's variables is stored in the StartupStruct. - All system variables are initialized to their proper values. - All of your own variables are initialized to zeroes. - Automatically opens some libraries (dos,intuition,gfx,gadtools,utility) - Program name is determined and stored in system variable. - Current task is added to the CallerList, which allows to recover from a soft crash (see ExitCleanup for an explaination). - All actions requested by the tags are done (see below). - The arguments are parsed in both CLI and WB modes. If the WB has called us, the tool types are parsed using supplied template and converted to CLI arguments. If there's a multi-selected icon, it will be used as the first argument (if the first argument is /M, all multiselected icons will be parsed). If the program has been called as a default tool of some project, the project's name is used as the 1st argument. If there is some icon used as the first argument, its tool types override the program's ones. - If the program is started from Workbench, its current directory is set to its home directory or to directory containing the first argument. - Task's exception handler is replaced by custom one. It shows all address and data registers, the program counter and the status register (SR). The user may suspend the program, try to abort it (in this case, all resources tracked by SS functions are freed) or reboot the machine. [The exception code is NOT replaced if there is already another exception handler stored in RAM -> you can use breakpoints in your favourite debugger etc.] [The algorithm used for detection of custom exception handler might have some problems with future kickstarts larger than 1/2 Meg.] - All other system variables are set to their correct values (see SS.i) - Address of ExitCleanup function is pushed onto stack allowing simple exit by usual RTS instruction INPUTS StartupStruct - pointer to startup structure. This structure is the following format: DC.W VarSize ; requested size of user's variables DC.W ReqSSVer ; required version of SS.library -- here are stored the tags -- WbMsg - pointer to WorkBench startup message (you must get it manually). Can have any value when started from CLI. Must be 0 when started from process created by CreateProc, which is NOT started by the WorkBench. TAG SYSTEM The tags are stored in special (read: non-standard) format. This format uses variable-length tagitems: a) Special SSLib trackers (codes 0000-3FFF). These trackers have absolutely non-systematic arguments, therefore if SSLib encounters any unknown tag of this type (e.g. generated by newer version of the macros), it can't be simply ignored => the "Unknown Tracker" alert is shown and the program is terminated. If you use these trackers, make sure that your "required version number" value matches all these tag types you're using. This is usually done automatically by ssmac.h. b) Longword trackers. These are utility.library compatible with one small exception: TAG_IGNORE, TAG_MORE and TAG_SKIP are not supported and act as TAG_END. The implementation is simple: TAG_END ($00000000) and is understood as special SSLib tracker $0000 with the same meaning. All other longword trackers start with $8000, which says that StartupInit has to fetch next word as tag ID and next longword as tag parameters (in case of string args, it's a pointer to the string). The tag ID must be in range 8000-FFFF. c) Optional trackers (C000-FFFF). These trackers have variable size of argument, but there's a simple mechanism to determine this size: it's encoded in bits #12 and #13 of tag ID: 00 means no parameters, 01=one word, 10=one longword, 11=string (null-terminated and padded by zeroes to even length). If one of these optional trackers is encountered and cannot be interpreted, it's simply skipped. d) Extended trackers (4000-7FFF). Similar to Optional trackers, but can't be ignored (see notes in "Special trackers" paragraph). This mechanism is relatively good, but there are currently no tags of types b,c,d. These types will be used in later versions. TAGS You usually needn't to specify the tags directly, because the there exist simple generation macros for most of them. Many pointers are relative (marked as RelPtr). They can be generated by the following macro: RelPtr macro \@a dc.w \1-\@a endm Tag Parameters Meaning sst_finish none End of TagList sst_wbconsole Create console window if started from WB. This window is used as standard input and output. sst_template string,word Specify argument template and offset from A5 to store the arguments on (see ParseArgs). sst_usertrk RelPtr Define user tracker types. You pass a relative pointer to UserTrkTypes structure: DC.B NumberOfTrackers,0 followed by RelPtrs to freeing routines (see FreeObject) sst_extrahelp string Define extra help string for argument parsing. sst_exitrout RelPtr Define exit routine, which will be called by ExitCleanup (or any error exit routine) before any cleanup will be done. This mechanism can be used for closing of windows and other similar actions. The exit routine may call ExitCleanup and the error exit routines, in which case it won't be called again. sst_usererr RelPtr Define user's error routine. This routine will be called by DisplayError and all error routines which display errors. The routine will have the same parameters as DisplayError (A0=Message, A1=FormatData). If this routine calls any of the error functions, it will be called again. sst_nowbstart Exit with error message when called from WB. sst_library string,WV,W Open library of specified name and version (WV), store its base to variable specified by its offset from A5 (W). Exit with error message if can't be opened. sst_trylib string,WV,W Try to open library (same function as previous tag, but if failed, it will simply continue with base=0). sst_nowbargs Don't parse WB arguments. sst_noprogname Don't print program's name in error messages. sst_cputype Min,Max Fail if CPU type isn't in specified range. 0=68000...4=68040, -1=no upper limit sst_fputype Min,-1 Fail if FPU type isn't in specified range 0=none,1=68881,2=68882,3=68040 sst_sysver Min,Max Fail if kickstart version isn't in specified range. sst_errorreq Forces using of requesters for error messages. sst_errors BitMap.L Disable automatic processing of specified errors (see SS.i for constants (err_xxx)). sst_wbconname string Use WB Console specified by name sst_envvar string Try to fetch default values of parameters. These values are overriden by user-selected parameters. sst_poolsize PoolSize.L Specify size of task's private memory pool. This pool is used for allocation of all trackers. Default size = 512 bytes. Specify higher values when using tracking very frequently. This tag MUST be specified before all other tags. The value must be an integer multiple of 8. sst_poolthresh PoolThr.L Specify threshold of task's private memory pool (see TrackPool, PoolAlloc). Default threshold=373. Usage: rare. This tag MUST be specified directly after sst_poolsize. NOTES Argument parsing could be problematic when running from several debuggers (for example MonAm older than 3.04), because SSLib uses standard V37 way to pass them using buffered standard input. See also ssmac.h for some work- around. SEE ALSO ExitCleanup RESULT A5=pointer to the variable zone. This value is required by all the routines in this library excluding where this doc says something other. If you call SSLib with different value in A5, weird things can occur. -------------------------------------------------------------------------------- SYNOPSIS StrCat(A0=Dest,A1=Source) -> A0=AfterPtr FUNCTION This function performs string concatenation. It concatenates the second string to the first one. INPUTS Dest,Source = strings to work with. RESULT A0 contains address of the null character at the end of the destination string. It allows to concatenate multiple strings without touching contents of A0. -------------------------------------------------------------------------------- SYNOPSIS StrToL(A0=String) FUNCTION Convert string containing a number in ASCII form to binary form. It supports decimal, octal (prefixed by 0) and hexadecimal (prefixed by 0x or $) numbers. All spaces before the number are skipped. If there're any invalid characters, the standard error mechanism is used. If the user hasn't disabled it, the error message err_number is displayed and the program is terminated. This function isn't slow, but it isn't recommended to use it for processing of long sequences of numbers, because it uses the longword multiply function of the utility.library, which is relatively slow on 68000 and 68010. INPUTS String - pointer to string to be converted. RESULT Value of the number. D1 contains address of illegal character if failed or 0 if input string contains valid number. -------------------------------------------------------------------------------- SYNOPSIS TestBreak() FUNCTION Test the CTRL-C signal and abort the program if active. NOTES Doesn't modify contents of D0,D1,A0,A1. SEE ALSO exec/SetSignal, arp/CheckAbort, arp/CheckBreak, dos/dos.i -------------------------------------------------------------------------------- SYNOPSIS TrackAlloc(D0=size) FUNCTION Allocate, clear and track public memory of specified size. If the memory is not available, exit with error message if its's enabled by corresponding error bit. If you want to allocate large block of memory and you don't need it to be cleared, use TrackAllocMem(Size,1) instead. INPUTS Size = how large (in bytes) chunk of memory you want to allocate RESULT Pointer to memory chunk or 0 if not enough memory. D1=object tracker SEE ALSO TrackAllocMem, FreeObject, exec/AllocMem -------------------------------------------------------------------------------- SYNOPSIS TrackAllocMem(D0=size,D1=requirements) FUNCTION Allocate memory with specified attributes. This function is very similar to TrackAlloc. INPUTS Size = how large chunk you want to allocate Requirements = memory requirements (see exec/memory.h) RESULT Pointer to allocated memory chunk or 0 if out of memory of required type. D1=object tracker SEE ALSO TrackAlloc, FreeObject, exec/AllocMem -------------------------------------------------------------------------------- SYNOPSIS TrackDevice(A0=DevName,A1=IORQ,D0=unit,D1=flags,[A2=ErrTable]) FUNCTION Open device and track it. In case of difficulty, write an error message and abort the program if requested by corresponding error bit. INPUTS DevName = device name, case-sensitive IORQ = IORequest to use with this device (if IORQ<256, TrackIoRq(0,IORQ) will be called to create new IORequest, which will be linked by TrackSlave to device's tracker) Unit = device unit number Flags = OpenDevice flags ErrTable = optional pointer to error message table (this pointer MUST be specified if you want to use ChkDoIO, but it may be NULL). The table is a sequence of error definition blocks terminated by a block of 0 errors (both Min and NumErr fields are zero). Each block has the following format: DC.W Min ; Number of first error message DC.W NumErr ; Number of error messages in this block DC.L ErrPointer[NumErr] ; Pointers to error strings RESULT Error code or 0 if successful. trk_data of the tracker contains pointer to IORequest used by this device. D1=object tracker A1=copy of trk_data (pointer to associated IORequest) SEE ALSO ChkDoIO, TrackIORQ, TrackPort, FreeObject, exec/OpenDevice -------------------------------------------------------------------------------- SYNOPSIS TrackDosObject(D0=Type,A0=TagList) FUNCTION Allocate dos object and track it. Does usual error handling and reporting (err_memory). INPUTS Type = dos object type TagList = dos object tag list RESULT Pointer to allocated dos object or 0 if not successful. D1=object tracker SEE ALSO dos/AllocDosObject, FreeObject -------------------------------------------------------------------------------- SYNOPSIS TrackExtd(D0.B=type,D1=extsize) FUNCTION Create an extended tracker structure and connect it to active resource list (if there's no resource list, one will be created). The extended tracker is a standard resource tracker, which has additional data behind trk_sizeof. These bytes are for your own use. INPUTS Type = tracker type ID (see SS.i) ExtSize = size of tracker extension RESULT Pointer to created object tracker. A0=tracker, A1=pointer to trk_ext SEE ALSO TrackObject -------------------------------------------------------------------------------- SYNOPSIS TrackIoRq(A0=OptionalPort,D0=size or 0) FUNCTION Create an IO Request and track it. This function can use user-supplied message port or create special message port for this IORQ. In case of difficulty, writes error message and aborts the program if requested by corresponding error bit. INPUTS OptionalPort = pointer to user-supplied message port or 0 if nothing supplied Size = requested IoRequest size or 0 for IOStdReq structure RESULT Pointer to created IORequest. D1=object tracker SEE ALSO TrackPort, TrackDevice, FreeObject -------------------------------------------------------------------------------- SYNOPSIS TrackLibrary(A0=LibName,D0=version) FUNCTION Open library and track it. If the library isn't available and you hadn't disabled it using the error bits, the error message will be displayed and the program will be aborted. INPUTS LibName = name of library, is case-sensitive Version = required minimal version of library RESULT Pointer to library node or 0 if unsuccessful D1=object tracker SEE ALSO FreeObject, exec/OpenLibrary, StartupInit -------------------------------------------------------------------------------- SYNOPSIS TrackLock(A0=name,D0=lockmode) FUNCTION Lock dos object and track it. Error handling as usually. INPUTS Name = name of object you wish to lock LockMode = lock mode (see dos/dos.i) RESULT Dos lock or 0 if not possible. D1=object tracker SEE ALSO dos/Lock, FreeObject -------------------------------------------------------------------------------- SYNOPSIS TrackObject(D0.B=type) FUNCTION Create a standard tracker and connect it to active resource list (if there's no resource list, one will be created). This function is used to track objects of your own types defined using the UserTrkTypes structure (tracker types in range $80 to $FF) or to track objects defined by ss.library extensions (not implemented yet). Your object freeing function will be called ONLY if the trk_data field contains non-null value. This suspiciously-looking rule allows you to track your objects simply with respect to all possible failures: - call TrackObject (if there isn't enough memory to do it -> aborted) - store A1 - allocate your object - restore A1 - store optional data at A1 if you need - store pointer to your object to -(A1) If allocation of your object fails and you abort the program, you don't have to free the tracker, because it will be done automatically by ExitCleanup (or other exit routine, which calls ExitCleanup) and your object-freeing routine won't be called. If you don't abort the program, you have simply to free the tracker using FreeObject and your object-freeing routine won't be called, too. INPUTS Type = tracker type ID (see SS.i) RESULT Pointer to created object tracker. A0=tracker, A1=pointer to trk_ext SEE ALSO CreateResList, FreeObject, FreeResList, GetResList, sv_usertrk, TrackRoutine, TrackExtd -------------------------------------------------------------------------------- SYNOPSIS TrackOpen(A0=Name,D0=Openmode) FUNCTION Open a file and track it. Does usual error checking and handling (see some other tracking function). INPUTS Name = name of the file you want to open OpenMode = Open() mode - see dos/dos.i - MODE_* also can be a SS open mode: OPEN_OLD - identical to MODE_OLDFILE (but shorter value) OPEN_NEW - identical to MODE_NEWFILE (but shorter value) OPEN_APPEND - open using MODE_OLDFILE and Seek to end RESULT File handle of opened file or 0 if Open() has failed. D1=object tracker SEE ALSO dos/Open, dos/dos.i, FreeObject -------------------------------------------------------------------------------- SYNOPSIS TrackPool(Quantum,Threshold,Attributes) D0 D1 D2 FUNCTION Create a memory pool and track it. Error checking is performed according to common rules (see elsewhere what does it mean). Pooled allocation is a relatively fast memory allocation strategy designed for manipulating small blocks of memory. It's based on memory chunks, each of them has given size (Quantum). Any memory block requested by PoolAlloc, which size is less or equal to Threshold, is allocated inside one of memory chunks. Blocks greater than Threshold are allocated using standard AllocMem and linked to the pool. All memory blocks in the pool can be freed separately or simultaneously by FreeObject. INPUTS Quantum - allocation quantum Threshold - size of largest block allocated inside chunks Attributes - requested memory attributes (MEMF_#? - see AllocMem) RESULT Pointer to memory pool tracker. SEE ALSO FreeObject, PoolAlloc, PoolFree, exec/AllocMem -------------------------------------------------------------------------------- SYNOPSIS TrackLinPool(Quantum,Attributes) D0 D1 FUNCTION Create a linear memory pool and track it. Linear pooled allocation is an extremely fast memory allocation strategy designed for allocating of small blocks of memory, which are freed together. The pool manager allocates memory in large blocks of given size (Quantum). It tries to use currently active block for each allocation request. If it fails, new block is created. INPUTS Quantum - allocation quantum Attributes - requested memory attributes (MEMF_#? - see AllocMem) RESULT Pointer to linear memory pool tracker. SEE ALSO FreeObject, LinearAlloc, LinearAllocN -------------------------------------------------------------------------------- SYNOPSIS TrackPort() FUNCTION Create a message port and track it. Does usual error checking and handling. RESULT Pointer to properly initialized message port. D1=object tracker SEE ALSO exec/CreateMsgPort, FreeObject, CreateIORQ -------------------------------------------------------------------------------- SYNOPSIS TrackRoutine(A0=routine,A1=args) FUNCTION Define a tracker, which will call your routine in time of freeing. The Args you supply will be passed in A0 to your routine. If A1=0, no routine will be called. For the reason of this suspicious action, see TrackObject (there are applied the same rules). INPUTS Routine = pointer to routine You wish to call Args = user data passed to the routine in time of resource freeing RESULT Tracker A1 points to Args and can be used in similar way as in TrackObject, but you needn't to use -(A1). SEE ALSO TrackObject, FreeObject -------------------------------------------------------------------------------- SYNOPSIS TrackSignal() FUNCTION Allocate a signal and track it. Does usual error checking and handling. RESULT Number of signal or -1 if there are no free signals. SEE ALSO exec/AllocSignal, FreeObject NOTE D1=object tracker -------------------------------------------------------------------------------- SYNOPSIS TrackSlave(A0=Master,A1=Slave) FUNCTION Connect Slave to a list of Master's slaves and re-connect the Master to the front of current resource list, therefore it will be freed before the slaves. The linkage mechanism uses the Tracker.trk_ext field as pointer to the first slave. It causes that standard trackers (excluding trt_null) cannot be used as masters. The routine tracker (obtained via TrackRoutine) can be used, but its entry data (passed in A0 to user's resource freeing routine) will be destroyed (but it won't be 0 in any case -> the routine is called everytime). SEE ALSO TrackObject, FreeObject --------------------------------------------------------------------------------