workbench/libs/asyncio/asyncio.doc

   1 TABLE OF CONTENTS
   2
   3 asyncio/CloseAsync
   4 asyncio/FGetsAsync
   5 asyncio/FGetsLenAsync
   6 asyncio/OpenAsync
   7 asyncio/ReadAsync
   8 asyncio/ReadCharAsync
   9 asyncio/ReadLineAsync
  10 asyncio/SeekAsync
  11 asyncio/WriteAsync
  12 asyncio/WriteCharAsync
  13 asyncio/WriteLineAsync
  14 \fasyncio/CloseAsync                                         asyncio/CloseAsync
  15
  16    NAME
  17         CloseAsync -- close an async file.
  18
  19    SYNOPSIS
  20         success = CloseAsync( file );
  21           d0                   a0
  22
  23         LONG CloseAsync( struct AsyncFile * );
  24
  25    FUNCTION
  26         Closes a file, flushing any pending writes. Once this call has been
  27         made, the file can no longer be accessed.
  28
  29    INPUTS
  30         file - the file to close. May be NULL, in which case this function
  31                returns -1 and sets the IoErr() code to ERROR_INVALID_LOCk.
  32
  33    RESULT
  34         result - < 0 for an error, >= 0 for success. Indicates whether closing
  35             the file worked or not. If the file was opened in read-mode,
  36             then this call will always work. In case of error,
  37                 dos.library/IoErr() can give more information.
  38
  39    SEE ALSO
  40         OpenAsync(), dos.library/Close()
  41
  42 \fasyncio/FGetsAsync                                         asyncio/FGetsAsync
  43
  44    NAME
  45         FGetsAsync -- read a line from an async file, fgets-style.
  46
  47    SYNOPSIS
  48         buffer = FGetsAsync( file, buffer, size );
  49           d0                  a0     a1     d0
  50
  51         APTR ReadLineAsync( struct AsyncFile *, APTR, LONG );
  52
  53    FUNCTION
  54         This function reads a single line from an async file, stopping at
  55         either a NEWLINE character or EOF. In either event, UP TO the
  56         number of size specified bytes minus 1 will be copied into the
  57         buffer. It returns the number of bytes put into the buffer,
  58         excluding the null-termination. 0 indicates EOF, and -1 indicates
  59         read error.
  60
  61         If terminated by a newline, the newline WILL be the last character in
  62         the buffer. The string read in IS null-terminated.
  63
  64    INPUTS
  65         file - opened file to read from, as obtained from OpenAsync()
  66         buffer - buffer to read the line into.
  67         size - size of the buffer, in bytes.
  68
  69    RESULT
  70         buffer - Pointer to buffer passed in, or NULL for immediate EOF or
  71             for an error. If NULL is returned for EOF, then
  72             dos.library/IoErr() returns 0.
  73
  74    SEE ALSO
  75         OpenAsync(), CloseAsync(), ReadCharAsync(), WriteLineAsync(),
  76         FGetsLenAsync(), ReadLineAsync(), dos.library/FGets()
  77
  78 \fasyncio/FGetsLenAsync                                   asyncio/FGetsLenAsync
  79
  80    NAME
  81         FGetsLenAsync -- read a line from an async file.
  82
  83    SYNOPSIS
  84         buffer = FGetsLenAsync( file, buffer, size, length );
  85           d0                     a0     a1     d0     a2
  86
  87         APTR FGetsLenAsync( struct AsyncFile *, APTR, LONG, LONG * );
  88
  89    FUNCTION
  90         This function reads a single line from an async file, stopping at
  91         either a NEWLINE character or EOF. In either event, UP TO the
  92         number of size specified bytes minus 1 will be copied into the
  93         buffer. It returns the number of bytes put into the buffer,
  94         excluding the null-termination. 0 indicates EOF, and -1 indicates
  95         read error.
  96
  97         If terminated by a newline, the newline WILL be the last character in
  98         the buffer. The string read in IS null-terminated.
  99
 100    INPUTS
 101         file - opened file to read from, as obtained from OpenAsync()
 102         buffer - buffer to read the line into.
 103         size - size of the buffer, in bytes.
 104         length - pointer to ULONG to hold the length of the line, excluding
 105             the terminating null.
 106
 107    RESULT
 108         buffer - Pointer to buffer passed in, or NULL for immediate EOF or
 109             for an error. If NULL is returned for EOF, then
 110             dos.library/IoErr() returns 0.
 111
 112    SEE ALSO
 113         OpenAsync(), CloseAsync(), ReadCharAsync(), WriteLineAsync(),
 114         FGetsAsync(), ReadLineAsync(), dos.library/FGets()
 115
 116 \fasyncio/OpenAsync                                           asyncio/OpenAsync
 117
 118    NAME
 119         OpenAsync -- open a file for asynchronous IO.
 120
 121    SYNOPSIS
 122         file = OpenAsync( fileName, accessMode, bufferSize
 123          d0                  a0         d0          d1
 124                                                [, sysbase, dosbase ] );
 125                                                     a1       a2
 126
 127         struct AsyncFile *OpenAsync( const STRPTR, LONG, LONG
 128                            [, struct ExecBase *, struct DosLibrary * ] );
 129
 130         file = OpenAsyncFromFH( handle, accessMode, bufferSize
 131                                   a0        d0          d1
 132                                                [, sysbase, dosbase ] );
 133                                                     a1       a2
 134
 135         struct AsyncFile *OpenAsyncFromFH( BPTR, LONG, LONG
 136                            [, struct ExecBase *, struct DosLibrary * ] );
 137
 138    FUNCTION
 139         The named file is opened and an async file handle returned. If the
 140         accessMode is MODE_READ, an existing file is opened for reading.
 141         If accessMode is MODE_WRITE, a new file is created for writing. If
 142         a file of the same name already exists, it is first deleted. If
 143         accessMode is MODE_APPEND, an existing file is prepared for writing.
 144         Data written is added to the end of the file. If the file does not
 145         exists, it is created.
 146
 147         'fileName' is a filename and CANNOT be a window specification such as
 148         CON: or RAW:, or "*"
 149
 150         'bufferSize' specifies the size of the IO buffer to use. There are
 151         in fact two buffers allocated, each of roughly (bufferSize/2) bytes
 152         in size. The actual buffer size use can vary slightly as the size
 153         is rounded to speed up DMA.
 154
 155         If the file cannot be opened for any reason, the value returned
 156         will be NULL, and a secondary error code will be available by
 157         calling the routine dos.library/IoErr().
 158
 159     INPUTS
 160         name - name of the file to open, cannot be a window specification
 161         accessMode - one of MODE_READ, MODE_WRITE, or MODE_APPEND
 162         bufferSize - size of IO buffer to use. 8192 is recommended as it
 163             provides very good performance for relatively little memory.
 164         sysbase - Library base needed for the "no externals" version of the
 165             library.
 166         dosbase - Library base, as sysbase.
 167
 168     RESULTS
 169         file - an async file handle or NULL for failure. You should not access
 170             the fields in the AsyncFile structure, these are private to the
 171             async IO routines. In case of failure, dos.library/IoErr() can
 172             give more information.
 173
 174     NOTES (by MH)
 175         Although stated that CON:, RAW:, or "*" cannot be used as the file
 176         name, tests indicates that the 2.0+ "Console:" volume is safe to
 177         use for writing (haven't tested reading). No guarantees though.
 178
 179         Also note that there is no MODE_READWRITE for AsyncIO. You cannot
 180         read and write to the same AsyncFile.
 181
 182     SEE ALSO
 183         CloseAsync(), dos.library/Open()
 184
 185 \fasyncio/PeekAsync                                           asyncio/PeekAsync
 186
 187    NAME
 188         PeekAsync -- read bytes from an async file without advancing file
 189             pointer.
 190
 191    SYNOPSIS
 192         actualLength = PeekAsync( file, buffer, numBytes );
 193              d0                    a0     a1       d0
 194
 195    FUNCTION
 196         This function tries to read bytes of information from an opened
 197         async file into the buffer given. 'numBytes' is the number of bytes
 198         to read from the file.
 199
 200         The read is done without advancing the file pointer, and the read
 201         is limited to what is available in the current buffer (or the next
 202         buffer, if the current buffer is empty). If the current buffer does
 203         not contain 'numBytes' bytes, only the bytes left in the buffer is
 204         read.
 205
 206         Using PeekAsync() can remove the need to SeekAsync() back after some
 207         ReadAsync() calls (making your read operations more pipe friendly).
 208
 209         The value returned is the length of the information actually read.
 210         So, when 'actualLength' is greater than zero, the value of
 211         'actualLength' is the the number of characters read. A value of
 212         zero means that end-of-file has been reached. Errors are indicated
 213         by a value of -1.
 214
 215     INPUTS
 216         file - opened file to read, as obtained from OpenAsync()
 217         buffer - buffer where to put bytes read
 218         numBytes - number of bytes to read into buffer
 219
 220     RESULT
 221         actualLength - actual number of bytes read, or -1 if an error. In
 222             case of error, dos.library/IoErr() can give more information.
 223
 224     SEE ALSO
 225         OpenAsync(), CloseAsync(), ReadCharAsync(), WriteAsync(),
 226         dos.library/Read()
 227
 228
 229 \fasyncio/ReadAsync                                           asyncio/ReadAsync
 230
 231    NAME
 232         ReadAsync -- read bytes from an async file.
 233
 234    SYNOPSIS
 235         actualLength = ReadAsync( file, buffer, numBytes );
 236              d0                    a0     a1       d0
 237
 238         LONG ReadAsync( struct AsyncFile *, APTR, LONG );
 239
 240    FUNCTION
 241         This function reads bytes of information from an opened async file
 242         into the buffer given. 'numBytes' is the number of bytes to read from
 243         the file.
 244
 245         The value returned is the length of the information actually read.
 246         So, when 'actualLength' is greater than zero, the value of
 247         'actualLength' is the the number of characters read. Usually
 248         ReadAsync() will try to fill up your buffer before returning. A value
 249         of zero means that end-of-file has been reached. Errors are indicated
 250         by a value of -1.
 251
 252     INPUTS
 253         file - opened file to read, as obtained from OpenAsync()
 254         buffer - buffer where to put bytes read
 255         numBytes - number of bytes to read into buffer
 256
 257     RESULT
 258         actualLength - actual number of bytes read, or -1 if an error. In
 259             case of error, dos.library/IoErr() can give more information.
 260
 261     SEE ALSO
 262         OpenAsync(), CloseAsync(), ReadCharAsync(), WriteAsync(),
 263         dos.library/Read()
 264
 265 \fasyncio/ReadCharAsync                                   asyncio/ReadCharAsync
 266
 267    NAME
 268         ReadCharAsync -- read a single byte from an async file.
 269
 270    SYNOPSIS
 271         byte = ReadCharAsync( file );
 272          d0                    a0
 273
 274         LONG ReadCharAsync( struct AsyncFile * );
 275
 276    FUNCTION
 277         This function reads a single byte from an async file. The byte is
 278         returned, or -1 if there was an error reading, or if the end-of-file
 279         was reached.
 280
 281    INPUTS
 282         file - opened file to read from, as obtained from OpenAsync()
 283
 284    RESULT
 285         byte - the byte read, or -1 if no byte was read. In case of error,
 286             dos.library/IoErr() can give more information. If IoErr()
 287             returns 0, it means end-of-file was reached. Any other value
 288             indicates an error.
 289
 290    SEE ALSO
 291         OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync()
 292         dos.library/Read()
 293
 294 \fasyncio/ReadLineAsync                                   asyncio/ReadLineAsync
 295
 296    NAME
 297         ReadLineAsync -- read a line from an async file.
 298
 299    SYNOPSIS
 300         bytes = ReadLineAsync( file, buffer, size );
 301          d0                     a0     a1     d0
 302
 303         LONG ReadLineAsync( struct AsyncFile *, APTR, ULONG );
 304
 305    FUNCTION
 306         This function reads a single line from an async file, stopping at
 307         either a NEWLINE character or EOF. In either event, UP TO the
 308         number of size specified bytes minus 1 will be copied into the
 309         buffer. It returns the number of bytes put into the buffer,
 310         excluding the null-termination. 0 indicates EOF, and -1 indicates
 311         read error.
 312
 313         If the line in the file is longer than the buffer, the line will be
 314         truncated (any newline will be present). Any data left in the file
 315         upto the newline will be lost.
 316
 317         If terminated by a newline, the newline WILL be the last character in
 318         the buffer. The string read in IS null-terminated.
 319
 320    INPUTS
 321         file - opened file to read from, as obtained from OpenAsync()
 322         buffer - buffer to read the line into.
 323         size - size of the buffer, in bytes.
 324
 325    RESULT
 326         bytes - number of bytes read. In case of error (-1 is returned)
 327             dos.library/IoErr() can give more information. EOF is indicated
 328             by a return of 0.
 329
 330    SEE ALSO
 331         OpenAsync(), CloseAsync(), ReadCharAsync(), FGetsAsync(),
 332         WriteLineAsync(), dos.library/FGets()
 333
 334 \fasyncio/SeekAsync                                           asyncio/SeekAsync
 335
 336    NAME
 337         SeekAsync -- set the current position for reading or writing within
 338             an async file.
 339
 340    SYNOPSIS
 341         oldPosition = SeekAsync( file, position, mode );
 342              d0                   a0      d0      d1
 343
 344         LONG SeekAsync( struct AsyncFile *, LONG, LONG );
 345
 346    FUNCTION
 347         SeekAsync() sets the read/write cursor for the file 'file' to the
 348         position 'position'. This position is used by the various read/write
 349         functions as the place to start reading or writing. The result is the
 350         current absolute position in the file, or -1 if an error occurs, in
 351         which case dos.library/IoErr() can be used to find more information.
 352         'mode' can be MODE_START, MODE_CURRENT or MODE_END. It is used to
 353         specify the relative start position. For example, 20 from current
 354         is a position 20 bytes forward from current, -20 is 20 bytes back
 355         from current.
 356
 357         To find out what the current position within a file is, simply seek
 358         zero from current.
 359
 360     INPUTS
 361         file - an opened async file, as obtained from OpenAsync()
 362         position - the place where to move the read/write cursor
 363         mode - the mode for the position, one of MODE_START, MODE_CURRENT,
 364             or MODE_END.
 365
 366     RESULT
 367         oldPosition - the previous position of the read/write cursor, or -1
 368             if an error occurs. In case of error, dos.library/IoErr() can
 369             give more information.
 370
 371     NOTES (by MH)
 372         If you seek after having read only a few bytes, the function must
 373         wait for both buffers to be loaded, before the seek can be done.
 374         This can cause small delays. Note that the above case isn't the
 375         only one, but the typical one.
 376
 377     SEE ALSO
 378         OpenAsync(), CloseAsync(), ReadAsync(), WriteAsync(),
 379         dos.library/Seek()
 380
 381 \fasyncio/WriteAsync                                         asyncio/WriteAsync
 382
 383    NAME
 384         WriteAsync -- write data to an async file.
 385
 386    SYNOPSIS
 387         actualLength = WriteAsync( file, buffer, numBytes );
 388              d0                     a0     a1       d0
 389
 390         LONG WriteAsync( struct AsyncFile *, APTR, LONG );
 391
 392    FUNCTION
 393         WriteAsync() writes bytes of data to an opened async file. 'numBytes'
 394         indicates the number of bytes of data to be transferred. 'buffer'
 395         points to the data to write. The value returned is the length of
 396         information actually written. So, when 'actualLength' is greater
 397         than zero, the value of 'actualLength' is the number of characters
 398         written. Errors are indicated by a return value of -1.
 399
 400     INPUTS
 401         file - an opened file, as obtained from OpenAsync()
 402         buffer - address of data to write
 403         numBytes - number of bytes to write to the file
 404
 405     RESULT
 406         actualLength - number of bytes written, or -1 if error. In case
 407             of error, dos.library/IoErr() can give more information.
 408
 409     SEE ALSO
 410         OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync(),
 411         dos.library/Write()
 412
 413 \fasyncio/WriteCharAsync                                 asyncio/WriteCharAsync
 414
 415    NAME
 416         WriteCharAsync -- write a single byte to an async file.
 417
 418    SYNOPSIS
 419         result = WriteCharAsync( file, byte );
 420           d0                      a0    d0
 421
 422         LONG WriteCharAsync( struct AsyncFile *, UBYTE );
 423
 424    FUNCTION
 425         This function writes a single byte to an async file.
 426
 427    INPUTS
 428         file - an opened async file, as obtained from OpenAsync()
 429         byte - byte of data to add to the file
 430
 431    RESULT
 432         result - 1 if the byte was written, -1 if there was an error. In
 433             case of error, dos.library/IoErr() can give more information.
 434
 435    SEE ALSO
 436         OpenAsync(), CloseAsync(), ReadAsync(), WriteAsync(),
 437         dos.library/Write()
 438
 439 \fasyncio/WriteLineAsync                                 asyncio/WriteLineAsync
 440
 441    NAME
 442         WriteLineAsync -- write a line to an async file.
 443
 444    SYNOPSIS
 445         bytes = WriteLineAsync( file, buffer );
 446
 447         LONG WriteLineAsync( struct AsyncFile *, STRPTR );
 448
 449    FUNCTION
 450         This function writes an unformatted string to an async file. No
 451         newline is appended to the string.
 452
 453    INPUTS
 454         file - opened file to read from, as obtained from OpenAsync()
 455         buffer - buffer to write to the file
 456
 457    RESULT
 458         bytes - number of bytes written, or -1 if there was an error. In
 459             case of error, dos.library/IoErr() can give more information.
 460
 461    SEE ALSO
 462         OpenAsync(), CloseAsync(), ReadCharAsync(), WriteCharAsync(),
 463         FGetsAsync(), FGetsLenAsync(), ReadLineAsync(), dos.library/FPuts()
 464