1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>DB->compact()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C API Reference" /> 10 <link rel="up" href="db.html" title="Chapter��2.�� The DB Handle" /> 11 <link rel="prev" href="dbcreate.html" title="db_create" /> 12 <link rel="next" href="dbdel.html" title="DB->del()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DB->compact()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbcreate.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��2.�� 23 The DB Handle 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="dbdel.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbcompact"></a>DB->compact()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db.h> 39 40int 41DB->compact(DB *db, DB_TXN *txnid, 42 DBT *start, DBT *stop, DB_COMPACT *c_data, u_int32_t flags, DBT *end); </pre> 43 <p> 44 The <code class="methodname">DB->compact()</code> method compacts Btree and Recno access method 45 databases, and optionally returns unused Btree, Hash or Recno database 46 pages to the underlying filesystem. 47 </p> 48 <p> 49 The <code class="methodname">DB->compact()</code> <span> 50 <span> 51 method returns a non-zero error value on failure and 0 on success. 52 </span> 53 54 </span> 55 </p> 56 <div class="sect2" lang="en" xml:lang="en"> 57 <div class="titlepage"> 58 <div> 59 <div> 60 <h3 class="title"><a id="id1632862"></a>Parameters</h3> 61 </div> 62 </div> 63 </div> 64 <div class="sect3" lang="en" xml:lang="en"> 65 <div class="titlepage"> 66 <div> 67 <div> 68 <h4 class="title"><a id="id1632429"></a>txnid</h4> 69 </div> 70 </div> 71 </div> 72 <p> 73 If the operation is part of an application-specified transaction, the 74 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 75 handle returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; 76 if the operation is part of a Berkeley DB Concurrent Data Store group, the 77 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 78 from <a class="xref" href="envcdsgroup_begin.html" title="DB_ENV->cdsgroup_begin()">DB_ENV->cdsgroup_begin()</a>; 79 otherwise NULL. 80 </p> 81 <p> 82 If a transaction handle is supplied to this method, then the operation is 83 performed using that transaction. In this event, large sections of the 84 tree may be locked during the course of the transaction. 85 </p> 86 <p> 87 If no transaction handle is specified, but the operation occurs 88 in a transactional database, the operation will be implicitly 89 transaction protected using multiple transactions. These transactions 90 will be periodically committed to avoid locking large sections of the 91 tree. Any deadlocks encountered cause the compaction operation to 92 be retried from the point of the last transaction commit. 93 </p> 94 </div> 95 <div class="sect3" lang="en" xml:lang="en"> 96 <div class="titlepage"> 97 <div> 98 <div> 99 <h4 class="title"><a id="id1632702"></a>start</h4> 100 </div> 101 </div> 102 </div> 103 <p> 104 If non-NULL, the <span class="bold"><strong>start</strong></span> parameter is 105 the starting point for compaction in a Btree or Recno database. 106 Compaction will start at the smallest key greater than or equal to the 107 specified key. If NULL, compaction will start at the beginning of the 108 database. 109 </p> 110 </div> 111 <div class="sect3" lang="en" xml:lang="en"> 112 <div class="titlepage"> 113 <div> 114 <div> 115 <h4 class="title"><a id="id1632903"></a>stop</h4> 116 </div> 117 </div> 118 </div> 119 <p> 120 If non-NULL, the <span class="bold"><strong>stop</strong></span> parameter is 121 the stopping point for compaction in a Btree or Recno database. 122 Compaction will stop at the page with the smallest key greater than 123 the specified key. If NULL, compaction will stop at the end of the 124 database. 125 </p> 126 </div> 127 <div class="sect3" lang="en" xml:lang="en"> 128 <div class="titlepage"> 129 <div> 130 <div> 131 <h4 class="title"><a id="id1632651"></a>c_data</h4> 132 </div> 133 </div> 134 </div> 135 <p> 136 137 </p> 138 <p> 139 If non-NULL, the <span class="bold"><strong>c_data</strong></span> parameter 140 contains additional compaction configuration parameters, and returns 141 compaction operation statistics, in a structure of type DB_COMPACT. 142 </p> 143 <p> 144 The following input configuration fields are available from the 145 DB_COMPACT structure: 146 </p> 147 <div class="itemizedlist"> 148 <ul type="disc"> 149 <li> 150 <p> 151 <code class="literal">int compact_fillpercent;</code> 152 </p> 153 <p> 154 If non-zero, this provides the goal for filling pages, specified as a percentage 155 between 1 and 100. Any page in a Btree or Recno databases not at or 156 above this percentage full will be considered for compaction. The 157 default behavior is to consider every page for compaction, regardless 158 of its page fill percentage. 159 </p> 160 </li> 161 <li> 162 <p> 163 <code class="literal">int compact_pages;</code> 164 </p> 165 <p> 166 If non-zero, the call will return after the 167 specified number of pages have been freed, or 168 no more pages can be freed. 169 </p> 170 </li> 171 <li> 172 <p> 173 <code class="literal">db_timeout_t compact_timeout;</code> 174 </p> 175 <p> 176 If non-zero, and no <span class="bold"><strong>txnid</strong></span> parameter 177 was specified, this parameter identifies the lock timeout used for implicit transactions, in 178 microseconds. 179 </p> 180 </li> 181 </ul> 182 </div> 183 <p> 184 The following output statistics fields are available from the 185 <code class="literal">DB_COMPACT</code> structure: 186 </p> 187 <div class="itemizedlist"> 188 <ul type="disc"> 189 <li> 190 <p> 191 <code class="literal">u_int32_t compact_deadlock;</code> 192 </p> 193 <p> 194 An output statistics parameter: if no <span class="bold"><strong>txnid</strong></span> parameter was specified, the number of 195 deadlocks which occurred. 196 </p> 197 </li> 198 <li> 199 <p> 200 <code class="literal">u_int32_t compact_pages_examine;</code> 201 </p> 202 <p> 203 An output statistics parameter: the number of database pages reviewed 204 during the compaction phase. 205 </p> 206 </li> 207 <li> 208 <p> 209 <code class="literal">u_int32_t compact_pages_free;</code> 210 </p> 211 <p> 212 An output statistics parameter: the number of database pages freed 213 during the compaction phase. 214 </p> 215 </li> 216 <li> 217 <p> 218 <code class="literal">u_int32_t compact_levels;</code> 219 </p> 220 <p> 221 An output statistics parameter: the number of levels removed from the 222 Btree or Recno database during the compaction phase. 223 </p> 224 </li> 225 <li> 226 <p> 227 <code class="literal">u_int32_t compact_pages_truncated;</code> 228 </p> 229 <p> 230 An output statistics parameter: the number of database pages returned 231 to the filesystem. 232 </p> 233 </li> 234 </ul> 235 </div> 236 </div> 237 <div class="sect3" lang="en" xml:lang="en"> 238 <div class="titlepage"> 239 <div> 240 <div> 241 <h4 class="title"><a id="id1632483"></a>flags</h4> 242 </div> 243 </div> 244 </div> 245 <p> 246 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 247 or one of the following values: 248 </p> 249 <div class="itemizedlist"> 250 <ul type="disc"> 251 <li> 252 <p><a id="compact_DB_FREELIST_ONLY"></a> 253 <code class="literal">DB_FREELIST_ONLY</code> 254 </p> 255 <p> 256 Do no page compaction, only returning pages to the filesystem that are 257 already free and at the end of the file. This flag must be set if the 258 database is a Hash access method database. 259 </p> 260 </li> 261 <li> 262 <p><a id="compact_DB_FREE_SPACE"></a> 263 <code class="literal">DB_FREE_SPACE</code> 264 </p> 265 <p> 266 Return pages to the filesystem when possible. If this flag is not 267 specified, pages emptied as a result of compaction will be placed on 268 the free list for re-use, but never returned to the filesystem. 269 </p> 270 <p> 271 Note that only pages at the end of a file can be returned to the 272 filesystem. Because of the one-pass nature of the compaction 273 algorithm, any unemptied page near the end of the file inhibits 274 returning pages to the file system. A repeated call to the 275 <code class="methodname">DB->compact()</code> method with a low <span class="bold"><strong>compact_fillpercent</strong></span> may be used to return pages 276 in this case. 277 </p> 278 </li> 279 </ul> 280 </div> 281 </div> 282 <div class="sect3" lang="en" xml:lang="en"> 283 <div class="titlepage"> 284 <div> 285 <div> 286 <h4 class="title"><a id="id1633063"></a>end</h4> 287 </div> 288 </div> 289 </div> 290 <p> 291 If non-NULL, the <span class="bold"><strong>end</strong></span> parameter will 292 be filled in with the database key marking the end of the compaction 293 operation in a Btree or Recno database. This is generally the first 294 key of the page where the operation stopped. 295 </p> 296 </div> 297 </div> 298 <div class="sect2" lang="en" xml:lang="en"> 299 <div class="titlepage"> 300 <div> 301 <div> 302 <h3 class="title"><a id="id1633231"></a>Errors</h3> 303 </div> 304 </div> 305 </div> 306 <p> 307 The <code class="methodname">DB->compact()</code> <span> 308 <span> 309 method may fail and return one of the following non-zero errors: 310 </span> 311 312 </span> 313 </p> 314 <div class="sect3" lang="en" xml:lang="en"> 315 <div class="titlepage"> 316 <div> 317 <div> 318 <h4 class="title"><a id="id1632714"></a>DB_LOCK_DEADLOCK</h4> 319 </div> 320 </div> 321 </div> 322 <p> 323 A transactional database environment operation was selected to resolve 324 a deadlock. 325 </p> 326 </div> 327 <div class="sect3" lang="en" xml:lang="en"> 328 <div class="titlepage"> 329 <div> 330 <div> 331 <h4 class="title"><a id="id1633322"></a>DB_LOCK_NOTGRANTED</h4> 332 </div> 333 </div> 334 </div> 335 <p> 336 A Berkeley DB Concurrent Data Store database environment configured 337 for lock timeouts was unable to grant a lock in the allowed time. 338 </p> 339 </div> 340 <div class="sect3" lang="en" xml:lang="en"> 341 <div class="titlepage"> 342 <div> 343 <div> 344 <h4 class="title"><a id="id1633040"></a> DB_REP_HANDLE_DEAD</h4> 345 </div> 346 </div> 347 </div> 348 <p> 349 When a client synchronizes with the master, it is possible for committed 350 transactions to be rolled back. This invalidates all the database and cursor 351 handles opened in the replication environment. Once this occurs, an attempt to use 352 such a handle will 353 354 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 355 The application will need to discard the handle and open a new one in order to 356 continue processing. 357 </p> 358 </div> 359 <div class="sect3" lang="en" xml:lang="en"> 360 <div class="titlepage"> 361 <div> 362 <div> 363 <h4 class="title"><a id="id1633331"></a>DB_REP_LOCKOUT</h4> 364 </div> 365 </div> 366 </div> 367 <p> 368 The operation was blocked by client/master synchronization. 369 </p> 370 </div> 371 <div class="sect3" lang="en" xml:lang="en"> 372 <div class="titlepage"> 373 <div> 374 <div> 375 <h4 class="title"><a id="id1632885"></a>EACCES</h4> 376 </div> 377 </div> 378 </div> 379 <p> 380 An attempt was made to modify a read-only database. 381 </p> 382 </div> 383 <div class="sect3" lang="en" xml:lang="en"> 384 <div class="titlepage"> 385 <div> 386 <div> 387 <h4 class="title"><a id="id1633333"></a>EINVAL</h4> 388 </div> 389 </div> 390 </div> 391 <p> 392 An invalid flag value or parameter was specified. 393 </p> 394 </div> 395 </div> 396 <div class="sect2" lang="en" xml:lang="en"> 397 <div class="titlepage"> 398 <div> 399 <div> 400 <h3 class="title"><a id="id1633048"></a>Class</h3> 401 </div> 402 </div> 403 </div> 404 <p> 405 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 406 </p> 407 </div> 408 <div class="sect2" lang="en" xml:lang="en"> 409 <div class="titlepage"> 410 <div> 411 <div> 412 <h3 class="title"><a id="id1632779"></a>See Also</h3> 413 </div> 414 </div> 415 </div> 416 <p> 417 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 418 </p> 419 </div> 420 </div> 421 <div class="navfooter"> 422 <hr /> 423 <table width="100%" summary="Navigation footer"> 424 <tr> 425 <td width="40%" align="left"><a accesskey="p" href="dbcreate.html">Prev</a>��</td> 426 <td width="20%" align="center"> 427 <a accesskey="u" href="db.html">Up</a> 428 </td> 429 <td width="40%" align="right">��<a accesskey="n" href="dbdel.html">Next</a></td> 430 </tr> 431 <tr> 432 <td width="40%" align="left" valign="top">db_create��</td> 433 <td width="20%" align="center"> 434 <a accesskey="h" href="index.html">Home</a> 435 </td> 436 <td width="40%" align="right" valign="top">��DB->del()</td> 437 </tr> 438 </table> 439 </div> 440 </body> 441</html> 442