home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / cmanual-3.0.lha / CManual-3.0 / Amiga / Appendices / FunctionsAndLibraries / ExecLibrary.doc < prev    next >
Encoding:
Text File  |  1993-10-12  |  20.2 KB  |  673 lines
  1. 7    EXEC LIBRARY
  2.  
  3. 7.1  OPEN THE EXEC LIBRARY
  4.  
  5. The Exec Library is automatically opened when your program is
  6. loaded, so you do not have to open it yorself. The functions
  7. listed in this fil e can therefore directly be used.
  8.  
  9.  
  10.  
  11. 7.2  FUNCTIONS
  12.  
  13. AbortIO()
  14.  
  15.   This function will try to abort a previously started request.
  16.   Of course, only asynchronous commands can be aborted, and if
  17.   the request has already been completed it can not be aborted
  18.   any more.
  19.  
  20.   Synopsis: AbortIO( req )
  21.  
  22.   req:      (struct IORequest *) Pointer to the request you
  23.             want to abort.
  24.  
  25.  
  26.  
  27. AddHead()
  28.  
  29.   This function will add a note at the head of a list.
  30.  
  31.   Synopsis: AddHead( list, node )
  32.  
  33.   list:     (struct List *) Pointer to the list you wish to
  34.             insert the node in.
  35.  
  36.   node:     (struct Node *) Pointer to the node you want to
  37.             insert.
  38.  
  39.  
  40.  
  41. AddTail()
  42.  
  43.   This function will add a note at the tail of a list.
  44.  
  45.   Synopsis: AddTail( list, node )
  46.  
  47.   list:     (struct List *) Pointer to the list you wish to
  48.             insert the node in.
  49.  
  50.   node:     (struct Node *) Pointer to the node you want to
  51.             insert.
  52.  
  53.  
  54.  
  55. AllocMem()
  56.  
  57.   This function allocates memory. You specifies what type and
  58.   how much you want, and it returns a pointer to the allocated
  59.   memory, or NULL if there did not exist enough memory.
  60.  
  61.   Synopsis: memory = AllocMem( size, type );
  62.  
  63.   memory:   (void *) Pointer to the new allocated memory, or
  64.             NULL if no memory could be allocated. Remember!
  65.             Never use memory which you have not successfully
  66.             allocated.
  67.  
  68.   size:     (long) The size (in bytes) of the memory you want.
  69.             (AllocMem() always allocates memory in multiples of
  70.             eight bytes. So if you only ask for 9 bytes, Exec
  71.             would actually give you 16 Bytes (2*8).)
  72.  
  73.   type:     (long) You need to choose one of the three
  74.             following types of memory (see chapter 0
  75.             INTRODUCTION for more information about Chip and
  76.             Fast memory):
  77.  
  78.             MEMF_CHIP   Chip memory. This memory can be
  79.                         accessed by both the main processor, as
  80.                         well as the Chips. Graphics/Sound data
  81.                         MUST therefore be placed in Chip memory.
  82.                         If it does not matter what type of 
  83.                         memory you get (Fast or Chip), you
  84.                         should try to allocate Fast memory
  85.                         before you allocate Chip memory. (Chip
  86.                         memory is more valuable than Fast
  87.                         memory.)
  88.  
  89.             MEMF_FAST   Fast memory. This memory can only be
  90.                         accessed by the main processor.
  91.                         (Graphics and Sound data can NOT be
  92.                         stored in Fast memory, use Chip memory.)
  93.                         This memory is normally a little bit
  94.                         faster than Chip memory, since only the
  95.                         main processor is working with it, and
  96.                         it is not disturbed by the Chips.
  97.  
  98.             MEMF_PUBLIC If it does not matter what type of
  99.                         memory you get (you do not intend to
  100.                         use the memory for Graphics/Sound data),
  101.                         you should use Fast memory. However,
  102.                         all Amigas do not have Fast memory,
  103.                         since you need to by a memory expansion
  104.                         in order to get it. If want to tell
  105.                         Exec that you would like to use Fast
  106.                         memory if there is any, else use Chip
  107.                         memory, you should ask for MEMF_PUBLIC.
  108.  
  109.             If you want the allocated memory to be cleared
  110.             (initialized to zeros), you should set the flag
  111.             MEMF_CLEAR.
  112.  
  113.  
  114.  
  115. BeginIO()
  116.   
  117.   This function will send request blocks to a device. This
  118.   function is "asynchronous" which means that your program will
  119.   continue to run while the device is executing your command. 
  120.  
  121.   This function is very similar to SendIO(). The difference is
  122.   that this function will not clear some values in the request
  123.   block. If you are using the Audio Device or is using the
  124.   "Quick Mode" you should use this function.
  125.  
  126.   Synopsis: BeginIO( req )
  127.  
  128.   req:      (struct IORequest *) Pointer to the request you
  129.             want to have executed. When you want to use the
  130.             quick mode you have to use this low level function
  131.             rather than SendIO() and DoIO().
  132.  
  133.  
  134.  
  135. CheckIO()
  136.  
  137.   This function will check if an asynchronous request has been
  138.   completed or not.
  139.  
  140.   Synopsis: ptr = CheckIO( req );
  141.  
  142.   ptr:      (long) CheckIO() will either return NULL if the
  143.             request have not been completed or it will return a
  144.             pointer to the request block.
  145.  
  146.   req:      (struct IORequest *) Pointer to the request you
  147.             want to check.
  148.  
  149.  
  150.  
  151. CloseDevice()
  152.  
  153.   This function will close a previously opened device. All
  154.   devices you have opened must be closed before your program
  155.   may terminate.
  156.   
  157.   Synopsis: CloseDevice( req );
  158.  
  159.   reg:      (struct IORequest *) Pointer to the device's
  160.             request block.
  161.  
  162.  
  163.  
  164. CreateExtIO()
  165.  
  166.   This function will allocate and initialize an extended request
  167.   block of any desired size (must not be smaller than a normal
  168.   IORequest structure). The size depends on which device the
  169.   request block should be used with.
  170.  
  171.   Synopsis: ext_req = CreateExtIO( msg_port, size );
  172.  
  173.   ext_req:  (struct IORequest *) Pointer to the new extended
  174.             request block, or NULL if the request block could
  175.             not be created.
  176.  
  177.   msg_port: (struct MsgPort *) Pointer to the message port
  178.             the device should use to communicate with you.
  179.  
  180.   size:     (long) The number of bytes that should be allocated
  181.             for the extended request block. Use the function
  182.             sizeof() to find the exact number of bytes needed.
  183.  
  184.  
  185.  
  186. CreatePort()
  187.  
  188.   CreatePort() allocates and initializes a MsgPort structure.
  189.   If you give it a string as first parameter it will also make
  190.   the port public. (A port that has a name can be found by
  191.   other tasks and is therefore "public".) If CreatePort() of
  192.   some reason could not create a message port it returns NULL,
  193.   otherwise if everything is OK it returns a pointer to the
  194.   new MsgPort structure.
  195.  
  196.   Synopsis: msgp = CreatePort( name, pri );
  197.   
  198.   msgp:     (struct MsgPort *) Pointer to the new MsgPort
  199.             structure, or NULL if something went wrong.
  200.  
  201.   name:     (char *) Pointer to a string containing the name
  202.             of the message port, or NULL. If it is a string
  203.             the port will be made public (so other tasks can
  204.             find it) else only our task can use it.
  205.   
  206.   msgp:     (struct MsgPort *) Pointer to the MsgPort structure
  207.             that should be allocated.
  208.  
  209.   pri:      (BYTE) This message port's priority. Usually set
  210.             to 0 - normal priority.
  211.  
  212.  
  213.  
  214. CreateStdIO()
  215.  
  216.   This function will allocate and initialize a standard request
  217.   block (IORequest structure).
  218.  
  219.   Synopsis: std_req = CreateStdIO( msg_port );
  220.  
  221.   std_req:  (struct IORequest *) Pointer to the new standard
  222.             request block (struct IOStdReq *), or NULL if the
  223.             request block could not be created.
  224.  
  225.   msg_port: (struct MsgPort *) Pointer to the message port
  226.             the device should use to communicate with you.
  227.  
  228.  
  229.  
  230. DeletePort()
  231.  
  232.   DeletePort() will close a message port that is presently
  233.   open. All ports that has been created must be closed before
  234.   the program may terminate.
  235.  
  236.   Synopsis: DeletePort( msgp );
  237.  
  238.   msgp:     (struct MsgPort *) Pointer to the MsgPort structure,
  239.             that should be closed.
  240.  
  241.  
  242.  
  243. DeleteStdIO()
  244.  
  245.   This function will delete a standard request block you
  246.   previouly have created with help of the CreateStdIO()
  247.   function. Remember that all request block you have
  248.   allocated must be deallocated before your program
  249.   terminates!
  250.  
  251.   Synopsis: DeleteStdIO( std_req );
  252.  
  253.   std_req:  (struct IOStdReq *) Pointer to the standard
  254.             request block you want to delete.
  255.  
  256.  
  257.  
  258. DeleteExtIO()
  259.  
  260.   This function will delete an extended request block you
  261.   previouly have created with help of the CreateExtIO()
  262.   function. Note that the size must be set to the same value
  263.   as when you created the request block. Remember that all
  264.   request block you have allocated must be deallocated before
  265.   your program terminates!
  266.   
  267.   Synopsis: DeleteExtIO( std_req, size );
  268.  
  269.   std_req:  (struct IOStdReq *) Pointer to the extended
  270.             request block you want to delete.
  271.  
  272.   size:     (long) The size of the request block, in bytes.
  273.  
  274.  
  275.  
  276. Disable() 
  277.  
  278.   This function will lock out all other tasks and even
  279.   interrupts are stopped. As long as you are in this disabled
  280.   mode no other processes or interrupts will be executed. If
  281.   you put your task to sleep with a Wait() call will the
  282.   disable mode temporarily be stopped and other tasks and
  283.   interrupts may be executed again. However, when your program
  284.   wakes up again will the disabled mode start again. The only
  285.   way to really stop the disabled mode is to use the Enable()
  286.   function.
  287.   
  288.   Note that the disable mode will not even allow interrupts
  289.   from being executed. This can be very dangerous since there
  290.   are a lot of important interrupts on the Amiga that should
  291.   not be forced to wait. You should therefore only use the
  292.   disabled mode for very short periods.
  293.  
  294.   Synopsis: Disable();
  295.  
  296.  
  297.  
  298. DoIO()
  299.  
  300.   This function is used to send request blocks to a device.
  301.   This function is "synchronous" which means that your program
  302.   will automatically be put to sleep while the device is
  303.   executing your command. Once it has finished your program
  304.   will wake up. Since your program is put to sleep ("task
  305.   sleep") no processing time is waisted while you are waiting
  306.   for your request to be completed.
  307.  
  308.   Synopsis: error = DoIO( req );
  309.  
  310.   error:    (long) DoIO() will return first when the request has
  311.             been completed or something has failed. If the
  312.             request was successfully completed zero is returned,
  313.             else an error number is returned. What error number
  314.             depends on which device was used. See below for a
  315.             complete list of standard error commands.
  316.  
  317.   req:      (struct IORequest *) Pointer to the request you
  318.             want to have executed.
  319.  
  320.  
  321.  
  322. Enable()
  323.  
  324.   This function will permit other tasks and interrupts to be
  325.   executed again after previously have been disabled by the
  326.   Disable() function.
  327.   
  328.   Synopsis: Enable();
  329.  
  330.  
  331.  
  332. Enqueue()
  333.  
  334.   This function will insert nodes into lists considering the
  335.   node's priority. The higher priority the closer to the head
  336.   they are placed and vice versa.
  337.   
  338.   NOTE! This function can of course not be used to handle mini
  339.   lists. (Mini nodes do not have any priority field.)
  340.  
  341.   Synopsis: Enqueue( list, node );
  342.  
  343.   list:     (struct List *) Pointer to the list you wish to
  344.             insert the node in.
  345.  
  346.   node:     (struct Node *) Pointer to the node you want to
  347.             insert.
  348.  
  349.  
  350.  
  351. FindName()
  352.  
  353.   This function will scan a list and search for nodes by their
  354.   name. It will return a pointer to the first node with the
  355.   specified name or NULL if no more node could be found. If it
  356.   found a node you simply have to call it again to find the
  357.   next.
  358.  
  359.   NOTE! This function can of course not be used to handle mini
  360.   lists. (Mini nodes do not have any name field.)
  361.  
  362.   Synopsis: node = FindName( list, name );
  363.  
  364.   node:     (struct Node *) If FindName() finds a node with the
  365.             name "name" it returns a pointer to it. If no node
  366.             was found it returns NULL.
  367.  
  368.   list:     (struct List *) Pointer to the list you want to
  369.             examine. If you have already found a node and want
  370.             to search for the next you should give it a pointer
  371.             to the last node you found.
  372.  
  373.   name:     (char *) Pointer to a NULL terminated string that
  374.             contains the name of the node(s) you look for.
  375.  
  376.  
  377.  
  378. FindPort()
  379.  
  380.   FindPort() will try to locate an already existing message
  381.   port. If the function finds the port it returns a pointer to
  382.   it, else the function returns NULL.
  383.  
  384.   Synopsis: msgp = FindPort( name );
  385.   
  386.   msgp:     (struct MsgPort *) FindPort() will return a pointer
  387.             to the port we asked for, or NULL if it could not
  388.             find it.
  389.  
  390.   name:     (char *) Pointer to a string containing the name of
  391.             the port we are looking for.
  392.  
  393.  
  394.  
  395. Forbid()
  396.  
  397.   This function will lock out all other tasks. As long as you
  398.   are in this forbidden mode no other processes will be
  399.   executed. If you put your task to sleep with a Wait() call
  400.   will the forbidden mode temporarily be stopped and other
  401.   tasks may run again. However, when your program wakes up
  402.   again will the forbidden mode start again. The only way to
  403.   really stop the forbidden mode is to use the Permit()
  404.   function.
  405.   
  406.   Synopsis: Forbid();
  407.  
  408.  
  409.  
  410. FreeMem()
  411.  
  412.   This function deallocated previously allocated memory.
  413.   Remember to deallocate all memory you have taken, and never
  414.   deallocate memory which you have not taken.
  415.  
  416.   Synopsis: FreeMem( memory, size );
  417.  
  418.   memory    (void *) Pointer to some memory which has
  419.             previously been allocated. Remember! never use
  420.             memory which has been deallocated.
  421.  
  422.   size      (long) The size (in bytes) of the memory you want
  423.             to deallocate.
  424.  
  425.  
  426.  
  427. GetMsg()
  428.  
  429.   GetMsg() will try to remove a message from the port's
  430.   message list, and return a pointer to the message. If it
  431.   could not find any message it returns NULL. Before your
  432.   program terminates it should try to collect all waiting
  433.   messages.
  434.  
  435.   Synopsis: msg = GetMsg( msgp );
  436.  
  437.   msg:      (struct Message *) If GetMsg() could find a
  438.             message at the port it returns a pointer to the
  439.             message, and removes the message from the queue.
  440.             If no message was found, it returns NULL.
  441.  
  442.   msgp:     (struct MsgPort *) Pointer to the message port you
  443.             want to get the message from.
  444.  
  445.  
  446.  
  447. Insert()
  448.  
  449.   This function is used to insert nodes into a list. If the
  450.   node should be placed first or last in the list you should
  451.   use the faster functions AddHead() or AddTail().
  452.  
  453.   Synopsis: Insert( list, node, pred );
  454.  
  455.   list:     (struct List *) Pointer to the list you wish to
  456.             insert the node in.
  457.  
  458.   node:     (struct Node *) Pointer to the node you want to
  459.             insert.
  460.  
  461.   pred:     (struct Node *) Pointer to a node which the new
  462.             node should be placed after. (If this field is NULL
  463.             or points to the list header the node will be
  464.             inserted first in the list. If this field points to
  465.             the list's lh_Tail field the node will be inserted
  466.             last in the list. However, if you which to insert
  467.             a node first or last in a list you should use the
  468.             faster functions AddHead() or AddTail().)
  469.  
  470.  
  471.  
  472. NewList()
  473.  
  474.   This function initializes a list structure.
  475.  
  476.   Synopsis: NewList( list );
  477.  
  478.   list:     (struct List *) Pointer to the list that should be
  479.             initialized.
  480.  
  481.  
  482.  
  483. OpenDevice()
  484.  
  485.   This function will open a specified device. Remember that you
  486.   must always open the device before you may start to use it.
  487.  
  488.   Synopsis: error = OpenDevice( name, unit, req, flags );
  489.  
  490.   error:    (long) If OpenDevice() managed to open the device
  491.             it returns 0, else an error number is returned.
  492.  
  493.   name:     (char *) Name of the device you want to open.
  494.             See the following chapters for more information.
  495.  
  496.   unit:     (long) Which unit you want to open. Some devices
  497.             does not have several units and this field is then
  498.             ignored.
  499.  
  500.   req:      (struct IORequest *) Pointer to a request block.
  501.             Note that some devices may need a larger extended
  502.             request blocks.
  503.  
  504.   flags:    (long) Special flags may sometimes be used here,
  505.             otherwise this field is ignored. 
  506.  
  507.  
  508.  
  509. Permit()
  510.  
  511.   This function will permit other tasks to run again after
  512.   previously have been forbidden by the Forbid() function.
  513.   
  514.   Synopsis: Permit();
  515.  
  516.  
  517.  
  518. PutMsg()
  519.  
  520.   PutMsg() will put a message at the end of the port's queue
  521.   of messages. Note that after you have sent a message you may
  522.   not read or alter it until the other task has replied!
  523.  
  524.   Synopsis: PutMsg( msgp, message );
  525.  
  526.   msgp:     (struct MsgPort *) Pointer to the message port
  527.             to which you want to send a message.
  528.  
  529.   message:  (struct Message *) Pointer to the whole message
  530.             area.
  531.  
  532.  
  533.  
  534. RemHead()
  535.  
  536.   This function will remove a note at the head of a list and
  537.   returns a pointer to the removed node.
  538.  
  539.   Synopsis: node = RemHead( list )
  540.  
  541.   list:     (struct List *) Pointer to the list you wish to
  542.             remove the head node from.
  543.  
  544.   node:     (struct Node *) Pointer to the node you have
  545.             removed, or NULL if there were no more nodes to
  546.             remove.
  547.  
  548.  
  549.  
  550. Remove()
  551.  
  552.   This function is used to remove nodes from a list. If the
  553.   node should be removed at the tail of the list you should use
  554.   the faster functions RemHead() or RemTail().
  555.  
  556.   Synopsis: Remove( node );
  557.  
  558.   node:     (struct Node *) Pointer to the node you want to
  559.             insert.
  560.  
  561.   Here is an example how to remove the node "author":
  562.  
  563.  
  564.  
  565. RemTail()
  566.  
  567.   This function will remove a note at the tail of a list and
  568.   returns a pointer to the removed node.
  569.  
  570.   Synopsis: node = RemTail( list )
  571.  
  572.   list:     (struct List *) Pointer to the list you wish to
  573.             remove the tail node from.
  574.  
  575.   node:     (struct Node *) Pointer to the node you have
  576.             removed, or NULL if there were no more nodes to
  577.             remove.
  578.  
  579.  
  580.  
  581. ReplyMsg()
  582.  
  583.   This function tells Intuition that you have finished reading
  584.   the message. Remember, once you have replied you may not
  585.   examine or change the IntuiMessage structure any more.
  586.   
  587.   Synopsis:   ReplyMsg( my_message );
  588.   
  589.   my_message: (struct Message *) Pointer to a Message
  590.               structure, in this case a pointer to an
  591.               IntuiMessage structure.
  592.  
  593.  
  594.  
  595. SendIO()
  596.  
  597.   This function is used to send request blocks to a device.
  598.   This function is "asynchronous" which means that your program
  599.   will continue to run while the device is executing your
  600.   command. 
  601.  
  602.   Synopsis: SendIO( req )
  603.  
  604.   req:      (struct IORequest *) Pointer to the request you
  605.             want to have executed.
  606.  
  607.  
  608.  
  609. Wait()
  610.  
  611.   Wait() will put the task to sleep, and will first wake up
  612.   when one of the specified signal bits arrives. The advantage
  613.   with this function compared to WaitPort() is that you can
  614.   monitor several message ports at the same time. You only
  615.   need to tell Wait() which signal you want to wait for, and
  616.   once one or more of them arrives the task is put to work
  617.   again.
  618.  
  619.   Synopsis: rsig = Wait( wsig )
  620.  
  621.   rsig:     (ULONG) When one of the specified signal bits was
  622.             received, the task is woken up and Wait() returns
  623.             the signal bit value that woke it up.
  624.  
  625.   wsig:     (ULONG) Wait() will put the task to sleep, and it
  626.             will only wake up if one of the specified signal
  627.             bit values is received.
  628.  
  629.  
  630.  
  631. WaitIO()
  632.   
  633.   This function will put your program to sleep and wait for the
  634.   asynchronous request to be completed. Your program will first
  635.   wake up when the device has finished your request. WaitIO()
  636.   will automatically remove the message at the reply port.
  637.  
  638.   Synopsis: error = WaitIO( req );
  639.  
  640.   error:    (long) WaitIO() will return first when the request,
  641.             that has previously been sent, has been completed
  642.             or something has failed. If the request was
  643.             successfully completed zero is returned, else an
  644.             error number is returned. What error number depends
  645.             on which device was used.
  646.  
  647.   req:      (struct IORequest *) Pointer to the request you
  648.             want to wait for to be completed. Note that the
  649.             request must have already been sent to the device
  650.             by either a SendIO() or BeginIO() function call. If
  651.             the request has already been completed WaitIO()
  652.             will immediately return.
  653.  
  654.  
  655.  
  656. WaitPort()
  657.  
  658.   WaitPort() will put the task to sleep, and will first wake
  659.   up when a message arrives. While the task is sleeping it does
  660.   not use any computer time.
  661.  
  662.   Synopsis: msg = WaitPort( msgp );
  663.   
  664.   msg:      (struct Message *) When a message arrives the task
  665.             is woken up and WaitPort() returns a pointer to the
  666.             first message that has arrived. (There may arrive
  667.             several messages at the same time.)
  668.  
  669.   msgp:     (struct MsgPort *) Pointer to the message port you
  670.             want to wait at.
  671.  
  672.  
  673.