DB_MPOOLFILE->get
|
|
#include <db.h>
int
DB_MPOOLFILE->get(DB_MPOOLFILE *mpf,
db_pgno_t *pgnoaddr, u_int32_t flags, void **pagep);
Description: DB_MPOOLFILE->get
The DB_MPOOLFILE->get method returns pages from the cache.
All pages returned by DB_MPOOLFILE->get will be retained (that is,
pinned), in the pool until a subsequent call to
DB_MPOOLFILE->put.
The returned page is size_t type aligned.
Fully or partially created pages have all their bytes set to a nul byte,
unless the DB_MPOOLFILE->set_clear_len method was called to specify other
behavior before the file was opened.
The DB_MPOOLFILE->get method
will return DB_PAGE_NOTFOUND if the requested page does not exist and DB_MPOOL_CREATE was
not set.
Unless otherwise specified, the DB_MPOOLFILE->get method
returns a non-zero error value on failure
and 0 on success.
Parameters
- flags
- The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one
or more of the following values:
- DB_MPOOL_CREATE
- If the specified page does not exist, create it. In this case, the
pgin method, if specified, is
called.
- DB_MPOOL_LAST
- Return the last page of the source file, and copy its page number into
the memory location to which pgnoaddr refers.
- DB_MPOOL_NEW
- Create a new page in the file, and copy its page number into the memory
location to which pgnoaddr refers. In this case, the
pgin method, if specified, is
not called.
The DB_MPOOL_CREATE, DB_MPOOL_LAST, and
DB_MPOOL_NEW flags are mutually exclusive.
- pagep
- The pagep parameter references memory into which
a pointer to the returned page is copied.
- pgnoaddr
- If the flags parameter is set to DB_MPOOL_LAST or
DB_MPOOL_NEW, the page number of the created page is copied
into the memory location to which the pgnoaddr parameter
refers. Otherwise, the pgnoaddr parameter is the page to
create or retrieve.
Page numbers begin at 0; that is, the first page in the file is page
number 0, not page number 1.
Errors
The DB_MPOOLFILE->get method
may fail and return one of the following non-zero errors:
- EAGAIN
- The page reference count has overflowed. (This should never happen
unless there is a bug in the application.)
- EINVAL
- If 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; or if an
invalid flag value or parameter was specified.
- ENOMEM
- The cache is full, and no more pages will fit in the pool.
Class
DB_ENV, DB_MPOOLFILE
See Also
Memory Pools and Related Methods
Copyright (c) 1996-2005 Sleepycat Software, Inc. - All rights reserved.