fmpio(3)

NAME
MPset, MPget, MPopen, MPclose, MPflush, MPseek, MPread, MPwrite - File Memory Buffer Pool Stdio Interface

SYNOPSIS
#include <fmpio.h>

extern int MPset
(
    int pagesize,
    int maxcache,
    int flags
);

extern int MPget
(
    int *pagesize,
    int *maxcache,
    int flags
);

extern MPFILE *MPopen
(
    const char *path,
    int flags
);

extern int MPclose(MPFILE *mpfs);

extern int MPflush(MPFILE *mpfs);

extern int MPseek
(
    MPFILE *mpfs,
    off_t offset,
    int whence
);

extern int MPread
(
    MPFILE *mpfs,
    void *buf,
    size_t nbytes
);

extern int MPwrite
(
    MPFILE *mpfs,
    void *buf,
    size_t nbytes
);

PARAMETERS

int pagesize
    IN: pagesize to use for next open/create.

int maxcache
    IN: max number of pages to cache.

int flags	(MPset)
    IN: flags = 0, MP_PAGEALL.

int *pagesize
    OUT: pagesize to used in last open/create.

int *maxcache
    OUT: max number of pages cached in last open/create.

int flags	(MPget)
    IN:.

const char *path
    IN: filename.

int flags	(MPopen)
    IN: DFACC_CREATE, DFACC_READ, DFACC_WRITE, DFACC_RDWR, DFACC_ALL.

MPFILE *mpfs
    IN: File Memory pool handle.

off_t offset
    IN: Offset into the file.

int whence
    IN: SEEK_CUR, SEEK_SET, SEEK_END.

void *buf	(MPread)
    IN: User buffer to read data into.

size_t nbytes	(MPread)
    IN: number of bytes to read in.

void *buf	(MPwrite)
    IN: User buffer to write data from.

size_t nbytes	(MPwrite)
    IN: number of bytes to write out.

DESCRIPTION

  MPset
Set the pagesize and maximum number of pages to cache on the next open/create of a file. A pagesize that is a power of 2 is recommended. The values set here only affect the next open/creation of a file and do not change a particular file's paging behaviour after it has been opened or created. This maybe changed in a later release. Use flags arguement of 'MP_PAGEALL' if the whole file is to be cached in memory otherwise passs in zero.

  MPget
This gets the last pagesize and maximum number of pages cached for the last open/create of a file.

  MPopen
Open/Create the file for reading/writing and create a memory pool for the file. Currently we let the library decide whether to use the default PAGESIZE for creating pages and MAXCACHE for number of pages to cache in the pool.

  MPclose
First sync the file memory pool to disk. Next close the file memory pool. Finally close the file.

  MPflush
Flushes the file memory pool to disk.

  MPseek
Seeks to the correct page in the file depending upon the offset and the flag 'whence'. Similiar to the stdio routine. Assumes the flags values for SEEK_SET, SEEK_CUR and SEEK_END are universal. May not be true for non-Unix OS's.

  MPread
This routine handles getting the correct pages to read to satisfy the request. The data is then copied from the memory pool into the user's buffer.

  MPwrite
This routine handles getting the correct pages to write to satisfy the request. The data is then copied from the user's buffer to the memory pool.

RETURNS

  MPset
Returns SUCCEED if successful and FAIL otherwise.

  MPget
Returns SUCCEED.

  MPopen
Pointer to MPFILE struct if successful and NULL otherwise.

  MPclose
Returns SUCCEED on success and FAIL otherwise.

  MPflush
Returns SUCCEED on success and FAIL otherwise.

  MPseek
Returns offset into the file on success and FAIL otherwise.

  MPread
Returns number of bytes read if successful and FAIL otherwise.

  MPwrite
Returns number of bytes written if successful and FAIL otherwise.

NAME

  MPset
MPset - set pagesize and maximum number of pages to cache on next open/create.

  MPget
MPget - get last pagesize and max number of pages cached for open/create.

  MPopen
MPopen - open/create the file and create a memory pool for file.

  MPclose
MPclose - close the file, sync the file memory pool to disk and close it.

  MPflush
MPflush - flush file memory pool to disk.

  MPseek
MPseek - seek to the specified file offset in the memory pool.

  MPread
MPread - read 'nbytes' from file memory pool into 'buf'.

  MPwrite
MPwrite - write 'nbytes' form 'buf' to the file memory pool.

NOTE

  MPset
Currently 'maxcache' has to be greater than 1. Maybe use special case of 0 to specify you want to turn page buffering off or use the flags arguement. Current memory usage overhead for the Memory Pool is approximately ~(2k + maxcache*(28+pagesize) + npages*20) bytes.

  MPseek
Note that it returns an 'int' as opposed to 'off_t'. This is because the HDF library still deals with file offsets in terms of signed integers....*sigh*...hopefully This will be changed in a future release.

  MPread
The memcpy from the buffer pool to the users buffer is an expensive operation.

  MPwrite
The memcpy from the the users buffer to the memory pool is an expensive operation.

CONTACT
George Velamparampil <georgev@ncsa.uiuc.edu>

NCSA Software Development Group

HDF Group

152 Computing Applications Bldg.

605 E. Springfield Ave.

Champaign, IL 61820