The user interface

All of the functions needed to carry out basic I/O are described in this subsection. Proper declarations of these routines are provided by the header file psio.h. Note that before any open/close functions may be called, the input parsing library, libipv1 must be initialized so that the necessary file striping information may be read from user input, but this is hidden from the programmer in lower-level functions. NB, ULI is used as an abbreviation for unsigned long int in the remainder of this manual.

int psio_init(void): Before any files may be opened or the basic read/write functions of libpsio may be used, the global data needed by the library functions must be initialized using this function.

int psio_done(void): When all interaction with the direct-access files is complete, this function is used to free the library's global memory.

int psio_open(ULI unit, int status): Opens the direct access file identified by unit. The status flag is a boolean used to indicate if the file is new (0) or if it already exists and is being re-opened (1). If specified in the user input file, the file will be automatically opened as a multivolume (striped) file, and each page of data will be read from or written to each volume in succession.

int psio_close(ULI unit, int keep): Closes a direct access file identified by unit. The keep flag is a boolean used to indicate if the file's volumes should be deleted (0) or retained (1) after being closed.

int psio_read_entry(ULI unit, char *key, char *buffer, ULI size): Used to read an entire TOC entry identified by the string key from unit into the array buffer. The number of bytes to be read is given by size, but this value is only used to ensure that the read request does not exceed the end of the entry. If the entry does not exist, an error is printed to stderr and the program will exit.

int psio_write_entry(ULI unit, char *key, char *buffer, ULI size): Used to write an entire TOC entry idenitified by the string key to unit into the array buffer. The number of bytes to be written is given by size. If the entry already exists and its data is being overwritten, the value of size is used to ensure that the write request does not exceed the end of the entry.

int psio_read(ULI unit, char *key, char *buffer, ULI size, psio_address sadd, psio_address *eadd): Used to read a fragment of size bytes of a given TOC entry identified by key from unit into the array buffer. The starting address is given by the sadd and the ending address (that is, the entry-relative address of the next byte in the file) is returned in *eadd.

int psio_write(ULI unit, char *key, char *buffer, ULI size, psio_address sadd, psio_address *eadd): Used to write a fragment of size bytes of a given TOC entry identified by key to unit into the array buffer. The starting address is given by the sadd and the ending address (that is, the entry-relative address of the next byte in the file) is returned in *eadd.

The page/offset address pairs required by the preceeding read and write functions are supplied via variables of the data type psio_address, defined by:

  typedef struct {
    ULI page;
    ULI offset;
  } psio_address;

The PSIO_ZERO defined in a macro provides a convenient input for the 0/0 page/offset.