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
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Determining the Scope of the Modifications</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Porting Berkeley DB" />
<link rel="up" href="newbinary.html" title="Chapter 2. Creating a New Berkeley DB Binary" />
<link rel="prev" href="newbinary.html" title="Chapter 2. Creating a New Berkeley DB Binary" />
<link rel="next" href="buildtarget.html" title="Building on the Target Platform" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 11.2.5.3</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">
Determining the Scope of the Modifications
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="newbinary.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. Creating a New Berkeley DB Binary</th>
<td width="20%" align="right"> <a accesskey="n" href="buildtarget.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="modscope"></a>
Determining the Scope of the Modifications
</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="modscope.html#osfunc">
Do Changes Need to be Made to the Operating System Functionality?
</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="modscope.html#standardfunc">Are Some Standard Functions Missing on the Target Platform?</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="modscope.html#sharedmem">How Will the Port Handle Shared Memory?</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="modscope.html#typemutex">What Type of Mutexes Will the Port Use?</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="modscope.html#otherchanges">Do Any Other Changes Need to be Made?</a>
</span>
</dt>
</dl>
</div>
<p>
Once 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:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a class="xref" href="modscope.html#osfunc" title="Do Changes Need to be Made to the Operating System Functionality?">
Do Changes Need to be Made to the Operating System Functionality?
</a>
</p>
</li>
<li>
<p>
<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>
</p>
</li>
<li>
<p>
<a class="xref" href="modscope.html#sharedmem" title="How Will the Port Handle Shared Memory?">How Will the Port Handle Shared Memory?</a>
</p>
</li>
<li>
<p>
<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>
</p>
</li>
<li>
<p>
<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>
</p>
</li>
</ul>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="osfunc"></a>
Do Changes Need to be Made to the Operating System Functionality?
</h3>
</div>
</div>
</div>
<p>
Berkeley 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.
</p>
<p>
Within a Berkeley DB distribution, typically, there is only a single
version of these files for all platforms that Berkeley DB supports. Those
versions of the files live in the <code class="literal">os</code> directory of the
distribution and follow the ANSI C and POSIX 1003.1 standards. Within each
file, there is usually one, but sometimes several functions (for example,
the <code class="literal">os_alloc.c</code> file contains functions such as
<code class="literal">malloc</code>, <code class="literal">realloc</code>,
<code class="literal">strdup</code>, <code class="literal">free</code>).
The following table describes the files in the os directory of the Berkeley DB distribution along with the POSIX functions that must be ported.
</p>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>
<p>
POSIX Functions
</p>
</th>
<th>
<p>
Internal Function Name
</p>
</th>
<th>
<p>
Source File
</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>
abort() is required if diagnostic build is used or if snprintf is not provided by the platform
</p>
</td>
<td>
<p>
__os_abort()
</p>
</td>
<td>
<p>
os_abort.c
</p>
</td>
</tr>
<tr>
<td>
<p>
</p><p>
freeaddrinfo()
</p><p>
</p><p>getaddrinfo(), htonl(), htons(), inet_addr(), and gethostbyname() are required for Replication Manager</p><p>
</p>
</td>
<td>
<p>
__os_getaddrinfo(), __os_freeaddrinfo()
</p>
</td>
<td>
os_addrinfo.c
</td>
</tr>
<tr>
<td>
<p>
malloc(), realloc(), strdup(), free(), memcpy(), memset(), strlen()
</p>
</td>
<td>
__os_umalloc(), __os_urealloc(), __os_ufree(), __os_strdup(), __os_calloc(), __os_malloc(), __os_realloc(), __os_free(), __os_guard(), __ua_memcpy()
</td>
<td>
<p>
os_alloc.c
</p>
</td>
</tr>
<tr>
<td>
<p>
clock_gettime(), time(), gettimeofday()
</p>
</td>
<td>
<p>
__os_gettime()
</p>
</td>
<td>
<p>
os_clock.c
</p>
</td>
</tr>
<tr>
<td>
<p>
sysconf()
</p>
</td>
<td>
<p>
__os_cpu_count()
</p>
</td>
<td>
<p>
os_cpu.c
</p>
</td>
</tr>
<tr>
<td>
<p>
ctime(), ctime_r()
</p>
</td>
<td>
<p>
__os_ctime()
</p>
</td>
<td>
<p>
os_ctime.c
</p>
</td>
</tr>
<tr>
<td>
<p>
opendir(), closdir(), readdir(), stat()
</p>
</td>
<td>
<p>
__os_dirlist(), __os_dirfree()
</p>
</td>
<td>
<p>
os_dir.c
</p>
</td>
</tr>
<tr>
<td>
<p>
strncpy()
</p>
</td>
<td>
<p>
__os_get_errno_ret_zero(), __os_get_errno(), __os_get_syserr(), __os_set_errno(), __os_strerror(), __os_posix_err()
</p>
</td>
<td>
<p>
os_errno.c
</p>
</td>
</tr>
<tr>
<td>
<p>
fcntl() is required for DB_REGISTER
</p>
</td>
<td>
<p>
__os_fdlock()
</p>
</td>
<td>
<p>
os_flock.c
</p>
</td>
</tr>
<tr>
<td>
<p>
fsync(), fdatasync()
</p>
</td>
<td>
<p>
__vx_fsync(), __os_fsync()
</p>
</td>
<td>
<p>
os_fsync.c
</p>
</td>
</tr>
<tr>
<td>
<p>
getenv() and strcpy() are required when environment variables are used to configure the database
</p>
</td>
<td>
<p>
__os_getenv()
</p>
</td>
<td>
<p>
os_getenv.c
</p>
</td>
</tr>
<tr>
<td>
<p>
close(), open()
</p>
</td>
<td>
<p>
__os_openhandle(), __os_closehandle()
</p>
</td>
<td>
<p>
os_handle.c
</p>
</td>
</tr>
<tr>
<td>
<p>
getpid()
</p>
<p>
pthread_self() is required for replication and failchk functionality
</p>
</td>
<td>
<p>
__os_id()
</p>
</td>
<td>
<p>
os_pid.c
</p>
</td>
</tr>
<tr>
<td>
<p>
shmget(), shmdt(), shmctl(), and shmat() are required when envrionment uses share memory for regions
</p>
<p>munmap() is required when envrionment uses memory mapped files for regions or read-only databases
</p>
<p>munlock() is required when environment is configured with DB_LOCKDOWN
</p>
</td>
<td>
<p>
__os_attach(), __os_detach(), __os_mapfile(), __os_unmapfile(), __os_map(), __shm_mode(), __no_system_mem()
</p>
</td>
<td>
<p>
os_map.c
</p>
</td>
</tr>
<tr>
<td>
<p>
mkdir(), chmod()
</p>
</td>
<td>
<p>
__os_mkdir()
</p>
</td>
<td>
<p>
os_mkdir.c
</p>
</td>
</tr>
<tr>
<td>
<p>
fchmod() </p>
<p>directio() is required when explicitly enabling DIRECTIO_ON
</p>
</td>
<td>
<p>
__os_open()
</p>
</td>
<td>
<p>
os_open.c
</p>
</td>
</tr>
<tr>
<td>
<p>
rename()
</p>
</td>
<td>
<p>
__os_rename()
</p>
</td>
<td>
<p>
os_rename.c
</p>
</td>
</tr>
<tr>
<td>
<p>
getuid() is required when environment variables are used to configure the database
</p>
</td>
<td>
<p>
__os_isroot()
</p>
</td>
<td>
<p>
os_root.c
</p>
</td>
</tr>
<tr>
<td>
<p>
read(), write(), pread(), pwrite()
</p>
</td>
<td>
<p>
__os_io(), __os_read(), __os_write(), __os_physwrite()
</p>
</td>
<td>
<p>
os_rw.c
</p>
</td>
</tr>
<tr>
<td>
<p>
lseek()
</p>
</td>
<td>
<p>
__os_seek()
</p>
</td>
<td>
<p>
os_seek.c
</p>
</td>
</tr>
<tr>
<td>
<p>
stat(), fstat()
</p>
</td>
<td>
<p>
__os_exists(), __os_ioinfo() </p>
</td>
<td>
<p>
os_stat.c
</p>
</td>
</tr>
<tr>
<td>
<p>
ftruncate() is required when using truncate
</p>
</td>
<td>
<p>
__os_truncate() </p>
</td>
<td>
<p>
os_truncate.c
</p>
</td>
</tr>
<tr>
<td>
<p>
unlink()
</p>
</td>
<td>
<p>
__os_unlink()
</p>
</td>
<td>
<p>
os_unlink.c
</p>
</td>
</tr>
<tr>
<td>
<p>
yield(), sched_yield()
</p>
</td>
<td>
<p>
__os_yield(), __os_sleep() </p>
</td>
<td>
<p>
os.yield.c
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>
When the operating system primitives on the target platform are identical
or close to the POSIX semantics that Berkeley DB requires, then no code
changes 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.
</p>
<p>
Where different code is required, you write an entirely different version
of 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.
There are <code class="literal">os</code>_<span class="emphasis"><em>xxx</em></span>
subdirectories in the Berkeley DB distribution for several established
non-POSIX platforms. For example, there is a
<code class="literal">os_vxworks</code> directory that contains VxWorks
versions of some of the files in the os directory, and Windows versions of
some files are in the <code class="literal">os_windows</code> directory. If
your target platform needs a different version of a file, you will need to
write 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.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="standardfunc"></a>Are Some Standard Functions Missing on the Target Platform?</h3>
</div>
</div>
</div>
<p>
In some cases, the target platform may not provide the few POSIX
functions required by Berkeley DB or the functions provided by the
target platform may not operate in a standard compliant way.
Berkeley DB provides replacement functions in the
<code class="literal">clib</code> directory
of the Berkeley DB distribution.
</p>
<p>
You need to determine how your target platfrom handles these functions:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
When the target platform does <span class="emphasis"><em>not</em></span> have a POSIX
function required by Berkeley DB, no action is required on your
part. When Berekely DB cannot find one of these functions on the
target platform, it automatically uses the replacement functions
supplied in the <code class="literal">clib</code> directory of the Berkeley
DB distribution. For example, if the target platform does not have
the <code class="literal">atoi</code> or <code class="literal">strtol</code> functions,
Berkeley DB uses <code class="literal">clib/atoi.c</code> and
<code class="literal">clib/strtol.c</code>.
</p>
</li>
<li>
<p>
When the target platform has a function required by Berekely DB, but that
function operates in a non-standard compliant way, you can code to the
replacement functions supplied in the <code class="literal">clib</code> directory.
</p>
</li>
</ul>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="sharedmem"></a>How Will the Port Handle Shared Memory?</h3>
</div>
</div>
</div>
<p>
In order to write
multiprocess 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.
</p>
<p>
On UNIX/POSIX systems, Berkeley DB uses
<code class="literal">mmap</code> and <code class="literal">shmget</code> for that purpose,
but any interface that provides access to named shared memory is
sufficient. If you have a simple, flat address space, you should be able
to use the code in <code class="literal">os_vxworks/os_map.c</code> as a starting point for the port.
</p>
<p>
If 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.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="typemutex"></a>What Type of Mutexes Will the Port Use?</h3>
</div>
</div>
</div>
<p>
Berkeley DB requires some form of self-blocking mutual exclusion
mutex. Blocking mutexes
are preferred as they tend to be less CPU-expensive and less likely
to cause thrashing. If blocking mutexes are not available, however,
test-and-set will work as well. The code for mutexes is in two
places in the system: the include file
<code class="literal">dbinc/mutex_int.h</code>, and the
distribution directory <code class="literal">mutex</code>.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="otherchanges"></a>Do Any Other Changes Need to be Made?</h3>
</div>
</div>
</div>
<p>
In most cases, you do not need to make any changes to the Berkeley DB
source code that is not in the abstraction layer (that is, in the
<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.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="newbinary.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="newbinary.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="buildtarget.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 2. Creating a New Berkeley DB Binary </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Building on the Target Platform</td>
</tr>
</table>
</div>
</body>
</html>
|
