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