There are certain restrictions that affect how you develop
plug-in libraries.
The following list outlines the restrictions for developing
plug-in libraries.
- C-linkage
- Plug-in libraries must be linked with C-linkage. Header files
providing the prototypes, data structures needed to implement the
plug-ins, and error code definitions are provided for C/C++ only.
Functions that DB2® will resolve
at load time must be declared with extern "C" if the plug-in library
is compiled as C++.
- .NET common language runtime is not supported
- The .NET common language runtime (CLR) is not supported for compiling
and linking source code for plug-in libraries.
- Signal handlers
- Plug-in libraries must not install signal handlers or change the
signal mask, because this will interfere with the DB2 signal handlers. Interfering with the DB2 signal handlers could seriously
interfere with the ability for DB2 to report and recover from errors, including traps in the plug-in
code itself. Plug-in libraries should also never throw C++ exceptions,
as this can also interfere with the error handling used in DB2.
- Thread-safe
- Plug-in libraries must be thread-safe and re-entrant. The plug-in
initialization function is the only API that is not required to be
re-entrant. The plug-in initialization function could potentially
be called multiple times from different processes; in which case,
the plug-in will cleanup all used resources and reinitialize itself.
- Exit handlers and overriding standard C library and operating
system calls
- Plug-in libraries should not override standard C library or operating
system calls. Plug-in libraries should also not install exit handlers
or pthread_atfork handlers. The use of exit handlers
is not recommended because they could be unloaded before the program
exits.
- Library dependencies
- On Linux or UNIX, the processes that load the plug-in libraries
can be setuid or setgid, which means
that they will not be able to rely on the $LD_LIBRARY_PATH,
$SHLIB_PATH, or $LIBPATH environment variables
to find dependent libraries. Therefore, plug-in libraries should not
depend on additional libraries, unless any dependent libraries are
accessible through other methods, such as the following situations:
- By being in /lib or /usr/lib
- By having the directories they reside in being specified OS-wide
(such as in the ld.so.conf file on Linux)
- By being specified in the RPATH in the plug-in
library itself
This restriction is not applicable to Windows operating systems.
- Symbol collisions
- When possible, plug-in libraries should be compiled and linked
with any available options that reduce the likelihood of symbol collisions,
such as those that reduce unbound external symbolic references. For
example, use of the "-Bsymbolic" linker option on HP, Solaris, and Linux can help prevent problems
related to symbol collisions. However, for plug-ins written on AIX®, do not use the "-brtl" linker option explicitly or implicitly.
- 32-bit and 64-bit applications
- 32-bit applications must use 32-bit plug-ins. 64-bit applications
must use 64-bit plug-ins. Refer to the topic about 32-bit and 64-bit
considerations for more details.
- Text strings
- Input text strings are not guaranteed to be null-terminated, and
output strings are not required to be null-terminated. Instead, integer
lengths are given for all input strings, and pointers to integers
are given for lengths to be returned.
- Passing authorization ID parameters
- An authorization ID (authid) parameter that DB2 passes into a plug-in (an input authid parameter)
will contain an upper-case authid, with padded blanks removed. An
authid parameter that a plug-in returns to DB2 (an output authid parameter) does not require
any special treatment, but DB2 will fold the authid to upper-case and pad it with blanks according
to the internal DB2 standard.
- Size limits for parameters
- The plug-in APIs use the following as length limits for parameters:
#define DB2SEC_MAX_AUTHID_LENGTH 255
#define DB2SEC_MAX_USERID_LENGTH 255
#define DB2SEC_MAX_USERNAMESPACE_LENGTH 255
#define DB2SEC_MAX_PASSWORD_LENGTH 255
#define DB2SEC_MAX_DBNAME_LENGTH 128
A particular plug-in
implementation may require or enforce smaller maximum lengths for
the authorization IDs, user IDs, and passwords. In particular, the
operating system authentication plug-ins supplied with DB2 database systems are restricted to the maximum
user, group and namespace length limits enforced by the operating
system for cases where the operating system limits are lower than
those stated previously.
- Security plug-in library extensions in AIX
- On AIX systems, security
plug-in libraries can have a file name extension of .a or .so. The mechanism used to load the plug-in library depends
on which extension is used:
On all platforms other than AIX, security plug-in libraries are always assumed to be dynamically
loadable shared objects.
- Fork
- Plug-in libraries should not fork because file descriptors and
sockets will be duplicated in the child process, and this can cause
hangs or incorrect behavior. In particular, it can cause false file
lock conflicts if child was forked when we had an open file descriptor
on that file. There is also the possibility that the fork will inherit
many other resources like semaphores.