home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Misc / CBMDevKit3.dms / CBMDevKit3.adf / AsynchIO / async.doc next >
Encoding:
Text File  |  1993-11-17  |  7.7 KB  |  244 lines
  1. TABLE OF CONTENTS
  2.  
  3. asyncio/CloseAsync
  4. asyncio/OpenAsync
  5. asyncio/ReadAsync
  6. asyncio/ReadCharAsync
  7. asyncio/SeekAsync
  8. asyncio/WriteAsync
  9. asyncio/WriteCharAsync
  10. asyncio/CloseAsync                                         asyncio/CloseAsync
  11.  
  12.    NAME
  13.     CloseAsync -- close an async file.
  14.  
  15.    SYNOPSIS
  16.     success = CloseAsync(file);
  17.  
  18.     LONG CloseAsync(struct AsyncFile *);
  19.  
  20.    FUNCTION
  21.     Closes a file, flushing any pending writes. Once this call has been
  22.     made, the file can no longer be accessed.
  23.  
  24.    INPUTS
  25.     file - the file to close. May be NULL, in which case this function
  26.            returns -1 and sets the IoErr() code to ERROR_INVALID_LOCk.
  27.  
  28.    RESULT
  29.     result - < 0 for an error, >= 0 for success. Indicates whether closing
  30.          the file worked or not. If the file was opened in read-mode,
  31.              then this call will always work. In case of error,
  32.              dos.library/IoErr() can give more information.
  33.  
  34.    SEE ALSO
  35.     OpenAsync(), dos.library/Close()
  36.  
  37. asyncio/OpenAsync                                           asyncio/OpenAsync
  38.  
  39.    NAME
  40.     OpenAsync -- open a file for asynchronous IO.
  41.  
  42.    SYNOPSIS
  43.     file = OpenAsync(fileName, accessMode, bufferSize);
  44.  
  45.     struct AsyncFile OpenAsync(const STRPTR, UBYTE, LONG);
  46.  
  47.    FUNCTION
  48.     The named file is opened and an async file handle returned. If the
  49.     accessMode is MODE_READ, an existing file is opened for reading.
  50.     If accessMode is MODE_WRITE, a new file is created for writing. If
  51.     a file of the same name already exists, it is first deleted. If
  52.     accessMode is MODE_APPEND, an existing file is prepared for writing.
  53.     Data written is added to the end of the file. If the file does not
  54.     exists, it is created.
  55.  
  56.     'fileName' is a filename and CANNOT be a window specification such as
  57.     CON: or RAW:, or "*"
  58.  
  59.     'bufferSize' specifies the size of the IO buffer to use. There are
  60.     in fact two buffers allocated, each of roughly (bufferSize/2) bytes
  61.     in size. The actual buffer size use can vary slightly as the size
  62.     is rounded to speed up DMA.
  63.  
  64.     If the file cannot be opened for any reason, the value returned
  65.     will be NULL, and a secondary error code will be available by
  66.     calling the routine dos.library/IoErr().
  67.  
  68.     INPUTS
  69.     name - name of the file to open, cannot be a window specification
  70.     accessMode - one of MODE_READ, MODE_WRITE, or MODE_APPEND
  71.     bufferSize - size of IO buffer to use. 8192 is recommended as it
  72.              provides very good performance for relatively little
  73.              memory.
  74.  
  75.     RESULTS
  76.     file - an async file handle or NULL for failure. You should not access
  77.            the fields in the AsyncFile structure, these are private to the
  78.            async IO routines. In case of failure, dos.library/IoErr() can
  79.            give more information.
  80.  
  81.     SEE ALSO
  82.     CloseAsync(), dos.library/Open()
  83.  
  84. asyncio/ReadAsync                                           asyncio/ReadAsync
  85.  
  86.    NAME
  87.     ReadAsync -- read bytes from an async file.
  88.  
  89.    SYNOPSIS
  90.     actualLength = ReadAsync(file, buffer, numBytes);
  91.  
  92.     LONG ReadAsync(struct AsyncFile *, APTR, LONG);
  93.  
  94.    FUNCTION
  95.     This function reads bytes of information from an opened async file
  96.         into the buffer given. 'numBytes' is the number of bytes to read from
  97.         the file.
  98.  
  99.     The value returned is the length of the information actually read.
  100.     So, when 'actualLength' is greater than zero, the value of
  101.     'actualLength' is the the number of characters read. Usually
  102.     ReadAsync() will try to fill up your buffer before returning. A value
  103.     of zero means that end-of-file has been reached. Errors are indicated
  104.     by a value of -1.
  105.  
  106.     INPUTS
  107.     file - opened file to read, as obtained from OpenAsync()
  108.     buffer - buffer where to put bytes read
  109.     numBytes - number of bytes to read into buffer
  110.  
  111.     RESULT
  112.     actualLength - actual number of bytes read, or -1 if an error. In
  113.                case of error, dos.library/IoErr() can give more
  114.                information.
  115.  
  116.     SEE ALSO
  117.     OpenAsync(), CloseAsync(), ReadCharAsync(), WriteAsync(),
  118.     dos.library/Read()
  119.  
  120. asyncio/ReadCharAsync                                   asyncio/ReadCharAsync
  121.  
  122.    NAME
  123.     ReadCharAsync -- read a single byte from an async file.
  124.  
  125.    SYNOPSIS
  126.     byte = ReadCharAsync(file);
  127.  
  128.     LONG ReadCharAsync(struct AsyncFile *);
  129.  
  130.    FUNCTION
  131.     This function reads a single byte from an async file. The byte is
  132.     returned, or -1 if there was an error reading, or if the end-of-file
  133.     was reached.
  134.  
  135.    INPUTS
  136.     file - opened file to read from, as obtained from OpenAsync()
  137.  
  138.    RESULT
  139.     byte - the byte read, or -1 if no byte was read. In case of error,
  140.            dos.library/IoErr() can give more information. If IoErr()
  141.            returns 0, it means end-of-file was reached. Any other value
  142.            indicates an error.
  143.  
  144.    SEE ALSO
  145.     OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync()
  146.     dos.library/Read()
  147.  
  148. asyncio/SeekAsync                                           asyncio/SeekAsync
  149.  
  150.    NAME
  151.     SeekAsync -- set the current position for reading or writing within
  152.              an async file.
  153.  
  154.    SYNOPSIS
  155.     oldPosition = SeekAsync(file, position, mode);
  156.  
  157.     LONG SeekAsync(struct AsyncFile *, LONG, BYTE);
  158.  
  159.    FUNCTION
  160.     SeekAsync() sets the read/write cursor for the file 'file' to the
  161.     position 'position'. This position is used by the various read/write
  162.     functions as the place to start reading or writing. The result is the
  163.     current absolute position in the file, or -1 if an error occurs, in
  164.     which case dos.library/IoErr() can be used to find more information.
  165.     'mode' can be SEEK_START, SEEK_CURRENT or SEEK_END. It is used to
  166.     specify the relative start position. For example, 20 from current
  167.     is a position 20 bytes forward from current, -20 is 20 bytes back
  168.     from current.
  169.  
  170.     To find out what the current position within a file is, simply seek
  171.     zero from current.
  172.  
  173.     INPUTS
  174.     file - an opened async file, as obtained from OpenAsync()
  175.     position - the place where to move the read/write cursor
  176.     mode - the mode for the position, one of SEEK_START, SEEK_CURRENT,
  177.            or SEEK_END.
  178.  
  179.     RESULT
  180.     oldPosition - the previous position of the read/write cursor, or -1
  181.               if an error occurs. In case of error, dos.library/IoErr()
  182.               can give more information.
  183.  
  184.     SEE ALSO
  185.     OpenAsync(), CloseAsync(), ReadAsync(), WriteAsync(),
  186.     dos.library/Seek()
  187.  
  188. asyncio/WriteAsync                                         asyncio/WriteAsync
  189.  
  190.    NAME
  191.     WriteAsync -- write data to an async file.
  192.  
  193.    SYNOPSIS
  194.     actualLength = WriteAsync(file, buffer, numBytes);
  195.  
  196.     LONG WriteAsync(struct AsyncFile *, APTR, LONG);
  197.  
  198.    FUNCTION
  199.     WriteAsync() writes bytes of data to an opened async file. 'numBytes'
  200.     indicates the number of bytes of data to be transferred. 'buffer'
  201.     points to the data to write. The value returned is the length of
  202.     information actually written. So, when 'numBytes' is greater than
  203.     zero, the value of 'numBytes' is the number of characters written.
  204.     Errors are indicated by a return value of -1.
  205.  
  206.     INPUTS
  207.     file - an opened file, as obtained from OpenAsync()
  208.     buffer - address of data to write
  209.     numBytes - number of bytes to write to the file
  210.  
  211.     RESULT
  212.     actualLength - number of bytes written, or -1 if error. In case
  213.                of error, dos.library/IoErr() can give more
  214.                information.
  215.  
  216.     SEE ALSO
  217.     OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync(),
  218.     dos.library/Write()
  219.  
  220. asyncio/WriteCharAsync                                 asyncio/WriteCharAsync
  221.  
  222.    NAME
  223.     WriteCharAsync -- write a single byte to an async file.
  224.  
  225.    SYNOPSIS
  226.     result = WriteCharAsync(file, byte);
  227.  
  228.     LONG WriteCharAsync(struct AsyncFile *, UBYTE);
  229.  
  230.    FUNCTION
  231.     This function writes a single byte to an async file.
  232.  
  233.    INPUTS
  234.     file - an opened async file, as obtained from OpenAsync()
  235.     byte - byte of data to add to the file
  236.  
  237.    RESULT
  238.     result - 1 if the byte was written, -1 if there was an error. In
  239.          case of error, dos.library/IoErr() can give more information.
  240.  
  241.    SEE ALSO
  242.     OpenAsync(), CloseAsync(), ReadAsync(), WriteAsync(),
  243.     dos.library/Write()
  244.