+I$Berkeley DB: log_open[P

log_open





#include <db.h>

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





Description



The log_openHfunction copies a pointer, to the log identified by the directoryBdir, into the memory location referenced by regionp.

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

EIf the log region is being created and log files are already present,@the log files are recovered and subsequent log writes areappended to the end of the log.

BThe 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, see8Log File Limits.

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.V

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 befree-threaded.


VAll files created by the log subsystem 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 logging subsystem is configuredDbased on the dbenv argument to log_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).

HThe fields of the DB_ENV structure used by log_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 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.S

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

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

;See Log File Limitsfor more information.



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

Environment Variables





DB_HOME
>If the dbenv argument to log_open was initialized usingcdb_appinit the environment variable DB_HOME mayBbe 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.


U

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




Errors

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

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

&The specified file size was too large.





See Also

9log_archive,5log_close,9log_compare,3log_file,5log_flush,1log_get, log_open,1log_put,>log_register,3log_stat,6log_unlinkandBlog_unregister.
ÿÿ