DB_LOG(3)

NAME
db_log - log-manager access method

DESCRIPTION
specific details of the logging access method.

These functions provide a general-purpose logging facility sufficient for transaction management. Logs can be shared by multiple processes.

A log is represented by the directory, not the file, named by the first argument to db_open(3). The first argument must be non-NULL, and the directory must already exist db_open is called. In that directory, the log is stored in one or more files named in the format ``log.YYYY.MM.DD.HH.MM.SS'', where ``YYYY.MM.DD.HH.SS'' is the approximate creation time of the log file, and is guaranteed to be unique in the directory.

The group of the created files is based on the system and directory defaults, and is not further specified by the log access method. All files are created with the mode specified to db_open, (as described in chmod(2)) and modified by the process' umask value (see umask(2)).

The flags argument to db_open must be 0 for the db_log access method.

ACCESS METHOD SPECIFIC INFORMATION
The log access method specific data structure provided to db_open is typedef'd and named LOGINFO. A LOGINFO structure has at least the following fields, which may be initialized before calling db_open:

off_t max_file_size;
    The maximum size of a single file in the log. If not specified, the maximum size defaults to an implementation-specific value.

int lorder;
    The byte order for integers in the stored database metadata. The number should represent the order as an integer; for example, big endian order would be the number 4,321. If lorder is 0 (no order is specified) the current host order is used.

If the log already exists, the values specified for the parameters max_file_size and lorder are ignored in favor of the values used when the log was created.

DB OPERATIONS
The data part of the key/data pair used by the log access method is the same as for other access methods. The key is different. Each log record is identified by a log sequence number (LSN), which is stored in a DBT, and which is used as the key for all log functions that take key arguments. Applications cannot create LSN's, and all LSN's provided to functions as arguments must first be retrieved using the put or seq functions. To provide a distinguished value for applications, it is guaranteed that no valid LSN will ever have a size of 0.

Applications can compare LSN's using the log_lsn_compare function (see below).

Applications can associate LSN's with specific log files. The function log_lsn_file (see below), returns the name of the log file containing the record with a specified LSN. (The mapping of LSN to file is needed for database administration. For example, a transaction manager typically records the earliest LSN needed for restart, and the database administrator may want to archive log files to tape when they contain only LSN's before the earliest one needed for restart.)

Applications can truncate the log file up to a specific LSN using the log_trunc function (see below).

The functions returned by db_open for the log access method are as described in db_open, with the following exceptions and additions:

type
    The type is DB_LOG.

del The del function always returns an error for the log-manager access method, setting errno to EINVAL.

int (*log_flush)(const DB *db, const DBT *lsn);
    The log_flush function flushes the log up to and including the log record lsn.

int (*log_lsn_compare)(const DB *,
    const DBT *lsn1, const DBT *lsn2); A pointer to a function which is provided to permit applications to compare LSN's. The log_lsn_compare function returns an integer less than, equal to, or greater than zero if the first LSN is considered to be respectively less than, equal to, or greater than the second LSN.

int (*log_lsn_file)(const DB *db,
    const DBT *lsn, char *name);
    The log_lsn_file function stores a pointer to the name of the file containing lsn in the address referenced by name. This pointer is to an internal static object, and subsequent calls to the same function will modify the same object.

int (*log_unlink)(const char *path, int force);
    The log_unlink function destroys the log represented by path. If the force parameter is not set to 1 and there are other processes using the log, then log_unlink will return -1, setting errno to EBUSY. If force is not set or there are no processes using the log, then all files used by the log are destroyed. log_unlink will return -1 on failure, setting errno, and 0 on success.

int (*log_trunc)(const DB *db, const DBT *lsn);
    The log_trunc function truncates the log up to an LSN which is less than lsn.

put A log record containing data is appended to the log. Unlike the put functions for other access methods, the key parameter is not initialized by the application, instead, the LSN assigned to the data is returned in the key parameter.

    The caller is responsible for providing any necessary structure to data . (For example, in a write-ahead logging protocol, the application must understand what part of data is an operation code, what part is redo information, and what part is undo information. In addition, most transaction managers will store in data the LSN of the previous log record for the same transaction, to support chaining back through the transaction's log records during undo.)

    The parameter flag must be set to 0 or exactly one of the following values:

    R_CHECKPOINT
        Specify the key/data pair of the current call as the one to be returned when the seq function is next called with the R_CHECKPOINT flag.

    R_FLUSH
        Flush immediately (ignoring any possibility for group commit).

seq The seq function takes the following additional flag:

    R_CHECKPOINT
        The last key/data pair stored by the put function (using the R_CHECKPOINT flag) is returned, and the cursor is set or initialized to reference it. The expected use of this flag is during restart and to determine what part of the log must be available for restart. Therefore, the log record retrieved with R_CHECKPOINT should contain all the information that the transaction manager will need for this purpose.

sync
    The sync function always returns an error for the log-manager access method, setting errno to EINVAL.

SEE ALSO
db_btree(3), db_hash(3), db_lock(3), db_mpool(3), db_open(3), db_recno(3), db_txn(3)