home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / cmanual-3.0.lha / CManual / Amiga / Appendices / FunctionsAndLibraries / ExecLibrary.doc < prev    next >
Text File  |  1993-10-12  |  21KB  |  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.   previ