Disclaimer
Information in this document is subject to change without notice.
Companies, names, and data used in examples (other than those
standard to the machine used for the manuals development) are
fictitious.  This document may be not be distributed outside of
this package without the express written permission of Global
Constructs.  Global Constructs, its logos and slogans are
trademarks of Global Constructs. Microsoft, Windows, and Windows
95 are trademarks of Microsoft Corporation.  Other trademarks,
trade names, service marks, or service names belong to their
respective companies.  Global Constructs denies any proprietary
interest in trademarks and trade names other than its own.

Copyright  1997, by Global Constructs.  All rights reserved.






               Memory Library Programming Toolkit
                          Version 2.05
                                
          A memory based file system supporting normal,
                stacked, and synchronized files.
                                
                      by Global Constructs.
                                
                                
                                
                                
                 Use a Courier 10 point font for
                  optimal viewing of this file.
                        Table of Contents


Introduction                                                    1
     Installation                                               1
     Contents                                                   1

Notices and Legal Information                                   2
     Freeware                                                   2
     Distribution                                               2
     Warranty and Licensing Information                         2

Why Should I Register?                                          4
     Additional Licensing Information                           4
     Ordering the Registered Version                            4

Technical Support                                               5
     Reporting Bugs                                             5

How To Use Product                                              6
     Library Reference                                          7
          errmem                                                8
          ftruncate                                             9
          mclose                                               10
          mcreat                                               11
          mdup 12
          meof 13
          mheapsize                                            14
          minfo                                                15
          mopen                                                16
          mpeek                                                18
          mpull                                                19
          mpush                                                20
          mread                                                21
          mseek                                                22
          msetsize                                             23
          mstat                                                24
          mstrerr                                              25
          msync                                                26
          mtell                                                27
          mtruncate                                            28
          mwrite                                               29

Version History                                                30

Performance Tests                                              31


Introduction

The Memory Library Programming Toolkit is a versatile module for
C and C++ programmers who require a fast and simple to use memory
or stacked based file system.  The Memory Library provides many
advantages over disk based temporary files or custom coding of
stacked based arrays.

*    Faster access to temporary files than disk based temporary
     files.  Many memory files of any type may be opened and
     accessible at any given time.
*    Function calls with a POSIX-like naming convention provide
     quick understanding and porting from similarly called POSIX
     routines.
*    Full support for file access and manipulation using almost
     20 functions.
*    Quick and easy use of first-in/first-out (FIFO) and first-
     in/last-out (FILO) memory file types (note an FILO file is
     equivalent to LIFO).  Avoids the work of custom designing an
     array-based FIFO or FILO stack each time that you need one.
*    A memory file may be opened and pre-loaded with a disk based
     file, permitting continuation from a pre-saved point.
*    The Memory Library provides customizable synchronization of
     its memory files to a disk-based file to provide an automated
     method of protecting information.
*    Memory files may be created with no filename for easier
     implementation of a temporary file.
*    Memory files may be limited to a maximum file size by you
     for those instances where you do not wish them to consume too
     much memory.
*    Stacked memory files (FIFO/FILO) dynamically grow and shrink
     thereby only using as much memory as is necessary to maintain the
     file.  Stack overflows are also avoided unless an Out Of Memory
     condition is reached naturally or by a maximum file size limit
     being set.
*    Normal random access memory files are dynamic in size, using
     only as much memory as what is required to maintain the file.
*    Disk caching is reduced since the Memory Library uses no
     form of caching for its memory files.

Version 2.05 of the Memory Library Programming Toolkit has been
tested with Watcom C/C++ 10.6, Borland C++ 4.02, Code Warrior 6,
Code Warrior Gold 11, Gnu C compiler with FreeBSD versions 2.1.5r
and 2.2a.

Installation

See the file install.txt for instructions on installing the
Memory Library Programming Toolkit.

Contents

See the file contents.txt for a list of files included in the
Memory Library Package.

Notices and Legal Information

Freeware

This program is Freeware, copyrighted, and not in the Public
Domain.  This product, including the source code, may be freely
used by an individual for personal, non-commercial purposes.  Use
of this product within a business, for commercial use, or for
commercial purposes requires the purchase and registration of the
product.  Use of this product outside of the limitations specified
here are in violation of the copyright.  Please support this
product by becoming a registered user.

Distribution

This freeware version may be distributed in its entirety, without
the express written permission of Global Constructs.  It may be
freely distributed in its entirety for non-commercial purposes.
Commercial distribution of this product requires the express
written permission of Global Constructs.

This freeware product is for personal use only.  No product,
program, or library created with the use of this freeware product
may be distributed freely or otherwise.

In no way does the purchase of this freeware product as part of a
shareware/freeware collection from a distributor or any other
agent provide or guarantee a registration of the product with
Global Constructs.  Any registration or registered support of
this product is provided to registered users only.  To become a
registered user see the section Why Should I Register and the
order form in the file order.txt.

Warranty and Licensing Information

By using the software, the licensee agrees to abide by the
copyright law and all other applicable laws of the United States.
Including, but not limited to, export control laws, and the terms
of this license. Global Constructs shall have the right to,
terminate this license immediately by written notice upon the
licensee's breach of, or non-compliance with, any of its terms.
The licensee may be held legally responsible for any copyright
infringement that is caused or encouraged by the licensee's
failure to abide by the terms of this license.

     THIS  SOFTWARE  AND ACCOMPANYING WRITTEN  MATERIALS  IS
     PROVIDED  "AS IS" WITHOUT WARRANTY OF ANY KIND,  EITHER
     EXPRESS  OR IMPLIED, INCLUDING WITHOUT LIMITATION,  THE
     IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR  A
     PARTICULAR  PURPOSE GLOBAL CONSTRUCTS DOES NOT  WARRANT
     THAT  THE FUNCTIONS CONTAINED IN THE SOFTWARE  WILL  BE
     UNINTERRUPTED OR ERROR-FREE. THE ENTIRE RISK AS TO  THE
     QUALITY  AND  PERFORMANCE  OF  THE  SOFTWARE  IS   WITH
     LICENSEE.

     IN  NO  EVENT  WILL  GLOBAL  CONSTRUCTS  BE  LIABLE  TO
     LICENSEE  OR ANY THIRD PARTY FOR ANY DAMAGES  INCLUDING
     ANY  LOST  PROFITS,  LOST SAVINGS OR OTHER  INCIDENTAL,
     CONSEQUENTIAL OR SPECIAL DAMAGES ARISING OUT OF THE USE
     OR   INABILITY  TO  USE  THE  PRODUCT  EVEN  IF  GLOBAL
     CONSTRUCTS HAS BEEN ADVISED OF THE POSSIBILITY OF  SUCH
     DAMAGES.
     
                         ACKNOWLEDGMENT

     BY  USING  THE  FREEWARE VERSION OF THE MEMORY  LIBRARY
     PROGRAMMING TOOLKIT YOU ACKNOWLEDGE THAT YOU HAVE  READ
     THIS  LIMITED WARRANTY, UNDERSTAND IT AND AGREE  TO  BE
     BOUND  BY  THOSE TERMS AND CONDITIONS AS SET  FORTH  IN
     THIS WARRANTY AND LICENSE.

After  payment is received by Global Constructs, the use of  this
software  is  limited  to use on only one  personal  computer  or
workstation which is not used as a server.  An additional payment
is  required  for  use  on each additional personal  computer  or
workstation.   For information on a site license  contact  Global
Constructs   at   sales@globalconstructs.com  or  the   following
address.

     Global Constructs
     P.O. Box 200305
     Arlington, TX 76006
     (817) 275-5114

Any use of this product if in violation of the above restrictions
is not protected nor provided for by the license.

Why Should I Register?

Registration of the Memory Library Programming Toolkit provides
the following benefits.

1.   You are planning to use the product within a commercial
     product, environment, or on a network server.
2.   All programs created with the registered version of the
     Memory Library Programming Toolkit are royalty free.
3.   Technical support is available by email, phone, or postal
     mail.
4.   Technical support is provided for a period of six (6) months
     from the date of registration of the Memory Library
     Programming Toolkit.

Additional Licensing Information

The following applies to the registered version of the product
and is in addition to that information provided in the Warranty
and Licensing Information section, except where this information
replaces the aforementioned section.  If any condition of this
agreement is held by a court of competent jurisdiction to be
invalid, void or unenforceable, the rest of the agreement shall
remain in full force and effect and shall in no way be affected,
impaired or invalidated.

After payment is received by Global Constructs, the use of this
software is limited to use on only one personal computer or
workstation which is not used as a server.  An additional payment
is required for use on each additional personal computer or
workstation.  For information on a site license contact Global
Constructs.

This product may be used royalty free for the purposes of using
its functionality within a program.  This product may not be
distributed or sold as part of a development package without the
express permission of Global Constructs.  This includes but is
not limited to its use in a dynamic or shared run-time library
which is made available to consumers or developers.

You must retain all copyright or other notices marked within the
product and on all copies and programs developed with this
product.

Ordering the Registered Version

To order the registered version see order.txt.

Technical Support

Technical support for the Memory Library Programming Toolkit is
provided to all users via our email address.

     support@globalconstructs.com

Registered users may also contact us by phone or regular postal
mail at the following address.

     Global Constructs
     Attn. Technical Support
     P.O. Box 200305
     Arlington, TX 76006
     (817) 275-5114

Be sure to include your registration number on correspondence to
ensure prompt service.  The phone number provided is equipped
with voice mail.  If support does not answer then follow the
directions provided to leave a message and we will return your
call.

Reporting Bugs

In the event you discover a bug or wish to comment on the
product, please complete the information requested in bugform.txt
and send it to us, or use the Technical Report Form located at
our web site: www.globalconstructs.com.  Bug fixes will be
considered on the current version only.  We will make an effort
to direct you to any existing patches still available for any
older version.

How To Use Product

The Memory Library Programming Toolkit is a group of source code
and header files designed to enhance your programming effort.
The toolkit is equipped with an extensive set of functions which
enable the programmer to quickly and effortlessly create stack
based files or normal random access files in memory.  This
library is designed for the C programmer, with extensions
permitted for the C++ user.

To use the functions in the library you must include the file
memfile.h in any source files that you wish to take advantage of
the Memory Library Programming Toolkit.  A line such as,

#include memfile.h

will suffice.  Be sure to include the path to the header in your
include path before compiling.

The included functions are designed in the same format and
operation as their POSIX equivalents.  The following table
demonstrates this.

                                        
Memory Lib    POSIX       |Memory Lib   POSIX
===========   =========== |==========   =============
mclose        close       |mpush        No Equivalent
                          |
mcreat        creat       |mread        read
                          |
mdup          dup         |mseek        lseek
                          |
meof          eof         |msetsize     No Equivalent
                          |
mheapsize     No          |mstat        stat
              Equivalent  |
minfo         No          |mstrerr      strerr
              Equivalent  |
mopen         open        |msync        No Equivalent
                          |
mpeek         No          |mtell        tell or
              Equivalent  |             lseek(fh,0,SEEK_CUR)
                          |
mpull         No          |mtruncate    ftruncate
              Equivalent  |
                          |mwrite       write

One other function that is not listed here is available in the
static library in some systems.  The function ftruncate() is used
by the memory library.  For compatibility see the appropriate doc
page in the following Library Reference section.

There is also a replacement error control variable to errno.  Any
errors which occur in the Memory Library functions will return an
error in errmem.

Library Reference

The following section is provided as a library reference to the
functions, error variable, and constants available in this
library.

The library is listed alphabetically with one document per page.
The function pages will list the function, a description of its
operation, its return value and parameters, the errors it
generates if any, and any known bugs or limitations (KBL) at this
time.  The use of constants are also listed as appropriate for
each function.

The following type definitions are used within memfile.h and
throughout this document.

typedef signed long           int32;
typedef unsigned long         int32u;
typedef signed short          int16;
typedef unsigned short        int16u;


errmem

Format    int16 errmem;

The variable errmem is used for passing all error conditions from
the Memory Library to the program.  It is unnecessary to declare
errmem, it has already been declared in the library.  An external
reference is defined in memfile.h.

The following error values may be set in the variable errmem.
When errmem equals zero no error has occurred.

     accessModeConflict       More than one of the following is being
                              attempted for the same file: I_RDONLY,
                              I_WRONLY, I_RDWR
     badFileHandle            Bad or invalid file handle
     diskReadError            Error occurred while loading disk
                              based file
     exclAccessDenied         File already open with another file
                              handle
     exclCreateFailed         File exists and cannot be created
                              for exclusive access
     fileDoesNotExist         File to be opened does not exist
     fileModeConflict         More than one file type is set
     fileNotReadable          File mode or access does not permit
                              reading
     fileNotWritable          File mode or access does not permit
                              writing
     invalidBufferPtr         NULL pointer provided on mread,
                              mwrite, mpush, or mpull
     invalidParameter         Invalid parameter value set
     loadFailFileExists       Disk file failed to load due to existing
                              memory file
     loadFailModeConflict     Disk file failed to load due to
                              conflict with its file mode (read only,
                              write only, etc.)
     maxFileSizeExceeded      Maximum file size limitation exceeded
     noTruncOnRead            file truncation is not permitted on
                              a read only file
     outOfMemory              Insufficient memory to perform
                              operation
     pullNotAllowed           pull not permitted on normal file,
                              use read instead
     stackFileDup             Stacked memory files are allowed
                              one file handle only
     stackFileSeek            Stacked files may get current
                              position only
     stackFileRead            Read not permitted on stacked file,
                              use pull instead
     syncDiskFileOnly         Sync on opening of non-disk file
                              attempted
     syncSeekFailure          Seek on disk based sync file failed
                              on synchronization
     syncWriteFailure         Write on disk based sync file
                              failed to synchronize
     seekPastBeginning        Seek attempted to before beginning
                              of the file
     tooManyOpenHandles       all available file handles are assigned

ftruncate

     int ftruncate (int handle, off_t newsize)

     Truncates file to new size if the file was larger than
     newsize.  This is included on those systems which do not
     support ftruncate.

     Parameters
     handle    File handle number
     newsize   Size to change file to if larger

     Returns zero if successful, otherwise -1 and errno is set.

     Errors
     EACCES    Access denied to file.
     EBADF     Bad file handle number.
     ENOSPC    Not enough space on device to perform operation.

     KBLs None.

mclose

     int16 mclose (int16 handle)

     Closes memory file and releases all memory.  It will close
     any related disk based file which is synchronized.

     Parameter
     handle              File handle number.

     Returns zero if successful.  Otherwise, it returns -1 and
     errmem is set to indicate the error.

     Errors
     badFileHandle
     syncSeekFailure
     syncWriteFailure

     KBLs Closure of the last file handle for the memory file
          removes it from memory losing all information.

mcreat

     int16 mcreat (int16 handle, int16u mode)

     Creates a memory file and sets it to size zero.  It is
     implemented as a macro calling mopen() as follows.

     #define mcreat(a,b) mopen(b, I_WRONLY | I_CREAT | I_TRUNC, c)

     See mopen for further detail.

mdup

     int16 mdup (int16 handle)

     Duplicates file handle given as parameter and returns new
     file handle which also points to the memory file.

     Parameter
     handle              File handle number.

     Returns the new file handle, or -1 on an error and errmem is
set.

     Errors
     badFileHandle
     stackFileDup
     exclAccessDenied
     outOfMemory
     tooManyOpenHandles

     KBLs None.

meof

     int16 meof (int16 handle)

     Tests for end of file for memory file.

     Parameter
     handle              File handle number.

     Returns 1 if at end of file, 0 if not at end of file, and -1
     on an error and errmem is set.

     Error
     badFileHandle

     KBLs None.

mheapsize

     void mheapsize (int32 heapsize)

     Changes the default file allocation size.  To reset the heap
     size to the default, set the parameter to zero (0L).  Heap
     size requests of less than zero set the heap size to the
     default.

     Parameter
     heapsize  Size in bytes to set allocation to, four byte
               boundary aligned.

     Void return.

     KBLs The function will set the heap size to the next
          available four byte boundary size if a non-four byte
          boundary value is provided.

minfo

     fileInfo *minfo (int16 handle)

     Gets detailed information on a particular memory file.  This
     routine allocates space for this information so be sure to
     call free(fileInfo *) when finished.  The fileInfo structure
     is defined as follows.

     typedef struct _fileinfo {
          int32 filesize;          /* size of file in bytes */
          int32 maxfilesize;  /* maximum file size to write */
          int32 totalclusters;     /* total memory reserved for file */
          int32u filemode;         /* type of memory file */
          int16u syncrate;         /* sync rate for the memory file */
          int16u synccount;   /* # of writes before synchronization */
          int16 numsegments;  /* number of memory segments for file */
     } fileInfo;

     Parameter
     handle              File handle number.

     Returns a pointer to a fileInfo structure, or NULL on an
     error with errmem set.

     Errors
     badFileHandle
     outOfMemory

     KBLs None.

mopen

     int mopen (const char *path, int16 access, int16u mode)

     Opens a memory file for read, write, append, and create
     access.

     Parameters
     path           A NULL pointer may be passed for the
               filename, doing so will create a file with no
               name.  Multiple uses of this method will create
               multiple files, not multiple file handles to the
               same file.

     access    The access mode is established by a combination of
               the bits defined as follows.
               
          I_RDONLY  Access the memory file for read access only
          I_WRONLY  Access the memory file for write access only
          I_RDWR    Access the memory file for read and write
                    access
          I_APPEND  Writes will occur at the end of the memory
                    file
          I_CREAT   Create the memory file if it does not already
                    exist
          I_TRUNC   Truncate the memory file
          I_BINARY  Open the file in binary mode, which does not
                    change the data on a read/write or push/pull.
                    This is the default access mode whether or
                    not it has been specified.
          I_EXCL    Open a memory file for exclusive access.  If
                    the file exists and then the open will fail
                    (since there is a file handle assigned to
                    that file already).
          I_LOAD    Create a memory file and load a disk based
                    file into it.  If the memory file exists then
                    the open will fail.  I_CREAT is set by
                    default when I_LOAD is set, whether or not
                    I_CREAT has been specified.

     mode The file mode permissions for the file are specified by
          an optional argument as a combination of bits as
          follows.  The mode parameter is ignored unless the
          access mode bit I_CREAT or I_LOAD is set and the file
          does not exist.

          M_IREAD   Permit read access to the created memory file
          M_IWRITE  Permit write access to the created memory file
          M_IFIFO   Set file type as a first-in/first-out memory file
          M_IFILO   Set file type as a first-in/last-out memory file

     A stacked file (FIFO or FILO) may be opened with one I_RDWR
     file handle or one I_RDONLY and I_WRONLY file handle only.
     Note that multiple stacked memory files may be open at one
     time.

     Note that use of a NULL pointer in the filename parameter is
     not POSIX compliant if you intend on changing the memory
     file code to POSIX code.  File types of FIFO and FILO will
     produce file types normal for your system if NOMEMFILE_H is
     defined.

mopen (continued)

     Returns a handle for the file.  When an error occurs while
     opening the file, -1 is returned and the variable errmem is
     set.  A disk file loaded as a memory file can return a file
     handle and set errmem.  This can occur in such cases as a
     partial read or disk I/O error.

     Errors
     fileModeConflict
     accessModeConflict
     loadFailFileExists
     loadFailModeConflict
     exclCreateFailed
     exclAccessDenied
     fileNotReadable
     fileNotWritable
     stackFileDup
     noTruncOnRead
     fileDoesNotExist
     syncDiskFileOnly
     outOfMemory
     diskReadError
     tooManyOpenHandles

     KBLs 'path' is stored as a filename without regard for
          current paths or other conventions.
          Wildcards and special characters are considered valid
          characters in filename.
          All files are handled as binary only.
          Shared memory files are not supported.

mpeek

     int32 mpeek (int16 handle, void *buffer, int32u len)

     Reads a memory block from the beginning of the stack for
     FIFO operations, the end of the stack for FILO operations,
     or the current file position for normal files changing the
     file position or size.

     Parameters
     handle    File handle number
     buffer    Pointer to input buffer
     len       Length of record to read into the buffer

     Returns the number of bytes read from the file.  When there
     is no error, this is the number given by the len argument.
     When the end of the file is encountered before the read
     completes, the return value will be less than the number of
     bytes requested.  A value of -1 may be returned in the case
     of some input errors.  When an error has occurred, errmem
     contains a value indicating the type of error that has been
     detected.

     Errors
     badFileHandle
     invalidBufferPtr
     fileNotReadable

     KBLs As mopen().

mpull

     int32 mpull (int16 handle, void *buffer, int32u len)

     Reads a memory block from the beginning of the stack for
     FIFO operations or the end of the stack for FILO operations,
     reducing the size of the stack file in the process.

     Parameters
     handle    File handle number
     buffer    Pointer to input buffer
     len       Length of record to read into the buffer

     Returns the number of bytes read from the file.  When there
     is no error, this is the number given by the len argument.
     When the end of the file is encountered before the read
     completes, the return value will be less than the number of
     bytes requested.  A value of -1 may be returned in the case
     of some input errors.  When an error has occurred, errmem
     contains a value indicating the type of error that has been
     detected.

     Errors
     badFileHandle
     invalidBufferPtr
     pullNotAllowed
     fileNotReadable
     syncSeekFailure
     syncWriteFailure

     KBLs As mopen().

mpush

     int16 mpush (int16 handle, void *buffer, int32u length)

     Writes to the end of a stacked memory file.  It is
     implemented as a macro calling mwrite() as follows.

     #define mpush  mwrite

     See mwrite for further detail.

mread

     int32 mread (int16 handle, void *buffer, int32u len)

     Reads a memory block from the current file position.

     Parameters
     handle    File handle number.
     buffer    Pointer to buffer to read record into.
     len       Length of record to read.

     Returns the number of bytes read from the file.  When there
     is no error, this is the number given by the len argument.
     When the end of the file is encountered before the read
     completes, the return value will be less than the number of
     bytes requested.  A value of -1 may be returned in the case
     of some input errors.  When an error has occurred, errmem
     contains a value indicating the type of error that has been
     detected.

     Errors
     badFileHandle
     invalidBufferPtr
     stackFileRead

     KBLs As mopen().

mseek

     int32 mseek (int16 handle, int32 offset, int16 whence)

     Sets file position of memory file.

     Parameters
     handle    File handle numbers.
     offset    Value to shift file position depending upon whence
               value.
     whence    Position from which to start offset.  Valid values are

          SEEK_SET  Offset from start of memory file
          SEEK_CUR  Offset from current file position
          SEEK_END  Offset from end of memory file

     Returns file position if successful.  Otherwise, it returns
     -1 and errmem is set to indicate the error.

     Errors
     badFileHandle
     invalidParameter
     stackFileSeek
     seekPastBeginning

     KBLs For FIFO and FILO file types, mseek(fh,0,SEEK_CUR) or
          mtell(fh) are only allowed.

msetsize

     int16 msetsize(int16 handle, int32 maxsize)

     Sets the maximum size a file may reach.  mwrite() and
     mpush() will not exceed this amount if set, although they
     can write to an existing file which exceeds this limit if
     the write does not extend the file.  mread(), mseek(), and
     mpull() are not affected by this limit in any way.

     Parameters
     handle    The file handle on which to set a file size limit.
     maxsize   The maximum file size in bytes to which the file
               may be extended.  Setting maxsize to zero will
               disable the file size limit for that file handle.

     Returns zero if successful, otherwise -1 on an error and
     errmem is set.

     Errors
     badFileHandle
     invalidParameter

     KBLs None.

mstat

     int16 mstat (const char *path, struct stat *buf)

     Provides statistical information on a memory file.  For more
     detailed information used the routine minfo().

     Parameters
     path      Path and file name of memory file on which to
               get statistics.
     buf       Pointer to valid memory buffer.

     Returns zero when the information is successfully obtained,
     -1 on an error with errmem set.

     Errors
     fileDoesNotExist
     invalidBufferPtr

     KBLs This function will only get the file size and the hard
          links used by the file.

mstrerr

     const char *mstrerror( int16 errnum )

     mstrerr maps the error number contained in errmem to an
     error message string.

     Parameter
     errmem    The number of the error usually returned by
               errmem.

     Returns a pointer to a string containing the requested error
     message.  The pointer is to a constant string and should not
     be modified by the calling routine.

     KBLs None.

msync

     int16 msync ( int16 handle, int16u num )

     Set the number of write operations to occur between each
     synchronization with the corresponding disk file.

     Parameters
     handle    File handle number
     num       Number of write operations between
               synchronizations.  The default is 100, setting num
               to zero will disable synchronization, clear the
               M_ISYNC mode flag for the file, and close the disk
               based file.

     Returns zero if successful, otherwise -1 and errmem is set

     Errors
     badFileHandle

     KBLs None.

mtell

     int16 mtell (int16 handle)

     Returns current pointer position for file handle.  It is
     implemented as a macro calling mseek() as follows.

     #define mtell(a)         mseek(a, 0, SEEK_CUR)

     See mseek for further detail.

mtruncate

     int16 mtruncate (int16 handle, int32 newsize)

     Truncates file to new size if the file was larger than
newsize

     Parameters
     handle    File handle number
     newsize   Size to change file to if larger

     Returns zero if successful, otherwise -1 and errmem is set.

     Errors
     badFileHandle
     invalidParameter
     fileNotWritable
     syncSeekFailure
     syncWriteFailure

     KBLs None.

mwrite

     int mwrite(int handle, void *buffer, unsigned len)

     Writes a memory block at the current file position.

     Parameters
     handle    File handle number
     buffer    Pointer to data buffer of outputted information
     len       Length of block to write from the buffer

     Returns the number of bytes written to the file.  When there
     is no error, this is the number given by the len argument.
     In the case of an error, such as there being no space
     available to contain the file data, the return value will be
     less than the number of bytes transmitted.  A value of -1
     may be returned in the case of some output errors.  When an
     error has occurred, errmem contains a value indicating the
     type of error that has been detected.

     Errors
     badFileHandle
     invalidBufferPtr
     fileNotWritable
     maxFileSizeExceeded
     syncSeekFailure
     syncWriteFailure
     outOfMemory

     KBLs As mopen().  If M_ISYNC option is used and an error
          occurs in the '\0' byte fill for a file position past
          the end of the file, then the sync counter will not be
          decremented for that one memory file write operation.

Version History

Read the file history.txt for the version development of this
product.

Performance Tests

The following results were obtained with the performance program
(memperf.c) which writes 10,000 1K byte records, and then reads
them back.  Each test was performed using a temporary file in the
temporary directory of a hard drive, an array of 10,000 elements
of size 1K bytes each to emulate a file, a normal random access
memory file, a stack based FIFO memory file, and a stack based
FILO/LIFO memory file.

The source for the performance program used is included with the
registered version of the Memory Library Programming Toolkit.

Processor: Pentium-60                        Operating System:
                                             Windows 95     RAM:
                                             48 MB

     Benchmark times in seconds.
                    Create    Write    Read    Close    Total
     Temp Dir File   0.000    9.210   4.400    0.000   13.610
     Array           1.630    0.080   0.050    0.000    1.760
     Memory Files
     Normal          0.000    1.500   0.100    0.000    1.600
     FIFO            0.000    1.510   0.630    0.000    2.140
     FILO            0.000    1.500   0.630    0.000    2.130

Processor: Pentium-60                        Operating System:
                                             DOS 32-bit     RAM:
                                             48 MB

     Benchmark times in seconds.
                    Create    Write    Read    Close    Total
     Temp Dir File   0.060   16.250 129.900    0.170  146.380
     Array           0.330    0.060   0.110    0.000    0.500
     Memory Files
     Normal          0.000    0.660   0.060    0.000    0.720
     FIFO            0.000    0.720   0.550    0.000    1.270
     FILO            0.000    0.600   0.540    0.000    1.140

Processor: 486DX2-80                         Operating System:
                                             Windows 95     RAM:
                                             16 MB

     Benchmark times in seconds.
                    Create    Write    Read    Close    Total
     Temp Dir File   0.030   26.220  28.980    0.020   55.250
     Array           1.400    0.090   0.100    0.000    1.590
     Memory Files
     Normal          0.000    1.210   0.290    0.000    1.500
     FIFO            0.000    1.210   1.090    0.000    2.300
     FILO            0.000    1.230   1.070    0.000    2.300

Processor: 486DX2-80                         Operating System:
                                             DOS 32-bit     RAM:
                                             16 MB

     Benchmark times in seconds.
                    Create    Write    Read    Close    Total
     Temp Dir File   0.030  279.300 132.420    0.330  412.050
     Array           0.550    0.050   0.060    0.000    0.660
     Memory Files
     Normal          0.000    0.390   0.160    0.000    0.550
     FIFO            0.000    0.330   0.830    0.000    1.160
     FILO            0.000    0.380   0.880    0.000    1.260
     
Performance Tests (continued)

Processor: Pentium-133                       Operating System:
                                             BSD 2.2a  RAM: 32 MB

     Benchmark times in seconds.
                    Create    Write    Read    Close    Total
     Temp Dir File   0.000    0.617   0.578    0.000    1.195
     Array           0.203    0.023   0.016    0.008    0.250
     Memory Files
     Normal          0.000    0.226   0.031    0.023    0.280
     FIFO            0.000    0.219   0.289    0.000    0.508
     FILO            0.000    0.219   0.281    0.016    0.516

Processor: Pentium-90                        Operating System:
                                             BSD 2.1.5r     RAM:
                                             8 MB

     Benchmark times in seconds.
                    Create    Write    Read    Close    Total
     Temp Dir File   0.000    1.969   1.086    0.000    3.055
     Array           0.672    0.312   0.219    0.008    1.211
     Memory Files
     Normal          0.000    0.773   0.125    0.008    0.906
     FIFO            0.000    0.789   0.884    0.008    1.681
     FILO            0.000    0.773   0.711    0.000    1.484

