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>Determining the Scope of the Modifications</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Porting Berkeley DB" /> 10 <link rel="up" href="newbinary.html" title="Chapter��2.��Creating a New Berkeley DB Binary" /> 11 <link rel="prev" href="newbinary.html" title="Chapter��2.��Creating a New Berkeley DB Binary" /> 12 <link rel="next" href="buildtarget.html" title="Building on the Target Platform" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center"> 19Determining the Scope of the Modifications 20</th> 21 </tr> 22 <tr> 23 <td width="20%" align="left"><a accesskey="p" href="newbinary.html">Prev</a>��</td> 24 <th width="60%" align="center">Chapter��2.��Creating a New Berkeley DB Binary</th> 25 <td width="20%" align="right">��<a accesskey="n" href="buildtarget.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="modscope"></a> 35Determining the Scope of the Modifications 36</h2> 37 </div> 38 </div> 39 </div> 40 <div class="toc"> 41 <dl> 42 <dt> 43 <span class="sect2"> 44 <a href="modscope.html#osfunc"> 45Do Changes Need to be Made to the Operating System Functionality? 46</a> 47 </span> 48 </dt> 49 <dt> 50 <span class="sect2"> 51 <a href="modscope.html#standardfunc">Are Some Standard Functions Missing on the Target Platform?</a> 52 </span> 53 </dt> 54 <dt> 55 <span class="sect2"> 56 <a href="modscope.html#sharedmem">How Will the Port Handle Shared Memory?</a> 57 </span> 58 </dt> 59 <dt> 60 <span class="sect2"> 61 <a href="modscope.html#typemutex">What Type of Mutexes Will the Port Use?</a> 62 </span> 63 </dt> 64 <dt> 65 <span class="sect2"> 66 <a href="modscope.html#otherchanges">Do Any Other Changes Need to be Made?</a> 67 </span> 68 </dt> 69 </dl> 70 </div> 71 <p> 72Once you have a good build of Berkeley DB on a UNIX or UNIX-like system, look over the code to determine what type of code changes you need to make so that you can successfully build Berkeley DB on your target system. This process involves determining: 73</p> 74 <div class="itemizedlist"> 75 <ul type="disc"> 76 <li> 77 <p> 78 <a class="xref" href="modscope.html#osfunc" title="Do Changes Need to be Made to the Operating System Functionality?"> 79Do Changes Need to be Made to the Operating System Functionality? 80</a> 81</p> 82 </li> 83 <li> 84 <p> 85<a class="xref" href="modscope.html#standardfunc" title="Are Some Standard Functions Missing on the Target Platform?">Are Some Standard Functions Missing on the Target Platform?</a> 86</p> 87 </li> 88 <li> 89 <p> 90<a class="xref" href="modscope.html#sharedmem" title="How Will the Port Handle Shared Memory?">How Will the Port Handle Shared Memory?</a> 91</p> 92 </li> 93 <li> 94 <p> 95<a class="xref" href="modscope.html#typemutex" title="What Type of Mutexes Will the Port Use?">What Type of Mutexes Will the Port Use?</a> 96</p> 97 </li> 98 <li> 99 <p> 100<a class="xref" href="modscope.html#otherchanges" title="Do Any Other Changes Need to be Made?">Do Any Other Changes Need to be Made?</a> 101</p> 102 </li> 103 </ul> 104 </div> 105 <div class="sect2" lang="en" xml:lang="en"> 106 <div class="titlepage"> 107 <div> 108 <div> 109 <h3 class="title"><a id="osfunc"></a> 110Do Changes Need to be Made to the Operating System Functionality? 111</h3> 112 </div> 113 </div> 114 </div> 115 <p> 116Berkeley DB uses about forty operating system primitives. The Berkeley DB distribution contains files which are wrappers around these operating system primitives that act as an abstraction layer to separate the main Berkeley DB code from operating system and architecture-specific components. You <span class="emphasis"><em>must</em></span> port these files (or versions of these files) whenever you port Berkeley DB to a new platform. 117</p> 118 <p> 119Within a Berkeley DB distribution, typically, there is only a single 120version of these files for all platforms that Berkeley DB supports. Those 121versions of the files live in the <code class="literal">os</code> directory of the 122distribution and follow the ANSI C and POSIX 1003.1 standards. Within each 123file, there is usually one, but sometimes several functions (for example, 124the <code class="literal">os_alloc.c</code> file contains the 125<code class="literal">malloc</code>, <code class="literal">realloc</code>, 126<code class="literal">strdup</code>, and <code class="literal">free</code> functions). The following table describes the files in the os directory of the Berkeley DB distribution. 127</p> 128 <div class="informaltable"> 129 <table border="1" width="80%"> 130 <colgroup> 131 <col /> 132 <col /> 133 </colgroup> 134 <thead> 135 <tr> 136 <th> 137 <p> 138 Source file 139 </p> 140 </th> 141 <th> 142 <p> 143 Description 144 </p> 145 </th> 146 </tr> 147 </thead> 148 <tbody> 149 <tr> 150 <td> 151 <p> 152os_abort.c 153 </p> 154 </td> 155 <td> 156 <p> 157abort() 158 </p> 159 </td> 160 </tr> 161 <tr> 162 <td> 163 <p> 164os_abs.c 165 </p> 166 </td> 167 <td> 168 <p> 169Return if a filename is an absolute path name 170 </p> 171 </td> 172 </tr> 173 <tr> 174 <td> 175 <p> 176os_addrinfo.c 177 </p> 178 </td> 179 <td> 180 <p> 181getaddrinfo(), freeaddrinfo() 182 </p> 183 </td> 184 </tr> 185 <tr> 186 <td> 187 <p> 188os_alloc.c 189 </p> 190 </td> 191 <td> 192 <p> 193malloc(), realloc(), strdup(), free() 194 </p> 195 </td> 196 </tr> 197 <tr> 198 <td> 199 <p> 200os_clock.c 201 </p> 202 </td> 203 <td> 204 <p> 205clock_gettime() 206 </p> 207 </td> 208 </tr> 209 <tr> 210 <td> 211 <p> 212os_config.c 213 </p> 214 </td> 215 <td> 216 <p> 217Minor run-time configuration information 218 </p> 219 </td> 220 </tr> 221 <tr> 222 <td> 223 <p> 224os_ctime.c 225 </p> 226 </td> 227 <td> 228 <p> 229ctime() 230 </p> 231 </td> 232 </tr> 233 <tr> 234 <td> 235 <p> 236os_dir.c 237 </p> 238 </td> 239 <td> 240 <p> 241Return a list of files for a directory 242 </p> 243 </td> 244 </tr> 245 <tr> 246 <td> 247 <p> 248os_errno.c 249 </p> 250 </td> 251 <td> 252 <p> 253Library and system error translation 254 </p> 255 </td> 256 </tr> 257 <tr> 258 <td> 259 <p> 260os_fid.c 261 </p> 262 </td> 263 <td> 264 <p> 265Return a unique identifier for a file 266 </p> 267 </td> 268 </tr> 269 <tr> 270 <td> 271 <p> 272os_fsync.c 273 </p> 274 </td> 275 <td> 276 <p> 277fsync() 278 </p> 279 </td> 280 </tr> 281 <tr> 282 <td> 283 <p> 284os_handle.c 285 </p> 286 </td> 287 <td> 288 <p> 289Return a file handle 290 </p> 291 </td> 292 </tr> 293 <tr> 294 <td> 295 <p> 296os_pid.c 297 </p> 298 </td> 299 <td> 300 <p> 301Return a unique identifier for a threa 302 </p> 303 </td> 304 </tr> 305 <tr> 306 <td> 307 <p> 308os_map.c 309 </p> 310 </td> 311 <td> 312 <p> 313Shared memory mapping 314 </p> 315 </td> 316 </tr> 317 <tr> 318 <td> 319 <p> 320os_mkdir.c 321 </p> 322 </td> 323 <td> 324 <p> 325mkdir() 326 </p> 327 </td> 328 </tr> 329 <tr> 330 <td> 331 <p> 332os_oflags.c 333 </p> 334 </td> 335 <td> 336 <p> 337open() Used to convert open flags to Berkeley DB flags 338 </p> 339 </td> 340 </tr> 341 <tr> 342 <td> 343 <p> 344os_open.c 345 </p> 346 </td> 347 <td> 348 <p> 349Return a file handle 350 </p> 351 </td> 352 </tr> 353 <tr> 354 <td> 355 <p> 356os_rename.c 357 </p> 358 </td> 359 <td> 360 <p> 361rename() 362 </p> 363 </td> 364 </tr> 365 <tr> 366 <td> 367 <p> 368os_root.c 369 </p> 370 </td> 371 <td> 372 <p> 373Return if application has special permissions 374 </p> 375 </td> 376 </tr> 377 <tr> 378 <td> 379 <p> 380os_rpath.c 381 </p> 382 </td> 383 <td> 384 <p> 385Return last separator in a path 386 </p> 387 </td> 388 </tr> 389 <tr> 390 <td> 391 <p> 392os_rw.c 393 </p> 394 </td> 395 <td> 396 <p> 397read(), write() 398 </p> 399 </td> 400 </tr> 401 <tr> 402 <td> 403 <p> 404os_seek.c 405 </p> 406 </td> 407 <td> 408 <p> 409lseek() 410 </p> 411 </td> 412 </tr> 413 <tr> 414 <td> 415 <p> 416os_sleep.c 417 </p> 418 </td> 419 <td> 420 <p> 421sleep() 422 </p> 423 </td> 424 </tr> 425 <tr> 426 <td> 427 <p> 428os_spin.c 429 </p> 430 </td> 431 <td> 432 <p> 433Return the number of test-and-set mutex spins before blocking 434 </p> 435 </td> 436 </tr> 437 <tr> 438 <td> 439 <p> 440os_stat.c 441 </p> 442 </td> 443 <td> 444 <p> 445stat() 446 </p> 447 </td> 448 </tr> 449 <tr> 450 <td> 451 <p> 452os_tmpdir.c 453 </p> 454 </td> 455 <td> 456 <p> 457Return the directory name used by the system for temporary files 458 </p> 459 </td> 460 </tr> 461 <tr> 462 <td> 463 <p> 464os_truncate.c 465 </p> 466 </td> 467 <td> 468 <p> 469ftruncate() 470 </p> 471 </td> 472 </tr> 473 <tr> 474 <td> 475 <p> 476os_uid.c 477 </p> 478 </td> 479 <td> 480 <p> 481Return unique 32-bit id 482 </p> 483 </td> 484 </tr> 485 <tr> 486 <td> 487 <p> 488os_unlink.c 489 </p> 490 </td> 491 <td> 492 <p> 493unlink() 494 </p> 495 </td> 496 </tr> 497 <tr> 498 <td> 499 <p> 500os.yield.c 501 </p> 502 </td> 503 <td> 504 <p> 505yield() 506 </p> 507 </td> 508 </tr> 509 </tbody> 510 </table> 511 </div> 512 <p> 513When the operating system primitives on the target platform are identical 514or close to the POSIX semantics that Berkeley DB requiress, then no code 515changes or minimal code changes to the files in the <code class="literal">os</code> directory are required. If the operating system primitives are quite different, then some code changes may be required to bridge the gap between the requirements of Berkeley DB and what the operating system provides. 516</p> 517 <p> 518Where different code is required, you write an entirely different version 519of the file and place it in an <code class="literal">os</code>_<span class="emphasis"><em>xxx</em></span> directory where <span class="emphasis"><em>xxx</em></span> represents a platform name. 520There are <code class="literal">os</code>_<span class="emphasis"><em>xxx</em></span> 521subdirectories in the Berkeley DB distribution for several established 522non-POSIX platforms. For example, there is a he 523<code class="literal">os_vxworks</code> directory that contains VxWorks 524versions of some of the files in the os directory, and Windows versions of 525some files are in the <code class="literal">os_windows</code> directory. If 526your target platform needs a different version of a file, you will need to 527write that file and place it in a new <code class="literal">os</code>_<span class="emphasis"><em>xxx</em></span> directory that you create for your target platform. 528</p> 529 </div> 530 <div class="sect2" lang="en" xml:lang="en"> 531 <div class="titlepage"> 532 <div> 533 <div> 534 <h3 class="title"><a id="standardfunc"></a>Are Some Standard Functions Missing on the Target Platform?</h3> 535 </div> 536 </div> 537 </div> 538 <p> 539 In some cases, the target platform may not provide the few POSIX 540 functions required by Berkeley DB or the functions provided by the 541 target platform may not operate in a standard compliant way. 542 Berkeley DB provides replacement functionsin the 543 <code class="literal">clib</code> directory 544 of the Berkeley DB distribution. 545</p> 546 <p> 547You need to determine how your target platfrom handles these functions: 548</p> 549 <div class="itemizedlist"> 550 <ul type="disc"> 551 <li> 552 <p> 553 When the target platform does <span class="emphasis"><em>not</em></span> have a POSIX 554 function required by Berkeley DB, no action is required on your 555 part. When Berekely DB cannot find one of these functions on the 556 target platform, it automatically uses the replacement functions 557 supplied in the <code class="literal">clib</code> directory of the Berkeley 558 DB distribution. For example, if the target platform does not have 559 the <code class="literal">atoi</code> or <code class="literal">strtol</code> functions, 560 Berkeley DB uses <code class="literal">clib/atoi.c</code> and 561 <code class="literal">clib/strtol.c</code>. 562</p> 563 </li> 564 <li> 565 <p> 566When the target platform has a function required by Berekely DB, but that 567function operates in a non-standard compliant way, you can code to the 568replacement functions supplied in the <code class="literal">clib</code> directory. 569</p> 570 </li> 571 </ul> 572 </div> 573 </div> 574 <div class="sect2" lang="en" xml:lang="en"> 575 <div class="titlepage"> 576 <div> 577 <div> 578 <h3 class="title"><a id="sharedmem"></a>How Will the Port Handle Shared Memory?</h3> 579 </div> 580 </div> 581 </div> 582 <p> 583 In order to write 584multiprocess database applications (not multithreaded, but threads of control running in different address spaces), Berkeley DB must be able to name pieces of shared memory and access them from multiple processes. 585</p> 586 <p> 587 On UNIX/POSIX systems, Berkeley DB uses 588 <code class="literal">mmap</code> and <code class="literal">shmget</code> for that purpose, 589 but any interface that provides access to named shared memory is 590 sufficient. If you have a simple, flat address space, you should be able 591 to use the code in <code class="literal">os_vxworks/os_map.c</code> as a starting point for the port. 592</p> 593 <p> 594If you are not intending to write multiprocess database applications, then this won't be necessary, as Berkeley DB can simply allocate memory from the heap if all threads of control will live in a single address space. 595</p> 596 </div> 597 <div class="sect2" lang="en" xml:lang="en"> 598 <div class="titlepage"> 599 <div> 600 <div> 601 <h3 class="title"><a id="typemutex"></a>What Type of Mutexes Will the Port Use?</h3> 602 </div> 603 </div> 604 </div> 605 <p> 606 Berkeley DB requires some form of self-blocking mutual exclusion 607 mutex. Blocking mutexes 608 are preferred as they tend to be less CPU-expensive and less likely 609 to cause thrashing. If blocking mutexes are not available, however, 610 test-and-set will work as well. The code for mutexes is in two 611 places in the system: the include file 612 <code class="literal">dbinc/mutex_int.h</code>, and the 613 distribution directory <code class="literal">mutex</code>. 614</p> 615 </div> 616 <div class="sect2" lang="en" xml:lang="en"> 617 <div class="titlepage"> 618 <div> 619 <div> 620 <h3 class="title"><a id="otherchanges"></a>Do Any Other Changes Need to be Made?</h3> 621 </div> 622 </div> 623 </div> 624 <p> 625In most cases, you do not need to make any changes to the Berkeley DB 626source code that is not in the abstraction layer (that is, that is in the 627<code class="literal">os</code> directory) as that code is designed to be platform-independent code. However, in some situations, the compiler for the target platform is non-standard and may raise errors when compiling some aspects of the Berkeley DB code (for example, additional casting may be required, or a certain type may cause a problem). In these cases, you will need to modify the generic Berkeley DB code in order to have error-free compilation. 628</p> 629 </div> 630 </div> 631 <div class="navfooter"> 632 <hr /> 633 <table width="100%" summary="Navigation footer"> 634 <tr> 635 <td width="40%" align="left"><a accesskey="p" href="newbinary.html">Prev</a>��</td> 636 <td width="20%" align="center"> 637 <a accesskey="u" href="newbinary.html">Up</a> 638 </td> 639 <td width="40%" align="right">��<a accesskey="n" href="buildtarget.html">Next</a></td> 640 </tr> 641 <tr> 642 <td width="40%" align="left" valign="top">Chapter��2.��Creating a New Berkeley DB Binary��</td> 643 <td width="20%" align="center"> 644 <a accesskey="h" href="index.html">Home</a> 645 </td> 646 <td width="40%" align="right" valign="top">�� Building on the Target Platform</td> 647 </tr> 648 </table> 649 </div> 650 </body> 651</html> 652