+I%Berkeley DB: memp_open[P

memp_open





#include <db.h>

)int memp_open(char *dir, u_int32_t flags,1 int mode, DB_ENV *dbenv, DB_MPOOL **regionp);





Description



The memp_openRfunction copies a pointer, to the "memory pool" identified by the directoryBdir, into the memory location referenced by regionp.

HIf the dir pathname argument is NULL or the DB_MPOOL_PRIVATE flagFis set, any necessary temporary files are created as described for the—DB_TMP_DIR value in Berkeley DB File Naming. Otherwise, the;dir pathname argument is interpreted as described in@Berkeley DB File Naming.

KThe flags and mode arguments specify how files will be opened,and/or created if they do not already exist.SThe flags value is specified by logically OR'ing together one or more of thefollowing values:

[

DB_CREATE
Create any underlying files, as necessary. If the files do not alreadyBexist and the DB_CREATE flag is not specified, the call will fail.e

DB_MPOOL_PRIVATE
Create a private MPOOL that is not shared with any other process (although%it may be shared with other threads).Y

DB_NOMMAP
Always copy files in this memory pool into the local cache instead of<mapping them into process memory (see the description of the<mp_mmapsize field of the DB_ENV structure for further information).Y

DB_THREAD
Cause the m4_reg(DB_MPOOL) handle returned by memp_open to be useable>by multiple threads within a single address space, i.e., to befree-threaded.


OAll files created by the memory pool subsystem (other than files created by the”memp_fopen function, which are separately specified) are created with mode mode (as describedHin chmod(2)) and modified by the process' umask value at the time$of creation (see umask(2)))).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

'The memory pool subsystem is configuredEbased on the dbenv argument to memp_open which is a pointer toFa structure of type DB_ENV. Applications normally use the same DB_ENVkstructure (initialized by db_appinit) as an argument to all of*the subsystems in the Berkeley DB package.

OReferences to the DB_ENV structure are maintained by Berkeley DB, so it may notDbe discarded until the last close function, corresponding to an open?function for which it was an argument, has returned. To ensureKcompatibility with future releases of Berkeley DB, all fields of the DB_ENVGstructure that are not explicitly set should be initialized to 0 beforeIthe first time the structure is used. Do this by declaring the structure?external or static, or by calling one of the C library routines$bzero(3) or memset(3).

IThe fields of the DB_ENV structure used by memp_open are described below.CIf dbenv is NULL or any of its fields are set to 0, defaults3appropriate for the system are used where possible.

FThe following fields in the DB_ENV structure may be initialized beforecalling memp_open:

>

void *(*db_errcall)(char *db_errpfx, char *buffer);

FILE *db_errfile;

const char *db_errpfx;
int db_verbose;
The error fields of the DB_ENV behave as described for db_appinit.g

size_t mp_mmapsize;
Files that are opened read-only in the pool (and that satisfy a few otherHcriteria) are, by default, mapped into the process address space insteadKof being copied into the local cache. This can result in better-than-usualIperformance, as available virtual memory is normally much larger than theJlocal cache, and page faults are faster than page copying on many systems.HHowever, in the presence of limited virtual memory it can cause resourceLstarvation, and in the presence of large databases, it can result in immenseKprocess sizes. If mp_mmapsize is non-zero, it specifies the maximumLfile size, in bytes, for a file to be mapped into the process address space.By default, it is set to 10Mb.b

size_t mp_size;
The suggested size of the shared memory buffer pool, i.e., the cache, inEbytes. This should be the size of the normal working data set of theDapplication, with some small amount of additional memory for unusualDsituations. (Note, the working set is not the same as the number ofGsimultaneously referenced pages, and should be quite a bit larger!) TheGdefault cache size is 128K bytes, and may not be specified as less than 20K bytes.

9For information on tuning the Berkeley DB cache size, seeASelecting a cache size.



The memp_openHfunction returns the value of errno on failure, and 0 on success.



Environment Variables

Q

DB_HOME
If the dbenv argument to memp_open was initialized usingcdb_appinit the environment variable DB_HOME mayBbe used as the path of the database home for the interpretation ofthe dir argument.


V

TMPDIR
If the dbenv argument to memp_open was NULL or not initializedhusing db_appinit the environment variable TMPDIR mayLbe used as the directory in which to create the memory pool, as described in memp_open.




Errors

RIf a fatal error occurs in Berkeley DB, the memp_open function may fail and returnFDB_RUNRECOVERY, at which point all subsequent database calls will alsoreturn DB_RUNRECOVERY.

The memp_open)function may fail and return errnoKfor any of the errors specified for the following Berkeley DB and C library functions:DBmemp->pgin(3),DBmemp->pgout(3), abort(3), close(3),8db_version,dbenv->db_paniccall(3), fcntl(3), fflush(3), fprintf(3),free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3),9log_compare,5log_flush, lseek(3), malloc(3), memcmp(3), memcpy(3),8memp_close,:memp_unlink, memset(3),mmap(3), munmap(3),open(3), pread(3),pstat_getdynamic(3), pwrite(3),read(3), shmat(3), shmctl(3), shmdt(3),sigfillset(3),sigprocmask(3),stat(3), strerror(3), strlen(3), sysconf(3),time(3), unlink(3), vfprintf(3), vsnprintf(3),and write(3).

In addition, the memp_open)function may fail and return errnofor the following conditions:

R

EAGAIN
The shared memory region was locked and (repeatedly) unavailable.
B

EINVAL
An invalid flag value or parameter was specified.

FThe DB_THREAD flag was specified and spinlocks are not implemented forthis architecture.

@A NULL pathname was specified without the DB_MPOOL_PRIVATE flag.

.The specified cache size was impossibly small.

!

i

See Also

l8memp_close,=memp_fclose,e9memp_fget,d;memp_fopen,o9memp_fput,e9memp_fset,s;memp_fsync,e memp_open,Amemp_register,6memp_stat,6memp_stat,6memp_sync,;memp_tricklecand/:memp_unlink.
b>˙˙r pathname argument is NULL or the DB_MPOOL_PRIVATE flagFis set, any necessary temporary files are created as d