rdmmapi - synchronized read

SYNOPSIS

int    rdmmapi(buf,bufsize,fp,mp)
char  *buf;
int    bufsize;
FILE  *fp;
MMAPI *mp;

bool freadex_strip8;

DESCRIPTION

buf            where to put the data
bufsize        the maximum number of bytes that will fit in buf
fp             the file to read from which must be opened binary ("rb")
mp             the Metamorph 3 API to synchronize for

freadex_strip8 controls whether the high bit will be stripped from
               incoming data

This function works very much like fread() with one important exception; it guarantees that a hit will not be broken across a buffer boundary. The way it works is as follows:

1. A normal fread() for the number of requested bytes is performed.

2. rdmmapi() searches backwards from the end of the buffer for an occurrence of the ending delimiter regular expression.

3. The data that is beyond the last occurrence of an ending delimiter is pushed back into the input stream. (The method that is used depends on whether an fseek() can be performed or not.)

If the freadex_strip8 global variable is non-zero the 8th bit will be stripped off all of the incoming data. This is useful for reading WordStar(C) and other files that set the high bit. Setting freadex_strip8 incurs a speed penalty because every byte read gets stripped. Don't use this flag unless it is absolutely necessary.

rdmmapi() should be used any time you are doing delimited searches. An unsynchronized read can cause hits to be missed.

DIAGNOSTICS
rdmmapi() returns the number of bytes actually read into buf or (-1) if there was an error.