home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d169 / src / dres / doc / misc.doc < prev    next >
Text File  |  1988-11-22  |  5KB  |  162 lines
  1.  
  2.                   MISC.DOC
  3.  
  4.     These are miscellanious useful routines for your enjoyment.
  5.  
  6.  
  7. WildCmp                             WildCmp
  8.  
  9.     CBOOL  = WildCmp(wildcard, filename)
  10.     char *wildcard;
  11.     char *filename;
  12.  
  13.     The wildcard characters supported are * and ?.  The wildcard is
  14.     compared against the filename and (1) returned on success, (0) on
  15.     failure.
  16.  
  17.  
  18. WaitMsg                             WaitMsg
  19.  
  20.     msg    = WaitMsg(msg)
  21.     EXECMSG *msg;
  22.  
  23.     This routines Waits for a message to be returned just like WaitIO()
  24.     waits for an io request to complete.  The message is REMOVED from the
  25.     reply port after it has returned.
  26.  
  27.     the message must have a valid mn_ReplyPort() and must have been queued
  28.     with PutMsg(), which sets the ln_Type to NT_MESSAGE, and replied with
  29.     ReplyMsg(), which sets the ln_Type to NT_REPLYMSG.
  30.  
  31.  
  32. CheckMsg                            CheckMsg
  33.  
  34.     msg/NULL = CheckMsg(msg)
  35.     EXECMSG *msg;
  36.  
  37.     This routine checks to see if the message has been returned.  The
  38.     same restrictions apply as for WaitMsg().  the message is NOT removed.
  39.     The message is returned if it has been returned (not removed), or
  40.     NULL otherwise.
  41.  
  42.  
  43. CheckPort                            CheckPort
  44.  
  45.     msg/NULL = CheckPort(port)
  46.     EXECMSG *msg;
  47.     PORT *port;
  48.  
  49.     This routine works like WaitPort(), but (1) does not block, and
  50.     (2) does not remove the message.  If the port is not empty the first
  51.     message is returned (not removed), else NULL is returned if the port
  52.     is empty.
  53.  
  54.  
  55. LockAddr                            LockAddr
  56.  
  57.     (void) LockAddr(&lock)
  58.     long lock[2];
  59.  
  60.     The lock structure (8 bytes) MUST initially be 0.  This routine obtains
  61.     an exclusive lock on the structure and blocks until that lock can be
  62.     obtained.  The structure must be word-aligned.
  63.  
  64.     Unless it is forced to block, this subroutine is extremely fast.  This
  65.     routine does not allocate any signals, but uses the reserved EXEC
  66.     semaphore signal.
  67.  
  68.  
  69. LockAddrB                            LockAddrB
  70.  
  71.     (void) LockAddr(bitno, &lock)
  72.     long bitno;
  73.     long lock[2];
  74.  
  75.     The lock structure actually supports up to 8 independant exclusive
  76.     locks.  LockAddr() is a special case which uses bit # 0.  This call
  77.     works as in LockAddr() but you may specify the bit you wish to lock
  78.     (0 to 7).  If you specify 0, this call is equivalent to LockAddr().
  79.  
  80.  
  81. UnLockAddr                            UnLockAddr
  82.  
  83.     (void) UnLockAddr(&lock)
  84.     long lock[2];
  85.  
  86.     Remove an exclusive lock you had previously obtained.  If other tasks
  87.     are waiting for this lock, ALL are awakened even though only one will
  88.     get the lock next.    This ensures that the highest priority task will
  89.     get the lock next.
  90.  
  91.     This routine is extremely fast if nobody else is waiting for the lock,
  92.     else it has to Signal() them.  You MUST have previously obtained the
  93.     lock.
  94.  
  95.  
  96. UnLockAddrB                            UnLockAddrB
  97.  
  98.     (void) UnLockAddrB(bitno, &lock)
  99.     long bitno;
  100.     long lock[2];
  101.  
  102.     Again, this routine works the same as UnLockAddr() with the exception
  103.     that you may specify one of the 8 bits to unlock (0 to 7).
  104.  
  105.  
  106. DoSyncMsg                            DoSyncMsg
  107.  
  108.     (void) DoSyncMsg(port, msg)
  109.     PORT *port;
  110.     EXECMSG *msg;
  111.  
  112.     This routine PutMsg()s a message and waits for it to be returned.  This
  113.     routine creates its own reply port on the stack and stuffs it into
  114.     mn_ReplyPort for you.  Thus, virtually no setup is required to use
  115.     this routine.
  116.  
  117.  
  118. FindName2                            FindName2
  119.  
  120.     node/NULL = FindName2(list, name)
  121.  
  122.     This routine is identical to the EXEC FindName() call with the exception
  123.     that it ignores nodes whos ln_Name fields are NULL.  ln_Name fields in
  124.     the list nodes must contain either NULL or a valid string pointer.
  125.  
  126.  
  127. GetTaskData                            GetTaskData
  128.  
  129.     ptr = GetTaskData(name, bytes)
  130.     APTR ptr;
  131.     char *name;
  132.     long bytes;
  133.  
  134.     This routine retrieves/allocates task-private named storage.  For a
  135.     specific name, the first GetTaskData() call will allocate the specified
  136.     # of bytes and zero them.  Space to hold the name itself is also
  137.     allocated (i.e. you can use a temporary buffer to hold 'name' when you
  138.     make this call).  Future calls return the pointer to the already
  139.     allocated storage without modifying it.
  140.  
  141.     The storage is automatically freed if the TASK is removed... note that
  142.     the task is not normally removed when a C program exits back into a
  143.     CLI enviroment... it uses the CLI's task to run the program.  The
  144.     task's memory list is used to implement this function.
  145.  
  146.  
  147. FreeTaskData                            FreeTaskData
  148.  
  149.     (void) FreeTaskData(name)
  150.     char *name;
  151.  
  152.     If the task-private name exists, the storage associated with it is
  153.     freed.  This works with memlist entries allocated with GetTaskData()
  154.     or by the user, assuming the ln_Name field points to a valid string.
  155.  
  156.     (note:  FreeEntry() is used after the associated MemList structure is
  157.      unlinked frlom the list.  ln_Name is not specifically freed but the
  158.      way GetTaskData() works, the second entry is actually the storage
  159.      associated with the ln_Name)
  160.  
  161.  
  162.