Berkeley DB: DbLog::open
Полезная информация

DbLog::open


#include <db_cxx.h>

static int DbLog::open(const char *dir, u_int32_t flags, int mode, DbEnv *dbenv, DbLog **regionp);

Description

The DbLog::open method copies a pointer, to the log identified by the directory dir, into the memory location referenced by regionp.

The dir pathname argument is interpreted as described in Berkeley DB File Naming.

If the log region is being created and log files are already present, the log files are recovered and subsequent log writes are appended to the end of the log.

The log is stored in one or more files in the specified directory. Each file is named using the format log.NNNNN, where NNNNN is the sequence number of the file within the log. For further information, see Log File Limits.

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

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

DB_THREAD
Cause the m4_reg(DB_LOG) handle returned by DbLog::open to be useable by multiple threads within a single address space, i.e., to be free-threaded.

All files created by the log subsystem are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)))). The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.

The logging subsystem is configured based on the dbenv argument. It is expected that applications will use a single DbEnv object as the argument to all of the subsystems in the Berkeley DB package. The fields of the DbEnv object used by DbLog::open are described below. References to the DbEnv object are maintained by Berkeley DB, so it is necessary that the object and memory it references be valid until the object is destroyed. Any of the DbEnv fields that are not explicitly set will default to appropriate values.

The following fields in the DbEnv object may be initialized, using the appropriate set method, before calling DbLog::open:

void *(*db_errcall)(char *db_errpfx, char *buffer);
FILE *db_errfile;
const char *db_errpfx;
class ostream *db_error_stream;
int db_verbose;
The error fields of the DbEnv behave as described for DbEnv::appinit.

u_int32_t lg_max;
The maximum size of a single file in the log, in bytes. Because DbLsn file offsets are unsigned 4-byte values, lg_max may not be larger than the maximum unsigned 4-byte value.

If lg_max is 0, a default value of 10Mb. is used.

See Log File Limits for more information.

The DbLog::open method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.

Environment Variables

DB_HOME
If the dbenv argument to DbLog::open was initialized using DbEnv::appinit the environment variable DB_HOME may be used as the path of the database home for the interpretation of the dir. Specifically, DbLog::open is affected by the configuration string value of DB_LOG_DIR.

TMPDIR
If the dbenv argument to DbLog::open was NULL or not initialized using DbEnv::appinit the environment variable TMPDIR may be used as the directory in which to create the log, as described in DbLog::open.

Errors

If a fatal error occurs in Berkeley DB, the DbLog::open method may fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, at which point all subsequent database calls will also fail in the same way. Methods marked as returning errno will, by default, throw an exception that encapsulates the error information. The default error behavior can be changed, see DbException.

The DbLog::open method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: abort(3), atoi(3), close(3), closedir(3), DbEnv::version, fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3), DbLog::unlink, lseek(3), malloc(3), memcpy(3), memset(3), mmap(3), munmap(3), open(3), opendir(3), pstat_getdynamic(3), read(3), readdir(3), realloc(3), shmat(3), shmctl(3), shmdt(3), sigfillset(3), sigprocmask(3), snprintf(3), stat(3), strchr(3), strerror(3), strlen(3), strncmp(3), sysconf(3), unlink(3), vfprintf(3), vsnprintf(3), and write(3). In addition, the DbLog::open method may fail and throw an exception or return errno for the following conditions:

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

EINVAL
An invalid flag value or parameter was specified.

The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.

The specified file size was too large.

Class

DbLog

See Also

DbLog::archive, DbLog::close, DbLog::compare, DbLog::file, DbLog::flush, DbLog::get, DbLog::open, DbLog::put, DbLog::db_register, DbLog::stat, DbLog::unlink and DbLog::db_unregister.