int
memp_fget(DB_MPOOLFILE *mpf,
db_pgno_t *pgnoaddr, u_int32_t flags, void **pagep);
Description
The memp_fget function copies a pointer to the page with the page
number specified by pgnoaddr, from the source file in the
DB_MPOOLFILE, into the memory location referenced by pagep.
If the page does not exist or cannot be retrieved, memp_fget will
fail.
Page numbers begin at 0, i.e., the first page in the file is page number
0, not page number 1.
The returned page is size_t type aligned.
The flags value must be set to 0 or by bitwise inclusively OR'ing together one or more
of the following values.
Create a new page in the file and copy its page number to the location
referenced by pgnoaddr. In this case, the
pgin function, if specified, is
not called.
The DB_MPOOL_CREATE, DB_MPOOL_LAST and
DB_MPOOL_NEW flags are mutually exclusive.
Created pages have all their bytes set to 0, unless otherwise specified
when the file was opened.
All pages returned by memp_fget will be retained (i.e.
pinned), in the pool until a subsequent call to
memp_fput.
The memp_fget function returns a non-zero error value on failure and 0 on success.
Errors
The memp_fget function may fail and return a non-zero error for the following conditions:
EAGAIN
The page reference count has overflowed. (This should never happen unless
there's a bug in the application.)
EINVAL
An invalid flag value or parameter was specified.
The DB_MPOOL_NEW flag was set and the source file was not opened for writing.
More than one of DB_MPOOL_CREATE, DB_MPOOL_LAST and DB_MPOOL_NEW was set.
EIO
The requested page does not exist and DB_MPOOL_CREATE was not set.
ENOMEM
The cache is full and no more pages will fit in the pool.
The memp_fget function may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
If a catastrophic error has occurred, the memp_fget function may fail and return
DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail
in the same way.