Chapter 6. Programming Manual

This chapter describes all the publicly available functions in the library.

6.1. Preparation

To use `Libshishi', you have to perform some changes to your sources and the build system. The necessary changes are small and explained in the following sections. At the end of this chapter, it is described how the library is initialized, and how the requirements of the library are verified.

A faster way to find out how to adapt your application for use with `Libshishi' may be to look at the examples at the end of this manual (Section 6.15).

6.1.1. Header

All interfaces (data types and functions) of the library are defined in the header file `shishi.h'. You must include this in all programs using the library, either directly or through some other header file, like this:

#include <shishi.h>

The name space of `Libshishi' is shishi_* for function names, Shishi* for data types and SHISHI_* for other symbols. In addition the same name prefixes with one prepended underscore are reserved for internal use and should never be used by an application.

6.1.2. Initialization

`Libshishi' must be initialized before it can be used. The library is initialized by calling shishi_init (Section 6.2). The resources allocated by the initialization process can be released if the application no longer has a need to call `Libshishi' functions, this is done by calling shishi_done.

In order to take advantage of the internationalisation features in `Libshishi', such as translated error messages, the application must set the current locale using setlocale before initializing `Libshishi'.

6.1.3. Version Check

It is often desirable to check that the version of `Libshishi' used is indeed one which fits all requirements. Even with binary compatibility new features may have been introduced but due to problem with the dynamic linker an old version is actually used. So you may want to check that the version is okay right after program startup.

const char * shishi_check_version (const char * req_version) req_version: version string to compare with, or NULL

Check that the the version of the library is at minimum the one given as a string in req_version.

Return value: the actual version string of the library; NULL if the condition is not met. If NULL is passed to this function no check is done and only the version string is returned. It is a pretty good idea to run this function as soon as possible, because it may also intializes some subsystems. In a multithreaded environment if should be called before any more threads are created.

The normal way to use the function is to put something similar to the following early in your main:

  if (!shishi_check_version (SHISHI_VERSION))
      printf ("shishi_check_version failed:\n"
              "Header file incompatible with shared library.\n");

6.1.4. Building the source

If you want to compile a source file including the `shishi.h' header file, you must make sure that the compiler can find it in the directory hierarchy. This is accomplished by adding the path to the directory in which the header file is located to the compilers include file search path (via the -I option).

However, the path to the include file is determined at the time the source is configured. To solve this problem, `Libshishi' uses the external package pkg-config that knows the path to the include file and other configuration options. The options that need to be added to the compiler invocation at compile time are output by the -cflags option to pkg-config shishi. The following example shows how it can be used at the command line:

gcc -c foo.c `pkg-config shishi --cflags`

Adding the output of pkg-config shishi -cflags to the compilers command line will ensure that the compiler can find the `Libshishi' header file.

A similar problem occurs when linking the program with the library. Again, the compiler has to find the library files. For this to work, the path to the library files has to be added to the library search path (via the -L option). For this, the option -libs to pkg-config shishi can be used. For convenience, this option also outputs all other options that are required to link the program with the `Libshishi' libararies (in particular, the -lshishi option). The example shows how to link foo.o with the `Libshishi' library to a program foo.

gcc -o foo foo.o `pkg-config shishi --libs`

Of course you can also combine both examples to a single command by specifying both options to pkg-config:

gcc -o foo foo.c `pkg-config shishi --cflags --libs`

6.1.5. Autoconf tests

If you work on a project that uses Autoconf () to help find installed libraries, the suggestions in the previous section are not the entire story. There are a few methods to detect and incorporate Shishi into your Autoconf based package. The preferred approach, is to use Libtool in your project, and use the normal Autoconf header file and library tests. Autoconf test via pkg-config

If your audience is a typical GNU/Linux desktop, you can often assume they have the pkg-config tool installed, in which you can use its Autoconf M4 macro to find and set up your package for use with Shishi. The following illustrate this scenario.

                       [don't use the KERBEROS_V5 mechanism]),
if test "$kerberos_v5" != "no" ; then
	PKG_CHECK_MODULES(SHISHI, shishi >= 0.0.0,
	if test "$kerberos_v5" != "yes" ; then
		AC_MSG_WARN([shishi not found, disabling Kerberos 5])
                          [Define to 1 if you want Kerberos 5.])
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos_v5) Standalone Autoconf test using Libtool

If your package uses Libtool(), you can use the normal Autoconf tests to find the Shishi library and rely on the Libtool dependency tracking to include the proper dependency libraries (e.g., Libidn). The following illustrate this scenario.

	AC_CHECK_LIB(shishi, shishi_check_version,
		[kerberos5=yes AC_SUBST(SHISHI_LIBS, -lshishi)],
                       [disable Kerberos 5 unconditionally]),
if test "$kerberos5" != "no" ; then
		  [Define to 1 if you want Kerberos 5.])
	AC_MSG_WARN([Shishi not found, disabling Kerberos 5])
AC_MSG_CHECKING([if Kerberos 5 should be used])
AC_MSG_RESULT($kerberos5) Standalone Autoconf test

If your package does not use Libtool, as well as detecting the Shishi library as in the previous case, you must also detect whatever dependencies Shishi requires to work (e.g., libidn). Since the dependencies are in a state of flux, we do not provide an example and we do not recommend this approach, unless you are experienced developer.