#include <db.h>

int
log_open(const char *dir, u_int32_t flags,
    int mode, DB_ENV *dbenv, DB_LOG **regionp);

Description

The log_open function 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 log_open to be useable by multiple threads within a single address space, i.e., to be free-threaded.

The logging subsystem is configured based on the dbenv argument to log_open which is a pointer to a structure of type DB_ENV. Applications normally use the same DB_ENV structure (initialized by db_appinit) as an argument to all of the subsystems in the Berkeley DB package.

References to the DB_ENV structure are maintained by Berkeley DB, so it may not be discarded until the last close function, corresponding to an open function for which it was an argument, has returned. To ensure compatibility with future releases of Berkeley DB, all fields of the DB_ENV structure that are not explicitly set should be initialized to 0 before the 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).

The fields of the DB_ENV structure used by log_open are described below. If dbenv is NULL or any of its fields are set to 0, defaults appropriate for the system are used where possible.

The following fields in the DB_ENV structure may be initialized before calling log_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.

u_int32_t lg_max;

The maximum size of a single file in the log, in bytes. Because DB_LSN 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 log_open function returns the value of errno on failure, and 0 on success.

Environment Variables

DB_HOME

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

TMPDIR

If the dbenv argument to log_open was NULL or not initialized using db_appinit the environment variable TMPDIR may be used as the directory in which to create the log, as described in log_open.

Errors

The log_open function may fail and return errno for any of the errors specified for the following Berkeley DB and C library functions: abort(3), atoi(3), close(3), closedir(3), db_version, fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3), log_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 log_open function may fail and 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.

See Also