kai_util - KDOS Asynchronous I/O Utilities

The KAI_UTIL package allows programs to asynchronously access the KDOS file server. The package is patterned after the Solaris asynchronous I/O library, which includes four functions: aioread(3), aiowrite(3), aiowait(3), and aiocancel(3). The KAI_UTIL package has kai counterparts to the Solaris functions and adds functions for opening and closing files, etc.

KDOS files can be opened for reading or writing:

    #include  "kai_util.h"	/* KDOS asynchronous I/O library. */
    int  newFd, oldFd ;
    ...
    newFd = kaiOpen ("newFile", O_WRONLY, 0) ;
    oldFd = kaiOpen ("oldFile", O_RDONLY, 0) ;

Functions such as kaiOpen(), kaiClose(), kaiDelete(), etc. are synchronous operations: the function waits until the desired operation is completed by the KDOS file server before returning to the caller. Reading from and writing to a KDOS file are the only operations which can be performed asynchronously using the KAI_UTIL package.

To asynchronously read from or write to a KDOS file, you must first allocate a result block for each outstanding, asynchronous operation. The desired operation is then queued up for processing by the KDOS file server (which may be on a separate card). When an operation completes, the results of the operation will be stored in the corresponding result block.

For example, the following code fragment issues 3 write requests to the KDOS file server:

    char  buffer1[128], buffer2[64], buffer3[256] ;
    KaiResult  result[3] ;
    ...
    kaiWrite (newFd, buffer1, sizeof buffer1, 0, SEEK_CUR, &result[0]) ;
    kaiWrite (newFd, buffer2, sizeof buffer2, 0, SEEK_CUR, &result[1]) ;
    kaiWrite (newFd, buffer3, sizeof buffer3, 0, SEEK_CUR, &result[2]) ;

(Since the KDOS file system doesn't support seeking, 0/SEEK_CUR is the effective behavior of read and write operations, regardless of what you specify in the offset/whence arguments.) When the KDOS file server is on another card, the buffers passed into kaiRead() and kaiWrite() must be accessible from the KDOS file server's card. kaiRead() and kaiWrite() transparently pass the VME addresses of their buffers to the KDOS file server.

The KaiResult structure passed to kaiRead() and kaiWrite() has several fields of interest to a client application:

• errNo - is initialized to EINPROGRESS when the I/O request is issued. When the completion of the request is detected by kaiWait() (see below), errNo will receive the ERRNO code returned by the operation.
  
  
• ioReturn - receives the I/O return value when the request completes. This value is simply the return value of a normal read(2) or write(2) call; i.e., the number of bytes read or written.
  
  
• userData - is a void * pointer which can be set by the client application for whatever purpose it desires.

Once an I/O request has been issued, the application program can go do something else and check back later to see if the request has completed. Waiting for an operation to complete is accomplished by calling kaiWait(). Assuming the three outstanding kaiWrite()s from the example above, you can simply wait for the last request to complete:

    KaiResult  *r ;
    ...
    while (result[2].errNo == EINPROGRESS) {
        r = kaiWait (-1.0) ;
        if ((r == &result[2]) || (r == NULL))  break ;
    }

Since requests are processed in first-in/first-out order by the KDOS file server, the first two kaiWrite() requests will complete before the last request completes. The test for EINPROGRESS in the WHILE loop is necessary in case another kaiWait() has processed the target request's completion status. For example, if kaiClose() was called immediately after issuing the three kaiWrite() requests, the kaiWait() loop inside of the synchronous kaiClose() would have already seen and processed the request completions resulting from the kaiWrite()s. It would then be unnecessary to go into the explicit kaiWait() loop above.

A KDOS file can be closed and/or deleted:

    kaiClose (newFd) ;
    kaiDelete ("newFile") ;

The following code fragment uses kaiList() to scan the KDOS directory and kaiStat() to obtain information about individual KDOS files:

    char  *fileName ;
    int  i = 0 ;
    struct  stat  info ;
    ...
    while (fileName = kaiList (i++)) != NULL) {
        kaiStat (fileName, &info) ;
        printf ("%s (%ld bytes)\n", fileName, info.st_size) ;
    }

Public Procedures

kaiCancel() - cancels an outstanding I/O request. (Not Supported)

kaiClose() - closes a KDOS file.

kaiDelete() - deletes a KDOS file.

kaiList() - retrieves the name of a KDOS file.

kaiOpen() - opens a KDOS file.

kaiRead() - enqueues a READ request on a KDOS file.

kaiReadW() - enqueues a READ request and waits until the READ completes.

kaiRename() - renames a KDOS file.

kaiStat() - retrieves information about a KDOS file.

kaiWait() - waits for the next I/O request to complete.

kaiWrite() - enqueues a WRITE request on a KDOS file.

kaiWriteW() - enqueues a WRITE request and waits until the WRITE completes.

Public Variables

kdosdMailboxName - specifies the name of the KDOS file server's command mailbox in the following format: "name@card". The default is "KdosdCommand@RE1", which assumes the KDOS file server is running on the RE1 card.

Source Files

kai_util.c

kai_util.h