Sun logo      Previous      Contents      Index      Next     

Sun Java System LDAP SDK for C Programming Guide

Chapter 1

The Sun™ Java System Directory Server Resource Kit (DSRK) LDAP SDK for C Programming Guide provides instructions for the Lightweight Directory Access Protocol (LDAP) software development kit (SDK) for C as well as usage information for the application programming interfaces (APIs). This introductory chapter contains the following sections:


The DSRK includes the Sun Java System LDAP SDK for C. The LDAP SDK for C includes the C libraries for the LDAP API as well as sample code that demonstrates how to call most of the functions. The APIs are defined by the header files that declare all of the functions, data types and code values available in the binaries. You use the functions contained in this API to write C or C++ client applications that take full advantage of the capabilities of Sun Java System Directory Server. The API also includes custom extensions that give access to the latest features in Directory Server 5.2.


Because they are built around core functions of the LDAP v2 and v3 standards, the API can be used to interact with any conforming LDAP server. This API conforms to the Internet Engineering Task Force (IETF) standard proposed in The C LDAP Application Programming Interface (


The Lightweight Directory Access Protocol (v3), RFC 2251 ( defines a set of operations that must be used to access data in a LDAPv3-compliant directory server. The functionality implemented in the LDAP SDK for C closely follows these operations as a C API is defined for each operation. Using the C API, you can enable your clients to connect to LDAPv3-compliant directory servers and perform standard or extended LDAP functions such as:

For example, if you are writing an email application, you can use the functions in the API to retrieve email addresses from an LDAP server.

Synchronous and Asynchronous Operations

The API functions allow you to perform LDAP operations synchronously or asynchronously. (The only differences between these two options are in the calling convention; the LDAP exchanges are identical.)

For more information on synchronous and asynchronous operations, see "Synchronous Examples" and "Asynchronous Examples" as well as "Managing Memory" of Chapter 4, "Using the LDAP API." For a complete list of the functions implemented in this SDK, refer to Chapter 17, "Function Reference."

Installation Instructions

Instructions on installing the DSRK can be found in the Sun Java System Directory Server Resource Kit Tools Reference ( After installation, the base directory for the LDAP SDK for C on a Solaris™ operating system is DSRK_base/lib/ldapcsdk.

Provided Directories and Files

The DSRK, in addition to the utilities discussed in the Sun Java System Directory Server Resource Kit Tools Reference ( and the SDK discussed in the Sun Java System Directory Server Resource Kit LDAP SDK for Java Programming Guide (, installs C header files, C libraries, tools, and example programs for use with the LDAP SDK for C. These files are contained in the directories outlined in Table 1-1. The directories are installed in DSRK_base/lib/ldapcsdk.

Table 1-1  LDAP SDK for C Directories




This directory contains miscellaneous files that can be modified and used. They are described in this chapter’s section, "Miscellaneous Files."


This directory contains sample source code and makefiles for LDAP clients. See the README file in this directory for more information.


This directory contains the header files. You must include the files contained in this directory in your client source files. The header files are described in this chapter’s section, "Header Files."


This directory contains Netscape Portable Runtime (NSPR) header files. The NSPR provides a platform-neutral API for system level and libc-like functions. More information on these headers and NSPR in general can be found in the NSPR Reference (


This directory contains private header files that are not documented in this guide.


This directory contains the C library files. The specific library used is dependent on the type of application you are building. For details, see this chapter’s section, "Libraries."


This directory contains private libraries that are not documented.


This directory contains the LDAP command-line tools. They are described in the Tools Reference ( In order to use these applications, you need to ensure that they can find the LDAP API shared library or dynamic link library.

Header Files

Header files contain information about the library that programs using it need to know; for example, it might contain constants and types, along with prototypes for functions available in the library. The LDAP SDK for C header files can be found in the DSRK_base/lib/ldapcsdk/include directory. They are listed in Table 1-2.

Table 1-2  LDAP SDK for C Header Files 

Header File



A header file related to the templates (ldaptemplates.conf).


Contains the interface for libiutil, the Innosoft migration library.


Contains prototypes for the standard Basic Encoding Rules (BER) functions, structures and defines. More information is in the section on "lber.h."


Contains deprecated functions that should not be used. This header is included by ldap.h.


Contains functions, structures and defines that extend the standard LDAP C API specification. This header is included by ldap.h.


A private header file that contains platform-specific definitions / abstraction layer.


Contains the standard LDAP functions, structures and defines. This header is included in ldap.h.


Contains functions, structures and defines that will be deprecated in future releases. This header is included in ldap.h.


This base header contains LDAP functions, structures, and defines to mirror the latest LDAP C API specifications. This header also includes the ldap-deprecated.h, ldap-extension.h, ldap-standard.h, and ldap-to-be-deprecated.h headers. More information is in "ldap.h."


Contains prototypes for LDAP over SSL functions, structures, and defines. More information is in "ldap_ssl.h."


Contains prototypes for the functions, structures, and defines contained in the Netscape Portable Runtime. More information is in "ldappr.h."


A header file related to the search preferences (ldapsearchprefs.conf).


To make use of the functions contained in the LDAP SDK for C, whether you are developing on a UNIX�-based or 32-bit Microsoft� Windows system, you must include the ldap.h header file in your C source files as shown in the following line of code:

#include “ldap.h”

Including this file in your source also includes the following header files:


lber.h is included in ldap-standard.h; therefore you do not need to explicitly include it. Basic Encoding Rules (BER) is a simple tag/value scheme that encodes requests and decodes results as well as sending and receiving said requests.


If you are calling the LDAP over SSL functions, you also need to include the ldap_ssl.h header file, as follows:

#include “ldap_ssl.h”


To make use of the Netscape Portable Runtime (NSPR) with your LDAP applications, you must include ldappr.h. NSPR is a set of platform-neutral API that provides system functions such as threads, thread synchronization, I/O, interval timing, and atomic operations. This header file contains prototypes for functions that tie the LDAP libraries to NSPR. You include it as follows:

#include “ldappr.h”

You can find more information on NSPR in the ldappr.h header file itself and at the Netscape Portable Runtime project page. Additional information regarding the DSRK and NSPR can be found in "Dependencies."

Miscellaneous Files

The LDAP SDK for C ships with the the sample files described in Table 1-3. They can be called by the end user specifically when using certain API. They are in the DSRK_base/lib/ldapcsdk/etc directory.

Table 1-3  Sample Configuration Files

File Name



This LDAP filter configuration file can be used in context with ldap_init_getfilter().


This file is used to map the two letter country codes to their full names by ldap_friendly_name().


This configuration file was used in context with a deprecated function.


This configuration file was used in context with a deprecated function.


The LDAP SDK for C comes with several different libraries. A library is a set of ready-made functions which are linked into a program. There are two types of libraries: static and shared. Static (or archive) libraries are compiled with the code. Shared libraries are dynamically loaded into memory when needed, reducing the size of the executable. The specific library files to which you link is dependent on the type of application you are building.


Static libraries, although also installed, are not listed nor described.

Library Naming Conventions

Libraries on different systems have different naming conventions. Table 1-4 details the conventions relevant to Sun Java System DSRK.

Table 1-4  Library Naming Convention by Operating System 

Operating System

Static Library Name

Shared Library Name








On UNIX-based systems, the shared library file name may be fully qualified by prefixing path information.

Installed Shared Libraries

Table 1-5 outlines the installed libraries. They can be found in the DSRK_base/lib/ldapcsdk/lib directory.

Table 1-5  Shared Libraries 

UNIX-based Library

Windows Library



LDAP library


LDAP library built with NSPR. This library requires the library installed in the DSRK_base/lib/ldapcsdk/lib-private directory.


LDAP library built with support for Secure Sockets Layer. It requires the and libraries installed in the DSRK_base/lib/ldapcsdk/lib-private directory.


The following dependencies are essential when compiling your application.

LDAP Tools

The LDAP SDK for C includes several utilities to help you work with LDAP data sets. They are installed in the DSRK_base/lib/ldapcsdk/tools directory (and duplicated in the DSRK_base/bin/dsrk52 directory). Table 1-6 outlines the tools; more information can be found in the Tools Reference ( A list of options can be retreived by typing the tool name at the command line.

Table 1-6  LDAP Utilities




Compares the contents of a single LDAP entry or subtree in two directories.


Compares an attribute value against the contents of a given LDAP entry.


Deletes existing LDAP entries.


Edits the contents of a LDAP directory, either by adding new entries or modifying existing ones.


Issues search requests to an LDAP directory and displays the result as LDAP Data Interchange Format (LDIF) text.

Compiling Applications

As detailed in "Provided Directories and Files," the DSRK includes header files and corresponding shared libraries for it’s API functions. You must include the header files and link to the libraries when compiling your application. Inclusion of the header files is discussed in "Header Files." Linking to shared libraries is done when compiling the application; this is discussed in the following sections.


The LDAP SDK for C is tested and certified to work with C compilers. It is not guaranteed to work with C++ compilers.

Compiling on UNIX Platforms

When compiling clients on UNIX platforms, you might need to specify a link option to link the application to the appropriate shared libraries. When compiling the application (using the gcc or cc command), you would use the -L option to add a new path and file for which the link editor can search. (Path names defined using the -L option are used only by the link editor implementation of the compiler application.) For example, on Solaris, you might use the following link option:

gcc ... -Lpath_to_file -file_name ...


Refer to Makefile in the DSRK_base/lib/ldapcsdk/examples directory for more details on compiling your applications on UNIX platforms.

Compiling on Windows Systems

The DSRK provides both static (or import) and dynamic versions of it’s Windows-based libraries. When compiling clients on 32-bit Windows systems (Windows 2000, Windows 2003, Windows XP, Windows NT, Windows 95, Windows 98, and Windows ME), make sure to link to the SSL-enabled static library. The name of the library, installed in DSRK_base/WindowsVersion/lib/ldapcsdk/lib, is nsldapssl32v50.lib.


The LDAP SDK for C does not support 16 or 64-bit Windows systems.

Using the DLL

You should also copy the nsldap32v50.dll dynamic link library (DLL) to a directory where your client can find it. Sun Java System Directory Server might install a different version of the nsldap32v50.dll in the Windows system32 directory. Make sure that your client finds the version of the DLL that is included with the DSRK before it finds the version in the system32 directory. For example, you can copy the DSRK DLL to the same directory as your client application. During run-time, your client searches for the DLL in the following locations:

  1. The directory from which the application loaded.
  2. The current directory.
  3. The Windows system directory, typically winnt\system32.
  1. The directories listed in the PATH environment variable.


A Windows application can use either a command-line interface, or a graphical user interface (GUI). Under 32-bit Windows systems, there is also the notion of a console application in which all user interaction happens via a standard DOS shell interface, with a FILE pointer like that in Unix. This does not exist under Win16, where a Windows window is required. Because of this, make sure to define:

Linking To NSPR Libraries

The NSPR libraries (as discussed in “ldappr.h”) are distributed with the LDAP SDK for C. When linking with SSL-enabled applications, you must also link with the NSPR libraries. For more information on the NSPR libraries, see the NSPR Reference (

Linking Dependencies

When you run LDAP clients on UNIX-based or Windows system, you must ensure that the operating system can find the shared libraries that support the functions called by your application. (Generally, these files are referred to as runtime libraries.) Any of the following options will accomplish this.

See the Makefile in the examples directory for examples of additional flags and defines that you might need to specify when compiling and linking your LDAP client. Different platforms might require different sets of define statements.

The Example Programs

The DSRK ships with several examples that demonstrate the use of the functions contained in the LDAP SDK for C library. Located in the DSRK_base/lib/ldapcsdk/examples directory, the example code assumes that you are running clients against the LDAPv3-compliant Sun Java System Directory Server and that you have the sample database properly loaded. For details on the source files, refer to the README contained in the examples directory.


The samples use synchronous LDAP calls and their asynchronous counterparts. The synchronous LDAP calls are more straightforward than their asynchronous counterparts therfore, it is suggested you look at these examples first.

Synchronous Examples

The synchronous calls block the calling process until all results have been returned. Because these programs usually rely on event loops, they are not appropriate for use with clients that implement a GUI in a single-threaded environment. However, these sample programs work fine with command-line clients and CGI programs. Table 1-7 lists the synchronous examples in the LDAP SDK for C.

Table 1-7  Synchronous Example Programs 

Example Source



Shows how to use ldap_search_s() to search for all entries which have an attribute value that exactly matches what you're searching for. In this example, all entries with the surname (last name) Jensen are retrieved and displayed.


Like search.c, but enables an in-memory cache.


Like search.c, but the search is done over an SSL-protected TCP connection.


Like ssnoauth.c, but with certificate-based authentication thrown in.


Shows how to use server-side sorting in conjunction with the ldap_search_ext_s() function.


Shows how to use ldap_search_s() to retrieve a particular entry from the directory.


Retrieves specific attributes from an entry.


Shows how to use ldap_compare_s(), which allows you to test if a particular value is contained in an attribute of an entry.


Shows how to use ldap_modify_s() to replace and add to values in an attribute.


Shows how to use ldap_modrdn2_s() to change the relative distinguished name (RDN) of an entry.


Shows how to use the ldap_getfilter*() family of functions, which help generate LDAP filters based on an arbitrary search string provided by a user.


Shows how to use the ldap_create_filter() function to generate LDAP filters.

Asynchronous Examples

These examples use the asynchronous LDAP calls; you begin an operation, and periodically poll to see if any results have been returned. Table 1-8 lists the asynchronous examples in the LDAP SDK for C.

Table 1-8  Asynchronous Example Programs 

Example Source



Initiates a search for entries, printing the results as they arrive.


Like asearch.c but uses the PerLDAP routines to incorporate Netscape Portable Runtime (NSPR).


Adds an entry to the directory.


Deletes an entry from the directory.


Shows how to use Persistent Search (an LDAPv3 extension) to monitor a directory server for changes.


Attempts to bind to the directory and reports back any password expiration information received. This demonstrates how clients can process password policy information.

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.