# dklibs 1.27.0

- Overview
- Download
- Download / Installation
- Installation from source on Windows systems
- Usage
- FAQ
- Change log
- Other projects
- Tutorial
- Developer docu
- stc
- tracecc and trana
- tracecc GUI
- tracecc PDF man.
- API: sort and search
- API: Generic I/O
- Preferences
- File search
- Font configuration
- LaTeX encodings
- Security
- DK libraries for Java

## FAQ

- Basics
- What is dklibs
- Which license terms are applied to the package?
- Where can I get the latest version?
- Installation
- Installation on Unix/Linux
- System preparation FAQ
- What does "system preparation" mean?
- Why doesn't the configure script handle an incomplete setup?
- [gcc] How can I report the include search path?
- How can I set the search paths?
- [gcc] How can I set default search paths?
- Build process FAQ
- Which libraries should I install before building dklibs?
- I installed gzip and bzip2. Why do I get error messages about zlib.h and/or bzlib.h files not found?
- How do I handle incompatible versions of recommended libraries?
- How do I build and install the software
- [Mac OS + Fink] Are there special installation instructions?
- [Linux] How do I build shared libraries?
- [Solaris, Sun Workshop compiler] How do I build shared libraries?
- How can I get help using the configure script?
- How do I prepare a directory tree to create an installation package?
- Installation on Windows
- Are there executable setup programs to install the software`
- Why do setup executables contain the applications too?
- How can I build the software from source?
- After installing the software, what should I do next?
- Using the libraries
- Where should CFLAGS and LDFLAGS point to when installing dklibs-based applications?
- Why must CFLAGS/LDFLAGS not point to the dklibs source directory when installing dklibs-based applications?
- UTF-8 support FAQ
- What is UTF-8?
- What problems can occur when using UTF-8 encoding?
- What's the problem with Fig files and UTF-8?
- [Unix/Linux] How will I know whether or not UTF-8 is used?
- How does my graphical desktop handle native characters?
- Can I simply change the LANG environment variable for one program?
- How do Fig drawing applications handle UTF-8 encoding?
- How do fig2vect, text2lat and echo2lat handle UTF-8 encoding?
- How are LaTeX encodings found, how do I create my own tables?
- Using the programs
- Using the Tracecc GUI
- What is the Tracecc GUI?
- Which version of Java is required to run the Tracecc GUI?
- Why do I get a class loader exception when starting the Tracecc GUI?
- How do I localize the Tracecc GUI to my language?

### Basics

What is dklibs

The dklibs package contains a set of libraries and some applications to support the use of the libraries.
The following libraries are contained in the package:

- dkport
  Portability layer.
- dkc
  General purpose C functions.
  Command line application support (includes logging, localization and preference management).
- dknet
  Portable client side TCP/IP networking.
- dkbif
  Library to read bitmap images.
- dklatsup
  Support for applications creating LaTeX source files.
- dksdbi
  Simple interface to NDBM, GDBM and BDB databases.

The following programs are included in the package:

- stc
  String table compiler, converts text string table sources into binary string tables.
- tracecc
  Tracing preprocessor for C, C++, Objective-C and Java.
- trana
  Trace output analyzer

Which license terms are applied to the package?

- dklibs
  Copyright (C) 2000-2008 Dipl.-Ing. Dirk Krause
- Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  - Neither the name of the Dirk Krause nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission.
- This software is provided by the copyright holders and contributors ``as is'' and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed.
  In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

Where can I get the latest version?

This project is hosted on SourceForge, check http://dklibs.sourceforge.net/ for information.
The download area is below the project page http://sourcforge.net/projects/dklibs/

### Installation

#### Installation on Unix/Linux

##### System preparation FAQ

What does "system preparation" mean?

Before you install this software or any of the required/recommended libraries you must make sure the software can be built.
The C compiler must be ready to use both header files distributed with your system and as a part of additional software. The linker must be configured to use the both system libraries and additional libraries.
Some C compilers and linkers are only pre-configured to use libraries shipped with the OS or with the compiler, but no additional libraries. In such cases you need to extend the search paths.
If additional software is installed into /usr/local (found on many Unix/Linux systems), /sw (found on MacOS) or /opt/another-directory (just an example) the C compiler must be configured to search for header files in /usr/local/include, /sw/include and /opt/another-directory/include in addition to the default directories. The linker must be configured to search for library files in /usr/local/lib, /sw/lib and /opt/another-directory/lib.

Why doesn't the configure script handle an incomplete setup?

- If software distributions provide a C compiler and libraries and install both into /sw, it is common sense that C compiler and linker must have /sw/include and /sw/lib in the search paths. The installation process should set this automatically or remind you to do it manually.
- The effort would be growing with m*n*p where m is the number of directories (/usr/local, /sw, /opt/another-directory, /opt/yet-another-directory...), n is the number of compilers to support (one wants CFLAGS, one wants C_INCLUDE_PATH...) and p is the number of projects to maintain.
- Automatic guessing of directories is not the usual behaviour of configure scripts. Most users expect the configure script to use exactly the search paths they have configured.
- To check for a number of directories and to support a number of compilers would produce more code in the configure script than the real configure script contents. But I like to keep things small and simple.
- This large amount of work is possibly (and likely) for the trash can after software distribution comes with a useful setup.

[gcc] How can I report the include search path?

Type

    gcc -v -E -

and press CTRL-D after inspecting the output.
Normally the library search path is corresponding to the include search path, the final "include" subdirectory is replaced by "lib".

How can I set the search paths?

You can set the environment variables CFLAGS and LDFLAGS, i.e.

    CPPFLAGS="-I/usr/local/include -I/sw/include -I/opt/another-directory/include"
    CFLAGS="-I/usr/local/include -I/sw/include -I/opt/another-directory/include"
    LDFLAGS="-L/usr/local/lib -L/sw/lib -L/opt/another-directory/lib"
    export CPPFLAGS CFLAGS LDFLAGS

To have the settings available immediately after each login, add a section

    if [ "X$CPPFLAGS" = "X" ]
    then
      CPPFLAGS="-I/usr/local/include -I/sw/include -I/opt/another-directory/include"
    else
      CPPFLAGS="$CPPFLAGS -I/usr/local/include -I/sw/include -I/opt/another-directory/include"
    fi
    if [ "X$CFLAGS" = "X" ]
    then
      CFLAGS="-I/usr/local/include -I/sw/include -I/opt/another-directory/include"
    else
      CFLAGS="$CFLAGS -I/usr/local/include -I/sw/include -I/opt/another-directory/include"
    fi
    if [ "X$LDFLAGS" = "X" ]
    then
      LDFLAGS="-L/usr/local/lib -L/sw/lib -L/opt/another-directory/lib"
    else
      LDFLAGS="$LDFLAGS -L/usr/local/lib -L/sw/lib -L/opt/another-directory/lib"
    fi
    export CPPFLAGS CFLAGS LDFLAGS

to your .profile file.
To make the settings available to all users, add the section to /etc/profile.
Note: Different shells might use different file names and a different syntax.

[gcc] How can I set default search paths?

For gcc you can use environment variables instead of command line options to extend the search paths. Add

    if [ "X$C_INCLUDE_PATH" = "X" ]
    then
      C_INCLUDE_PATH="/usr/local/include:/sw/include:/opt/another-directory/include"
    else
      C_INCLUDE_PATH="${C_INCLUDE_PATH}:/usr/local/include:/sw/include:/opt/another-directory/include"
    fi
    if [ "X$CPP_INCLUDE_PATH" = "X" ]
    then
      CPP_INCLUDE_PATH="/usr/local/include:/sw/include:/opt/another-directory/include"
    else
      CPP_INCLUDE_PATH="${CPP_INCLUDE_PATH}:/usr/local/include:/sw/include:/opt/another-directory/include"
    fi
    if [ "X$LIBRARY_PATH" = "X" ]
    then
      LIBRARY_PATH="/usr/local/include:/sw/include:/opt/another-directory/include"
    else
      LIBRARY_PATH="${LIBRARY_PATH}:/usr/local/include:/sw/include:/opt/another-directory/include"
    fi
    export C_INCLUDE_PATH CPP_INCLUDE_PATH LIBRARY_PATH

either to your .profile (for a user-specific setup) or to /etc/profile (for a system-wide setup).
Note: Different shells might use different file names and a different syntax.

##### Build process FAQ

Which libraries should I install before building dklibs?

- zlib
  http://www.zlib.net/
  The zlib library is used to read and write compressed files. The dkbif library (which is in turn used by bmeps) uses this library, the fig2vect program too.
- libbz2
  http://sources.redhat.com/bzip2/
  The libbz2 library is used for compression.
- libpng
  http://www.libpng.org/pub/png/libpng.html
  The libpng library is used by the dkbif library (which is in turn used by bmeps) and by the fig2vect program.
- JPEG library
  ftp://ftp.uu.net/graphics/jpeg/
  The JPEG library is used by the dkbif library (which is in turn used by bmeps) and by the fig2vect program.
- NetPBM
  http://sourceforge.net/projects/netpbm
  The NetPBM librariy is used by the dkbif library (which is in turn used by bmeps).
- TIFF library
  http://www.remotesensing.org/libtiff
  The TIFF library is used by the dkbif library (which is in turn used by bmeps).
- OpenSSL
  http://www.openssl.org/
  OpenSSL is used to create messages digests (hashes) of files in kls and to create random numbers in the dkappr module (which is used by createp and rndbytes).
- At least one of:
  - NDBM
    Part of the operating system installation.
  - GDBM
    ftp://ftp.informatik.rwth-aachen.de/pub/gnu/gdbm/
  - Berkeley DB
    http://www.oracle.com/database/berkeley-db/
  NDBM is a database API, some commercial Unix variants (i.e. Solaris) have NDBM support in their C runtime libraries. On these systems I recommend to use the NDBM functions shipped with the system, there is no need to install GDBM. If you insist on installing GDBM make sure the NDBM API functions of GDBM do not hide the "native" NDBM functions.
  On systems without "native" NDBM you should install GDBM.

I installed gzip and bzip2. Why do I get error messages about zlib.h and/or bzlib.h files not found?

Make sure to install the include files and other files for development process too! For some Linux distributions the header files for library xyz are in a package having "xyz-devel" or "xyz-developer" in the name.

How do I handle incompatible versions of recommended libraries?

The configure script only checks for the presence of header files in most cases. For some libraries there are significant API changes between different versions. Run

      make clean

and edit config.h manually to remove the "HAVE_..." lines enabling the problematic header files.
Run

      make

again.

Example: Disabling use of the Berkeley DB
The dklibs module dksdbdb was written to use BDB 4.5. If you have version 4.4 you may get compilation errors when compiling dksdbdb.c.
The main header file for Berkeley DB is ``db.h''.
So run

      make clean

and edit the ``config.h'' file.
Replace

      #define HAVE_DB_H     1

by

      #define HAVE_DB_H     0

and continue compilation.

How do I build and install the software

After unpacking the archive using (version number may differ)

    gzip -dc dklibs-1.8.0-tar.gz | tar xvf -

change into the new "dklibs" directory and run

    ./configure
    make
    make install

[Mac OS + Fink] Are there special installation instructions?

Note: I'm not a Mac user, so I can not give very detailed information. But I'll attempt to describe the process here.

- The dklibs library set depends on some other libraries. Mac OS versions of these libraries are available in the Fink project.
- If you did not yet install Fink (see http://www.finkproject.org), install it now.
  If you can choose packages manually, make sure to install
  - zlib and zlib-devel
  - libbz2 and libbz2-devel
  - libpng and libpng-devel
  - libjpeg and libjpeg-devel
  - netpbm and netpbm-devel
  - libtiff and libtiff-devel
  - openssl and openssl-devel
  - gdbm and gdbm-devel
  The package names shown here are as on my Linux system. May be names differ on Mac OS / Fink. The important point is to not just install binaries but header files and development support too.
- I do not know whether or not the Fink installation process sets up include paths and library paths for your compiler and linker to use the Fink header files and libraries.
  Previous versions didn't.
- So before running configure we have to make sure to set the environment variables properly:

      CFLAGS="-I/sw/include $CFLAGS"
      CPPFLAGS="-I/sw/include $CPPFLAGS"
      LDFLAGS="-L/sw/lib $LDFLAGS"
      export CFLAGS
      export CPPFLAGS
      export LDFLAGS
      ./configure

  If you have a 64-bit version of Fink, you might have an /sw64 directory instead of /sw. If you have a /sw64 directory you need to replace all occurances of ``/sw'' by ``/sw64'' in the commands shown above.
- After configuring we probably need to disable Berkely DB support. There are significant API changes between 4.4 and 4.5.
  Edit the ``config.h'' file in your favourite text editor, search for a line containing ``HAVE_DB_H'' and replace

      #define HAVE_DB_H 1

  by

      #define HAVE_DB_H 0

- Now we should be able to run:

      make
      make install

- The default installation goes into the /usr/local directory. You must make sure the directory ``/usr/local/bin'' is listed in the PATH environment variable of your system.
- If you want to compile and install software using the dklibs library set you have to set environment variables properly to contain ``/usr/local/include'' and ``/usr/local/lib'' before you call the configure script of the other packages:

      CFLAGS="-I/sw/include -I/usr/local/include $CFLAGS"
      CPPFLAGS="-I/sw/include -I/usr/local/include $CPPFLAGS"
      LDFLAGS="-L/sw/lib -L/usr/local/lib $LDFLAGS"
      export CFLAGS
      export CPPFLAGS
      export LDFLAGS

  Again, if you have an ``/sw64'' directory instead of ``/sw'' you must replace all occurances of ``/sw'' by ``/sw64'' in the commands shown above.

[Linux] How do I build shared libraries?

- Run

      ./configure
      make -f Makefile-shared-linux
      make -f Makefile-shared-linux install

- Edit /etc/ld.so.conf, make sure /usr/local/lib is included.
- Run the ldconfig program (typically /sbin/ldconfig).

[Solaris, Sun Workshop compiler] How do I build shared libraries?

- Run

      ./configure
      make -f Makefile-shared-solaris-workshop
      make -f Makefile-shared-solaris-workshop install

- Make sure the /usr/local/lib path is in the search path for shared libraries.
  Possibly you want to set the LD_LIBRARY_PATH environment variable.

How can I get help using the configure script?

The usual options can be provided to the configure script, run

    ./configure --help

to see a list of possible options.

How do I prepare a directory tree to create an installation package?

Run

    ./configure
    make
    make pp=/home/joe/package install

to create the directory structure needed to prepare a package in the `/home/joe/package` directory.

#### Installation on Windows

Are there executable setup programs to install the software`

There are two different executable setup packages available from the dklibs-win32 package in the downloads section on the SourcForge project page. Both packages not only contain dklibs but also some of my applications using the libraries.
The dklibs-win32-user-*.exe is the recommended setup, it installs binaries and documentation on the local computer.
The dklibs-win32-base-*.exe only installs the binaries, documentation start menu entries will point to web resources. Use this setup only if you really need to save disk space and your computer is permanently connected to the internet.

Why do setup executables contain the applications too?

There are dependencies between the software packages, the applications need some file shipped with the libaries to run (i.e. string tables for error messages...). Registry entries are needed to find directories. When using different setup executables for libraries and applications users might choose different installation directories what will end up in file-not-found errors.
Keeping all things in one setup executable make it easier to do a consistent setup.

How can I build the software from source?

The installation from source is described in detail in the inst_w32.html file.

After installing the software, what should I do next?

Follow the Post installation steps described in install.html.

### Using the libraries

Where should CFLAGS and LDFLAGS point to when installing dklibs-based applications?

Both variables must point to the include/lib subdirectory of the dklibs installation directory, not the source directory.

Why must CFLAGS/LDFLAGS not point to the dklibs source directory when installing dklibs-based applications?

The dklibs library set uses an include file "dkconfig.h" which comes in two versions:

- The first version is shipped with the source archive. This file includes the "config.h" file produced by the "configure" script in the source directory.
- The second version is created during the the installation process and installed as $(includedir)/dkconfig.h. All the #define's in this file are fixed, no "config.h" file is included here. This file must be used to install software linked against the libraries.

If the first version is used while installing dklibs-based applications the compiler includes a "config.h" file. But it will not find the file for dklibs, it will used the "config.h" file for the application instead. A lot of #define's will be missing.

### UTF-8 support FAQ

What is UTF-8?

UNICODE is a character set using 32 bits. Documents using this character set can use characters/glyphs from different languages.
UTF-8 is an encoding for UNICODE characters using 1 byte for the glyphs used most often and up to 6 bytes (48 bits) for the not-so-popular glyphs.

What problems can occur when using UTF-8 encoding?

The same glyph is encoded differently when using UTF-8 and traditional encodings. An application showing text must know whether or not the text is UTF-8 encoded or not.

What's the problem with Fig files and UTF-8?

The Fig file format does not allow to provide information whether or not UTF-8 is used.
So there are two ways to tell applications processing Fig files which encoding is used:

- command line options and
- special comments in the Fig files. These comments are processed by programs like fig2vect and ignored by other programs.

[Unix/Linux] How will I know whether or not UTF-8 is used?

Check the LANG environment variable. If it ends on ``.UTF-8'' (not case-sensitive) -- like ``de_DE.UTF-8'' your system uses UTF-8 encoding.
If it does not end on ``.UTF-8'' -- i.e. ``de_DE'' -- your system does not use UTF-8 encoding.

How does my graphical desktop handle native characters?

Handling of native characters (i.e. german umlauts) depends on the systems LANG setting.

- If UTF-8 is turned off and you type the german umlaut ä on the keyboard, one byte -- the ANSI code for ä -- is sent from the X11 system to the application.
- If UTF-8 is turned on and you type ä two bytes -- the UTF-8 encoded ä -- is sent to the application.
  An UTF-8 aware application will inspect the two bytes, find the ä and save the ä correctly in output files (using the encoding required by the file format specification). To render texts on screen the ä is sent to X11 UTF-8 encoded.
  If the application is not UTF-8 aware it simply stores the two bytes as two characters. In most cases text is shown fine on screen (if X11 is set up to use UTF-8 it will create keyboard events containging UTF-8 encoded data, the routines showing text expect UTF-8 encoded text). When saving data to files, data is stored UTF-8 encoded no matter whether or not the file format specification allows this.

Can I simply change the LANG environment variable for one program?

No, don't do that! All desktop applications must use the same UTF-8 setting. You may change LANG from ``de_DE'' to ``en_US'' or from ``de_DE.UTF-8'' to ``en_US.UTF-8'', but not from ``de_DE'' to ``de_DE.UTF-8''.
If you want to change the UTF-8 usage, log in as root (or Administrator), change the setting globally -- i.e. in /etc/sysconfig/i18n -- and reboot the system.
If the desktop delivers not-UTF-8 encoded data and an application expects UTF-8 encoded data (or vice versa) there is a wide variety of results: unknown keyboard bindings, application crashes...

How do Fig drawing applications handle UTF-8 encoding?

- jFig -- or one of the libraries jFig uses -- seems to handle UTF-8 encoding perfectly (from my point of view). If LANG is set to ``de_DE.UTF-8'' german umlauts are saved to Fig files using 1 byte. This indicates that the texts were recoded internally before saving to file.
- In XFig handling differs depending on where german umlauts are inserted. When typing text in the drawing area, german umlauts are ignored. In the "Edit" dialog box german umlauts are converted into two malformed characters. Text is saved to output files UTF-8 encoded, two bytes are used for ä.
  Note: The statements above are related to XFig 3.2.4 on Fedora Core 5 using ``de_DE.UTF-8''. The behaviour can differ for other XFig versions, other OS and other localization settings.

How do fig2vect, text2lat and echo2lat handle UTF-8 encoding?

Fig2vect cares about UTF-8 encoded text in non-special text only.
In special text you can use LaTeX code directly to produce the glyphs you need.
Handling UTF-8 encoded strings depends on the driver:

- EPS and PDF: The driver can hande UNICODE characters in the range 0x00000000...0x000000FF. Texts are recoded from UTF-8 to ANSI and saved in WinAnsiEncoding in PDF files and in ISOLatin1Encoding in EPS files.
  Characters above 0x000000FF can not be handled.
- TeX and MetaPost: The texts are recoded to UNICODE, the driver uses the dkle_...() functions to find an appropriate LaTeX encoding.
  Note: The encoding tables in dklibs are very incomplete, at this time they contain support for some european languages only.
  If you have created a table for codes not yet in the list, please share it and use the bug track/feature request mechanisms on SourceForge.

In text2lat and echo2lat input text is UTF-8 decoded if necessary, the programs replace each character by the corresponding LaTeX encoding. Text2lat allows to specify whether or not newlines are replaced by ``\\<newline>'' and whether or not spaces are replaced by ``~''.

How are LaTeX encodings found, how do I create my own tables?

The dklibs library set uses a preference to find a shared directory (shared between all dklibs-based applications). This directory is /usr/local/share on Unix/Linux and c:\programme\krause\share on Windows by default. The ``c:\programme'' part can differ, it depends on your Windows version and language.
This directory contains a sub-directory ``uc2lat-t'' providing tables for translation from UNICODE to LaTeX. There is a nested directory structure containing multiple files. Files are loaded on demand.
The encoding for UNICODE 0x01234567 is found by searching the file 01/23/45.dat file for an 0x67 entry.
There are three types of entries in the file:

- * hex LaTeX
  The LaTeX code can be used both in normal and in math mode.
- t hex LaTeX
  The LaTeX code can be used in normal (non-math) mode only.
- m hex LaTeX
  The LaTeX code can be used in math mode only.

Example (from 00/00/00.dat):

    *       0x23    \#

    t       0x2A    \textasteriskcentered{}
    m       0x2A    *

    t       0x3C    \textless{}
    m       0x3C    <

If you have created or modified tables, please share them! If you are willing to publish them under BSD-style license conditions (the license used by dklibs), please use the bug-tracking or feature-request mechanisms or forums on SourceForge (http://sourceforge.net/projects/dklibs/) to submit the tables.

### Using the programs

#### Using the Tracecc GUI

What is the Tracecc GUI?

The Tracecc GUI is a Java application providing a graphical user interface to the tracecc program.

Which version of Java is required to run the Tracecc GUI?

The Tracecc GUI requires the Java Runtime Environment in version 1.5 (sometimes referred to as Java 5). I recommend to use the current JRE available on http://java.sun.com.

Why do I get a class loader exception when starting the Tracecc GUI?

Most likely you are using an insufficient JRE implementation, which does not provide all the classes needed by the Tracecc GUI.
Make sure to use the up-to-date JRE from http://java.sun.com.

How do I localize the Tracecc GUI to my language?

- The users language and region are retrieved from either the "LANG" environment variable or from the system properties.
- The program has built-in default strings for all the texts used by the application.
- Before the GUI is constructed the application attempts to read text files containing texts in the users preferred language/region pair or in the preferred language. If the text file is not found the built-in defaults are used.
- The location of the localized files in the source tree is the "loc/language/region" directory or "loc/language". Two-letter codes are used for language and region, both in lower-case characters.
  The location of the localized files in the jar archive is "/language/region" or "/language".
- The Tracecc GUI uses 3 files:
  - tracegui.txt
    for the texts in the Tracecc GUI application except the GUI setup dialog box.
    This is a text replacement file to replace the texts from the "def_t" array in the TraceccGuiMain.java file.
  - dkguiset.txt
    for the texts in the GUI setup dialog box.
    This is a text replacement file to replace the texts from the "def_t" array in the DkGuiDialog.java file.
  - index.html
    for the help text.
    This is a normal HTML file without any embedded images or objects.
- The syntax of text replacement files is as follows:
  - All lines starting with "#" in column 0 are comment lines.
  - The text in each line (except the comment lines) replaces one text from the built-in array. The first non-comment line replaces array element 0, the next array element 1 ...
    For long texts use long lines, do not split texts about several lines.
- To localize the application to your language, create a subdirectory in loc for your language, copy the files from the "de" directory into your new directory and edit the files.
  You should have the corresponding source files open to see where you need empty lines (for empty texts) or lines containing spaces (as placeholders).
  When you are done, run the

      ./build

  script to create a new *.jar file.