-I7Berkeley DB Reference Guide: Environment[P1

Berkeley DB Reference Guide: Environment



!

File naming



FThe most important task of the environment is to structure file namingwithin Berkeley DB.

GEach of the locking, logging, memory pool and transaction subsystems ofDBerkeley DB require shared memory regions, backed by the filesystem.FFurther, cooperating applications (or multiple invocations of the sameHapplication) must agree on the location of the shared memory regions andQother files used by the Berkeley DB subsystems, the log files used by the logging*subsystem, and, of course, the data files.

NAlthough it is possible to specify full pathnames to all Berkeley DB functionsDthis is cumbersome and requires that applications be recompiled whendatabase files are moved.sThe db_appinit function makes it possible to place database files in aGsingle directory, or in multiple directories, grouped by their functionwithin the database.

IApplications are normally expected to specify a single directory home fortheir database.lThis can be done easily in the call to db_appinit by specifying(a value for the db_home argument.KThere are more complex configurations where it may be desirable to override9db_home or provide supplementary path information.

JThe following describes the possible ways in which file naming information,may be specified to the Berkeley DB library.HThe specific circumstances and order in which these ways are applied are$described in a subsequent paragraph.



db_home
fIf the db_home argument to db_appinit is non-NULL,Dits value may be used as the database home, and files named relative to its path.

DB_HOME
gIf the DB_HOME environment variable is set when db_appinitFis called, its value may be used as the database home, and files namedrelative to its path.

db_config
gThe db_config argument to db_appinit may be used toFspecify an array of character strings of the format NAME VALUE,Lthat specify file name information for the Berkeley DB process' environment.

GThe characters delimiting the two parts of the entry may be one or moreHwhitespace characters, and trailing whitespace characters are discarded.@Each entry must specify both the NAME and the VALUE of the pair.:All entries with unrecognized NAME values will be ignored.3The db_config array must be NULL terminated.

DB_CONFIG
BThe same information specified to the db_config argument toddb_appinit may be specified using a configuration file.JIf a database home directory has been specified (either by the applicationispecifying a non-NULL db_home argument to db_appinit,Gor by the application setting the DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT6flags and the DB_HOME environment variable being set),Fany file named DB_CONFIG in the database home directory will be/read for lines of the format NAME VALUE.

GThe characters delimiting the two parts of the entry may be one or moreHwhitespace characters, and trailing whitespace characters are discarded.FAll empty lines or lines whose first character is a whitespace or hash%(#) character will be ignored.?Each line must specify both the NAME and the VALUE of the pair.8All lines with unrecognized NAME values will be ignored.



=The following NAME VALUE pairs in the db_configGargument and the DB_CONFIG file are currently supported by Berkeley DB.



DB_DATA_DIR
GThe path of a directory to be used as the location of the access method`data files, e.g., paths specified to the db_open functionwill be relative to this path.

LThe DB_DATA_DIR paths are additive, and specifying more than one will resultCin each specified directory being searched for database data files.JIf multiple paths are specified, created data files will always be created(in the first directory specified.

DB_LOG_DIR
JThe path of a directory to be used as the location of logging files, e.g.,Nfiles created by the Log Manager subsystem will be relative to this directory.?If specified, this is the directory name that will be passed to3log_open.

DB_TMP_DIR
LThe path of a directory to be used as the location of temporary files, e.g.,Gfiles created to back in-memory access method databases will be createdrelative to this path.LNote, these temporary files can potentially be quite large, depending on thesize of the database.

GIf DB_TMP_DIR is not specified, the following environment variables are9checked in order: TMPDIR, TEMP, TMP,TempFolder.LIf one of them is set, temporary files are created relative to the directory it specifies.

JIf DB_TMP_DIR is not specified and none of the above environment variablesEare set, the first possible one of the following directories is used:</var/tmp, /usr/tmp, /temp, /tmp,!C:/temp and C:/tmp.



IThe following describes the specific circumstances and order in which theAdifferent ways of specifying file naming information are applied. Specifically,SBerkeley DB file name processing proceeds sequentially through the following steps:

j

absolute pathnames
If the file name specified to a Berkeley DB function is an absolute pathname,;that file name is used without modification by Berkeley DB.

EOn UNIX systems, an absolute pathname is defined as any pathname that'begins with a leading slash (/).

IOn Windows systems, an absolute pathname is any pathname that begins with@a leading slash or leading backslash (\), or any pathnameIbeginning with a single alphabetic character, a colon and a leading slash"or backslash, e.g., C:/tmp.

DB_CONFIG
KIf a relevant configuration string (e.g., DB_DATA_DIR), is specified in theGDB_CONFIG configuration file, the VALUE from the NAME VALUE pair&is prepended to the current file name.7If the resulting file name begins with a leading slash,Bthe file name is used without further modification by Berkeley DB.

KThe DB_CONFIG configuration file is intended to permit systems to customizeMfile location for a database independent of applications using that database. For example,Fa database administrator can move the database log and data files to a5different location without application recompilation.

db_config
KIf a relevant configuration string (e.g., DB_DATA_DIR), is specified in theEdb_config argument and is not specified in the DB_CONFIG file,Ethe VALUE from the NAME VALUE pair is prepended to the current file name.7If the resulting file name begins with a leading slash,Bthe file name is used without further modification by Berkeley DB.

CThe db_config argument is intended to permit applications to'customize file location for a database. For example,Ean application writer can place data files and log files in different" directories,Bor instantiate a new log directory each time the application runs.

DB_HOME
IIf the DB_HOME environment variable was set, (and the application has setmLthe appropriate DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT environment variable),0its value is prepended to the current file name.7If the resulting file name begins with a leading slash,hBthe file name is used without further modification by Berkeley DB.

dGThe DB_HOME environment variable is intended to permit users and system3Gadministrators to override application and installation defaults, e.g.,sC

    env DB_HOME=/database/my_home application

@Alternatively, application writers are encouraged to support theK-h option found in the supporting Berkeley DB utilities to let userssspecify a database home.

db_home
eBIf the application specified a non-NULL db_home argument tohdb_appinit (and the database home was not already specifiedEusing the DB_HOME environment variable) its value is prepended to the current file name.7If the resulting file name begins with a leading slash,uBthe file name is used without further modification by Berkeley DB.

(nothing)
GFinally, all file names are interpreted relative to the current workingidirectory of the process.e
i

LThe common model for a Berkeley DB environment is one where only the DB_HOMECenvironment variable, or the db_home argument, is specified. DIn this case, all data files will be presumed to be relative to thatNdirectory, and all files created by the Berkeley DB subsystems will be createdin that directory.

bGThe more complex model for a transaction environment might be one whereyKa database home is specified, using either the DB_HOME environment variablercor the db_home argument to db_appinit, and theneLDB_DATA_DIR and DB_LOG_DIR are set to the relative path names of directoriesDunderneath the home directory using the db_config argument toNdb_appinit or the DB_CONFIG file.

Examples

h4Store all files in the directory /a/database:

N



JCreate temporary backing files in /b/temporary, and all other filesin /a/database:

h



<Store data files in /a/database/datadir, log files in?/a/database/logdir, and all other files in the directory./a/database:m



AStore data files in /a/database/data1 and /b/data2,r8and all other files in the directory /a/database.CAny data files that are created will be created in /b/data2, 8because it is the first DB_DATA_DIR directory specified:

i



/)See the file examples/ex_appinit.caQin the Berkeley DB source distribution for an example of how an application mightbeuse db_appinit to configure its Berkeley DB environment.a

nG AgKInbd˙˙ectory will be/read for lines of the format NAME VALUE.

GThe characters delimiting the two parts of the entry may be one or moreHwhitespace characters, and trailing whitespace characters are discarded.FAl