1<!--$Id: region.so,v 10.33 2005/06/11 12:32:49 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Shared memory regions</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></b></td> 13<td align=right><a href="/env/naming.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/env/security.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Shared memory regions</b></p> 16<p>Each of the Berkeley DB subsystems within an environment is described by one 17or more regions, or chunks of memory. The regions contain all of the 18per-process and per-thread shared information (including mutexes), that 19comprise a Berkeley DB environment. These regions are created in one of three 20types of memory, depending on the flags specified to the 21<a href="/api_c/env_open.html">DB_ENV->open</a> method:</p> 22<ol> 23<p><li>If the <a href="/api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag is specified to the <a href="/api_c/env_open.html">DB_ENV->open</a> method, 24regions are created in per-process heap memory; that is, memory returned 25by <b>malloc</b>(3). 26<p>This flag should not be specified if more than a single process is 27accessing the environment because it is likely to cause database 28corruption and unpredictable behavior. For example, if both a server 29application and Berkeley DB utilities (for example, <a href="/utility/db_archive.html">db_archive</a>, 30<a href="/utility/db_checkpoint.html">db_checkpoint</a> or <a href="/utility/db_stat.html">db_stat</a>) are expected to access the 31environment, the <a href="/api_c/env_open.html#DB_PRIVATE">DB_PRIVATE</a> flag should not be specified.</p> 32<p><li>If the <a href="/api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag is specified to <a href="/api_c/env_open.html">DB_ENV->open</a>, 33shared regions are created in system memory rather than files. This is 34an alternative mechanism for sharing the Berkeley DB environment among 35multiple processes and multiple threads within processes. 36<p>The system memory used by Berkeley DB is potentially useful past the lifetime 37of any particular process. Therefore, additional cleanup may be 38necessary after an application fails because there may be no way for 39Berkeley DB to ensure that system resources backing the shared memory regions 40are returned to the system.</p> 41<p>The system memory that is used is architecture-dependent. For example, 42on systems supporting X/Open-style shared memory interfaces, such as 43UNIX systems, the <b>shmget</b>(2) and related System V IPC 44interfaces are used. Additionally, VxWorks systems use system memory. 45In these cases, an initial segment ID must be specified by the 46application to ensure that applications do not overwrite each other's 47database environments, so that the number of segments created does not 48grow without bounds. See the <a href="/api_c/env_set_shm_key.html">DB_ENV->set_shm_key</a> method for more 49information.</p> 50<p>On Windows platforms, the use of the <a href="/api_c/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag is 51problematic because the operating system uses reference counting to 52clean up shared objects in the paging file automatically. In addition, 53the default access permissions for shared objects are different from 54files, which may cause problems when an environment is accessed by 55multiple processes running as different users. See 56<a href="/ref/build_win/notes.html">Windows Notes</a> for more 57information.</p> 58<p><li>If no memory-related flags are specified to <a href="/api_c/env_open.html">DB_ENV->open</a>, memory 59backed by the filesystem is used to store the regions. On UNIX systems, 60the Berkeley DB library will use the POSIX mmap interface. If mmap is not available, 61the UNIX shmget interfaces may be used instead, if they are available. 62</ol> 63<a name="2"><!--meow--></a> 64<p>Any files created in the filesystem to back the regions are created in 65the environment home directory specified to the <a href="/api_c/env_open.html">DB_ENV->open</a> call. 66These files are named __db.### (for example, __db.001, __db.002 and 67so on). When region files are backed by the filesystem, one file per 68region is created. When region files are backed by system memory, a 69single file will still be created because there must be a well-known 70name in the filesystem so that multiple processes can locate the system 71shared memory that is being used by the environment.</p> 72<p>Statistics about the shared memory regions in the environment can be 73displayed using the <b>-e</b> option to the <a href="/utility/db_stat.html">db_stat</a> utility.</p> 74<table width="100%"><tr><td><br></td><td align=right><a href="/env/naming.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/env/security.html"><img src="/images/next.gif" alt="Next"></a> 75</td></tr></table> 76<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 77</body> 78</html> 79