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