home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / dev / asm / ssl / sslib.doc < prev    next >
Text File  |  1994-06-03  |  57KB  |  2,098 lines
  1. TABLE OF CONTENTS
  2.  
  3. ss.library/AddExtension
  4. ss.library/AddHashItem
  5. ss.library/CallBlock
  6. ss.library/ChkDoIO
  7. ss.library/ChkRead
  8. ss.library/ChkWrite
  9. ss.library/CreateResList
  10. ss.library/DisplayError
  11. ss.library/DosError
  12. ss.library/ExitCleanup
  13. ss.library/ExitError
  14. ss.library/FindHashItem
  15. ss.library/FormatString
  16. ss.library/FreeAllResLists
  17. ss.library/FreeObject
  18. ss.library/FreeResList
  19. ss.library/GetExtension
  20. ss.library/GetResList
  21. ss.library/InitHashTree
  22. ss.library/LinearAlloc
  23. ss.library/LinearAllocN
  24. ss.library/LoadFile
  25. ss.library/MergeResLists
  26. ss.library/ParseArgs
  27. ss.library/PoolAlloc
  28. ss.library/PoolFree
  29. ss.library/Printf
  30. ss.library/Puts
  31. ss.library/PutsNL
  32. ss.library/QuickSort
  33. ss.library/RelinkObject
  34. ss.library/RemExtension
  35. ss.library/ReportError
  36. ss.library/SetExtension
  37. ss.library/SimpleRequest
  38. ss.library/SortList
  39. ss.library/SortListName
  40. ss.library/SortLongs
  41. ss.library/SortStrings
  42. ss.library/StartupInit
  43. ss.library/StrCat
  44. ss.library/StrToL
  45. ss.library/TestBreak
  46. ss.library/TestStack
  47. ss.library/TrackAlloc
  48. ss.library/TrackAlloc
  49. ss.library/TrackAllocPub
  50. ss.library/TrackDevice
  51. ss.library/TrackDosObject
  52. ss.library/TrackExtd
  53. ss.library/TrackIoRq
  54. ss.library/TrackLibrary
  55. ss.library/TrackLinPool
  56. ss.library/TrackLock
  57. ss.library/TrackObject
  58. ss.library/TrackOpen
  59. ss.library/TrackPool
  60. ss.library/TrackPort
  61. ss.library/TrackRoutine
  62. ss.library/TrackSignal
  63. ss.library/TrackSlave
  64. ss.library/AddExtension                   ss.library/AddExtension
  65.  
  66.    NAME
  67.     AddExtension -- Add extension to file name.
  68.  
  69.    SYNOPSIS
  70.     Success = AddExtension(Name, Buffer, Extension, BufSize);
  71.     D0               A0    A1      A2     D0
  72.  
  73.    FUNCTION
  74.     Appends an extension to file name.  If there's already some extension
  75.     at the end of the name, nothing happens.
  76.  
  77.    INPUTS
  78.     Name - original file name
  79.  
  80.     Buffer - buffer to copy the result to
  81.  
  82.     Extension - extension to be added
  83.  
  84.     BufSize - size of the buffer
  85.  
  86.    RESULT
  87.     Success - TRUE if successful, FALSE if buffer overflow.
  88.  
  89.    SEE ALSO
  90.     SetExtension, GetExtension, RemExtension
  91.  
  92. ss.library/AddHashItem                       ss.library/AddHashItem
  93.  
  94.    NAME
  95.     AddHashItem -- Add item to hashed tree.
  96.  
  97.    SYNOPSIS
  98.     UserData = AddHashItem(Tree, ItemName, DataSize);
  99.     D0               A0    A1        D0
  100.  
  101.    FUNCTION
  102.     Add an item to hashed tree performing no checking of duplicity (if
  103.     you make duplicated entries, some of them will be lost and cannot be
  104.     found by any method, but are correctly freed if you free the tree).
  105.  
  106.     The item contains your own data area of specified size.
  107.  
  108.    INPUTS
  109.     Tree - hashed tree represented by its tracker
  110.  
  111.     ItemName - text key representing the item
  112.  
  113.     DataSize - the size of your data area for the item (0-32766, must be
  114.         even!)
  115.  
  116.    RESULT
  117.     UserData - Pointer to user data area of the item.  This data area is
  118.         preceeded by one word containing size of the area.  The area
  119.         is succeeded by key string.
  120.  
  121.    SEE ALSO
  122.     InitHashTree, FindHashItem, FreeObject
  123.  
  124. ss.library/CallBlock                     ss.library/CallBlock
  125.  
  126.    NAME
  127.     CallBlock -- Call a subprogram.
  128.  
  129.    SYNOPSIS
  130.     Failure = CallBlock(Routine, LeaveResources);
  131.     D0            A0         D0
  132.  
  133.    FUNCTION
  134.     Calls a subprogram.
  135.  
  136.     If the subprogram fails or LeaveResources=0, all resources allocated
  137.     by it are freed.
  138.  
  139.     If it doesn't fail and LeaveResources<>0, these resources are added
  140.     to current resource list of the caller.
  141.  
  142.     Registers D1-D7/A0-A6 are passed to called subprogram without
  143.     changes.  If it returns normally, D1-D7/A0-A4/A6 are passed back to
  144.     the caller.  In case of failure (return via ExitError), D2-D7/A2-A6
  145.     contain their original values (before call), values of D1/A0-A1 are
  146.     unexpectable.
  147.  
  148.    INPUTS
  149.     Routine - address of subroutine to be called
  150.  
  151.     LeaveResources - boolean value indicating that you want the resources
  152.         allocated by the subprogram to be allocated.  If not set,
  153.         they are freed automatically before return.
  154.  
  155.    RESULT
  156.     Failure - non-zero value if the routine has failed.
  157.  
  158.    NOTE
  159.     The called subprogram is not allowed to create its own resource
  160.     lists.
  161.  
  162.    SEE ALSO
  163.     MergeResLists
  164.  
  165. ss.library/ChkDoIO                       ss.library/ChkDoIO
  166.  
  167.    NAME
  168.     ChkDoIO -- Perform an I/O operation and test error.
  169.  
  170.    SYNOPSIS
  171.     Error = ChkDoIO(Message, DeviceTracker);
  172.     D0        A0     A1
  173.  
  174.    FUNCTION
  175.     This function acts like DoIO in exec.library with the following
  176.     differences, which make it easier to use in programs doing simple
  177.     I/O:
  178.  
  179.     - IO_FLAGS are NOT set to $01 (DoIO does it, but ChkDoIO sets only
  180.       the IOB_QUICK bit).  It makes ChkDoIO capable of handling I/O
  181.       commands requiring special information in flags.
  182.  
  183.     - While waiting for finish of the operation, the user may hit CTRL-C
  184.       and try to abort it.
  185.  
  186.     - If err_iofail and err_iofail2 bits are set, ChkDoIO does automatic
  187.       processing of I/O errors.  In this case, it uses the error table
  188.       stored in the device tracker (see TrackDevice) and the custom error
  189.       string.  If the error string has been found, "<Message> -
  190.       <error string>" is displayed and err_iofail2 is used.  In other
  191.       cases, "<Message> - <xxx.device> error <errcode>" and err_iofail is
  192.       used.
  193.  
  194.    INPUTS
  195.     Message - optional error message (if NULL, "I/O error" will be used)
  196.  
  197.     DeviceTracker - tracker of device to perform the I/O operation with.
  198.         It must contain reference to the error table (may be NULL).
  199.  
  200.    RESULT
  201.     Error - error code or 0 if successful.
  202.  
  203.    WARNING
  204.     It is not possible to use ChkDoIO on device trackers which don't
  205.     contain the error table.  A NULL pointer is a valid error table.
  206.  
  207.    SEE ALSO
  208.     TrackDevice, exec/DoIO
  209.  
  210. ss.library/ChkRead                       ss.library/ChkRead
  211.  
  212.    NAME
  213.     ChkRead -- Read from file and test error.
  214.  
  215.    SYNOPSIS
  216.     Success = ChkRead(Tracker, Buffer, Size);
  217.     D0          A0       A1       D0
  218.  
  219.    FUNCTION
  220.     Read from file and report any errors.  The file tracker is used
  221.     instead of file handle, because it contains file name used for error
  222.     reporting.  The report is generated whenever the size of read data is
  223.     not equal to the size specified as a parameter, therefore ChkRead
  224.     cannot be used for reading from interactive files (consoles etc.).
  225.  
  226.    INPUTS
  227.     Tracker - tracker of file to read the data from.
  228.  
  229.     Buffer - buffer to read the data to.
  230.  
  231.     Size - size of block you want to read.
  232.  
  233.    RESULT
  234.     Success - boolean value indicating success.
  235.  
  236.    WARNING
  237.     File name specified by a call to TrackFile must be still on its place
  238.     and mustn't be changed in any way.
  239.  
  240.    SEE ALSO
  241.     ChkWrite, TrackOpen, LoadFile
  242.  
  243. ss.library/ChkWrite                      ss.library/ChkWrite
  244.  
  245.    NAME
  246.     ChkWrite -- Write to file and test error.
  247.  
  248.    SYNOPSIS
  249.     Success = ChkWrite(Tracker, Buffer, Size);
  250.     D0           A0        A1        D0
  251.  
  252.    FUNCTION
  253.     Write to file and report any errors.  The file tracker is used
  254.     instead of file handle, because it contains file name used for error
  255.     reporting.  The report is generated whenever the size of written data
  256.     is not equal to the size specified as a parameter.
  257.  
  258.    INPUTS
  259.     Tracker - tracker of file to write the data to.
  260.  
  261.     Buffer - address of data to be written.
  262.  
  263.     Size - size of block you want to write.
  264.  
  265.    RESULT
  266.     Success - boolean value indicating success.
  267.  
  268.    WARNING
  269.     File name specified by a call to TrackFile must be still on its place
  270.     and mustn't be changed in any way.
  271.  
  272.    SEE ALSO
  273.     ChkRead, TrackOpen
  274.  
  275. ss.library/CreateResList                 ss.library/CreateResList
  276.  
  277.    NAME
  278.     CreateResList -- Create new resource list.
  279.  
  280.    SYNOPSIS
  281.     ResList = CreateResList();
  282.     D0
  283.  
  284.    FUNCTION
  285.     Create local resource list.  It can be useful if you need to have
  286.     local resources allocated in some part of program and freed after
  287.     leaving it and you don't want to free them separately by
  288.     FreeObject().
  289.  
  290.    RESULT
  291.     ResList - Pointer to created ResourceList structure.
  292.  
  293.    SEE ALSO
  294.     FreeResList, FreeAllResLists
  295.  
  296. ss.library/DisplayError                   ss.library/DisplayError
  297.  
  298.    NAME
  299.     DisplayError -- Display error message without exiting.
  300.  
  301.    SYNOPSIS
  302.     DisplayError(Text, Params);
  303.              A0    A1
  304.  
  305.    FUNCTION
  306.     Display an error message using standard or user-supplied error
  307.     displaying mechanism (it defaults to writing of the message into
  308.     standard output if it exists or to displaying a requester with it if
  309.     started from WB with no console window).  Using of requesters
  310.     (equivalent to SimpleRequest(A0,A1,"Exit")) for the default error
  311.     routine can be forced by the ssf_errorreq flag or the sst_errorreq
  312.     tag.
  313.  
  314.     This function automatically adds an exclamation mark ('!') to the
  315.     message and is able to process printf-style arguments.
  316.  
  317.     It's better if the error message isn't longer than one line.
  318.  
  319.    INPUTS
  320.     Text - pointer to message you want to display (MUSTN'T EXCEED 200
  321.         BYTES!!!)
  322.  
  323.     Params - pointer to optional parameters used for printf-style
  324.         formatting
  325.  
  326.    SEE ALSO
  327.     ExitError, DosError, ReportError, SimpleRequest, exec/RawDoFmt
  328.  
  329. ss.library/DosError                      ss.library/DosError
  330.  
  331.    NAME
  332.     DosError -- Exit with DOS error.
  333.  
  334.    SYNOPSIS
  335.     DosError(Text, Params);
  336.          A0    A1
  337.  
  338.    FUNCTION
  339.     Display an error message followed by DOS fault string explaining why
  340.     did error happen.  The DOS error number is determined from the
  341.     dos/IoErr() function, therefore you must call DosError() directly
  342.     after the function, which caused the error without calling any other
  343.     DOS functions (directly or indirectly).
  344.  
  345.     The program is terminated via standard exit mechanism with return
  346.     code according to sv_errrc.
  347.  
  348.     If IoErr() returns zero (no error cause known), the supplied message
  349.     is simply passed to ExitError().  If there is no such message,
  350.     "Unknown DOS Error" is used.
  351.  
  352.    INPUTS
  353.     Text - message text, can be empty (in this case, only the fault
  354.         string is shown).
  355.  
  356.     Params - pointer to optional parameters used for printf-style
  357.         formatting.
  358.  
  359.    NOTE
  360.     A5 may contain incorrect value on entry.  SSLib is able to find the
  361.     correct pointer automatically.
  362.  
  363.    SEE ALSO
  364.     ExitCleanup, ExitError
  365.  
  366. ss.library/ExitCleanup                       ss.library/ExitCleanup
  367.  
  368.    NAME
  369.     ExitCleanup -- Clean up and exit.
  370.  
  371.    SYNOPSIS
  372.     ExitCleanup();
  373.  
  374.  
  375.    FUNCTION
  376.     This service exits the program after performing some cleanup actions:
  377.  
  378.     - A5 is tested for correct value.  If it contains garbage, the
  379.       current task is searched for in the caller table.  If it isn't
  380.       found, the alert AN_ExitCrash is displayed.  (this very fatal
  381.       situation shouldn't occur).
  382.  
  383.     - the user's exit routine (sv_exitrout) is called.
  384.  
  385.     - all tracked resources are freed using FreeAllResLists().
  386.  
  387.     - all arguments supplied by DOS are freed.
  388.  
  389.     - the block of variables pointed to by A5 is freed.
  390.  
  391.     - some other actions which needn't to be described here.
  392.  
  393.    RESULT
  394.     Completely clean environment (all objects can be recycled...)
  395.  
  396.    NOTE
  397.     A5 may contain incorrect value on entry.  SSLib is able to find the
  398.     correct pointer automatically.
  399.  
  400.    SEE ALSO
  401.     StartupInit, ExitError, DosError
  402.  
  403. ss.library/ExitError                     ss.library/ExitError
  404.  
  405.    NAME
  406.     ExitError -- Display error message and exit.
  407.  
  408.    SYNOPSIS
  409.     ExitError(Text, Params);
  410.           A0    A1
  411.  
  412.    FUNCTION
  413.     Display an error message using DisplayError and exit the program with
  414.     return code sv_errrc.
  415.  
  416.     It's better if the error message isn't longer than one line.
  417.  
  418.    INPUTS
  419.     Text - pointer to error message (MUSTN'T EXCEED 200 BYTES!!!)
  420.  
  421.     Params - optional pointer for parameters used for printf-style
  422.         formatting
  423.  
  424.    RESULT
  425.     Horrified user.
  426.  
  427.    NOTE
  428.     A5 may contain incorrect value on entry.  SSLib is able to find the
  429.     correct pointer automatically.
  430.  
  431.    SEE ALSO
  432.     DisplayError, ExitCleanup
  433.  
  434. ss.library/FindHashItem                   ss.library/FindHashItem
  435.  
  436.    NAME
  437.     FindHashItem -- Find item in hashed tree.
  438.  
  439.    SYNOPSIS
  440.     UserDate = FindHashItem(Tree, ItemName);
  441.     D0            A0    A0
  442.  
  443.    FUNCTION
  444.     Find an item in hashed tree.  It's able to find only one occurence of
  445.     given string.
  446.  
  447.    INPUTS
  448.     Tree - hashed tree represented by its tracker
  449.  
  450.     ItemName - text key to find
  451.  
  452.    RESULT
  453.     UserDate - Pointer to user data area of the item.  (Additional fields
  454.         reachable from this point are listed in AddHashItem doc).
  455.         NULL if not found.
  456.  
  457.    SEE ALSO
  458.     InitHashTree, AddHashItem, FreeObject
  459.  
  460. ss.library/FormatString                   ss.library/FormatString
  461.  
  462.    NAME
  463.     FormatString -- Format data according to template.
  464.  
  465.    SYNOPSIS
  466.     FormatString(Format, Data, DestBuf);
  467.              A0      A1    A2
  468.  
  469.    FUNCTION
  470.     This function performs something like sprintf() in C.  It calls
  471.     exec/RawDoFmt with simple PutC routine, which stores all characters
  472.     into supplied destination buffer.
  473.  
  474.    INPUTS
  475.     Format - pointer to format string
  476.  
  477.     Data - pointer to parameters
  478.  
  479.     DestBuf - pointer to destination buffer
  480.  
  481. ss.library/FreeAllResLists               ss.library/FreeAllResLists
  482.  
  483.    NAME
  484.     FreeAllResLists -- Free all resource lists.
  485.  
  486.    SYNOPSIS
  487.     FreeAllResLists();
  488.  
  489.  
  490.    FUNCTION
  491.     Free all tracked resources in all resource lists and discard all the
  492.     lists.    Used by ExitCleanup().
  493.  
  494.    SEE ALSO
  495.     FreeResList, ExitCleanup
  496.  
  497. ss.library/FreeObject                    ss.library/FreeObject
  498.  
  499.    NAME
  500.     FreeObject -- Free tracked object.
  501.  
  502.    SYNOPSIS
  503.     FreeObject(Tracker);
  504.            A0
  505.  
  506.    FUNCTION
  507.     Free tracked object and remove the tracker.  For master trackers,
  508.     free all slave trackers.
  509.  
  510.     All trackers, which are not freed by calling of this service, will be
  511.     freed during the ExitCleanup process.  It will be done in reverse
  512.     order of their tracking.  Trackers connected as slaves will be
  513.     handled as usually (see below).
  514.  
  515.     The freeing routines may fail.    In this case, the resource freeing
  516.     process will be started again and the tracker will be freed without
  517.     calling the routine which caused the failure.
  518.  
  519.     The freeing routine for given tracker type is called only if the
  520.     trk_data field is not 0.  But the tracker itself is freed in any
  521.     case.
  522.  
  523.     If you free a tracker, which is a slave of some other tracker, the
  524.     tracked resource is correctly freed, but the tracker node remains in
  525.     memory until the master tracker is freed.
  526.  
  527.    INPUTS
  528.     Tracker - pointer to tracked object to be freed.
  529.  
  530.    SEE ALSO
  531.     FreeResList, Track#?, FreeAllResLists, ExitCleanup
  532.  
  533. ss.library/FreeResList                       ss.library/FreeResList
  534.  
  535.    NAME
  536.     FreeResList -- Free resource list.
  537.  
  538.    SYNOPSIS
  539.     FreeResList();
  540.  
  541.  
  542.    FUNCTION
  543.     Free all tracked objects in the top-level resource list and remove
  544.     the list.  Used to free local resource lists.  The object are removed
  545.     in head-to-tail order, therefore the object list acts as a LIFO
  546.     buffer.
  547.  
  548.    SEE ALSO
  549.     CreateResList, FreeAllResLists, FreeObject, Track#?, ExitCleanup
  550.  
  551. ss.library/GetExtension                   ss.library/GetExtension
  552.  
  553.    NAME
  554.     GetExtension -- Get filename extension.
  555.  
  556.    SYNOPSIS
  557.     Extension = GetExtension(Name);
  558.     D0             A0
  559.  
  560.    FUNCTION
  561.     Get last extension of given filename.
  562.  
  563.    INPUTS
  564.     Name - file name you want to get extension of
  565.  
  566.    RESULT
  567.     Extension - Pointer to extension of the file name.  If there's no
  568.         extension, the pointer points to the trailing NULL character
  569.         of the name.
  570.  
  571.    NOTE
  572.     A0=D0 on exit.
  573.  
  574.    SEE ALSO
  575.     AddExtension, GetExtension, RemExtension
  576.  
  577. ss.library/GetResList                    ss.library/GetResList
  578.  
  579.    NAME
  580.     GetResList -- Get pointer to current resource list.
  581.  
  582.    SYNOPSIS
  583.     RList = GetResList();
  584.     D0
  585.  
  586.    FUNCTION
  587.     Get current top-level resource list.  If there is no resource list,
  588.     new one is created.
  589.  
  590.    RESULT
  591.     RList - pointer to the resl_list item of the top-level resource list.
  592.  
  593.    NOTE
  594.     A0=D0 on exit.
  595.  
  596.    SEE ALSO
  597.     CreateResList, FreeResList, Track#?
  598.  
  599. ss.library/InitHashTree                   ss.library/InitHashTree
  600.  
  601.    NAME
  602.     InitHashTree -- Initialize a hashed tree.
  603.  
  604.    SYNOPSIS
  605.     Tracker = InitHashTree(TableSize, Flags);
  606.     D0               D0      D1
  607.  
  608.    FUNCTION
  609.     Initialize a hashed tree.  The hashed tree is a simple structure
  610.     containing data items accessed using text key.    SS Library allows to
  611.     simply manage these trees with both case-dependent and
  612.     case-independent key searching.
  613.  
  614.    INPUTS
  615.     TableSize - number of entries in the hash table.  Each entry occupies
  616.         4 bytes.  Must be a power of 2 between 8 and 32768.
  617.  
  618.     Flags - htf_nocase if all the comparisons have to be performed in
  619.         case-insensitive manner.  It is significantly slower than the
  620.         default case-sensitive algorithm.
  621.  
  622.    RESULT
  623.     Tracker - hashed tree tracker.    The tree is referenced always by this
  624.         tracker.
  625.  
  626.    SEE ALSO
  627.     AddHashItem, FindHashItem, FreeObject
  628.  
  629. ss.library/LinearAlloc                       ss.library/LinearAlloc
  630.  
  631.    NAME
  632.     LinearAlloc -- Allocate word-aligned space in linear pool.
  633.  
  634.    SYNOPSIS
  635.     Mem = LinearAlloc(Pool, Size);
  636.     D0          A0    D1
  637.  
  638.    FUNCTION
  639.     Allocates memory in given linear memory pool (created by
  640.     TrackLinPool).
  641.  
  642.     If Size is less or equal to free space in current memory chunk, the
  643.     memory is taken from it.  In all other cases, new memory chunk is
  644.     created.  If Size>Quantum, the new chunk is expanded to satisfy the
  645.     request.
  646.  
  647.    INPUTS
  648.     Pool - tracker of linear memory pool to allocate the block in
  649.  
  650.     Size - requested size
  651.  
  652.    RESULT
  653.     Mem - Pointer to allocated memory block (always even) or NULL if no
  654.         memory available and err_memory disabled.
  655.  
  656.    NOTE
  657.     If you don't depend on evenness of the allocated block, use
  658.     LinearAllocN instead.
  659.  
  660.    FUNCTION
  661.     Allocation of 0 bytes is allowed.
  662.  
  663.    INPUTS
  664.     Pool - tracker of linear memory pool to allocate the block in
  665.  
  666.     Size - requested size
  667.  
  668.    RESULT
  669.     Mem - Pointer to allocated memory block (always even) or NULL if no
  670.         memory available and err_memory disabled.
  671.  
  672.    WARNING
  673.     The Size parameter is given in D1 and NOT in D0 as usually the first
  674.     non-address parameter is.
  675.  
  676.    SEE ALSO
  677.     TrackLinPool, LinearAllocN
  678.  
  679. ss.library/LinearAllocN                   ss.library/LinearAllocN
  680.  
  681.    NAME
  682.     LinearAllocN -- Allocate unaligned space in linear pool.
  683.  
  684.    SYNOPSIS
  685.     Mem = LinearAllocN(Pool, Size);
  686.     D0           A0     D1
  687.  
  688.    FUNCTION
  689.     Allocates memory in given linear memory pool (created by
  690.     TrackLinPool).    Doesn't word-align the allocation, therefore is
  691.     usually used for allocation of strings.  Slightly faster than
  692.     LinearAlloc.
  693.  
  694.     If Size is less or equal to free space in current memory chunk, the
  695.     memory is taken from it.  In all other cases, new memory chunk is
  696.     created.  If Size>Quantum, the new chunk is expanded to satisfy the
  697.     request.
  698.  
  699.     Allocation of 0 bytes is allowed.
  700.  
  701.    INPUTS
  702.     Pool - tracker of linear memory pool to allocate the block in
  703.  
  704.     Size - requested size
  705.  
  706.    RESULT
  707.     Mem - Pointer to allocated memory block (may be odd) or NULL if no
  708.         memory available and err_memory disabled.
  709.  
  710.    WARNING
  711.     The Size parameter is given in D1 and NOT in D0 as usually the first
  712.     non-address parameter is.
  713.  
  714.    SEE ALSO
  715.     TrackLinPool, LinearAlloc
  716.  
  717. ss.library/LoadFile                      ss.library/LoadFile
  718.  
  719.    NAME
  720.     LoadFile -- Load whole file to memory.
  721.  
  722.    SYNOPSIS
  723.     File, Tracker = LoadFile(FileName);
  724.     D0    D1         A0
  725.  
  726.    FUNCTION
  727.     Read file from disk to memory.    Uses TrackOpen, TrackMem and ChkRead
  728.     and reports their errors if enabled.
  729.  
  730.     This function is able to decrunch powerpacked files using powerpacker
  731.     library.  Encrypted files are not supported yet.
  732.  
  733.     Error processing mechanism depends on err_openread and err_read error
  734.     bits.
  735.  
  736.    INPUTS
  737.     FileName - pointer to name of file you want to read.
  738.  
  739.    RESULT
  740.     File - Pointer to file in memory.  The file is preceeded by one
  741.         longword containing file size in bytes and is always
  742.         null-terminated (useful mostly for text files).  Zero when
  743.         unsuccessful and the default error processing is disabled.
  744.  
  745.     Tracker (D1) - Tracker of memory area containing the file or NULL if
  746.         unsuccessful.
  747.  
  748.    BUGS
  749.     Reading from interactive filehandles is not implemented, because it
  750.     is not possible to estimate size of interactive file.  If requested,
  751.     appropriate error message is displayed.
  752.  
  753.    SEE ALSO
  754.     ChkRead, TrackOpen, TrackAlloc, FreeObject
  755.  
  756. ss.library/MergeResLists                 ss.library/MergeResLists
  757.  
  758.    NAME
  759.     MergeResLists -- Merge two resource lists to one.
  760.  
  761.    SYNOPSIS
  762.     MergeResLists();
  763.  
  764.  
  765.    FUNCTION
  766.     Merges current resource list with the previous one.  Returns without
  767.     doing any action if less than two resource lists are defined.
  768.  
  769.     Used when you want to track some objects and connect them to the main
  770.     resource list, but if some allocation fails, all the allocated
  771.     objects have to be freed without freeing of the main resource list:
  772.  
  773.         CreateResList();
  774.         -- do the allocations here --
  775.         if (Failed) FreeResList();
  776.         else MergeResLists();
  777.  
  778.     In many cases, it's better to use CallBlock which does many things
  779.     automatically.
  780.  
  781.    SEE ALSO
  782.     CreateResList, FreeResList, CallBlock
  783.  
  784. ss.library/ParseArgs                     ss.library/ParseArgs
  785.  
  786.    NAME
  787.     ParseArgs -- Parse CLI Argument String.
  788.  
  789.    SYNOPSIS
  790.     Success, Tracker = ParseArgs(Source, Template, ExtraHelp,
  791.     D0     D1             A0      A1        A2
  792.         Destination, Flags);
  793.         A3         D0
  794.  
  795.    FUNCTION
  796.     Parse arguments.  This function does something similar to
  797.     dos/ReadArgs, but there are some little enhancements:
  798.  
  799.     - Automatic processing of errors (the program is automatically halted
  800.       after error if it isn't disabled by the corresponding flag bit).
  801.  
  802.     - Ability to process non-decimal numbers in /N arguments (see
  803.       StrToL).
  804.  
  805.     - Tracking functions are used for allocation of additional memory.
  806.  
  807.     - Provides mechanism for processing of default settings of non-/A
  808.       arguments.
  809.  
  810.     - Arguments specified in default settings may be overriden or
  811.       disabled by placing the minus ("-") sign before their keywords.
  812.       For example:
  813.  
  814.         Let's have the template "NAME/K,SWITCH/S,ANOTHER/S"
  815.         Default is "NAME Something ANOTHER"
  816.         Parameters are "NAME Suspicious -ANOTHER SWITCH"
  817.         Result is: NAME="Suspicious", ANOTHER=FALSE, SWITCH=TRUE
  818.  
  819.     The typical example of using ParseArgs with defaults is:
  820.  
  821.         if (! ParseArgs(Defaults,Template,&Vars,pafm_nofail |
  822.            pafm_ignorea)) Report_Bad_Defaults;
  823.         ParseArgs(Arguments,Template,&Vars,pafm_noclear);
  824.  
  825.     !! The /A arguments aren't taken from the defaults.
  826.  
  827.    INPUTS
  828.     Source - string to be parsed.  NULL means that the string has too be
  829.         fetched from the standard buffered input (this is where the
  830.         default arguments are stored by the shell).
  831.  
  832.     Template - template describing the arguments.
  833.  
  834.     ExtraHelp - an extra help string to be displayed when the user enters
  835.         '?' the second time.
  836.  
  837.     Destination - the array you want to store the arguments to.
  838.  
  839.     Flags - some flags controlling the parsing (see below).
  840.  
  841.    RESULT
  842.     Success - boolean value indicating success (always true when the
  843.         automatic error processing is turned on).
  844.  
  845.     Tracker (D1) - object tracker of buffers associated with the result
  846.         of the parsing.
  847.  
  848.    FLAGS
  849.     pafb_nofail - disable automatic processing of errors
  850.  
  851.     pafb_noclear - don't clear the array before parsing
  852.  
  853.     pafb_ignorea - don't check presence of /A arguments
  854.  
  855.    NOTE
  856.     You can freely modify the arguments returned by this function.
  857.  
  858.    SEE ALSO
  859.     StartupInit, StrToL, dos/ReadArgs
  860.  
  861. ss.library/PoolAlloc                     ss.library/PoolAlloc
  862.  
  863.    NAME
  864.     PoolAlloc -- Allocate memory in private pool.
  865.  
  866.    SYNOPSIS
  867.     Block = PoolAlloc(Pool, Size);
  868.     D0          A0    D0
  869.  
  870.    FUNCTION
  871.     Allocates memory in given memory pool (created by TrackPool).
  872.  
  873.     If Size is less or equal to Threshold of memory pool, the block is
  874.     allocated inside some chunk.  If there is no free chunk, new one is
  875.     created.  Large memory blocks are allocated separately and linked to
  876.     the pool.
  877.  
  878.     Attempt to allocate 0 bytes of memory results in alert AN_AllocZero
  879.     and termination of your program.
  880.  
  881.    INPUTS
  882.     Pool - tracker of memory pool you want to allocate the block in
  883.  
  884.     Size - requested size
  885.  
  886.    RESULT
  887.     Block - Pointer to allocated memory block.
  888.  
  889.    SEE ALSO
  890.     TrackPool, PoolFree
  891.  
  892. ss.library/PoolFree                      ss.library/PoolFree
  893.  
  894.    NAME
  895.     PoolFree -- Free memory in private pool.
  896.  
  897.    SYNOPSIS
  898.     PoolFree(Pool, Chunk, Size);
  899.          A0    A1     D0
  900.  
  901.    FUNCTION
  902.     Frees memory allocated by PoolAlloc.
  903.  
  904.     Partial freeing is not allowed.
  905.  
  906.    INPUTS
  907.     Pool - address of memory pool the chunk lies in.
  908.  
  909.     Chunk - address of memory chunk you want to free.
  910.  
  911.     Size - size of the chunk.
  912.  
  913.    SEE ALSO
  914.     TrackPool, PoolAlloc
  915.  
  916. ss.library/Printf                        ss.library/Printf
  917.  
  918.    NAME
  919.     Printf -- Glue to dos/VPrintf.
  920.  
  921.    SYNOPSIS
  922.     Printf(Text, Params);
  923.            A0    A1
  924.  
  925.    FUNCTION
  926.     The VPrintf service in the dos library has its parameters in data
  927.     registers, which usually involves many instructions for reordering of
  928.     the arguments.    This service does this required shuffling and calls
  929.     VPrintf.
  930.  
  931.    INPUTS
  932.     Text - pointer to format string
  933.  
  934.     Params - pointer to parameter array
  935.  
  936.    SEE ALSO
  937.     Puts, PutsNL, FormatString, dos/VPrintf
  938.  
  939. ss.library/Puts                           ss.library/Puts
  940.  
  941.    NAME
  942.     Puts -- Glue to dos/FPuts.
  943.  
  944.    SYNOPSIS
  945.     Puts(Text);
  946.          A0
  947.  
  948.    FUNCTION
  949.     There exists no puts() in the dos library and FPuts() has its
  950.     parameters in data registers, which usually involves many
  951.     instructions for reordering of the arguments.  This service does this
  952.     required shuffling and calls FPuts with a filehandle of your stdout.
  953.  
  954.    INPUTS
  955.     Text - pointer to message to print out
  956.  
  957.    SEE ALSO
  958.     PutsNL, Printf, dos/FPuts
  959.  
  960. ss.library/PutsNL                        ss.library/PutsNL
  961.  
  962.    NAME
  963.     PutsNL -- Glue to dos/FPuts.
  964.  
  965.    SYNOPSIS
  966.     PutsNL(Text);
  967.            A0
  968.  
  969.    FUNCTION
  970.     There exists no puts() in the dos library and FPuts() does not emit a
  971.     newline character after the string.  This function does the same
  972.     action as Puts and puts an additional newline after the string.
  973.  
  974.    INPUTS
  975.     Text - pointer to message to print out
  976.  
  977.    SEE ALSO
  978.     Puts, Printf, dos/FPuts
  979.  
  980. ss.library/QuickSort                     ss.library/QuickSort
  981.  
  982.    NAME
  983.     QuickSort -- Quickly sort an array.
  984.  
  985.    SYNOPSIS
  986.     QuickSort(Base, NumEl, ElSize, CompFunc);
  987.           A0    D0     D1      A1
  988.  
  989.    FUNCTION
  990.     Sort array of records in ascending order.  Uses a variant of the
  991.     QuickSort algorithm with minimal stack requirements.  Stack overflow
  992.     handled and reported (err_stack).
  993.  
  994.     See qsort() in any C book.
  995.  
  996.     Uses various optimizations depending on record size.
  997.  
  998.    INPUTS
  999.     Base - address of first element of the array
  1000.  
  1001.     NumEl - number of elements (max.  65535, may be zero)
  1002.  
  1003.     ElSize - size of one element (max.  65535)
  1004.  
  1005.     CompFunc - pointer to function used for comparison of two elements.
  1006.         Called with A0=&El1, A1=&El2.  Returns -1 if El1 < El2, 1 if
  1007.         El1 > El2, 0 if El1 == El2.  May modify D1, A0 and A1.    A5
  1008.         passed without changes.
  1009.  
  1010.    SEE ALSO
  1011.     SortLongs, SortStrings, SortList, SortListName
  1012.  
  1013. ss.library/RelinkObject                   ss.library/RelinkObject
  1014.  
  1015.    NAME
  1016.     RelinkObject -- Relink object to main resource list.
  1017.  
  1018.    SYNOPSIS
  1019.     RelinkObject(Object);
  1020.              A0
  1021.  
  1022.    FUNCTION
  1023.     Relink tracked object to the first resource list.
  1024.  
  1025.     You are not allowed to relink master/slave object.  This will be
  1026.     fixed in some future version.
  1027.  
  1028.    INPUTS
  1029.     Object - object to be relinked
  1030.  
  1031.    SEE ALSO
  1032.     TrackObject, CreateResList, FreeResList, FreeObject
  1033.  
  1034. ss.library/RemExtension                   ss.library/RemExtension
  1035.  
  1036.    NAME
  1037.     RemExtension -- Remove last extension from file name.
  1038.  
  1039.    SYNOPSIS
  1040.     RemExtension(Name);
  1041.              A0
  1042.  
  1043.    FUNCTION
  1044.     Remove filename extension if there's any.
  1045.  
  1046.    INPUTS
  1047.     Name - pointer to file name to remove extension of
  1048.  
  1049.    SEE ALSO
  1050.     AddExtension, SetExtension, GetExtension
  1051.  
  1052. ss.library/ReportError                       ss.library/ReportError
  1053.  
  1054.    NAME
  1055.     ReportError -- Handle an error condition.
  1056.  
  1057.    SYNOPSIS
  1058.     ReportError(ErrorCode, Arg1, Arg2, Arg3);
  1059.             D0           A1    D2    D3
  1060.  
  1061.    FUNCTION
  1062.     If the error bit corresponding to given error code is clear, error
  1063.     message is displayed and the program is stopped via ExitError().
  1064.  
  1065.     If the error bit is set, nothing happens and ReportError() returns
  1066.     with zero in both D0 and D1.
  1067.  
  1068.    INPUTS
  1069.     ErrorCode - code of error which has happened (see ss.i)
  1070.  
  1071.     Arg1 - first argument to be substituted to error message
  1072.  
  1073.     Arg2 - second argument
  1074.  
  1075.     Arg3 - third argument
  1076.  
  1077.    SEE ALSO
  1078.     ExitError, DisplayError, DosError
  1079.  
  1080. ss.library/SetExtension                   ss.library/SetExtension
  1081.  
  1082.    NAME
  1083.     SetExtension -- Set last extension in file name.
  1084.  
  1085.    SYNOPSIS
  1086.     Success = SetExtension(Name, Buffer, Extension, BufSize);
  1087.     D0               A0    A1      A2     D0
  1088.  
  1089.    FUNCTION
  1090.     Set last extension of given file name or add it if there's no
  1091.     extension yet.
  1092.  
  1093.    INPUTS
  1094.     Name - name to set extension in
  1095.  
  1096.     Buffer - buffer to store the result to
  1097.  
  1098.     Extension - extension to be used
  1099.  
  1100.     BufSize - size of the buffer
  1101.  
  1102.    RESULT
  1103.     Success - TRUE if successful, FALSE if buffer overflow.
  1104.  
  1105.    SEE ALSO
  1106.     AddExtension, GetExtension, RemExtension
  1107.  
  1108. ss.library/SimpleRequest                 ss.library/SimpleRequest
  1109.  
  1110.    NAME
  1111.     SimpleRequest -- Simple stub for EasyRequest.
  1112.  
  1113.    SYNOPSIS
  1114.     SimpleRequest(Text, Params, Gadgets);
  1115.               A0    A1        A2
  1116.  
  1117.    FUNCTION
  1118.     Display a message using intuition/EasyRequest, but with significantly
  1119.     simpler arguments.  For additional information see EasyRequest.
  1120.  
  1121.    INPUTS
  1122.     Text - pointer to message you want to display
  1123.  
  1124.     Params - pointer to optional parameters for printf-style formatting
  1125.  
  1126.     Gadgets - pointer to string containing texts for requester gadgets
  1127.         separated by '|'
  1128.  
  1129.    RESULT
  1130.     See EasyRequest
  1131.  
  1132.    SEE ALSO
  1133.     DisplayError, intuition/EasyRequest
  1134.  
  1135. ss.library/SortList                      ss.library/SortList
  1136.  
  1137.    NAME
  1138.     SortList -- Sort linked list.
  1139.  
  1140.    SYNOPSIS
  1141.     SortList(List, Func);
  1142.          A0    A1
  1143.  
  1144.    FUNCTION
  1145.     Sort standard double-linked list using user-supplied node comparison
  1146.     function.
  1147.  
  1148.    INPUTS
  1149.     List - pointer to list header
  1150.  
  1151.     Func - pointer to function used for comparision of two list nodes.
  1152.         A0=&&Node1, A1=&&Node2.  Returns -1 if Node1 < Node2, 1 if
  1153.         Node1 > Node2 and 0 if Node1 == Node2.    A5 is passed without
  1154.         changes.
  1155.  
  1156.    WARNING
  1157.     This function allocates a block of memory and _requires_ the
  1158.     err_memory bit set.
  1159.  
  1160.    SEE ALSO
  1161.     QuickSort, SortListName
  1162.  
  1163. ss.library/SortListName                   ss.library/SortListName
  1164.  
  1165.    NAME
  1166.     SortListName -- Sort linked list by node name.
  1167.  
  1168.    SYNOPSIS
  1169.     SortListName(List);
  1170.              A0
  1171.  
  1172.    FUNCTION
  1173.     Sort standard double-linked list by LN_NAME.  (uses utility/Stricmp
  1174.     for comparison of node names)
  1175.  
  1176.    INPUTS
  1177.     List - pointer to list header
  1178.  
  1179.    WARNING
  1180.     This function allocates a block of memory and _requires_ the
  1181.     err_memory bit set.
  1182.  
  1183. ss.library/SortLongs                     ss.library/SortLongs
  1184.  
  1185.    NAME
  1186.     SortLongs -- Sort an array of unsigned longwords.
  1187.  
  1188.    SYNOPSIS
  1189.     SortLongs(Array, NumEl);
  1190.           A0     D0
  1191.  
  1192.    FUNCTION
  1193.     Sort an array of unsigned longword integers in ascending order.
  1194.  
  1195.    INPUTS
  1196.     Array - pointer to array you want to sort
  1197.  
  1198.     NumEl - number of elements
  1199.  
  1200.    SEE ALSO
  1201.     QuickSort, SortStrings
  1202.  
  1203. ss.library/SortStrings                       ss.library/SortStrings
  1204.  
  1205.    NAME
  1206.     SortStrings -- Sort an array of string pointers.
  1207.  
  1208.    SYNOPSIS
  1209.     SortStrings(Array, NumEl);
  1210.             A0       D0
  1211.  
  1212.    FUNCTION
  1213.     Sort an array of string pointers in ascending order of strings.  Uses
  1214.     utility/Stricmp to compare the strings.
  1215.  
  1216.    INPUTS
  1217.     Array - pointer to array you want to sort
  1218.  
  1219.     NumEl - number of elements
  1220.  
  1221.    SEE ALSO
  1222.     QuickSort, SortLongs
  1223.  
  1224. ss.library/StartupInit                       ss.library/StartupInit
  1225.  
  1226.    NAME
  1227.     StartupInit -- Standard startup procedure of program.
  1228.  
  1229.    SYNOPSIS
  1230.     StartupInit(StartupStruct, WbMsg);
  1231.             A0           D7
  1232.  
  1233.    FUNCTION
  1234.     Performs standard startup initialization which includes:
  1235.  
  1236.     - Checks ss.library version requested by your program.
  1237.  
  1238.     - Allocate space for system variables and your own variables.  The A5
  1239.       register points to this memory region (directly to the ssbase item)
  1240.       allowing simple determination of the library base using
  1241.           MOVE.L (A5),A6.
  1242.       The system variables are stored below A5 (as described in SS.i) and
  1243.       may grow in future releases.    Your own variables are stored above
  1244.       A5.  The amount of user's variables is stored in the StartupStruct
  1245.       (as described below).
  1246.  
  1247.     - All system variables are initialized to their proper values.
  1248.  
  1249.     - All of your own variables are initialized to zeroes.
  1250.  
  1251.     - Automatically opens some libraries (dos, intuition, gfx, gadtools,
  1252.       utility)
  1253.  
  1254.     - Program name is determined and stored to system variable.
  1255.  
  1256.     - Current task is added to the CallerList, which allows to recover
  1257.       from a soft crash (see ExitCleanup for further explaination).
  1258.  
  1259.     - All actions requested by the tags are done (see below).
  1260.  
  1261.     - The arguments are parsed in both CLI and WB modes.  If the WB has
  1262.       called us, the tool types are parsed using supplied template and
  1263.       converted to CLI arguments.  If there's a multi-selected icon, it
  1264.       will be used as the first argument (if the first argument is /M,
  1265.       all multiselected icons will be parsed).  If the program has been
  1266.       called as a default tool of some project, the project's name is
  1267.       used as the 1st argument.  If there is some icon used as the first
  1268.       argument, its tool types override the program's ones.
  1269.  
  1270.     - If the program is started from Workbench, its current directory is
  1271.       set to its home directory or to directory containing the first
  1272.       argument.
  1273.  
  1274.     - Task's exception handler is replaced by custom one.  It shows all
  1275.       address and data registers, the program counter and the status
  1276.       register (SR).  The user may suspend the program, try to abort it
  1277.       (in this case, all resources tracked by SS functions are freed) or
  1278.       reboot the machine.  [The exception code is NOT replaced if there
  1279.       is already another exception handler stored in RAM -> you can use
  1280.       breakpoints in your favourite debugger etc.] [The algorithm used
  1281.       for detection of custom exception handler might have some problems
  1282.       with future kickstarts larger than 1/2 Meg.]
  1283.  
  1284.     - Address of the ExitCleanup function is pushed onto stack allowing
  1285.       simple exit by usual RTS instruction.
  1286.  
  1287.     The tags parsed by this function are stored in a special (read:
  1288.     non-standard) format.  This format uses variable-length tagitems:
  1289.  
  1290.     a) Special SSLib trackers (codes 0000-3FFF).  These trackers have
  1291.     absolutely non-systematic arguments, therefore if SSLib encounters
  1292.     any unknown tag of this type (e.g., generated by newer version of the
  1293.     macros), it can't be simply ignored => the "Unknown Tracker" alert is
  1294.     shown and the program is terminated.  If you use these trackers, make
  1295.     sure that your "required version number" value matches all these tag
  1296.     types you're using.  This is usually done automatically by ssmac.h.
  1297.  
  1298.     b) Longword trackers.  These are utility.library compatible with one
  1299.     small exception: TAG_IGNORE, TAG_MORE and TAG_SKIP are not supported
  1300.     and they act as TAG_END.  The implementation is very simple: TAG_END
  1301.     ($00000000) is understood as a special SSLib tracker $0000 with the
  1302.     same meaning.  All other longword trackers start with $8000, which
  1303.     says that StartupInit has to fetch next word as tag ID and next
  1304.     longword as tag parameters (in case of string args, it's a pointer to
  1305.     the string).  The tag ID must be in range 8000-FFFF.
  1306.  
  1307.     c) Optional trackers (C000-FFFF).  These trackers have variable size
  1308.     of argument, but there's a simple mechanism to determine this size:
  1309.     it's encoded in bits #12 and #13 of tag ID: 00 means no parameters,
  1310.     01=one word, 10=one longword, 11=string (null-terminated and padded
  1311.     by zeroes to even length).  If one of these optional trackers is
  1312.     encountered and cannot be interpreted, it's simply skipped.
  1313.  
  1314.     d) Extended trackers (4000-7FFF).  Similar to Optional trackers, but
  1315.     can't be ignored.
  1316.  
  1317.     Many pointers in the tags are relative (marked as RelPtr).  They can
  1318.     be simply generated by the following macro:
  1319.  
  1320.     RelPtr    macro
  1321.     \@a    dc.w    \1-\@a
  1322.         endm
  1323.  
  1324.    INPUTS
  1325.     StartupStruct - pointer to startup structure (see StartupStruct in
  1326.         ss.i).    It consists of two words followed by the tags.    The
  1327.         first word contains requested size of user's variables and
  1328.         must be at least 4 (the first variable is always a pointer to
  1329.         base of ss.library).  The second one specifies which version
  1330.         of ss.library does the program require.
  1331.  
  1332.     WbMsg - pointer to WorkBench startup message (you must get it
  1333.         manually).  Can be any value when started from CLI.  Must be
  1334.         0 when started from process created by CreateProc, which is
  1335.         NOT started by the WorkBench.  This sounds very complicated -
  1336.         see the start macro in ssmac.h if you are confused.
  1337.  
  1338.    RESULT
  1339.     A5 points to the variable zone.  This value is required by all
  1340.     services of this library excluding where this doc says something
  1341.     other.    If you call SSLib with different value in A5, weird things
  1342.     can occur (and really occur).
  1343.  
  1344.    TAGS
  1345.     sst_finish - End of TagList.
  1346.  
  1347.     sst_wbconsole - Create console window if started from WB.  This
  1348.         window is used as standard input and output.
  1349.  
  1350.     sst_template (string,word) - Specifies argument template and offset
  1351.         from A5 to store the arguments on (see ParseArgs).
  1352.  
  1353.     sst_usertrk (RelPtr) - Defines user tracker types.  You pass a
  1354.         relative tointer to UserTrkTypes structure:
  1355.             DC.B  NumberOfTrackers,0
  1356.         followed by RelPtrs to freeing routines (see FreeObject).
  1357.  
  1358.     sst_extrahelp (string) - Defines extra help string for argument
  1359.         parsing.
  1360.  
  1361.     sst_exitrout (RelPtr) - Define exit routine, which will be called by
  1362.         ExitCleanup (or any error exit routine) before any cleanup is
  1363.         done.  This mechanism can be used for closing of windows and
  1364.         other similar actions.    The exit routine may call ExitCleanup
  1365.         and the error exit routines, in which case it won't be called
  1366.         again.    In case of fail during StartupInit, this routine is
  1367.         not called.
  1368.  
  1369.     sst_usererr (RelPtr) - Defines user's error routine.  This routine
  1370.         will be called by DisplayError and all error routines which
  1371.         display errors.  The routine will have the same parameters as
  1372.         DisplayError (A0=Message, A1=FormatData).  If this routine
  1373.         calls any of the error functions, it will be called again.
  1374.  
  1375.     sst_nowbstart - Exit with error message when called from WB.
  1376.  
  1377.     sst_library (string,WV,W) - Open library of specified name and
  1378.         version (WV), store its base to variable specified by its
  1379.         offset from A5 (W).  Exit with error message if can't be
  1380.         opened.
  1381.  
  1382.     sst_trylib (string,WV,W) - Try to open library (same function as
  1383.         previous tag, but if fails, the program will continue with
  1384.         base=0).
  1385.  
  1386.     sst_nowbargs - Don't parse WB arguments.
  1387.  
  1388.     sst_noprogname - Don't print program's name in error messages.
  1389.  
  1390.     sst_cputype (Min,Max) - Fail if CPU type isn't in specified range.
  1391.         0=68000...4=68040, -1=no upper limit
  1392.  
  1393.     sst_fputype (Min,-1) - Fail if FPU type isn't in specified range.
  1394.         0=none,1=68881,2=68882,3=68040
  1395.  
  1396.     sst_sysver (Min,Max) - Fail if kickstart version isn't in specified
  1397.         range.
  1398.  
  1399.     sst_errorreq - Forces using of requesters for error messages.
  1400.  
  1401.     sst_errors (BitMap.L) - Disable automatic processing of specified
  1402.         errors (see SS.i for constants (err_xxx)).
  1403.  
  1404.     sst_wbconname (string) - Use WB Console specified by name
  1405.  
  1406.     sst_envvar (string) - Try to fetch default values of parameters from
  1407.         given environment variable.  These parameters are overriden
  1408.         by values entered by the user.
  1409.  
  1410.     sst_poolsize (PoolSize.L) - Specify size of task's private memory
  1411.         pool.  This pool is used for allocation of all trackers.
  1412.         Default size = 512 bytes.  Specify higher values when using
  1413.         tracking very frequently.  This tag MUST be specified before
  1414.         all other tags.  The value must be an integer multiple of 8.
  1415.  
  1416.     sst_poolthresh (PoolThr.L) - Specify threshold of task's private
  1417.         memory pool (see TrackPool, PoolAlloc).  Default
  1418.         threshold=373.    Usage: rare.  This tag MUST be specified
  1419.         directly after sst_poolsize or at the start if there is no
  1420.         poolsize tag.
  1421.  
  1422.     sst_nostderr - Force stderr=stdout.  Don't open "*" for stderr.
  1423.  
  1424.     sst_noiconarg - don't pass names of multiselected icons as the first
  1425.         argument.  They will be simply ignored.
  1426.  
  1427.    WARNING
  1428.     All registers excluding A4 and A6 are modified by this call.
  1429.  
  1430.    BUGS
  1431.     Argument parsing could be problematic when running from several
  1432.     debuggers (for example MonAm older than 3.04), because SSLib uses
  1433.     standard V37 way to pass them using buffered standard input.  See
  1434.     also ssmac.h for some workaround.  Also stderr may be incorrect in
  1435.     this case.  But this is NOT a bug in ss.library, it is a result of
  1436.     bugs in the debuggers.
  1437.  
  1438.    SEE ALSO
  1439.     ExitCleanup, ExitError
  1440.  
  1441. ss.library/StrCat                        ss.library/StrCat
  1442.  
  1443.    NAME
  1444.     StrCat -- Concatenate two strings.
  1445.  
  1446.    SYNOPSIS
  1447.     StrCat(Destination, Source);
  1448.            A0        A1
  1449.  
  1450.    FUNCTION
  1451.     This function performs usual string concatenation.
  1452.  
  1453.    INPUTS
  1454.     Destination - destination string
  1455.  
  1456.     Source - source string
  1457.  
  1458.    RESULT
  1459.     A0 contains address of the null character at the end of the
  1460.     destination string.  It allows to concatenate multiple strings
  1461.     without reloading of the destination pointer.
  1462.  
  1463. ss.library/StrToL                        ss.library/StrToL
  1464.  
  1465.    NAME
  1466.     StrToL -- Convert string to long integer number.
  1467.  
  1468.    SYNOPSIS
  1469.     Value, Position = StrToL(String);
  1470.     D0     D1         A0
  1471.  
  1472.    FUNCTION
  1473.     Convert string containing a number in ASCII form to binary form.
  1474.  
  1475.     It supports decimal, octal (prefixed by 0) and hexadecimal (prefixed
  1476.     by 0x or $) numbers.  All spaces before the number are skipped.
  1477.  
  1478.     If there're any invalid characters, the standard error mechanism is
  1479.     used.  If the user hadn't disabled it, the error message err_number
  1480.     is displayed and the program is terminated.
  1481.  
  1482.    INPUTS
  1483.     String - string to be converted
  1484.  
  1485.    RESULT
  1486.     Value - Value of number or 0 if invalid.
  1487.  
  1488.     Position (D1) - address of first invalid character if failed or zero
  1489.         if the input string contains valid number.
  1490.  
  1491. ss.library/TestBreak                     ss.library/TestBreak
  1492.  
  1493.    NAME
  1494.     TestBreak -- Test if the user has pressed break.
  1495.  
  1496.    SYNOPSIS
  1497.     TestBreak();
  1498.  
  1499.  
  1500.    FUNCTION
  1501.     Tests the CTRL-C signal and aborts the program if detected.
  1502.  
  1503.    NOTE
  1504.     Doesn't modify contents of D0,D1,A0,A1.
  1505.  
  1506.     Library base not needed in A6.
  1507.  
  1508.    SEE ALSO
  1509.     exec/SetSignal, arp/CheckAbort, arp/CheckBreak, dos.i
  1510.  
  1511. ss.library/TestStack                     ss.library/TestStack
  1512.  
  1513.    NAME
  1514.     TestStack -- Check stack overflow.
  1515.  
  1516.    SYNOPSIS
  1517.     TestStack();
  1518.  
  1519.  
  1520.    FUNCTION
  1521.     Test stack overflow and abort the program if it occured.
  1522.  
  1523.     The lowest possible value of SP is taken from sv_stklimit, which is
  1524.     initially set (by StartupInit) to TC_SPLOWER+128.
  1525.  
  1526.    NOTE
  1527.     Doesn't modify contents of D0,D1,A0,A1.
  1528.  
  1529.     Library base not needed in A6.
  1530.  
  1531.     The stack overflow error cannot be disabled.
  1532.  
  1533.    SEE ALSO
  1534.     TestBreak, StartupInit, ReportError
  1535.  
  1536. ss.library/TrackAlloc                    ss.library/TrackAlloc
  1537.  
  1538.    NAME
  1539.     TrackAlloc -- Allocate memory and track it.
  1540.  
  1541.    SYNOPSIS
  1542.     MemBlock, Tracker = TrackAlloc(Size, Requirements);
  1543.     D0      D1               D0    D1
  1544.  
  1545.    FUNCTION
  1546.     Allocate and track memory of specified size with specified
  1547.     attributes.  If the memory is not available, exit with error message
  1548.     if its's enabled by the corresponding error bit.
  1549.  
  1550.    INPUTS
  1551.     Size - how large (in bytes) chunk of memory you want to allocate.
  1552.  
  1553.     Requirements - memory requirements (as for AllocMem)
  1554.  
  1555.    RESULT
  1556.     MemBlock - pointer to allocated memory block 0 if not enough memory
  1557.         of required type and error processing is disabled.
  1558.  
  1559.     Tracker (D1) - object tracker - trk_data contains base address of the
  1560.         block (as returned in D0), trk_ext is set to block size.
  1561.  
  1562.    SEE ALSO
  1563.     TrackAlloc, TrackAllocPub, FreeObject, exec/AllocMem
  1564.  
  1565. ss.library/TrackAlloc                    ss.library/TrackAlloc
  1566.  
  1567.    NAME
  1568.     TrackAlloc -- Allocate cleared memory and track it.
  1569.  
  1570.    SYNOPSIS
  1571.     MemBlock, Tracker = TrackAlloc(Size);
  1572.     D0      D1               D0
  1573.  
  1574.    FUNCTION
  1575.     Allocate, clear and track public memory of specified size.  If the
  1576.     memory is not available, exit with error message if its's enabled by
  1577.     the corresponding error bit.
  1578.  
  1579.     If you want to allocate large block of memory and you don't need it
  1580.     to be cleared, use TrackAllocPub(Size) instead.
  1581.  
  1582.    INPUTS
  1583.     Size - how large (in bytes) chunk of memory you want to allocate.
  1584.  
  1585.    RESULT
  1586.     MemBlock - pointer to allocated and cleared memory block or 0 if not
  1587.         enough memory and error processing is disabled.
  1588.  
  1589.     Tracker (D1) - object tracker - trk_data contains base address of the
  1590.         block (as returned in D0), trk_ext is set to block size.
  1591.  
  1592.    SEE ALSO
  1593.     TrackAllocMem, TrackAllocPub, FreeObject, exec/AllocMem
  1594.  
  1595. ss.library/TrackAllocPub                 ss.library/TrackAllocPub
  1596.  
  1597.    NAME
  1598.     TrackAllocPub -- Allocate public memory and track it.
  1599.  
  1600.    SYNOPSIS
  1601.     MemBlock, Tracker = TrackAllocPub(Size);
  1602.     D0      D1              D0
  1603.  
  1604.    FUNCTION
  1605.     { no, this doesn't allocate a free place in a pub }
  1606.  
  1607.     Allocate region of public memory.  Doesn't perform any clearing!
  1608.  
  1609.     Equivalent to TrackAllocMem(Size,MEMF_PUBLIC).
  1610.  
  1611.    INPUTS
  1612.     Size - how large (in bytes) chunk of memory you want to allocate.
  1613.  
  1614.    RESULT
  1615.     MemBlock - pointer to allocated memory block or 0 if not enough
  1616.         memory and error processing is disabled.
  1617.  
  1618.     Tracker (D1) - object tracker - trk_data contains base address of the
  1619.         block (as returned in D0), trk_ext is set to block size.
  1620.  
  1621.    SEE ALSO
  1622.     TrackAllocMem
  1623.  
  1624. ss.library/TrackDevice                       ss.library/TrackDevice
  1625.  
  1626.    NAME
  1627.     TrackDevice -- Open device and track it.
  1628.  
  1629.    SYNOPSIS
  1630.     Error, Tracker, IORQ = TrackDevice(DevName, IORQ, Unit, Flags,
  1631.     D0     D1    A1           A0        A1      D0    D1
  1632.         ErrTable);
  1633.         A2
  1634.  
  1635.    FUNCTION
  1636.     Open device and track it.  In case of difficulty, write an error
  1637.     message and abort the program if requested by corresponding error
  1638.     bit.
  1639.  
  1640.    INPUTS
  1641.     DevName - device name, case-sensitive
  1642.  
  1643.     IORQ - IORequest to use with this device (if IORQ<256,
  1644.         TrackIoRq(0,IORQ) will be called to create new IORequest,
  1645.         which will be linked by TrackSlave to device's tracker).
  1646.  
  1647.     Unit - device unit number
  1648.  
  1649.     Flags - OpenDevice flags
  1650.  
  1651.     ErrTable - optional pointer to error message table (this pointer MUST
  1652.         be specified if you want to use ChkDoIO, but it may be NULL).
  1653.         The table is a sequence of error definition blocks terminated
  1654.         by a block of 0 errors (both Min and NumErr fields are zero).
  1655.         Each block starts with two words of data: the first one
  1656.         contains number of first error message in the block, the
  1657.         second one contains number error messages.  The header is
  1658.         followed by an array of longwords pointing to names of
  1659.         errors.
  1660.  
  1661.    RESULT
  1662.     Error - Error code or 0 if successful.
  1663.  
  1664.     Tracker (D1) - object tracker.    trk_data contains pointer to
  1665.         associated IoRequest structure, trk_sizeof[0] points to the
  1666.         error table (as given in A2).
  1667.  
  1668.     IORQ (A1) - copy of trk_data (pointer to associated IORequest)
  1669.  
  1670.    SEE ALSO
  1671.     ChkDoIO, TrackIORQ, TrackPort, FreeObject, exec/OpenDevice
  1672.  
  1673. ss.library/TrackDosObject                ss.library/TrackDosObject
  1674.  
  1675.    NAME
  1676.     TrackDosObject -- Allocate a dos object and track it.
  1677.  
  1678.    SYNOPSIS
  1679.     DosObject, Tracker = TrackDosObject(Type, TagList);
  1680.     D0       D1                D0      A0
  1681.  
  1682.    FUNCTION
  1683.     Allocate dos object and track it.  Does usual error handling and
  1684.     reporting (err_memory).
  1685.  
  1686.    INPUTS
  1687.     Type - dos object type
  1688.  
  1689.     TagList - dos object tag list
  1690.  
  1691.    RESULT
  1692.     DosObject - pointer to allocated dos object or 0 if not successful.
  1693.  
  1694.     Tracker (D1) - object tracker.    trk_data points to the object,
  1695.         trk_ext contains object type.
  1696.  
  1697.    SEE ALSO
  1698.     dos/AllocDosObject, FreeObject
  1699.  
  1700. ss.library/TrackExtd                     ss.library/TrackExtd
  1701.  
  1702.    NAME
  1703.     TrackExtd -- Create an extended tracker.
  1704.  
  1705.    SYNOPSIS
  1706.     Tracker, Tracker, TrkExt = TrackExtd(Type, ExtSize);
  1707.     D0     A0      A1             D0:8  D1
  1708.  
  1709.    FUNCTION
  1710.     Create an extended tracker structure and connect it to active
  1711.     resource list (if there's no resource list, one will be created).
  1712.  
  1713.     The extended tracker is a standard resource tracker, which has some
  1714.     additional data behind trk_sizeof.  These bytes are for your own use.
  1715.  
  1716.    INPUTS
  1717.     Type - tracker type (see ss.i)
  1718.  
  1719.     ExtSize - size of tracker extension block
  1720.  
  1721.    RESULT
  1722.     Tracker - pointer to newly created object tracker
  1723.  
  1724.     Tracker (A0) - pointer to the tracker
  1725.  
  1726.     TrkExt (A1) - pointer to trk_ext field of the tracker
  1727.  
  1728.    SEE ALSO
  1729.     TrackObject, FreeObject
  1730.  
  1731. ss.library/TrackIoRq                     ss.library/TrackIoRq
  1732.  
  1733.    NAME
  1734.     TrackIoRq -- Create an IoRequest and track it.
  1735.  
  1736.    SYNOPSIS
  1737.     IORQ, Tracker = TrackIoRq(OptionalPort, Size);
  1738.     D0    D1          A0        D0
  1739.  
  1740.    FUNCTION
  1741.     Create an IO Request and track it.  This function can use
  1742.     user-supplied message port or create special message port for this
  1743.     IORQ.  In case of difficulty, writes error message and aborts the
  1744.     program if requested by corresponding error bit.
  1745.  
  1746.    INPUTS
  1747.     OptionalPort - pointer to message port to be used as a reply port for
  1748.         the IoRequest.    If NULL, new port will be created including
  1749.         new signal.
  1750.  
  1751.     Size - size of the IoRequest or 0 for size of the IoExtStd structure.
  1752.  
  1753.    RESULT
  1754.     IORQ - pointer to newly created IoRequest structure.
  1755.  
  1756.     Tracker (D1) - obejct tracker.    trk_data points to the IoRequest
  1757.  
  1758.    SEE ALSO
  1759.     TrackPort, TrackDevice, FreeObject
  1760.  
  1761. ss.library/TrackLibrary                   ss.library/TrackLibrary
  1762.  
  1763.    NAME
  1764.     TrackLibrary -- Open a library and track it.
  1765.  
  1766.    SYNOPSIS
  1767.     Library, Tracker = TrackLibrary(LibName, Version);
  1768.     D0     D1            A0     D0
  1769.  
  1770.    FUNCTION
  1771.     Open library and track it.  If the library isn't available and you
  1772.     hadn't disabled it by the error bits, an error message will be
  1773.     displayed and the program will be aborted.
  1774.  
  1775.    INPUTS
  1776.     LibName - name of library, case is significant.
  1777.  
  1778.     Version - required minimal version (0=any).
  1779.  
  1780.    RESULT
  1781.     Library - pointer to library node or 0 if unsuccessful.
  1782.  
  1783.     Tracker (D1) - object tracker.    trk_data contains pointer to base of
  1784.         the library (as returned in D0).
  1785.  
  1786.    SEE ALSO
  1787.     FreeObject, StartupInit, exec/OpenLibrary
  1788.  
  1789. ss.library/TrackLinPool                   ss.library/TrackLinPool
  1790.  
  1791.    NAME
  1792.     TrackLinPool -- Create a linear memory pool and track it.
  1793.  
  1794.    SYNOPSIS
  1795.     LinPool = TrackLinPool(Quantum, Attributes);
  1796.     D0               D0    D1
  1797.  
  1798.    FUNCTION
  1799.     Create a linear memory pool and track it.
  1800.  
  1801.     Linear pooled allocation is an extremely fast memory allocation
  1802.     strategy designed for allocating of small blocks of memory, which are
  1803.     freed together.  The pool manager allocates memory in large blocks of
  1804.     given size (Quantum).  It tries to use currently active block for
  1805.     each allocation request.  If it fails, new block is created.
  1806.  
  1807.    INPUTS
  1808.     Quantum - allocation quantum
  1809.  
  1810.     Attributes - requested memory attributes (see AllocMem)
  1811.  
  1812.    RESULT
  1813.     LinPool - Pointer to linear memory pool tracker.
  1814.  
  1815.    SEE ALSO
  1816.     FreeObject, LinearAlloc, LinearAllocN
  1817.  
  1818. ss.library/TrackLock                     ss.library/TrackLock
  1819.  
  1820.    NAME
  1821.     TrackLock -- Lock dos object and track it.
  1822.  
  1823.    SYNOPSIS
  1824.     Lock, Tracker = TrackLock(Name, LockMode);
  1825.     D0    D1          A0    D0
  1826.  
  1827.    FUNCTION
  1828.     Lock dos object and track it.  Error handling as usually.
  1829.  
  1830.    INPUTS
  1831.     Name - name of the object you want to lock.  This pointer is stored
  1832.         in the tracker to be used later for reporting of errors,
  1833.         therefore you are not allowed to modify the name before
  1834.         freeing of the tracker.
  1835.  
  1836.     LockMode - lock mode (see dos.i)
  1837.  
  1838.    RESULT
  1839.     Lock - Dos lock or 0 if failed.
  1840.  
  1841.     Tracker (D1) - object tracker.    trk_data contains the lock, trk_ext
  1842.         points to the name.
  1843.  
  1844.    SEE ALSO
  1845.     dos/Lock, FreeObject
  1846.  
  1847. ss.library/TrackObject                       ss.library/TrackObject
  1848.  
  1849.    NAME
  1850.     TrackObject -- Create a standard tracker.
  1851.  
  1852.    SYNOPSIS
  1853.     Tracker, Tracker, TrkExt = TrackObject(Type);
  1854.     D0     A0      A1               D0:8
  1855.  
  1856.    FUNCTION
  1857.     Create a standard tracker and connect it to active resource list (if
  1858.     there's no resource list, new one will be created).
  1859.  
  1860.     This function is used to track objects of your own types defined
  1861.     using the UserTrkTypes structure (tracker types in range $80 to $FF)
  1862.     or to track objects defined by ss.library extensions (not implemented
  1863.     yet).
  1864.  
  1865.     Your object freeing function will be called ONLY if the trk_data
  1866.     field contains non-null value.    This suspiciously-looking rule allows
  1867.     you to track your objects simply with respect to all possible
  1868.     failures:
  1869.  
  1870.     - call TrackObject (if there isn't enough memory to do it -> aborted)
  1871.  
  1872.     - store A1
  1873.  
  1874.     - allocate your object
  1875.  
  1876.     - restore A1
  1877.  
  1878.     - store optional data at A1 if you need
  1879.  
  1880.     - store pointer to your object to -(A1)
  1881.  
  1882.     If allocation of your object fails and you abort the program, you
  1883.     don't have to free the tracker, because it will be done automatically
  1884.     by ExitCleanup (or other exit routine, which calls ExitCleanup) and
  1885.     your object-freeing routine won't be called.  If you don't abort the
  1886.     program, you have simply to free the tracker using FreeObject and
  1887.     your object-freeing routine won't be called, too.
  1888.  
  1889.    INPUTS
  1890.     Type - tracker type (as described in ss.i)
  1891.  
  1892.    RESULT
  1893.     Tracker - pointer to newly created object tracker
  1894.  
  1895.     Tracker (A0) - pointer to the tracker
  1896.  
  1897.     TrkExt (A1) - pointer to trk_ext field of the tracker
  1898.  
  1899.    NOTE
  1900.     There are some cases in which you want to suppress freeing of already
  1901.     tracked object (for example if you write some patch utility leaving
  1902.     patch code in memory after successful exit, but freeing it in case of
  1903.     failure).  It can be solved very simply by calling Remove(Tracker) -
  1904.     the tracker will be removed cleanly.  If you use this method,
  1905.     ExitCleanup will destroy the trackers themself (they are stored in a
  1906.     memory pool which is private to each task and is freed during the
  1907.     cleanup), but the tracked objects are not affected.  Do not call
  1908.     FreeObject on disconnected objects.
  1909.  
  1910.     Another way to do such a thing is to set Tracker.trk_type to
  1911.     trt_null, but it makes using of additional FreeObject() impossible,
  1912.     because it will free only the tracker, not the tracked object.
  1913.  
  1914.     You are not allowed to manipulate the positions of objects in the
  1915.     lists.    If you really need to do such a thing, use RelinkObject().
  1916.  
  1917.    SEE ALSO
  1918.     CreateResList, FreeObject, FreeResList, GetResList, TrackRoutine,
  1919.     TrackExtd, RelinkObject
  1920.  
  1921. ss.library/TrackOpen                     ss.library/TrackOpen
  1922.  
  1923.    NAME
  1924.     TrackOpen -- Open a file and track it
  1925.  
  1926.    SYNOPSIS
  1927.     FH, Tracker = TrackOpen(Name, OpenMode);
  1928.     D0  D1            A0    D0
  1929.  
  1930.    FUNCTION
  1931.     Open a file and track it.  Does usual error checking and handling
  1932.     (see some other tracking function).
  1933.  
  1934.    INPUTS
  1935.     Name - name of the file you want to open.  This pointer is stored in
  1936.         the tracker to be used later in error reports, therefore you
  1937.         are not allowed to modify the name until you free the
  1938.         tracker.
  1939.  
  1940.     OpenMode - Open() mode - see dos/dos.i - MODE_*.  You can also use
  1941.         one of SS open modes: OPEN_OLD (a synonym to MODE_OLDFILE,
  1942.         but slightly shorter value movable by MOVEQ), OPEN_NEW
  1943.         (identical to MODE_NEWFILE) or OPEN_APPEND (uses
  1944.         MODE_READWRITE and Seek() to EOF).
  1945.  
  1946.    RESULT
  1947.     FH - File handle or 0 if failed.
  1948.  
  1949.     Tracker (D1) - object tracker.    trk_data contains file handle,
  1950.         trk_ext points to file name.
  1951.  
  1952.    SEE ALSO
  1953.     dos/Open, dos.i, FreeObject
  1954.  
  1955. ss.library/TrackPool                     ss.library/TrackPool
  1956.  
  1957.    NAME
  1958.     TrackPool -- Create private memory pool and track it.
  1959.  
  1960.    SYNOPSIS
  1961.     MemPool = TrackPool(Quantum, Threshold, Attributes);
  1962.     D0            D0         D1     D2
  1963.  
  1964.    FUNCTION
  1965.     Create a memory pool and track it.  Error checking is performed
  1966.     according to common rules (see elsewhere what does it mean).
  1967.  
  1968.     Pooled allocation is a relatively fast memory allocation strategy
  1969.     designed for manipulating small blocks of memory.  It's based on
  1970.     memory chunks, each of them has given size (Quantum).  Any memory
  1971.     block requested by PoolAlloc, which size is less or equal to
  1972.     Threshold, is allocated inside one of memory chunks.  Blocks greater
  1973.     than Threshold are allocated using standard AllocMem and linked to
  1974.     the pool.
  1975.  
  1976.     All memory blocks in the pool can be freed separately or
  1977.     simultaneously by FreeObject.
  1978.  
  1979.    INPUTS
  1980.     Quantum - allocation quantum
  1981.  
  1982.     Threshold - size of largest block allocated inside chunks
  1983.  
  1984.     Attributes - requested memory attributes (MEMF_#? - see AllocMem)
  1985.  
  1986.    RESULT
  1987.     MemPool - pointer to memory pool tracker
  1988.  
  1989.    SEE ALSO
  1990.     FreeObject, PoolAlloc, PoolFree, exec/AllocMem
  1991.  
  1992. ss.library/TrackPort                     ss.library/TrackPort
  1993.  
  1994.    NAME
  1995.     TrackPort -- Create a message port and track it.
  1996.  
  1997.    SYNOPSIS
  1998.     Port, Tracker = TrackPort();
  1999.     D0    D1
  2000.  
  2001.    FUNCTION
  2002.     Create a message port and track it.  Does usual error checking and
  2003.     handling.
  2004.  
  2005.    RESULT
  2006.     Port - pointer to newly created MsgPort structure.
  2007.  
  2008.     Tracker (D1) - object tracker.    trk_data points to the port.
  2009.  
  2010.    SEE ALSO
  2011.     exec/CreateMsgPort, FreeObject, TrackIORQ
  2012.  
  2013. ss.library/TrackRoutine                   ss.library/TrackRoutine
  2014.  
  2015.    NAME
  2016.     TrackRoutine -- Create tracker with custom freeing routine.
  2017.  
  2018.    SYNOPSIS
  2019.     Tracker = TrackRoutine(Routine, Args);
  2020.     D0               A0    A1
  2021.  
  2022.    FUNCTION
  2023.     Define a tracker, which will call your routine in time of freeing.
  2024.     The Args you supply will be passed in A0 to your routine.
  2025.  
  2026.     If args=0, no routine will be called.  For the reason of this
  2027.     suspicious action, see TrackObject (there are applied the same
  2028.     rules).
  2029.  
  2030.    INPUTS
  2031.     Routine - pointer to routine You wish to call.    The routine should
  2032.         leave intact all registers except D0-D1/A0-A1/A6.
  2033.  
  2034.     Args - user data passed to the routine in time of resource freeing.
  2035.  
  2036.    RESULT
  2037.     Tracker - tracker of expected type.
  2038.  
  2039.     A1 points to Args and can be used in similar way as in TrackObject,
  2040.     but you should use (A1) instead of -(A1).
  2041.  
  2042.    SEE ALSO
  2043.     TrackObject, FreeObject
  2044.  
  2045. ss.library/TrackSignal                       ss.library/TrackSignal
  2046.  
  2047.    NAME
  2048.     TrackSignal -- Allocate signal and track it.
  2049.  
  2050.    SYNOPSIS
  2051.     Signal, Tracker = TrackSignal();
  2052.     D0    D1
  2053.  
  2054.    FUNCTION
  2055.     Allocate a signal and track it.  Does usual error checking and
  2056.     handling.
  2057.  
  2058.    RESULT
  2059.     Signal - Number of signal or -1 if there are no free signals.
  2060.  
  2061.     Tracker (D1) - object tracker.    trk_data contains number of signal.
  2062.  
  2063.    SEE ALSO
  2064.     exec/AllocSignal, FreeObject
  2065.  
  2066. ss.library/TrackSlave                    ss.library/TrackSlave
  2067.  
  2068.    NAME
  2069.     TrackSlave -- Join two trackers.
  2070.  
  2071.    SYNOPSIS
  2072.     TrackSlave(Master, Slave);
  2073.            A0       A1
  2074.  
  2075.    FUNCTION
  2076.     Connect Slave to a list of Master's slaves and re-connect the Master
  2077.     to the front of current resource list, therefore it will be freed
  2078.     before the slaves.
  2079.  
  2080.     The linkage mechanism uses the Tracker.trk_ext field as pointer to
  2081.     the first slave.  It causes that standard trackers (excluding
  2082.     trt_null) cannot be used as masters.  The routine tracker (obtained
  2083.     via TrackRoutine) can be used, but its entry data (passed in A0 to
  2084.     user's resource freeing routine) will be overwritten (but it won't be
  2085.     0 in any case -> the routine is called everytime).
  2086.  
  2087.     The slaves are freed in LIFO order (the last slave will be freed as
  2088.     the first one).
  2089.  
  2090.    INPUTS
  2091.     Master - tracker to be used as the master
  2092.  
  2093.     Slave - tracker to be used as the slave
  2094.  
  2095.    SEE ALSO
  2096.     TrackObject, FreeObject
  2097.  
  2098.