home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / System / Sysmon / autodocs / sysmon_lib.doc
Text File  |  2000-08-01  |  32KB  |  1,010 lines
  1. TABLE OF CONTENTS
  2.  
  3. sysmon.library/smAddBroadcastPort
  4. sysmon.library/smAllowExcept
  5. sysmon.library/smDisallowExcept
  6. sysmon.library/smEndExcept
  7. sysmon.library/smFindNode
  8. sysmon.library/smFindTaskInfo
  9. sysmon.library/smFreeze
  10. sysmon.library/smGetTaskInfo
  11. sysmon.library/smGetVBR
  12. sysmon.library/smHalt
  13. sysmon.library/smHibernate
  14. sysmon.library/smLockTaskTable
  15. sysmon.library/smNextTaskInfo
  16. sysmon.library/smRemBroadcastPort
  17. sysmon.library/smScheduleWakeUp
  18. sysmon.library/smSendBroadcastMsg
  19. sysmon.library/smSleep
  20. sysmon.library/smUnFreeze
  21. sysmon.library/smUnLockTaskTable
  22. sysmon.library/smVKPrintf
  23. sysmon.library/smVSnPrintf
  24. sysmon.library/smVSPrintf
  25. sysmon.library/smVSysLog
  26. sysmon.library/smWaitAnd
  27. sysmon.library/smWakeUp
  28. sysmon.library/smAddBroadcastPort           sysmon.library/smAddBroadcastPort
  29.  
  30.    NAME    
  31.      smAddBroadcastPort -- Add a Port to receive Broadcast Messages (V1)
  32.  
  33.    SYNOPSIS
  34.     smAddBroadcastPort( port )
  35.                         A1
  36.  
  37.     void smAddBroadcastPort(struct MsgPort *port);
  38.  
  39.    FUNCTION
  40.     This function registers a message port for reception of broadcast
  41.     messages send via smSendBroadcastMsg().
  42.     The Message port must be initialized and the ln_Pri and ln_Name fields
  43.     should be filled with appropriate values.
  44.  
  45.    INPUTS
  46.     port - A pointer to a properly initialized message port structure.
  47.  
  48.    RESULT
  49.     none.
  50.  
  51.    NOTES
  52.     The Broadcast Messages are sent in turn to each client, so your
  53.     application must be ready to process them quickly. If you are
  54.     unable to retrieve the message in the time specified in the
  55.     bcm_TimeOut field, the smSendBroadcastMsg() function will remove it
  56.     transparently from your port and pass it to the next one (be prepared
  57.     for an empty port when you receive a signal !).
  58.     When you have retrieved the message, you MUST reply it as quickly
  59.     as possible (make a copy if necessary). In particular, NEVER EVER
  60.     wait for user interaction when holding the message. This is parti-
  61.     cularly true for a BCM_SHUTDOWN message with the BCMB_DOOMSDAY bit set
  62.     in the bcm_Flags field as the shutdown procedure must be able to
  63.     complete in the 10 seconds time allowed by the keyboard.device
  64.     When you receive a BCM_SHUTDOWN message with a zero bcm_CountDown, you
  65.     should smRemBroadcastPort() your port and exit.
  66.  
  67.    BUGS
  68.  
  69.    SEE ALSO
  70.     sysmon.library/smRemBroadcastPort(), 
  71.     sysmon.library/smSendBroadcastMsg()
  72.  
  73. sysmon.library/smAllowExcept                     sysmon.library/smAllowExcept
  74.  
  75.    NAME    
  76.      smAllowExcept -- Restore exception processing. (V1)
  77.  
  78.    SYNOPSIS
  79.     smAllowExcept()
  80.  
  81.     void smAllowExcept( void );
  82.  
  83.    FUNCTION
  84.     Allow signal exceptions to be delivered to the task after they have
  85.     been disabled by smDisallowExcept().
  86.     If an exception signal has been received while exceptions were
  87.     disabled, the exception will be delivered now. You must execute
  88.     exactly one call to smAllowExcept() for each call to
  89.     smDisallowExcept().
  90.  
  91.    NOTES
  92.     This call is guaranteed to preserve all registers.
  93.  
  94.    BUGS
  95.  
  96.    SEE ALSO
  97.     sysmon.library/smDisallowExcept(), exec.library/Permit(),
  98.     exec.library/SetExcept().
  99. sysmon.library/smDisallowExcept               sysmon.library/smDisallowExcept
  100.  
  101.    NAME    
  102.      smDisallowExcept -- Prevents exception processing. (V1)
  103.  
  104.    SYNOPSIS
  105.     smDisallowExcept()
  106.  
  107.     void smDisallowExcept( void );
  108.  
  109.    FUNCTION
  110.     Prevents signal exceptions from being delivered to the task until a
  111.     matching call to smAllowExcept() is made. An Exception received while
  112.     disallowed will be delivered when allowed again.
  113.     Task switches, interrupts and processor exceptions are not concerned.
  114.     This call is used to protect access to resources that are shared with
  115.     the exception code.
  116.     Calls to smDisallowExcept() nest. You must execute exactly one call to
  117.     smAllowExcept() for each call to smDisallowExcept().
  118.  
  119.    WARNINGS
  120.     You can't arbitrate resources shared with exception code via
  121.     semaphore locking. You have to use this function (recommended),
  122.     Forbid() (which also prevents exception delivery) or SetExcept()
  123.     (turns off the exception signals manually).
  124.     The original exception mechanism in exec is quite broken, so it is
  125.     better to not use signal exceptions at all unless sysmon.library V1+
  126.     is installed.
  127.  
  128.    NOTES
  129.     This call is guaranteed to preserve all registers.
  130.  
  131.    BUGS
  132.  
  133.    SEE ALSO
  134.     sysmon.library/smAllowExcept(), exec.library/Forbid(),
  135.     exec.library/SetExcept(), exec.library/ObtainSemaphore().
  136. sysmon.library/smEndExcept                         sysmon.library/smEndExcept
  137.  
  138.    NAME    
  139.      smEndExcept -- End exception routine without returning to normal task
  140.     code. (V1)
  141.  
  142.    SYNOPSIS
  143.     smEndExcept( cleanup )
  144.              D0
  145.  
  146.     void smEndExcept( BOOL cleanup );
  147.  
  148.    FUNCTION
  149.     This function allows to continue execution of the task exception code
  150.     as if it was normal code, allowing to terminate cleanly by calling the
  151.     compiler's exit() function.
  152.     It calls smDisallowExcept() to avoid entering the exception code
  153.     recursively, so before exiting, you must call smAllowExcept() after
  154.     deactivating the exception signals and restoring the initial
  155.     exception code.
  156.     
  157.     
  158.    INPUTS
  159.      cleanup - a boolean flag that, if set, will clean the user stack of
  160.           what was saved there by the exception processing code. This
  161.           must only be used from the main exception code, not from a
  162.           subroutine.
  163.     
  164.    NOTES
  165.     This function is mainly intended to prepare for exit inside exception
  166.     code. If you want to continue running as normal code, you can call
  167.     this function with the cleanup flag set from main exception code, but
  168.     this is not recommended.
  169.     If this function is not called from exception code, it will not do
  170.     anything.
  171.  
  172.    BUGS
  173.  
  174.    SEE ALSO
  175.     ANSI-C exit(), dos.library/Exit(), sysmon.library/smDisallowExcept()
  176.  
  177. sysmon.library/smFindNode                           sysmon.library/smFindNode
  178.  
  179.    NAME    
  180.      smFindNode -- Check if a Node is part of a List. (V1)
  181.  
  182.    SYNOPSIS
  183.     node = smFindNode( list, node )
  184.     D0                 A0    A1
  185.  
  186.     struct Node *smFindNode(struct List *list, struct Node *node);
  187.  
  188.    FUNCTION
  189.     Check if a Node is linked in a List.
  190.  
  191.    INPUTS
  192.      list  - A pointer to a List structure
  193.     node  - A pointer to the node you want to check for beeing part of
  194.         the list
  195.     
  196.    RESULT
  197.      node  - If the node is linked in the List, its address is returned
  198.             else the function returns NULL.
  199.  
  200.    NOTES
  201.     No arbitration is done for access to the list!    If multiple tasks
  202.     access the same list, an arbitration mechanism such as
  203.     SignalSemaphores must be used.
  204.  
  205.    BUGS
  206.  
  207.    SEE ALSO
  208.     exec.library/FindName()
  209.  
  210. sysmon.library/smFindTaskInfo                   sysmon.library/smFindTaskInfo
  211.  
  212.    NAME    
  213.      smFindTaskInfo -- Find TaskInfo structure by Task Name. (V0)
  214.  
  215.    SYNOPSIS
  216.     tinfo = smFindTaskInfo( name )
  217.     D0                      A1
  218.  
  219.     struct TaskInfo *smFindTaskInfo( STRPTR name );
  220.  
  221.    FUNCTION
  222.     This function will search the TaskInfo Hash Table for a task with the
  223.     given name, and return a pointer to its TaskInfo structure. If a NULL
  224.     name pointer is given, a pointer to the TaskInfo of the current task
  225.     will be returned.
  226.  
  227.    INPUTS
  228.      name  - pointer to a NULL terminated string.
  229.     
  230.    RESULT
  231.      tinfo - A pointer to the corresponding TaskInfo structure or NULL
  232.             for an error (TaskInfo structure not found).
  233.  
  234.    NOTES
  235.     Unlike the original exec.library/FindTask() function, this call does
  236.     not need to Disable() interrupts during search. It will call the
  237.     smLockTaskTable() function with read access under V1 or higher (under
  238.     V0, it used Forbid()).
  239.     exec.library/FindTask() is now rerouted through this function for
  240.     efficiency when sysmon.library is active.
  241.     Unnamed tasks (NULL ln_Name) can't be found by this function, but at
  242.     least, then won't cause Enforcer/muForce hits during search (V1).
  243.  
  244.    BUGS
  245.  
  246.    SEE ALSO
  247.     exec.library/FindTask(), sysmon.library/smGetTaskInfo(),
  248.     sysmon.library/smNextTaskInfo(), sysmon.library/smLockTaskTable(),
  249.     sysmon.library/smUnLockTaskTable().
  250. sysmon.library/smFreeze                               sysmon.library/smFreeze
  251.  
  252.    NAME    
  253.      smFreeze -- Put a task out of schedule. (V0)
  254.  
  255.    SYNOPSIS
  256.     success = smFreeze( task )
  257.     D0                  A1
  258.  
  259.     BOOL smFreeze( struct Task *task );
  260.  
  261.    FUNCTION
  262.     Put a task into the TaskFrozen list. The task will no longer be
  263.     dispatched and exception signals will not be processed.
  264.     However, received signals are not lost; they will be processed
  265.     when the task comes out of the frozen state.
  266.  
  267.    INPUTS
  268.      task  - A pointer to a Task structure. If NULL, the current task
  269.         will be frozen.
  270.         Passing an invalid task pointer will result in an alert.
  271.     
  272.    RESULT
  273.      success - A boolean value indicating the success of the operation.
  274.               This call will fail if the Task is in a state that does
  275.           not allow it to be frozen (including the case when it is
  276.           already frozen).
  277.  
  278.    NOTES
  279.     This call is potentially dangerous. Freezing another task may lead
  280.     to deadlocks if the task was performing critical operations under
  281.     semaphore protection when it was frozen. So do not freeze another
  282.     task without good reasons.
  283.     When freezing yourself, make sure someone will bring you back to
  284.     life by calling smUnFreeze() on you.
  285.  
  286.    BUGS
  287.  
  288.    SEE ALSO
  289.     sysmon.library/smUnFreeze() , sysmon.library/smHibernate() ,
  290.     exec.library/Wait()
  291.  
  292. sysmon.library/smGetTaskInfo                     sysmon.library/smGetTaskInfo
  293.  
  294.    NAME    
  295.      smGetTaskInfo -- Get pointer to TaskInfo structure. (V0)
  296.  
  297.    SYNOPSIS
  298.     tinfo = smGetTaskInfo( task )
  299.     D0                     A0
  300.  
  301.     struct TaskInfo *smGetTaskInfo( struct Task *task );
  302.  
  303.    FUNCTION
  304.     Get a pointer to the TaskInfo structure associated to a given
  305.     Task.
  306.  
  307.    INPUTS
  308.      task  - A pointer to a Task structure. If NULL, the TaskInfo
  309.         structure of the current task will be returned.
  310.     
  311.    RESULT
  312.      tinfo - A pointer to the corresponding TaskInfo structure or NULL
  313.             for an error (TaskInfo structure not found).
  314.  
  315.    NOTES
  316.  
  317.    BUGS
  318.  
  319.    SEE ALSO
  320.     sysmon.library/smFindTaskInfo(), sysmon.library/smNextTaskInfo().
  321.  
  322. sysmon.library/smGetVBR                               sysmon.library/smGetVBR
  323.  
  324.    NAME    
  325.      smGetVBR -- Get the value of the 680x0 VBR. (V1)
  326.  
  327.    SYNOPSIS
  328.     base = smGetVBR()
  329.     D0
  330.  
  331.     APTR smGetVBR(void);
  332.  
  333.    FUNCTION
  334.     Retrieves the value of the 68010+ vector base register in D0.
  335.     On a 68000 system, the hard coded value of $0 is returned.
  336.  
  337.    INPUTS
  338.     none
  339.     
  340.    RESULT
  341.      base  - The base address of the 680x0 exception and interrupt vector
  342.         table.
  343.  
  344.    NOTES
  345.  
  346.    BUGS
  347.  
  348.    SEE ALSO
  349.  
  350. sysmon.library/smHalt                                   sysmon.library/smHalt
  351.  
  352.    NAME    
  353.      smHalt -- Halts the system for safe power down. (V0)
  354.  
  355.    SYNOPSIS
  356.     smHalt( flags )
  357.         D0
  358.  
  359.     void smHalt( ULONG flags );
  360.  
  361.    FUNCTION
  362.     This function will disable multitasking, blink the power LED, freeze 
  363.     all tasks except the caller, then display a guru like deadend alert
  364.     saying 'System Shutdown Complete' (without time out).
  365.     It is then safe to turn the power off.
  366.     If the user presses a mouse button to cancel the alert, the system
  367.     will be reset, generally via exec.library/ColdReboot().
  368.     If the DEL key (ASCII $7f) is pressed on a serial port terminal while
  369.     the power LED is blinking, control will be transfered to the ROM
  370.     debugger (ROM-Wack for V37, SAD for V39+)
  371.     If a keyboard reset is pending, the keyboard.device will be notified
  372.     that reset proceeding may continue and the caller task will be frozen,
  373.     awaiting doom. (V1 or higher)
  374.     In any case, this function never returns.
  375.  
  376.    INPUT
  377.      flags  - A bit pattern specifying options. Currently defined are :
  378.          HALTB_REBOOT : The alert is not displayed, causing the system
  379.          to reboot immediately.
  380.          HALTB_REKICK : Forces MMU-SoftKicked machines to reload
  381.          KickStart by disabling the MMU before rebooting (requires
  382.          mmu.library). The reset capture vectors and kicktags are
  383.          also cleared, wiping out reset resident modules (V1).
  384.     
  385.    WARNING
  386.     This function does not care about filesystem consistency or whatever
  387.     other tasks are doing when it is called. It is the responsability of
  388.     the caller to take appropriate precautions before calling this
  389.     function.
  390.  
  391.    BUGS
  392.     In V0, this function used RemTask() to stop the other tasks. This
  393.     could cause problems with still active interrupt routines.
  394.     The SBRSTB_OLDMMU flag (activated by the OLDMMURESET config option)
  395.     requires that the KBD_RESETHANDLERDONE keyboard command is sent
  396.     from supervisor mode under the boot MMU configuration (mmu.library
  397.     V42+ is required). This may not work under all configurations and
  398.     thus should only be used on systems that require it from proper
  399.     reset operation.
  400.     The exact way to perform a reset depends on the SBRSTB_CACHEREBOOT
  401.     and SBRSTB_OLDMMU reset flags. If SBRSTB_CACHEREBOOT is set, a cached
  402.     copy of the exec ColdReboot() function is used instead of the current
  403.     routine in the library vector, so as to avoid creative patches that
  404.     try to defer the reset. If SBRSTB_OLDMMU is set and the mmu.library
  405.     V42+ is available, a special reboot code is called with the MMU reset
  406.     to its boot configuration (mmu.library/RunOldConfig()) to avoid
  407.     reloading the kickstart on soft booting A3000s, unless HALTB_REKICK
  408.     was specified.
  409.  
  410.    SEE ALSO
  411.     exec.library/ColdReboot(), exec.library/Alert(),
  412.     mmu.library/RunOldConfig().
  413. sysmon.library/smHibernate                         sysmon.library/smHibernate
  414.  
  415.    NAME    
  416.      smHibernate -- Put the current task into hibernation. (V1)
  417.  
  418.    SYNOPSIS
  419.     smHibernate()
  420.  
  421.     void smHibernate( void );
  422.  
  423.    FUNCTION
  424.     Put the current task into the TaskWait list. The task will no longer
  425.     be dispatched but exception signals will still be processed. When an
  426.     exception arrives, the task will be temporarily scheduled and will
  427.     return to hibernation on return from the exception routine.
  428.     The task will return from hibernation when a smWakeUp() call is
  429.     executed on it.
  430.     If the task already has a wake up request pending when calling 
  431.     smHibernate(), it will return immediately without going to sleep.
  432.  
  433.    INPUTS
  434.     none - Hibernation is a voluntary wait state.
  435.     
  436.    NOTES
  437.     If you want to also block exceptions, either smDisallowExcept() before
  438.     calling smHibernate() or call smFreeze(NULL).
  439.  
  440.    BUGS
  441.  
  442.    SEE ALSO
  443.     sysmon.library/smFreeze() , sysmon.library/smWakeUp() ,
  444.     exec.library/Wait(), sysmon.library/smScheduleWakeUp()
  445.  
  446. sysmon.library/smLockTaskTable                 sysmon.library/smLockTaskTable
  447.  
  448.    NAME    
  449.      smLockTaskTable -- Lock TaskInfo Table for access. (V1)
  450.  
  451.    SYNOPSIS
  452.     smLockTaskTable( flags )
  453.                      D0
  454.  
  455.     void smLockTaskTable( ULONG flags );
  456.  
  457.    FUNCTION
  458.     This function will lock the TaskInfo table for access via semaphore
  459.     arbitration.
  460.  
  461.    INPUTS
  462.      flags  - a bit pattern specifying the type of access.
  463.         LTTB_READ for read access to the table (to scan the table via
  464.         smNextTaskInfo() for example). This lock can be shared.
  465.         LTTB_WRITE is for write access (task creation and removal) and
  466.         is *PRIVATE* to the sysmon.library
  467.         LTTB_REMOVE will prevent task removal to occur while the lock
  468.         is held. This allows system monitors to catch short life
  469.         tasks CPU usage.
  470.     
  471.    NOTES
  472.     Don't call any OS function that may spawn a new task or stop an
  473.     existing one (like dos.library I/O for example) while holding a
  474.     TaskInfo table lock.
  475.  
  476.    BUGS
  477.  
  478.    SEE ALSO
  479.     sysmon.library/smUnLockTaskTable(), sysmon.library/smFindTaskInfo(),
  480.     sysmon.library/smNextTaskInfo()
  481. sysmon.library/smNextTaskInfo                   sysmon.library/smNextTaskInfo
  482.  
  483.    NAME    
  484.      smNextTaskInfo -- Get the next TaskInfo entry. (V0)
  485.  
  486.    SYNOPSIS
  487.     newtinfo = smNextTaskInfo( tinfo )
  488.     D0                         A1
  489.  
  490.     struct TaskInfo *smNextTaskInfo( struct TaskInfo *tinfo );
  491.  
  492.    FUNCTION
  493.     This function returns the next TaskInfo structure in the Hash Table,
  494.     or NULL if there is no next entry.
  495.  
  496.    INPUT
  497.      tinfo  - Pointer to the current TaskInfo structure. If NULL, the
  498.          first TaskInfo structure will be returned.
  499.     
  500.    RESULT
  501.      newtinfo - A pointer to the next TaskInfo in the table, or NULL if
  502.            the end has been reached.
  503.  
  504.    WARNING
  505.     This function does not arbitrate for access to the TaskInfo HashTable.
  506.     You must call smLockTaskTable(LTTF_READ) before scanning with this
  507.     function (Use Forbid() for sysmon.library V0).
  508.  
  509.    BUGS
  510.  
  511.    SEE ALSO
  512.     exec.library/FindTask(), sysmon.library/smGetTaskInfo(),
  513.     sysmon.library/smFindTaskInfo(), sysmon.library/smLockTaskTable(),
  514.     sysmon.library/smUnLockTaskTable().
  515. sysmon.library/smRemBroadcastPort           sysmon.library/smRemBroadcastPort
  516.  
  517.    NAME    
  518.      smRemBroadcastPort -- Remove a BroadcastPort from the list (V1)
  519.  
  520.    SYNOPSIS
  521.     smRemBroadcastPort( port )
  522.                         A1
  523.  
  524.     void smRemBroadcastPort(struct MsgPort *port);
  525.  
  526.    FUNCTION
  527.     This function removes a port that was previously enabled for reception
  528.     of system broadcast messages. No resource deallocation is done, the
  529.     port is just removed from the broadcast list.
  530.     You should call this function when you received a BCM_SHUTDOWN message
  531.     with a zero value in the bcm_CountDown field, and your application
  532.     should then exit (reply the message first, of course !)
  533.  
  534.    INPUTS
  535.     port -  A pointer to a message port previously registered via
  536.         smAddBroadcastPort().
  537.  
  538.    RESULT
  539.     none.
  540.  
  541.    NOTES
  542.     Never call this function while holding a broadcast message or a 
  543.     deadlock will occur.
  544.  
  545.    BUGS
  546.  
  547.    SEE ALSO
  548.     sysmon.library/smAddBroadcastPort(), 
  549.     sysmon.library/smSendBroadcastMsg()
  550.  
  551. sysmon.library/smScheduleWakeUp               sysmon.library/smScheduleWakeUp
  552.  
  553.    NAME    
  554.      smScheduleWakeUp -- Ask for a WakeUp call after a certain time. (V1)
  555.  
  556.    SYNOPSIS
  557.     smScheduleWakeUp( timereq )
  558.                       A1
  559.  
  560.     void smScheduleWakeUp( struct timerequest *timereq );
  561.  
  562.    FUNCTION
  563.     This function sends a request to the timer.device to wake up the
  564.     task after a specified time.
  565.  
  566.    INPUTS
  567.      timereq  - An initialized timerequest structure. You must open the
  568.            timer.device with the desired unit and fill in the fields
  569.            for the desired time delay before calling this function.
  570.     
  571.    NOTES
  572.     This function is totally asynchronous. You must call smHibernate()
  573.     yourself if you want to go to sleep. The smSleep() function
  574.     provides a complete synchronous call using the VBLANK timer.
  575.     As this function does not need a signal bit, you should allocate
  576.     and initialize the message port for the device yourself using
  577.     AllocVec() and NewList(). This function will set up the port to
  578.     call smWakeUp() on message arrival by itself. A public message
  579.     port cannot be used.
  580.  
  581.    BUGS
  582.     The mechanism used to call a subroutine on message arrival at a port
  583.     (mp_Flags = 3) is not officially documented. However, I don't expect
  584.     exec internals to change in the near future ;-)
  585.  
  586.    SEE ALSO
  587.     timer.library/TR_ADDREQUEST, sysmon.library/smWakeUp(),
  588.     sysmon.library/smSleep(), exec.library/AllocVec(), amiga.lib/NewList()
  589.  
  590. sysmon.library/smSendBroadcastMsg           sysmon.library/smSendBroadcastMsg
  591.  
  592.    NAME    
  593.      smSendBroadcastMsg -- Send a Broadcast Message to registered ports (V1)
  594.  
  595.    SYNOPSIS
  596.     smSendBroadcastMsg( bcmsg )
  597.                         A1
  598.  
  599.     LONG smSendBroadcastMsg(struct BroadcastMsg *bcmsg);
  600.  
  601.    FUNCTION
  602.     This function sends a properly initialized broadcast message to all
  603.     registered clients in turn.
  604.  
  605.    INPUTS
  606.     bcmsg - A pointer to a properly initialized struct BroadcastMsg
  607.         bcm_Level indicates the severity of the reported event :
  608.         BCM_DEBUG is a debug message that can generally be ignored.
  609.         BCM_NORMAL is for general messages.
  610.         BCM_URGENT is for urgent conditions.
  611.         BCM_SHUTDOWN signals an incoming system shutdown. When
  612.         bcm_CountDown is zero, the shutdown is imminent.
  613.         BCM_UNMOUNT signals clients that have not exited yet that
  614.         filesystem access is no longer possible.
  615.         BCM_HALT is the last gasp before system halt/reboot. Power
  616.         supply monitors could use this to turn the power off.
  617.         bcm_Flags contains additional flags. Currently defined are :
  618.         BCMF_DOOMSDAY : a keyboard reset is pending. The system
  619.         will reset in at most 10 seconds. This flag will be set
  620.         automatically.
  621.         BCMF_CANCEL : a previously announced event has been cancelled.
  622.         bcm_TimeOut is the time out value in 1/50th second ticks. If a
  623.         client does not retrieve the message from its port in this
  624.         time period, it will be removed from the port, bcm_TimeOutCount
  625.         will be incremented and the message will be passed to the next
  626.         client. If a keyboard reset is pending, the timeout value will
  627.         be maxed at 5 ticks (1/10th second).
  628.         bcm_CountDown is a countdown in seconds for the announced event.
  629.         a zero value indicates an imminent event.
  630.         bcm_ReplyCount and bcm_TimeOutCount are return values and must be
  631.         set to zero.
  632.         bcm_SenderTask is the address of the calling task and is filled
  633.         by this function.
  634.         bcm_EventTxt is a descriptive ASCII text for the announced event.
  635.         bcm_Reserved are reserved fields that must be set to zero.
  636.  
  637.    RESULT
  638.     The value of the bcm_ReplyCount is returned in D0. A negative value
  639.     indicates an error condition.
  640.  
  641.    NOTES
  642.     The Broadcast Messages are sent in turn to each client, so your
  643.     application must be ready to process them quickly. If you are
  644.     unable to retrieve the message in the time specified in the
  645.     bcm_TimeOut field, the smSendBroadcastMsg() function will remove it
  646.     transparently from your port and pass it to the next one (be prepared
  647.     for an empty port when you receive a signal !).
  648.     When you have retrieved the message, you MUST reply it as quickly
  649.     as possible (make a copy if necessary). In particular, NEVER EVER
  650.     wait for user interaction when holding the message. This is parti-
  651.     cularly true for a BCM_SHUTDOWN message with the BCMB_DOOMSDAY bit set
  652.     in the bcm_Flags field as the shutdown procedure must be able to
  653.     complete in the 10 seconds time allowed by the keyboard.device
  654.     When you receive a BCM_SHUTDOWN message with a zero bcm_CountDown, you
  655.     should smRemBroadcastPort() your port and exit.
  656.  
  657.    BUGS
  658.  
  659.    SEE ALSO
  660.     sysmon.library/smAddBroadcastPort(), 
  661.     sysmon.library/smRemBroadcastPort()
  662.  
  663. sysmon.library/smSleep                                 sysmon.library/smSleep
  664.  
  665.    NAME    
  666.      smSleep -- Put a task into hibernation for a specified time. (V0)
  667.  
  668.    SYNOPSIS
  669.     success = smSleep( ticks )
  670.     D0                 D0
  671.  
  672.     BOOL smSleep( ULONG ticks );
  673.  
  674.    FUNCTION
  675.     This function makes the current task hibernate for the specified
  676.     period of time.
  677.  
  678.    INPUTS
  679.      ticks  - The number of ticks (50 per second) the task will sleep.
  680.          If ZERO, the function will return immediately.
  681.     
  682.    RESULT
  683.      success - A boolean value indicating the success of the operation.
  684.               It may fail in very low memory conditions, in that case
  685.           the function returns immediately.
  686.  
  687.    NOTES
  688.     This function uses the VBLANK unit of the timer.device with the
  689.     smScheduleWakeUp() and smHibernate() functions in V1.
  690.     In V0, smFreeze() was used.
  691.  
  692.    BUGS
  693.  
  694.    SEE ALSO
  695.     dos.library/Delay(), sysmon.library/smScheduleWakeUp(),
  696.     sysmon.library/smHibernate(), sysmon.library/smFreeze()
  697.  
  698. sysmon.library/smUnFreeze                           sysmon.library/smUnFreeze
  699.  
  700.    NAME    
  701.      smUnFreeze -- Put a frozen task back to life. (V0)
  702.  
  703.    SYNOPSIS
  704.     success = smUnFreeze( task )
  705.     D0                    A1
  706.  
  707.     BOOL smUnFreeze( struct Task *task );
  708.  
  709.    FUNCTION
  710.     Put a frozen task back into its previous state. If the task was
  711.     previously waiting or hibernating and signals or wakeup requests
  712.     have arrived, they will be precessed now.
  713.     
  714.    INPUTS
  715.      task  - A pointer to a Task structure. An invalid task pointer will
  716.         result in an alert.
  717.     
  718.    RESULT
  719.      success - A boolean value indicating the success of the operation.
  720.               This call will fail if the Task was not frozen.
  721.  
  722.    NOTES
  723.     This function may be called from interrupts.
  724.  
  725.    BUGS
  726.  
  727.    SEE ALSO
  728.     sysmon.library/smFreeze(), exec.library/Wait(), exec.library/Signal()
  729.  
  730. sysmon.library/smUnLockTaskTable             sysmon.library/smUnLockTaskTable
  731.  
  732.    NAME    
  733.      smUnLockTaskTable -- UnLock TaskInfo Table. (V1)
  734.  
  735.    SYNOPSIS
  736.     smUnLockTaskTable( flags )
  737.                        D0
  738.  
  739.     void smUnLockTaskTable( ULONG flags );
  740.  
  741.    FUNCTION
  742.     This function will release the TaskInfo table lock obtained via a
  743.     previous call to smLockTaskTable().
  744.  
  745.    INPUTS
  746.      flags  - a bit pattern specifying the type of lock. Must match the
  747.         flags previously passed to smLockTaskTable().
  748.     
  749.    NOTES
  750.     Don't call any OS function that may spawn a new task or stop an
  751.     existing one (like dos.library I/O for example) while holding a
  752.     TaskInfo table lock.
  753.  
  754.    BUGS
  755.  
  756.    SEE ALSO
  757.     sysmon.library/smLockTaskTable(), sysmon.library/smFindTaskInfo(),
  758.     sysmon.library/smNextTaskInfo()
  759. sysmon.library/smVKPrintf                           sysmon.library/smVKPrintf
  760.  
  761.    NAME    
  762.      smVKPrintf -- print formatted data to the debugging console. (V0)
  763.               (defaults to the serial port at 9600 baud)
  764.  
  765.    SYNOPSIS
  766.     smVKPrintf( format, values )
  767.                 A0      A1
  768.  
  769.     void smVKPrintf(STRPTR format, APTR values);
  770.     void smKPrintf(STRPTR format, ...);
  771.  
  772.    FUNCTION
  773.     Print a formatted C-type string to the debugging console.
  774.     See the exec.library/RawDoFmt() call for the supported % formatting
  775.     commands.
  776.  
  777.    INPUTS
  778.      format - A C style string with % commands to indicate where parameters
  779.          are to be inserted.
  780.     values - A pointer to an array of parameters, to be inserted into
  781.          specified places in the string.
  782.     
  783.    RESULT
  784.     NONE
  785.  
  786.    NOTES
  787.     RawDoFmt assumes 16 bit ints, so you will usually need 'l's in your
  788.     formats (ex: %ld versus %d).
  789.     This function may be called from interrupts.
  790.  
  791.    BUGS
  792.     The exec.library/RawPutChar() called by this function will busy wait
  793.     when a ^S character is typed at the remote console. This will hang
  794.     the system if smVKPrintf() was called from a Forbid()/Disable()
  795.     section or from supervisor mode. Type ^Q at the remote terminal to
  796.     resume output.
  797.  
  798.    SEE ALSO
  799.     dos.library/VPrintf(), exec.library/RawDoFmt(), debug.lib/KPrintF()
  800.  
  801. sysmon.library/smVSnPrintf                         sysmon.library/smVSnPrintf
  802.  
  803.    NAME    
  804.      smVSnPrintf -- format data to a sized character buffer. (V1)
  805.  
  806.    SYNOPSIS
  807.     endstr = smVSnPrintf( buffer, len, format, values )
  808.     D0                    A3      D0   A0      A1
  809.  
  810.     APTR smVSnPrintf(STRPTR buffer, ULONG len, STRPTR format, APTR values);
  811.     APTR smSnPrintf(STRPTR buffer, ULONG len, STRPTR format, ...);
  812.  
  813.    FUNCTION
  814.     Print a formatted C-type string to a sized character buffer to prevent
  815.     overflows. Unlike strncpy(), it guarantees a null-terminated buffer
  816.     so at most (len - 1) characters will be in the output string.
  817.     See the exec.library/RawDoFmt() call for the supported % formatting
  818.     commands.
  819.  
  820.    INPUTS
  821.     buffer - A pointer to a buffer large enough to contain the resulting
  822.          string.
  823.     len    - The size of the output buffer in bytes. 
  824.      format - A C style string with % commands to indicate where parameters
  825.          are to be inserted.
  826.     values - A pointer to an array of parameters, to be inserted into
  827.          specified places in the string.
  828.     
  829.    RESULT
  830.      endstr - A pointer to the end of the formatted data.
  831.  
  832.    NOTES
  833.     RawDoFmt assumes 16 bit ints, so you will usually need 'l's in your
  834.     formats (ex: %ld versus %d).
  835.     This function may be called from interrupts.
  836.     This function is adapted from an article posted on csa.programmer
  837.     by Ty Sarna (tsarna@endicor.com).
  838.  
  839.    BUGS
  840.     Before V1.8, this function was not reentrant.
  841.  
  842.    SEE ALSO
  843.     dos.library/VPrintf(), exec.library/RawDoFmt(), ANSI-C sprintf()
  844.     sysmon.library/smVSPrintf()
  845.  
  846. sysmon.library/smVSPrintf                           sysmon.library/smVSPrintf
  847.  
  848.    NAME    
  849.      smVSPrintf -- format data to a character buffer. (V0)
  850.  
  851.    SYNOPSIS
  852.     endstr = smVSPrintf( buffer, format, values )
  853.     D0                   A3      A0      A1
  854.  
  855.     APTR smVSPrintf(STRPTR buffer, STRPTR format, APTR values);
  856.     APTR smSPrintf(STRPTR buffer, STRPTR format, ...);
  857.  
  858.    FUNCTION
  859.     Print a formatted C-type string to a character buffer.
  860.     See the exec.library/RawDoFmt() call for the supported % formatting
  861.     commands.
  862.  
  863.    INPUTS
  864.     buffer - A pointer to a buffer large enough to contain the resulting
  865.          string.
  866.      format - A C style string with % commands to indicate where parameters
  867.          are to be inserted.
  868.     values - A pointer to an array of parameters, to be inserted into
  869.          specified places in the string.
  870.     
  871.    RESULT
  872.      endstr - A pointer to the end of the formatted data.
  873.  
  874.    NOTES
  875.     RawDoFmt assumes 16 bit ints, so you will usually need 'l's in your
  876.     formats (ex: %ld versus %d).
  877.     This function may be called from interrupts.
  878.  
  879.    BUGS
  880.  
  881.    SEE ALSO
  882.     dos.library/VPrintf(), exec.library/RawDoFmt(), ANSI-C sprintf()
  883.     sysmon.library/smVSnPrintf()
  884.  
  885. sysmon.library/smVSysLog                             sysmon.library/smVSysLog
  886.  
  887.    NAME    
  888.      smVSysLog -- Logs system messages to file or console. (V0)
  889.  
  890.    SYNOPSIS
  891.     success = smVSysLog( priority, format, values )
  892.     D0                   D0        A0      A1
  893.  
  894.     BOOL smVSysLog(ULONG priority, STRPTR format, APTR values);
  895.     BOOL smSysLog(ULONG priority, STRPTR format, ...);
  896.  
  897.    FUNCTION
  898.     Formats a system message via exec.library/RawDoFmt() and logs it
  899.     into a disk file and/or window and/or serial terminal based on
  900.     it's priority value and user defined thresholds.
  901.  
  902.    INPUTS
  903.     priority - A priority value and optional facility code and flags as 
  904.            defined in sysmon.i .
  905.            Low priority values mean high severity.
  906.            An optional facility code can also be used to identify the
  907.            system component or application logging this message.
  908.            LOG_NOHEAD can be used to write long messages in several
  909.            parts by skipping the header for subsequent calls.
  910.            LOG_NOWIN and LOG_NOFILE disable window and file logging
  911.            respectively in cases where it is not appropriate to have
  912.            file or window output.
  913.      format - A C style string with % commands to indicate where parameters
  914.          are to be inserted.
  915.     values - A pointer to an array of parameters, to be inserted into
  916.          specified places in the string.
  917.     
  918.    RESULT
  919.      success - A boolean value. TRUE for success, FALSE for an error.
  920.  
  921.    NOTES
  922.     The Sysmon.server process must be running for this call to succeed.
  923.     The format buffer is limited to SM_MAXLOGCHARS chars, so make sure
  924.     your formatted string will not cause it to overflow. Starting with V1,
  925.     the formatted string will be silently truncated to the SM_MAXLOGCHARS
  926.     limit.
  927.     The higher severity codes (LOG_EMERG and LOG_ALERT) are reserved for
  928.     system failures and should not be used by applications.
  929.     This function may return before logging is complete.
  930.     This function may be called from interrupts.
  931.     
  932.    BUGS
  933.     In V0, there was no check for buffer overflow.
  934.  
  935.    SEE ALSO
  936.     exec.library/RawDoFmt(), sysmon.library/smVKPrintf(),
  937.     sysmon.library/smVSnPrintf()
  938.  
  939. sysmon.library/smWaitAnd                             sysmon.library/smWaitAnd
  940.  
  941.    NAME
  942.     smWaitAnd -- wait for a set of signals to be set together
  943.  
  944.    SYNOPSIS
  945.     signals = smWaitAnd( signalSet )
  946.     D0             D0
  947.  
  948.     ULONG smWaitAnd( ULONG signalSet );
  949.  
  950.    FUNCTION
  951.     This function will cause the current task to wait for a set of
  952.     signals. The task will only be made ready again when all of the
  953.     specified signals are set. The signals are cleared in the received
  954.     signal mask and returned to the caller. While waiting, the task will
  955.     be put in the new TS_WAITAND state.
  956.     If less than two signals are to be waited for, this function will
  957.     fallback to the normal TS_WAIT state.
  958.  
  959.     If the signals are already set before calling smWaitAnd(), the wait
  960.     condition will be immediately satisfied, and the task will continue
  961.     to run without delay.
  962.  
  963.    INPUT
  964.     signalSet - The set of signals for which to wait.
  965.             Each bit represents a particular signal.
  966.  
  967.    RESULTS
  968.     signals - the set of signals that were active. Since this functions
  969.           waits until all signals are set, this is the same as the
  970.           input mask.
  971.  
  972.    WARNING
  973.     This function cannot be called while in supervisor mode or
  974.     interrupts!  This function will break the action of a Forbid() or
  975.     Disable() call.
  976.  
  977.    BUGS
  978.  
  979.    SEE ALSO
  980.     exec.library/Wait(),
  981.  
  982. sysmon.library/smWakeUp                               sysmon.library/smWakeUp
  983.  
  984.    NAME    
  985.      smWakeUp -- Wake Up an Hibernating task. (V1)
  986.  
  987.    SYNOPSIS
  988.     smWakeUp( task )
  989.               A1
  990.  
  991.     void smWakeUp( struct Task *task );
  992.  
  993.    FUNCTION
  994.     Put an hibernating task out of sleep. If the task is not currently
  995.     hibernating, set the wakeup pending flag.
  996.     
  997.    INPUTS
  998.      task  - A pointer to a Task structure. An invalid task pointer will
  999.         result in an alert.
  1000.     
  1001.    NOTES
  1002.     This function may be called from interrupts.
  1003.  
  1004.    BUGS
  1005.  
  1006.    SEE ALSO
  1007.     sysmon.library/smHibernate(), sysmon.library/smUnFreeze(),
  1008.     sysmon.library/smScheduleWakeUp(), exec.library/Signal()
  1009.  
  1010.