You are currently viewing a snapshot of taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to, please file a bug.

Mozilla LDAP C SDK Programmer's Guide


The LDAP C SDK Programmer's Guide documents the Mozilla LDAP C SDK, a software development kit (SDK) for writing Lightweight Directory Access Protocol (LDAP) client applications. This SDK supports the The C LDAP Application Program Interface Internet-Draft. The draft is a formal description of the C language API for LDAP.

The Mozilla LDAP C SDK includes the C libraries for the LDAP application programming interface (API). You use the functions contained in this API to enable your applications to connect to, search, and update LDAP servers located on a network or on the Internet. For a more detailed explanation of LDAP, see Chapter 2 - "An Introduction to LDAP"."

This Preface contains the following sections:

What You Are Expected to Know

This guide is intended for use by C and C++ programmers who want to enable new or existing client applications to connect to LDAP servers. The functionality contained in the LDAP C SDK allows you to search and update databases that are managed by LDAP servers. This book assumes that you are familiar with writing and compiling C applications on the platform(s) that you want to implement your client applications.

About This Release

While this manual has been updated to cover many of the newer features of the Mozilla LDAP C SDK, there are several areas of functionality that have not been fully documented. When in doubt, consult the header files or the source code.

Deprecated Functions

Although several functions have been deprecated in this release of the LDAP C SDK, the SDK still supports these deprecated functions for backward compatibility. The following table outlines some of the deprecated functions and the functions you should use in their place whenever you write new code. For more information on the functions that have been deprecated, refer to the ldap.h header file and the most recent C LDAP API Internet Draft.

Table 1 - Deprecated functions and their suggested replacements

Deprecated Function Suggested Replacement Function(s)
ldap_bind() ldap_simple_bind() or ldap_sasl_bind()
ldap_bind_s() ldap_simple_bind_s() or ldap_sasl_bind_s()
ldap_build_filter() ldap_create_filter()
ldap_cache_flush() ldap_memcache_*() functions
ldap_open() ldap_init()
ldap_perror() ldap_get_lderrno() (to get the result code) and ldap_err2string() (to get the corresponding error message for this result code)
ldap_result2error() ldap_parse_result()
ldap_setfilteraffixes() ldap_set_filter_additions()
ldap_version ldap_get_option() with the

Organization of This Guide

This guide explains how to use the Mozilla LDAP C SDK to enable applications to interact with LDAP servers. The guide documents the LDAP API, which consists of data structures and functions used to communicate with LDAP servers.

This manual is divided into four parts:

Table 2 details the chapters contained in the book:

Table 2 - Finding information in this manual

Chapter Description
Preface This chapter
Part 1, "Getting Started"
Chapter 1 "The Mozilla LDAP C SDK" Understand the components of the Mozilla LDAP C SDK and how to compile your own applications.
Chapter 2 "An Introduction to LDAP" Learn more about LDAP and the Directory Server.
Chapter 3 "A Short Example" See the complete source code for a sample client.
Part 2, "Writing Clients with the Mozilla LDAP C SDK"
Chapter 4 "Writing an LDAP Client" Write a program that connects, searches, and updates an LDAP server.
Chapter 5 "Using the LDAP API" Handle errors, understand synchronous and asynchronous functions, handle LDAP referrals.
Chapter 6 "Searching the Directory" Search an LDAP server for entries.
Chapter 7 "Using Filter Configuration Files" Create a search filter or parse a filter configuration file.
Chapter 8 "Adding, Updating, and Deleting Entries" Add, update, or remove a directory entry from an LDAP server.
Chapter 9 "Comparing Values in Entries" Compare a value against the attribute values in a directory entry.
Chapter 10 "Working with LDAP URLs" Interpret an LDAP URL.
Part 3, "Advanced Topics"
Chapter 11 "Getting Server Information" Get information about the server over the LDAP protocol.
Chapter 12 "Connecting Over SSL" Connect to an LDAP server over SSL.
Chapter 13 "Using SASL Authentication" Use a SASL mechanism to authenticate to the LDAP server.
Chapter 14 "Working with LDAP Controls" Send, receive, and interpret LDAPv3 controls.
Chapter 15 "Working with Extended Operations" Perform LDAPv3 extended operations.
Chapter 16 "Writing Multithreaded Clients" Write a multi-threaded client.
Part 4, "Reference"
Chapter 17 "Data Types and Structures" Look up the description of a data structure.
Chapter 18 "Function Reference" Look up the description of a function.
Chapter 19 "Result Codes" Look up the description of a status code returned by an API function.

Documentation Conventions

This book uses the following font conventions:

  • Monospace type is used for all sample code and code listings.
  • Monospace type is also used within paragraph text to represent language elements (such as function names and class names), reserved names, filenames, pathnames, directory names, HTML tags, and any text that must be typed at a terminal.
  • Italic serif font is used within code and language elements to indicate variable placeholders. For example, in the following command, filename is a variable placeholder:

    gunzip filename.tar.gz
  • Italic type is used within paragraph text for book titles, emphasis, variables, and placeholders.

Where to Find Additional Information

Netscape provides binary releases of this SDK with their Directory Server product. However, note that this SDK is primarily available in source code form as part of the open source project. Refer to the following site for more information on how you can get the source code and contribute to the further development of this SDK:

The following table lists several sources of information on LDAP and its associated technologies. Note that some of the links in this table are time-sensitve and the drafts might expire.

Table 3 - Sources of information on LDAP and associated protocols

RFC or Internet-Draft / Internet Location
Lightweight Directory Access Protocol (v2), RFC 1777
Lightweight Directory Access Protocol (v3), RFC 2251
The C LDAP Application Program Interface, Internet-Draft Revision 5 - Status: Deleted
LDAP Control Extension for Server Side Sorting of Search Results, RFC 2891
Simple Authentication and Security Layer (SASL), RFC 2222
Secure Sockets Layer (SSL) Protocol (v3), Internet-Draft Revision 3
Access Control Model for LDAPv3, Internet-Draft Revision 8 - Status: Deleted
LDAP Extensions for Scrolling View Browsing of Search Results, Internet-Draft Revision 5 - Status: Deleted
LDAP Control Extension for Server Side Sorting of Search Results, Internet Draft Revision 3 - Status: Deleted
LDAP Proxied Authorization Control, Revision 12
LDAP Authentication Response Control, RFC 3829
Persistent Search: A Simple LDAP Change Notification Mechanism, Internet-Draft Revision 2
Netscape Portable Runtime Library

Technical Documentation Provided By Netscape

You can find information on the LDAP protocol in the documentation for Netscape Directory Server. These documents, along with the installation instructions, release notes, and documentation for all Netscape servers, can be found at the following location: