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:
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 must port these files (or versions of these files) whenever you port Berkeley DB to a new platform.
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 os 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 os_alloc.c file contains functions such as
malloc, realloc,
strdup, free).
The following table describes the files in the os directory of the Berkeley DB distribution along with the POSIX functions that must be ported.
|
POSIX Functions |
Internal Function Name |
Source File |
|---|---|---|
|
abort() is required if diagnostic build is used or if snprintf is not provided by the platform |
__os_abort() |
os_abort.c |
|
freeaddrinfo()
getaddrinfo(), htonl(), htons(), inet_addr(), and gethostbyname() are required for Replication Manager
|
__os_getaddrinfo(), __os_freeaddrinfo() |
os_addrinfo.c |
|
malloc(), realloc(), strdup(), free(), memcpy(), memset(), strlen() |
__os_umalloc(), __os_urealloc(), __os_ufree(), __os_strdup(), __os_calloc(), __os_malloc(), __os_realloc(), __os_free(), __os_guard(), __ua_memcpy() |
os_alloc.c |
|
clock_gettime(), time(), gettimeofday() |
__os_gettime() |
os_clock.c |
|
sysconf() |
__os_cpu_count() |
os_cpu.c |
|
ctime(), ctime_r() |
__os_ctime() |
os_ctime.c |
|
opendir(), closdir(), readdir(), stat() |
__os_dirlist(), __os_dirfree() |
os_dir.c |
|
strncpy() |
__os_get_errno_ret_zero(), __os_get_errno(), __os_get_syserr(), __os_set_errno(), __os_strerror(), __os_posix_err() |
os_errno.c |
|
fcntl() is required for DB_REGISTER |
__os_fdlock() |
os_flock.c |
|
fsync(), fdatasync() |
__vx_fsync(), __os_fsync() |
os_fsync.c |
|
getenv() and strcpy() are required when environment variables are used to configure the database |
__os_getenv() |
os_getenv.c |
|
close(), open() |
__os_openhandle(), __os_closehandle() |
os_handle.c |
|
getpid() pthread_self() is required for replication and failchk functionality |
__os_id() |
os_pid.c |
|
shmget(), shmdt(), shmctl(), and shmat() are required when envrionment uses share memory for regions munmap() is required when envrionment uses memory mapped files for regions or read-only databases munlock() is required when environment is configured with DB_LOCKDOWN |
__os_attach(), __os_detach(), __os_mapfile(), __os_unmapfile(), __os_map(), __shm_mode(), __no_system_mem() |
os_map.c |
|
mkdir(), chmod() |
__os_mkdir() |
os_mkdir.c |
|
fchmod() directio() is required when explicitly enabling DIRECTIO_ON |
__os_open() |
os_open.c |
|
rename() |
__os_rename() |
os_rename.c |
|
getuid() is required when environment variables are used to configure the database |
__os_isroot() |
os_root.c |
|
read(), write(), pread(), pwrite() |
__os_io(), __os_read(), __os_write(), __os_physwrite() |
os_rw.c |
|
lseek() |
__os_seek() |
os_seek.c |
|
stat(), fstat() |
__os_exists(), __os_ioinfo() |
os_stat.c |
|
ftruncate() is required when using truncate |
__os_truncate() |
os_truncate.c |
|
unlink() |
__os_unlink() |
os_unlink.c |
|
yield(), sched_yield() |
__os_yield(), __os_sleep() |
os.yield.c |
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 os 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.
Where different code is required, you write an entirely different version
of the file and place it in an os_xxx directory where xxx represents a platform name.
There are os_xxx
subdirectories in the Berkeley DB distribution for several established
non-POSIX platforms. For example, there is a
os_vxworks directory that contains VxWorks
versions of some of the files in the os directory, and Windows versions of
some files are in the os_windows 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 os_xxx directory that you create for your target platform.
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
clib directory
of the Berkeley DB distribution.
You need to determine how your target platfrom handles these functions:
When the target platform does not 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 clib directory of the Berkeley
DB distribution. For example, if the target platform does not have
the atoi or strtol functions,
Berkeley DB uses clib/atoi.c and
clib/strtol.c.
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 clib directory.
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.
On UNIX/POSIX systems, Berkeley DB uses
mmap and shmget 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 os_vxworks/os_map.c as a starting point for the port.
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.
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
dbinc/mutex_int.h, and the
distribution directory mutex.
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
os 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.