1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
<! "@(#)open.so 10.10 (Sleepycat) 9/29/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<head>
<title>Berkeley DB: log_open</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btr
ee,hash,hashing,transaction,transactions,locking,logging,access method,access me
thods,java,C,C++">
</head>
<h1>log_open</h1>
<hr size=1 noshade>
<tt>
<h3>
<pre>
#include <db.h>
<p>
int
log_open(const char *dir, u_int32_t flags,
int mode, DB_ENV *dbenv, DB_LOG **regionp);
</pre>
</h3>
<h1>Description</h1>
<p>
The log_open
function copies a pointer, to the log identified by the <i>directory</i>
<b>dir</b>, into the memory location referenced by <b>regionp</b>.
<p>
The
<b>dir</b> pathname argument is interpreted as described in
<a href="../../ref/env/naming.html">Berkeley DB File Naming</a>.
<p>
If the log region is being created and log files are already present,
the log files are <i>recovered</i> and subsequent log writes are
appended to the end of the log.
<p>
The log is stored in one or more files in the specified directory.
Each file is named using the format <i>log.NNNNN</i>, where
<i>NNNNN</i> is the sequence number of the file within the log.
For further information, see
<a href="../../ref/log/limits.html">Log File Limits</a>.
<p>
The <b>flags</b> and <b>mode</b> arguments specify how files will be opened
and/or created if they do not already exist.
The flags value is specified by logically <b>OR</b>'ing together one or more of the
following values:
<dl compact>
<a name="DB_CREATE">
<p><dt>DB_CREATE<dd>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.
<a name="DB_THREAD">
<p><dt>DB_THREAD<dd>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
<i>free-threaded</i>.
</dl>
<p>
All files created by the log subsystem are created with mode <b>mode</b> (as described
in <b>chmod</b>(2)) and modified by the process' umask value at the time
of creation (see <b>umask</b>(2)))).
The group ownership of created files is based on the system and directory
defaults, and is not further specified by Berkeley DB.
<p>
The logging subsystem is configured
based on the <b>dbenv</b> 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 <a href="../../api_c/DbEnv/appinit.html">db_appinit</a>) as an argument to all of
the subsystems in the Berkeley DB package.
<p>
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
<b>bzero</b>(3) or <b>memset</b>(3).
<p>
The fields of the DB_ENV structure used by log_open are described below.
If <b>dbenv</b> is NULL or any of its fields are set to 0, defaults
appropriate for the system are used where possible.
<p>
The following fields in the DB_ENV structure may be initialized before
calling log_open:
<dl compact>
<p><dt>void *(*db_errcall)(char *db_errpfx, char *buffer);<dd>
<dt>FILE *db_errfile;<dd>
<dt>const char *db_errpfx;<dd>
<dt>int db_verbose;<dd>The error fields of the DB_ENV behave as described for <a href="../../api_c/DbEnv/appinit.html">db_appinit</a>.
<a name="lg_max">
<p><dt>u_int32_t lg_max;<dd>The maximum size of a single file in the log, in bytes.
Because DB_LSN file offsets are unsigned 4-byte values,
<b>lg_max</b> may not be larger than the maximum unsigned 4-byte value.
<p>
If <b>lg_max</b> is 0, a default value of 10Mb. is used.
<p>
See <a href="../../ref/log/limits.html">Log File Limits</a>
for more information.
</dl>
<p>
The log_open
function returns the value of <b>errno</b> on failure, and 0 on success.
<h1>Environment Variables</h1>
<p>
<dl compact>
<p><dt>DB_HOME<dd>
If the <b>dbenv</b> argument to log_open was initialized using
<a href="../../api_c/DbEnv/appinit.html">db_appinit</a> the environment variable <b>DB_HOME</b> may
be used as the path of the database home for the interpretation of
the <b>dir</b>. Specifically, log_open is affected by the
configuration string value of DB_LOG_DIR.
</dl>
<p>
<dl compact>
<p><dt>TMPDIR<dd>If the <b>dbenv</b> argument to log_open was NULL or not initialized
using <a href="../../api_c/DbEnv/appinit.html">db_appinit</a> the environment variable <b>TMPDIR</b> may
be used as the directory in which to create the log, as described in
log_open.
</dl>
<p>
<h1>Errors</h1>
If a fatal error occurs in Berkeley DB, the log_open function may fail and return
DB_RUNRECOVERY, at which point all subsequent database calls will also
return DB_RUNRECOVERY.
<p>
The log_open
function may fail and return <b>errno</b>
for any of the errors specified for the following Berkeley DB and C library
functions:
abort(3),
atoi(3),
close(3),
closedir(3),
<a href="../../api_c/DbEnv/version.html">db_version</a>,
fcntl(3),
fflush(3),
fprintf(3),
free(3),
fstat(3),
fsync(3),
getenv(3),
getpid(3),
getuid(3),
isdigit(3),
<a href="../../api_c/DbLog/unlink.html">log_unlink</a>,
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 <b>errno</b>
for the following conditions:
<dl compact>
<p><dt>EAGAIN<dd>The shared memory region was locked and (repeatedly) unavailable.
</dl>
<dl compact>
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
<p>
The DB_THREAD flag was specified and spinlocks are not implemented for
this architecture.
<p>
The specified file size was too large.
</dl>
<p>
<h1>See Also</h1>
<a href="../../api_c/DbLog/archive.html">log_archive</a>,
<a href="../../api_c/DbLog/close.html">log_close</a>,
<a href="../../api_c/DbLog/compare.html">log_compare</a>,
<a href="../../api_c/DbLog/file.html">log_file</a>,
<a href="../../api_c/DbLog/flush.html">log_flush</a>,
<a href="../../api_c/DbLog/get.html">log_get</a>,
log_open,
<a href="../../api_c/DbLog/put.html">log_put</a>,
<a href="../../api_c/DbLog/db_register.html">log_register</a>,
<a href="../../api_c/DbLog/stat.html">log_stat</a>,
<a href="../../api_c/DbLog/unlink.html">log_unlink</a>
and
<a href="../../api_c/DbLog/db_unregister.html">log_unregister</a>.
</tt>
</body>
</html>
|
