Copyright: Copyright © Regents of University of Michigan
Citation: X.500 Project


API Reference

cldap

cldap_close

cldap_open

cldap_search_s

cldap_setretryinfo

lber-decode

lber-encode

ld_errno

ldap

ldap_abandon

ldap_add

ldap_add_s

ldap_bind

ldap_bind_s

ldap_build_filter

ldap_cache

ldap_charset

ldap_compare

ldap_compare_s

ldap_count_entries

ldap_count_values

ldap_count_values_len

ldap_delete

ldap_delete_s

ldap_destroy_cache

ldap_disable_cache

ldap_disptmpl

ldap_dn2ufn

ldap_enable_cache

ldap_entry2html

ldap_entry2html_search

ldap_entry2text

ldap_entry2text_search

ldap_err2string

ldap_errlist

ldap_error

ldap_explode_dn

ldap_explode_dns

ldap_first_attribute

ldap_first_disptmpl

ldap_first_entry

ldap_first_searchobj

ldap_first_tmplcol

ldap_first_tmplrow

ldap_flush_cache

ldap_free_friendlymap

ldap_free_searchprefs

ldap_free_templates

ldap_friendly

ldap_friendly_name

ldap_get_dn

ldap_get_values

ldap_get_values_len

ldap_getfilter

ldap_getfilter_free

ldap_getfirstfilter

ldap_getnextfilter

ldap_init

ldap_init_getfilter

ldap_init_getfilter_buf

ldap_init_searchprefs

ldap_init_searchprefs_buf

ldap_init_templates

ldap_init_templates_buf

ldap_is_dns_dn

ldap_kerberos_bind_s

ldap_kerberos_bind1

ldap_kerberos_bind1_s

ldap_kerberos_bind2

ldap_kerberos_bind2_s

ldap_modify

ldap_modify_s

ldap_modrdn

ldap_modrdn_s

ldap_modrdn2

ldap_modrdn2_s

ldap_mods_free

ldap_msgfree

ldap_next_attribute

ldap_next_disptmpl

ldap_next_entry

ldap_next_searchobj

ldap_next_tmplcol

ldap_next_tmplrow

ldap_oc2template

ldap_open

ldap_perror

ldap_result

ldap_result2error

ldap_search

ldap_search_s

ldap_search_st

ldap_searchprefs

ldap_set_cache_options

ldap_setfilteraffixes

ldap_simple_bind

ldap_simple_bind_s

ldap_sort

ldap_sort_entries

ldap_sort_strcasecmp

ldap_sort_values

ldap_tmplattrs

ldap_ufn

ldap_ufn_search_c

ldap_ufn_search_ct

ldap_ufn_search_s

ldap_ufn_setfilter

ldap_ufn_setprefix

ldap_ufn_timeout

ldap_unbind

ldap_unbind_s

ldap_uncache_entry

ldap_uncache_request

ldap_vals2html

ldap_vals2text

ldap_value_free

ldap_value_free_len


Contacts

The WIndows Ldap project welcomes any feedback, suggestions, or comments on this product.  Our email address is:

ldap-support@umich.edu

We give it away free, but you're still a customer.


Contents
LDAP  (Lightweight Directory Access Protocol)

client library API for Microsoft Windows

(16 & 32 bits)

Overview

API Reference

Contacts

Disclaimer

Copyright © 1996 : The Regents of the University of Michigan


Disclaimer

The content of this help file originated as unix man pages.  We intentionally did not modify the source documents so we will be able to stay in synch with the official releases.  Our apologies for the non-standard appearance.


cldap_close
CLDAP_CLOSE (3)                1994                 CLDAP_CLOSE(3)

NAME

     cldap_close - Dispose of Connectionless LDAP Pointer

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     void cldap_close( ld )

     LDAP *ld;

DESCRIPTION

     The cldap_close() routine disposes of  memory  allocated  by

     cldap_open(3).   It should be called when all CLDAP communi-

     cation is complete.

     cldap_close() takes a single parameter _l_d, the LDAP  pointer

     returned by a previous call to cldap_open(3).

SEE ALSO

     ldap(3),          cldap_open(3),          cldap_search_s(3),

     cldap_setretryinfo(3)

November                 Last change: 18                        1


cldap_open
CLDAP_OPEN (3)                 1994                  CLDAP_OPEN(3)

NAME

     cldap_open - Prepare for Connectionless LDAP Communication

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     LDAP *cldap_open(host, port)

     char *host;

     int port;

DESCRIPTION

     The cldap_open() routine is called to  prepare  for  connec-

     tionless LDAP communication (over udp(4p)).  It allocates an

     LDAP structure which is passed to future search requests.

     cldap_open() takes _h_o_s_t, the nane of the host on  which  the

     LDAP  server  is running, and _p_o_r_t, the port number to which

     to connect.  If the default IANA-assigned  port  of  389  is

     desired,  LDAP_PORT  should be specified for _p_o_r_t.  _h_o_s_t can

     contain a space-separated list of hosts or addresses to try.

     cldap_open()  returns  a pointer to an LDAP structure, which

     should be passed to subsequent calls  to  cldap_search_s(3),

     cldap_setretryinfo(3),  and  cldap_close(3).  Certain fields

     in the LDAP structure can be set  to  indicate  size  limit,

     time  limit,  and how aliases are handled during operations.

     See ldap_open(3) and <ldap.h> for more details.

ERRORS

     If an error occurs, cldap_open() will return NULL and  errno

     will be set appropriately.

SEE ALSO

     ldap(3)      cldap_search_s(3),       cldap_setretryinfo(3),

     cldap_close(3), udp(4p)

November                 Last change: 18                        1


cldap_search_s
CLDAP_SEARCH_S (3)             1994              CLDAP_SEARCH_S(3)

NAME

     cldap_search_s - Connectionless LDAP Search

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int cldap_search_s( ld, base, scope, filter, attrs, attrsonly,

          res, logdn )

     LDAP *ld;

     char *base;

     int scope;

     char *filter;

     char **attrs;

     int attrsonly;

     LDAPMessage **res;

     char *logdn;

DESCRIPTION

     The cldap_search_s() routine performs an LDAP  search  using

     the Connectionless LDAP (CLDAP) protocol.

     cldap_search_s() has parameters and  behavior  identical  to

     that  of  ldap_search_s(3),  except  for the addition of the

     _l_o_g_d_n parameter.  logdn should contain a distinguished  name

     to be used only for logging purposed by the LDAP server.  It

     should be in the text format described by RFC 1779 "A String

     Representation of Distinguished Names".

RETRANSMISSION ALGORITHM

     cldap_search_s() operates  using  the  CLDAP  protocol  over

     udp(4p).   Since  UDP  is  a  non-reliable protocol, a retry

     mechanism   is   used   to   increase   reliability.     The

     cldap_setretryinfo(3)  routine  can be used to set two retry

     parameters:  _t_r_i_e_s, a count of the number of times to send a

     search  request  and _t_i_m_e_o_u_t, an initial timeout that deter-

     mines how long to wait  for  a  response  before  re-trying.

     _t_i_m_e_o_u_t  is  specified  seconds.  These values are stored in

     the ld_cldaptries and ld_cldaptimeout members of the _l_d LDAP

     structure,  and the default values set in ldap_open(3) are 4

     and 3 respectively.  The retransmission algorithm used is:

     Step 1.  Set the current timeout to ld_cldaptimeout seconds,

     and the current LDAP server address to the first LDAP server

     found during the ldap_open(3) call.

     Step 2:  Send the search request to the current LDAP  server

     address.

     Step 3:  Set the wait timeout to the current timeout divided

     by  the number of server addresses found during ldap_open(3)

     or to one second, whichever is larger.  Wait  at  most  that

November                 Last change: 18                        1

CLDAP_SEARCH_S(3)             1994              CLDAP_SEARCH_S(3)

     long  for a response; if a response is received, STOP.  Note

     that the wait timeout is always rounded  down  to  the  next

     lowest second.

     Step 5:  Repeat steps 2 and 3 for each LDAP server address.

     Step 6:  Set the current timeout to twice its previous value

     and repeat Steps 2 through 6 a maximum of _t_r_i_e_s times.

RETRANSMISSION EXAMPLE

     Assume that the default values for _t_r_i_e_s and  _t_i_m_e_o_u_t  of  4

     tries  and  3  seconds  are  used.   Further,  assume that a

     space-separated list of two hosts, each  with  one  address,

     was  passed  to cldap_open(3).  The pattern of requests sent

     will be (stopping as soon as a response is received):

       Time         Search Request Sent To:

        +0               Host A try 1

        +1  (0+3/2)      Host B try 1

        +2  (1+3/2)      Host A try 2

        +5  (2+6/2)      Host B try 2

        +8  (5+6/2)      Host A try 3

        +14 (8+12/2)          Host B try 3

        +20 (14+12/2)    Host A try 4

        +32 (20+24/2)    Host B try 4

        +44 (20+24/2)    (give up - no response)

ERRORS

     cldap_search_s() returns LDAP_SUCCESS if a search  was  suc-

     cessful  and the appropriate LDAP error code otherwise.  See

     ldap_error(3) for more information.

SEE ALSO

     ldap(3),  ldap_error(3),  ldap_search_s(3),   cldap_open(3),

     cldap_setretryinfo(3), cldap_close(3), udp(4p)

November                 Last change: 18                        2


cldap_setretryinfo
CLDAP_SETRETRYINFO (3)         1994          CLDAP_SETRETRYINFO(3)

NAME

     cldap_setretryinfo  -  Set   Connectionless   LDAP   Request

     Retransmission Parameters

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     void cldap_setretryinfo(ld, tries, timeout)

     LDAP *ld;

     int tries;

     int timeout;

DESCRIPTION

     The cldap_setretryinfo() routine is used to  set  the  CLDAP

     request retransmission behavior for future cldap_search_s(3)

     calls.

     cldap_setretryinfo() takes _l_d,  the  LDAP  pointer  returned

     from  a  previous  call to cldap_open(3), _t_r_i_e_s, the maximum

     number of times to send a request, and _t_i_m_e_o_u_t, the  initial

     time,  in seconds, to wait before re-sending a request.  The

     default values (set by cldap_open(3))  are  4  tries  and  3

     seconds between tries.  See cldap_search_s(3) for a complete

     description of the retransmission algorithm used.

SEE ALSO

     ldap(3), cldap_open(3), cldap_search_s(3), cldap_close(3)

November                 Last change: 18                        1


lber-decode
LBER-DECODE (3)                1994                 LBER-DECODE(3)

NAME

     ber_get_next,    ber_skiptag,    ber_peek_tag,    ber_scanf,

     ber_get_int, ber_get_stringb, ber_get_stringa, ber_get_null,

     ber_get_boolean,    ber_get_bitstring,    ber_first_element,

     ber_next_element  -  LBER  simplified  Basic  Encoding Rules

     library routines for decoding

SYNOPSIS

     #include <lber.h>

     typedef struct berelement {

         char *ber_buf;

         char *ber_ptr;

         char *ber_end;

         struct seqorset *ber_sos;

         int ber_tag;

         int ber_usertag;

     } BerElement;

     typedef struct sockbuf {

         int sb_sd;

         BerElement sb_ber;

     } Sockbuf;

     typedef struct berval {

         unsigned long bv_len;

         char *bv_val;

     };

     ber_get_next(sb, len, ber)

     Sockbuf *sb;

     unsigned long *len;

     BerElement *ber;

     ber_skip_tag(ber, len)

     BerElement *ber;

     unsigned long *len;

     ber_peek_tag(ber, len)

     BerElement *ber;

     unsigned long *len;

     ber_get_int(ber, num)

     BerElement *ber;

     long *num;

     ber_get_stringb(ber, buf, len)

     BerElement *ber;

     char *buf;

     unsigned long *len;

November                 Last change: 18                        1

LBER-DECODE(3)                1994                 LBER-DECODE(3)

     ber_get_stringa(ber, buf)

     BerElement *ber;

     char **buf;

     ber_get_stringal(ber, bv)

     BerElement *ber;

     struct berval **bv;

     ber_get_null(ber)

     BerElement *ber;

     ber_get_boolean(ber, bool)

     BerElement *ber;

     int *bool;

     ber_get_bitstringa(ber, buf, blen)

     BerElement *ber;

     char **buf;

     unsigned long *blen;

     ber_first_element(ber, len, cookie)

     BerElement *ber;

     unsigned long *len;

     char **cookie;

     ber_next_element(ber, len, cookie)

     BerElement *ber;

     unsigned long *len;

     char *cookie;

     ber_scanf(ber, fmt [, arg...] )

     BerElement *ber;

     char *fmt;

     ber_bvfree(bv)

     struct berval *bv;

     ber_bvecfree(bvec)

     struct berval **bvec;

DESCRIPTION

     These routines provide a subroutine interface to  a  simpli-

     fied  implementation  of  the Basic Encoding Rules of ASN.1.

     The version of BER these routines support is the one defined

     for  the  LDAP protocol.  The encoding rules are the same as

     BER, except that only definite form lengths  are  used,  and

     bitstrings and octet strings are always encoded in primitive

     form.  In addition, these lightweight BER routines  restrict

     tags  and  class  to  fit  in a single octet (this means the

     actual tag must be less than 31).  When a "tag" is specified

     in  the descriptions below, it refers to the tag, class, and

     primitive or constructed bit  in  the  first  octet  of  the

November                 Last change: 18                        2

LBER-DECODE(3)                1994                 LBER-DECODE(3)

     encoding.   This man page describes the decoding routines in

     the lber library.  See lber-encode(3)  for  details  on  the

     corresponding encoding routines.

     Normally, the only routines that need be called by an appli-

     cation  are  ber_get_next()  to get the next BER element and

     ber_scanf() to do  the  actual  decoding.   In  some  cases,

     ber_peek_tag()  may  also need to be called in normal usage.

     The other routines are provided for those applications  that

     need  more  control  than ber_scanf() provides.  In general,

     these routines return the tag of the element decoded, or  -1

     if an error occurred.

     The ber_get_next() routine is used to read the next BER ele-

     ment  from the given Sockbuf, _s_b.  A Sockbuf consists of the

     descriptor (usually socket, but a file descriptor works just

     as well) from which to read, and a BerElement structure used

     to maintain a buffer.  On the first call, the _s_b__b_e_r  struct

     should be zeroed.  It strips off and returns the leading tag

     byte, strips off and returns the length of the  entire  ele-

     ment  in  _l_e_n,  and  sets  up  _b_e_r  for  subsequent calls to

     ber_scanf() et al to decode the element.

     The ber_scanf() routine is used to decode a BER  element  in

     much the same way that scanf(3) works.  It reads from _b_e_r, a

     pointer to a BerElement such as returned by  ber_get_next(),

     interprets the bytes according to the format string _f_m_t, and

     stores the results in its additional arguments.  The  format

     string  contains conversion specifications which are used to

     direct the interpretation of the BER  element.   The  format

     string can contain the following characters.

          a  Octet string.  A char ** should be supplied.  Memory

             is  allocated, filled with the contents of the octet

             string, null-terminated, and returned in the parame-

             ter.

          s  Octet string.  A char * buffer should  be  supplied,

             followed  by  a pointer to an integer initialized to

             the size of the  buffer.   Upon  return,  the  null-

             terminated  octet string is put into the buffer, and

             the integer is set to the actual size of  the  octet

             string.

          O  Octet string.  A struct ber_val **  should  be  sup-

             plied, which upon return points to a malloced struct

             berval containing the octet string and  its  length.

             ber_bvfree()  can  be  called  to  free the malloced

             memory.

          b  Boolean.  A pointer to an  integer  should  be  sup-

             plied.

November                 Last change: 18                        3

LBER-DECODE(3)                1994                 LBER-DECODE(3)

          i  Integer.  A pointer to an  integer  should  be  sup-

             plied.

          B  Bitstring.  A char ** should be supplied which  will

             point  to the malloced bits, followed by an unsigned

             long *, which will point to the length (in bits)  of

             the bitstring returned.

          n  Null.  No parameter is  required.   The  element  is

             simply skipped if it is recognized.

          v  Sequence of octet strings.  A  char  ***  should  be

             supplied,  which  upon  return  points to a malloced

             null-terminated array of  char  *'s  containing  the

             octet  strings.  NULL is returned if the sequence is

             empty.

          V  Sequence of octet strings with  lengths.   A  struct

             berval  ***  should  be  supplied, which upon return

             points to a malloced null-terminated array of struct

             berval  *'s  containing  the octet strings and their

             lengths.  NULL is returned if the sequence is empty.

             ber_bvecfree()  can  be  called to free the malloced

             memory.

          x  Skip element.  The next element is skipped.

          {  Begin sequence.  No parameter is required.  The ini-

             tial sequence tag and length are skipped.

          }  End sequence.   No  parameter  is  required  and  no

             action is taken.

          [  Begin set.  No parameter is required.   The  initial

             set tag and length are skipped.

          ]  End set.  No parameter is required and no action  is

             taken.

     The ber_get_int() routine tries to interpret the  next  ele-

     ment as an integer, returning the result in _n_u_m.  The tag of

     whatever it finds is returned on success, -1 on failure.

     The ber_get_stringb() routine  is  used  to  read  an  octet

     string into a preallocated buffer.  The _l_e_n parameter should

     be initialized to the size of the buffer, and  will  contain

     the length of the octet string read upon return.  The buffer

     should be big enough to take the octet string value  plus  a

     terminating NULL byte.

     The ber_get_stringa() routine is used to malloc  space  into

     which an octet string is read.

November                 Last change: 18                        4

LBER-DECODE(3)                1994                 LBER-DECODE(3)

     The ber_get_stringal() routine is used to malloc space  into

     which  an  octet string and its length are read.  It takes a

     struct berval **, and returns the result in this parameter.

     The ber_get_null() routine is used to read a  NULL  element.

     It returns the tag of the element it skips over.

     The ber_get_boolean() routine is  used  to  read  a  boolean

     value.   It  is  called  the  same way that ber_get_int() is

     called.

     The ber_get_bitstringa() routine is used to read a bitstring

     value.   It  takes  a  char  ** which will hold the malloced

     bits, followed by an unsigned long *, which  will  point  to

     the length (in bits) of the bitstring returned.

     The ber_first_element() routine is used to  return  the  tag

     and  length  of  the first element in a set or sequence.  It

     also returns in _c_o_o_k_i_e a magic cookie parameter that  should

     be  passed  to subsequent calls to ber_next_element(), which

     returns similar information.

EXAMPLES

     Assume the variable _b_e_r contains a lightweight BER  encoding

     of the following ASN.1 object:

           AlmostASearchRequest := SEQUENCE {

               baseObject      DistinguishedName,

               scope           ENUMERATED {

                   baseObject    (0),

                   singleLevel   (1),

                   wholeSubtree  (2)

               },

               derefAliases    ENUMERATED {

                   neverDerefaliases   (0),

                   derefInSearching    (1),

                   derefFindingBaseObj (2),

                   alwaysDerefAliases  (3)

               },

               sizelimit       INTEGER (0 .. 65535),

               timelimit       INTEGER (0 .. 65535),

               attrsOnly       BOOLEAN,

               attributes      SEQUENCE OF AttributeType

           }

     The element can be decoded using ber_scanf() as follows.

           int    scope, ali, size, time, attrsonly;

           char   *dn, **attrs;

           if ( ber_scanf( ber, "{aiiiib{v}}", &dn, &scope, &ali,

               &size, &time, &attrsonly, &attrs ) == -1 )

November                 Last change: 18                        5

LBER-DECODE(3)                1994                 LBER-DECODE(3)

                   /* error */

           else

                   /* success */

ERRORS

     If an error occurs during decoding, generally these routines

     return -1.

NOTES

     The return values for all of these functions are declared in

     the <lber.h> header file.  Some routines may malloc memory.

SEE ALSO

     lber-encode(3) ldap-parse(3) ldap-sync(3) ldap-async(3)

     Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight

     Directory Access Protocol", OSI-DS-26, April 1992.

     Information Processing  -  Open  Systems  Interconnection  -

     Model  and  Notation - Service Definition - Specification of

     Basic Encoding  Rules  for  Abstract  Syntax  Notation  One,

     International  Organization  for  Standardization,  Interna-

     tional Standard 8825.

AUTHOR

     Tim Howes, University of Michigan

November                 Last change: 18                        6


lber-encode
LBER-ENCODE (3)                1992                 LBER-ENCODE(3)

NAME

     ber_alloc,     ber_flush,      ber_printf,      ber_put_int,

     ber_put_ostring,        ber_put_string,        ber_put_null,

     ber_put_boolean,      ber_put_bitstring,      ber_start_seq,

     ber_start_set,  ber_put_seq,  ber_put_set  - LBER simplified

     Basic Encoding Rules library routines for encoding

SYNOPSIS

     #include <lber.h>

     typedef struct berelement {

         char *ber_buf;

         char *ber_ptr;

         char *ber_end;

         struct seqorset *ber_sos;

         int ber_tag;

         int ber_usertag;

     } BerElement;

     typedef struct sockbuf {

         int sb_sd;

         BerElement sb_ber;

     } Sockbuf;

     BerElement *ber_alloc()

     ber_flush(sb, ber, freeit)

     Sockbuf *sb;

     BerElement *ber;

     int freeit;

     ber_printf(ber, fmt [, arg... ] )

     BerElement *ber;

     char *fmt;

     ber_put_int(ber, num, tag)

     BerElement *ber;

     long num;

     char tag;

     ber_put_ostring(ber, str, len, tag)

     BerElement *ber;

     char *str;

     unsigned long len;

     char tag;

     ber_put_string(ber, str, tag)

     BerElement *ber;

     char *str;

     char tag;

June                     Last change: 15                        1

LBER-ENCODE(3)                1992                 LBER-ENCODE(3)

     ber_put_null(ber, tag)

     BerElement *ber;

     char tag;

     ber_put_boolean(ber, bool, tag)

     BerElement *ber;

     int bool;

     char tag;

     ber_put_bitstring(ber, str, blen, tag)

     BerElement *ber;

     char *str;

     int blen;

     char tag;

     ber_start_seq(ber, tag)

     BerElement *ber;

     char tag;

     ber_start_set(ber, tag)

     BerElement *ber;

     char tag;

     ber_put_seq(ber)

     BerElement *ber;

     ber_put_set(ber)

     BerElement *ber;

DESCRIPTION

     These routines provide a subroutine interface to  a  simpli-

     fied  implementation  of  the Basic Encoding Rules of ASN.1.

     The version of BER these routines support is the one defined

     for  the  LDAP protocol.  The encoding rules are the same as

     BER, except that only definite form lengths  are  used,  and

     bitstrings and octet strings are always encoded in primitive

     form.  In addition, these lightweight BER routines  restrict

     tags  and  class  to  fit  in a single octet (this means the

     actual tag must be less than 31).  When a "tag" is specified

     in  the descriptions below, it refers to the tag, class, and

     primitive or constructed bit  in  the  first  octet  of  the

     encoding.   This man page describes the encoding routines in

     the lber library.  See lber-decode(3)  for  details  on  the

     corresponding decoding routines.

     Normally, the only routines that need be called by an appli-

     cation  are ber_alloc() to allocate a BER element for encod-

     ing, ber_printf() to do the actual encoding, and ber_flush()

     to  actually write the element.  The other routines are pro-

     vided for those applications that  need  more  control  than

     ber_printf()  provides.   In  general, these routines return

     the length of  the  element  encoded,  or  -1  if  an  error

June                     Last change: 15                        2

LBER-ENCODE(3)                1992                 LBER-ENCODE(3)

     occurred.

     The ber_alloc() routine is used to allocate a new  BER  ele-

     ment.  The ber_flush() routine is used to actually write the

     element to a socket (or file) descriptor, once it  has  been

     fully  encoded  (using  ber_printf()  and  friends).  The _s_b

     structure contains the descriptor and a BerElement used  for

     input  buffering.   Only  the _s_b__s_d field is relevant to the

     ber_flush() routine.

     The ber_printf() routine is used to encode a BER element  in

     much  the  same  way  that  sprintf(3) works.  One important

     difference, though, is that some state information  is  kept

     with the _b_e_r parameter so that multiple calls can be made to

     ber_printf() to append things to the end of the BER element.

     Ber_printf()  writes  to _b_e_r, a pointer to a BerElement such

     as returned by ber_alloc().  It interprets and  formats  its

     arguments  according  to  the format string _f_m_t.  The format

     string can contain the following characters:

          b  Boolean.  An integer parameter should  be  supplied.

             A boolean element is output.

          i  Integer.  An integer parameter should  be  supplied.

             An integer element is output.

          B  Bitstring.  A char * pointer to  the  start  of  the

             bitstring  is  supplied,  followed  by the number of

             bits in the bitstring.  A bitstring element is  out-

             put.

          n  Null.  No parameter is required.  A null element  is

             output.

          o  Octet string.  A char * is supplied, followed by the

             length  of  the  string pointed to.  An octet string

             element is output.

          s  Octet string.  A null-terminated string is supplied.

             An octet string element is output, not including the

             trailing NULL octet.

          t  Tag.  An int specifying the tag  to  give  the  next

             element is provided.  This works across calls.

          v  Several octet strings.  A null-terminated  array  of

             char  *'s  is  supplied.  Note that a construct like

             '{v}' is required to get an actual SEQUENCE OF octet

             strings.

          {  Begin sequence.  No parameter is required.

June                     Last change: 15                        3

LBER-ENCODE(3)                1992                 LBER-ENCODE(3)

          }  End sequence.  No parameter is required.

          [  Begin set.  No parameter is required.

          ]  End set.  No parameter is required.

     The ber_put_int() routine writes the integer element _n_u_m  to

     the BER element _b_e_r.

     The ber_put_boolean() routine writes the boolean value given

     by _b_o_o_l to the BER element.

     The ber_put_bitstring() routine writes _b_l_e_n bits starting at

     _s_t_r  as  a  bitstring  value to the given BER element.  Note

     that _b_l_e_n is the length _i_n _b_i_t_s of the bitstring.

     The ber_put_ostring() routine writes _l_e_n bytes  starting  at

     _s_t_r to the BER element as an octet string.

     The  ber_put_string()  routine  writes  the  null-terminated

     string  (minus the terminating ' ') to the BER element as an

     octet string.

     The ber_put_null() routine writes a NULL element to the  BER

     element.

     The ber_start_seq() routine is used to start a  sequence  in

     the  BER  element.   The ber_start_set() routine works simi-

     larly.  The end of the sequence or  set  is  marked  by  the

     nearest  matching  call  to  ber_put_seq() or ber_put_set(),

     respectively.

     The ber_first_element() routine is used to  return  the  tag

     and  length  of  the first element in a set or sequence.  It

     also returns in _c_o_o_k_i_e a magic cookie parameter that  should

     be  passed  to subsequent calls to ber_next_element(), which

     returns similar information.

EXAMPLES

     Assuming the following variable declarations, and  that  the

     variables have been assigned appropriately, an lber encoding

     of the following ASN.1 object:

           AlmostASearchRequest := SEQUENCE {

               baseObject      DistinguishedName,

               scope           ENUMERATED {

                   baseObject    (0),

                   singleLevel   (1),

                   wholeSubtree  (2)

               },

               derefAliases    ENUMERATED {

                   neverDerefaliases   (0),

June                     Last change: 15                        4

LBER-ENCODE(3)                1992                 LBER-ENCODE(3)

                   derefInSearching    (1),

                   derefFindingBaseObj (2),

                   alwaysDerefAliases  (3)

               },

               sizelimit       INTEGER (0 .. 65535),

               timelimit       INTEGER (0 .. 65535),

               attrsOnly       BOOLEAN,

               attributes      SEQUENCE OF AttributeType

           }

     can be achieved like so:

           int    scope, ali, size, time, attrsonly;

           char   *dn, **attrs;

           /* ... fill in values ... */

           if ( (ber = ber_alloc()) == NULLBER )

               /* error */

           if ( ber_printf( ber, "{siiiib{v}}", dn, scope, ali,

               size, time, attrsonly, attrs ) == -1 )

                   /* error */

           else

                   /* success */

ERRORS

     If an error occurs during encoding, generally these routines

     return -1.

NOTES

     The return values for all of these functions are declared in

     the <lber.h> header file.

SEE ALSO

     ldap-async(3) ldap-sync(3) ldap-parse(3) lber-decode(3)

     Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight

     Directory Access Protocol", OSI-DS-26, April 1992.

     Information Processing  -  Open  Systems  Interconnection  -

     Model  and  Notation - Service Definition - Specification of

     Basic Encoding  Rules  for  Abstract  Syntax  Notation  One,

     International  Organization  for  Standardization,  Interna-

     tional Standard 8825.

AUTHOR

     Tim Howes, University of Michigan

June                     Last change: 15                        5


ldap
LDAP (3)                       1995                        LDAP(3)

NAME

     ldap - Lightweight Directory Access Protocol package

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

DESCRIPTION

     The Lightweight Directory Access  Protocol  provides  TCP/IP

     access  to  the  X.500  Directory  or  to a stand-alone LDAP

     server.  The University of Michigan LDAP package includes  a

     stand-alone  server in slapd(8), an LDAP to X.500 gateway in

     ldapd(8), various LDAP clients, and an LDAP  client  library

     used  to  provide  programmatic access to the LDAP protocol.

     This man page gives an overview of  the  LDAP  library  rou-

     tines.

     Both synchronous and asynchronous APIs are  provided.   Also

     included  are various routines to parse the results returned

     from these  routines.   These  routines  are  found  in  the

     libldap.a library.

     The basic interaction is as follows.  A connection  is  made

     to  an  LDAP  server  by calling ldap_open(3).  An LDAP bind

     operation is performed by calling one  of  ldap_bind(3)  and

     friends.   Next,  other  operations are performed by calling

     one of  the  synchronous  or  asynchronous  routines  (e.g.,

     ldap_search_s(3)     or     ldap_search(3)    followed    by

     ldap_result(3)).  Results returned from these  routines  are

     interpreted  by calling the LDAP parsing routines.  The LDAP

     association is terminated by calling ldap_unbind(3).  Errors

     can be interpreted by calling ldap_perror(3).

SEARCH FILTERS

     Search filters to be passed to the ldap search routines  can

     be  constructed by hand, or by calling the ldap_getfilter(3)

     routines, which use the ldapgetfilter.conf(5) file to turn a

     string  (presumably  that a user has typed) into a series of

     search filters.

DISPLAYING RESULTS

     Results obtained from the ldap search routines can be output

     by     hand,     by    calling    ldap_first_entry(3)    and

     ldap_next_entry(3) to step  through  the  entries  returned,

     ldap_first_attribute(3)  and  ldap_next_attribute(3) to step

     through an entry's  attributes,  and  ldap_get_values(3)  to

     retrieve   a  given  attribute's  value,  and  then  calling

     printf(3) or whatever to display the values.

     Alternatively, the entry can be output automatically by cal-

     ling   the   ldap_entry2text(3),  ldap_entry2text_search(3),

     ldap_entry2html(3), or  ldap_entry2html_search(3)  routines.

November                 Last change: 13                        1

LDAP(3)                       1995                        LDAP(3)

     These  routines  look  up the object class of the entry they

     are passed in the ldaptemplates.conf(5) file to decide which

     attributes  to  display  and how to display them.  Output is

     handled via a routine passed in as a parameter.

USER FRIENDLY NAMING

     The ldap_ufn(3) routines implement a  user  friendly  naming

     scheme  via LDAP.  This scheme allows you to look up entries

     using fuzzy, untyped names like "mark smith, umich, us".

CACHING

     The ldap_cache(3) routines implement a local client  caching

     scheme,  providing  a  substantial  performance increase for

     repeated queries.

UTILITY ROUTINES

     Also   provided   are   various   utility   routines.    The

     ldap_sort(3)  routines  are  used  to  sort  the entries and

     values  returned  via  the  ldap   search   routines.    The

     ldap_friendly(3)  routines  are  used  to map from short two

     letter  country  codes  (or   other   strings)   to   longer

     "friendlier" names.

CONNECTIONLESS ACCESS

     The cldap_search_s(3)  routine  allows  you  to  access  the

     directory  via Connectionless LDAP (CLDAP), which is similar

     to LDAP but operates over UDP, obviating the need to set  up

     and   tear   down  a  connection  by  calling  ldap_open(3),

     ldap_bind(3), and ldap_unbind(3).  cldap_open(3)  should  be

     called  before  using  cldap_search_s(3).  All the same get-

     filter, parsing, and display that can be used  with  regular

     LDAP routines can be used with the CLDAP routines.

BER LIBRARY

     Also included in the distribution is a  set  of  lightweight

     Basic  Encoding  Rules routines.  These routines are used by

     the LDAP library routines to encode and decode LDAP protocol

     elements  using  the  (slightly  simplified)  Basic Encoding

     Rules defined by LDAP.  They are not normally used  directly

     by  an  LDAP  application  program.   The routines provide a

     printf and scanf-like  interface,  as  well  as  lower-level

     access.  These routines are found in the liblber.a library.

INDEX

     ldap_open(3)        open a connection to an LDAP server

     ldap_init(3)        initialize  the  LDAP  library   without

                         opening a connection to a server

     ldap_result(3)      wait for the result from an asynchronous

                         operation

November                 Last change: 13                        2

LDAP(3)                       1995                        LDAP(3)

     ldap_abandon(3)     abandon (abort) an  asynchronous  opera-

                         tion

     ldap_add(3)         asynchronously add an entry

     ldap_add_s(3)       synchronously add an entry

     ldap_bind(3)        asynchronously bind to the directory

     ldap_bind_s(3)      synchronously bind to the directory

     ldap_simple_bind(3) asynchronously  bind  to  the  directory

                         using simple authentication

     ldap_simple_bind_s(3)

                         synchronously  bind  to  the   directory

                         using simple authentication

     ldap_kerberos_bind_s(3)

                         synchronously  bind  to  the   directory

                         using kerberos authentication

     ldap_kerberos_bind1(3)

                         asynchronously bind to the  LDAP  server

                         using kerberos authentication

     ldap_kerberos_bind1_s(3)

                         synchronously bind to  the  LDAP  server

                         using kerberos authentication

     ldap_kerberos_bind2(3)

                         asynchronously bind  to  the  DSA  using

                         kerberos authentication

     ldap_kerberos_bind2_s(3)

                         synchronously bind to the DSA using ker-

                         beros authentication

     ldap_unbind(3)      synchronously  unbind  from   the   LDAP

                         server and close the connection

     ldap_unbind_s(3)    equivalent to ldap_unbind(3)

     ldap_memfree (3)    dispose of memory allocated by LDAP rou-

                         tines  (this  is only used on the Micro-

                         soft Windows platforms; use  free(3)  on

                         all other platforms).

     ldap_enable_cache(3)

                         enable LDAP client caching

     ldap_disable_cache(3)

November                 Last change: 13                        3

LDAP(3)                       1995                        LDAP(3)

                         disable LDAP client caching

     ldap_destroy_cache(3)

                         disable LDAP client caching and  destroy

                         cache contents

     ldap_flush_cache(3) flush LDAP client cache

     ldap_uncache_entry(3)

                         uncache requests pertaining to an entry

     ldap_uncache_request(3)

                         uncache a request

     ldap_set_cache_options(3)

                         set cache options

     ldap_compare(3)     asynchronous  compare  to  a   directory

                         entry

     ldap_compare_s(3)   synchronous compare to a directory entry

     ldap_delete(3)      asynchronously delete an entry

     ldap_delete_s(3)    synchronously delete an entry

     ldap_init_templates(3)

                         initialize  display  template   routines

                         from a file

     ldap_init_templates_buf(3)

                         initialize  display  template   routines

                         from a buffer

     ldap_free_templates(3)

                         free display template routine memory

     ldap_first_disptmpl(3)

                         get first display template

     ldap_next_disptmpl(3)

                         get next display template

     ldap_oc2template(3) return    template    appropriate    for

                         objectclass

     ldap_name2template(3)

                         return named template

     ldap_tmplattrs(3)   return attributes needed by template

     ldap_first_tmplrow(3)

November                 Last change: 13                        4

LDAP(3)                       1995                        LDAP(3)

                         return first row of displayable items in

                         a template

     ldap_next_tmplrow(3)

                         return next row of displayable items  in

                         a template

     ldap_first_tmplcol(3)

                         return first column of displayable items

                         in a template

     ldap_next_tmplcol(3)

                         return next column of displayable  items

                         in a template

     ldap_entry2text(3)  display an entry as text using a display

                         template

     ldap_entry2text_search(3)

                         search for and display an entry as  text

                         using a display template

     ldap_vals2text(3)   display values as text

     ldap_entry2html(3)  display  an  entry  as  HTML  (HyperText

                         Markup  Language)  using  a display tem-

                         plate

     ldap_entry2html_search(3)

                         search for and display an entry as  HTML

                         using a display template

     ldap_vals2html(3)   display values as HTML

     ldap_perror(3)      print an LDAP error indication to  stan-

                         dard error

     ld_errno(3)         LDAP error indication

     ldap_result2error(3)

                         extract LDAP error indication from  LDAP

                         result

     ldap_errlist(3)     list of ldap errors and their meanings

     ldap_err2string(3)  convert  LDAP  error  indication  to   a

                         string

     ldap_first_attribute(3)

                         return first attribute name in an entry

     ldap_next_attribute(3)

November                 Last change: 13                        5

LDAP(3)                       1995                        LDAP(3)

                         return next attribute name in an entry

     ldap_first_entry(3) return first entry in a chain of  search

                         results

     ldap_next_entry(3)  return next entry in a chain  of  search

                         results

     ldap_count_entries(3)

                         return number of  entries  in  a  search

                         result

     ldap_friendly_name(3)

                         map from unfriendly to friendly names

     ldap_free_friendlymap(3)

                         free resources used by ldap_friendly(3)

     ldap_get_dn(3)      extract the DN from an entry

     ldap_explode_dn(3)  convert a DN into its component parts

     ldap_explode_dns(3) convert a DNS-style  DN  into  its  com-

                         ponent parts (experimental)

     ldap_is_dns_dn(3)   check to see if a DN is a  DNS-style  DN

                         (experimental)

     ldap_dn2ufn(3)      convert a DN into user friendly form

     ldap_get_values(3)  return an attribute's values

     ldap_get_values_len(3)

                         return an attribute values with lengths

     ldap_value_free(3)  free      memory      allocated       by

                         ldap_get_values(3)

     ldap_value_free_len(3)

                         free      memory      allocated       by

                         ldap_get_values_len(3)

     ldap_count_values(3)

                         return number of values

     ldap_count_values_len(3)

                         return number of values

     ldap_init_getfilter(3)

                         initialize  getfilter  routines  from  a

                         file

November                 Last change: 13                        6

LDAP(3)                       1995                        LDAP(3)

     ldap_init_getfilter_buf(3)

                         initialize  getfilter  routines  from  a

                         buffer

     ldap_getfilter_free(3)

                         free     resources     allocated      by

                         ldap_init_getfilter(3)

     ldap_getfirstfilter(3)

                         return first search filter

     ldap_getnextfilter(3)

                         return next search filter

     ldap_build_filter(3)

                         construct an LDAP search filter  from  a

                         pattern

     ldap_setfilteraffixes(3)

                         set prefix and suffix for search filters

     ldap_modify(3)      asynchronously modify an entry

     ldap_modify_s(3)    synchronously modify an entry

     ldap_mods_free(3)   free array of pointers to mod structures

                         used by ldap_modify(3)

     ldap_modrdn2(3)     asynchronously  modify  the  RDN  of  an

                         entry

     ldap_modrdn2_s(3)   synchronously modify the RDN of an entry

     ldap_modrdn(3)      depreciated - use ldap_modrdn2(3)

     ldap_modrdn_s(3)    depreciated - use ldap_modrdn2_s(3)

     ldap_msgfree(3)     free results allocated by ldap_result(3)

     ldap_search(3)      asynchronously search the directory

     ldap_search_s(3)    synchronously search the directory

     ldap_search_st(3)   synchronously search the directory  with

                         timeout

     ldap_ufn_search_s(3)

                         user friendly search the directory

     ldap_ufn_search_c(3)

                         user friendly search the directory  with

                         cancel

November                 Last change: 13                        7

LDAP(3)                       1995                        LDAP(3)

     ldap_ufn_search_ct(3)

                         user friendly search the directory  with

                         cancel and timeout

     ldap_ufn_setfilter(3)

                         set filter file used by ldap_ufn(3) rou-

                         tines

     ldap_ufn_setprefix(3)

                         set prefix used by ldap_ufn(3) routines

     ldap_ufn_timeout(3) set timeout used by ldap_ufn(3) routines

     ldap_init_searchprefs(3)

                         initialize searchprefs routines  from  a

                         file

     ldap_init_searchprefs_buf(3)

                         initialize searchprefs routines  from  a

                         buffer

     ldap_free_searchprefs(3)

                         free  memory  allocated  by  searchprefs

                         routines

     ldap_first_searchobj(3)

                         return first searchpref object

     ldap_next_searchobj(3)

                         return next searchpref object

     ldap_sort_entries(3)

                         sort a list of search results

     ldap_sort_values(3) sort a list of attribute values

     ldap_sort_strcasecmp(3)

                         case insensitive string comparison

     ldap_set_string_translators(3)

                         set character set  translation  routines

                         used by LDAP library

     ldap_t61_to_8859(3) routine to translate from ISO-8859 char-

                         acters to the T.61 characters

     ldap_8859_to_t61(3) routine to translate from  T.61  charac-

                         ters to the ISO-8859 characters

     cldap_open(3)       open a connectionless LDAP (CLDAP)  ses-

                         sion

November                 Last change: 13                        8

LDAP(3)                       1995                        LDAP(3)

     cldap_search_s(3)   perform a  search  using  connectionless

                         LDAP

     cldap_setretryinfo(3)

                         set retry and timeout information  using

                         connectionless LDAP

     cldap_close(3)      terminate a connectionless LDAP session

SEE ALSO

     ldapd(8), slapd(8)

AUTHORS

     Tim Howes, Mark Smith, Gordon Good, Lance Sloan,  and  Steve

     Rothwell  from  the  University of Michigan, along with help

     from lots of others.

November                 Last change: 13                        9


ldap_abandon
LDAP_ABANDON (3)               1994                LDAP_ABANDON(3)

NAME

     ldap_abandon - Abandon an LDAP operation in progress

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_abandon(ld, msgid)

     LDAP *ld;

     int msgid;

DESCRIPTION

     The ldap_abandon() routine is used to abandon or  cancel  an

     LDAP  operation in progress.  The _m_s_g_i_d passed should be the

     message id of an outstanding LDAP operation, as returned  by

     ldap_search(3), ldap_modify(3), etc.

     ldap_abandon() checks to see if the result of the  operation

     has  already  come  in.   If  it has, it deletes it from the

     queue of pending messages.  If not, it sends an LDAP abandon

     operation to the the LDAP server.

     The caller can expect that the result of an abandoned opera-

     tion   will   not   be   returned  from  a  future  call  to

     ldap_result(3).

ERRORS

     ldap_abandon() returns 0 if everything goes  ok,  -1  other-

     wise,  setting _l_d__e_r_r_n_o appropriately. See ldap_error(3) for

     details.

SEE ALSO

     ldap(3), ldap_result(3), ldap_error(3)

December                 Last change: 1                         1


ldap_add
LDAP_ADD (3)                   1994                    LDAP_ADD(3)

NAME

     ldap_add, ldap_add_s - Perform an LDAP add operation

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_add(ld, dn, attrs)

     LDAP *ld;

     char *dn;

     LDAPMod *attrs[];

     int ldap_add_s(ld, dn, attrs)

     LDAP *ld;

     char *dn;

     LDAPMod *attrs[];

DESCRIPTION

     The ldap_add_s() routine is used  to  perform  an  LDAP  add

     operation.   It  takes  _d_n,  the DN of the entry to add, and

     _a_t_t_r_s, a null-terminated array of  the  entry's  attributes.

     The  LDAPMod structure is used to represent attributes, with

     the _m_o_d__t_y_p_e and _m_o_d__v_a_l_u_e_s fields being used  as  described

     under  ldap_modify(3), and the _l_d_a_p__o_p field being used only

     if you need to specify the LDAP_MOD_BVALUES  option.  Other-

     wise, it should be set to zero.

     Note that all entries except that specified by the last com-

     ponent  in  the  given  DN must already exist.  ldap_add_s()

     returns an LDAP error code indicating success or failure  of

     the operation.  See ldap_error(3) for more details.

     The ldap_add() routine works just like ldap_add_s(), but  it

     is  asynchronous.   It returns the message id of the request

     it initiated.  The result of this operation can be  obtained

     by calling ldap_result(3).

ERRORS

     ldap_add() returns  -1  in  case  of  error  initiating  the

     request, and will set the _l_d__e_r_r_n_o field in the _l_d parameter

     to indicate the error.  ldap_add_s()  will  return  an  LDAP

     error  code  directly  (LDAP_SUCCESS  if everything went ok,

     some error otherwise).

SEE ALSO

     ldap(3), ldap_modify(3)

November                 Last change: 15                        1


ldap_bind
LDAP_BIND (3)                  1994                   LDAP_BIND(3)

NAME

     ldap_bind,          ldap_bind_s,           ldap_simple_bind,

     ldap_simple_bind_s,                    ldap_kerberos_bind_s,

     ldap_kerberos_bind1,                  ldap_kerberos_bind1_s,

     ldap_kerberos_bind2,   ldap_kerberos_bind2_s,   ldap_unbind,

     ldap_unbind_s - LDAP bind routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_bind(ld, who, cred, method)

     LDAP *ld;

     char *who, *cred;

     int method;

     int ldap_bind_s(ld, who, cred, method)

     LDAP *ld;

     char *who, *cred;

     int method;

     int ldap_simple_bind(ld, who, passwd)

     LDAP *ld;

     char *who, *passwd;

     int ldap_simple_bind_s(ld, who, passwd)

     LDAP *ld;

     char *who, *passwd;

     int ldap_kerberos_bind_s(ld, who)

     LDAP *ld;

     char *who;

     int ldap_kerberos_bind1(ld, who)

     LDAP *ld;

     char *who;

     int ldap_kerberos_bind1_s(ld, who)

     LDAP *ld;

     char *who;

     int ldap_kerberos_bind2(ld, who)

     LDAP *ld;

     char *who;

     int ldap_kerberos_bind2_s(ld, who)

     LDAP *ld;

     char *who;

     int ldap_unbind(ld)

     LDAP *ld;

November                 Last change: 15                        1

LDAP_BIND(3)                  1994                   LDAP_BIND(3)

     int ldap_unbind_s(ld)

     LDAP *ld;

DESCRIPTION

     These routines provide various interfaces to the  LDAP  bind

     operation.   After  a  connection  is made to an LDAP server

     using ldap_open(3), an LDAP bind operation must be performed

     before other operations can be attempted over the conection.

     Both synchronous and asynchronous versions of  each  variant

     of  the  bind  call  are provided.  There are three types of

     calls, providing simple authentication, kerberos authentica-

     tion,  and  general routines to do either one.  All routines

     take  _l_d  as  their  first  parameter,  as   returned   from

     ldap_open(3).

SIMPLE AUTHENTICATION

     The simplest form of the bind call is  ldap_simple_bind_s().

     It  takes  the  DN  to  bind as in _w_h_o, and the userPassword

     associated with the entry in _p_a_s_s_w_d.   It  returns  an  LDAP

     error      indication      (see     ldap_error(3)).      The

     ldap_simple_bind() call is  asynchronous,  taking  the  same

     parameters  but  only  initiating  the  bind  operation  and

     returning the message id of the request it sent.  The result

     of  the  operation  can  be obtained by a subsequent call to

     ldap_result(3).

KERBEROS AUTHENTICATION

     If the LDAP library and LDAP  server  being  contacted  have

     been  compiled  with  the  KERBEROS option defined, Kerberos

     version 4 authentication can be accomplished by calling  the

     ldap_kerberos_bind_s() routine.  It assumes the user already

     has obtained a ticket granting ticket.  It takes _w_h_o, the DN

     of  the  entry  to bind as.  This routine does both steps of

     the   kerberos   binding   process    synchronously.     The

     ldap_kerberos_bind1_s() and ldap_kerberos_bind2_s() routines

     allow synchronous access to the individual steps,  authenti-

     cating  to  the  LDAP  server  and  DSA,  respectively.  The

     ldap_kerberos_bind1()  and  ldap_kerberos_bind2()   routines

     provide equivalent asynchronous access.

GENERAL AUTHENTICATION

     The ldap_bind() and ldap_bind_s() routines can be used  when

     the  authentication  method  to  use needs to be selected at

     runtime.  They both take an extra _m_e_t_h_o_d parameter selecting

     the  authentication  method to use.  It should be set to one

     of LDAP_AUTH_SIMPLE, LDAP_AUTH_KRBV41, or  LDAP_AUTH_KRBV42,

     to  select simple authentication, kerberos authentication to

     the LDAP server, or  kerberos  authentication  to  the  DSA,

     respectively.   ldap_bind()  returns  the  message id of the

     request it initiates.  ldap_bind_s() returns an  LDAP  error

     indication.

November                 Last change: 15                        2

LDAP_BIND(3)                  1994                   LDAP_BIND(3)

UNBINDING

     The ldap_unbind() call is used to unbind from the directory,

     terminate  the  current  association, and free the resources

     contained in the _l_d structure.  Once it is called, the  con-

     nection  to  the LDAP server is closed, and the _l_d structure

     is invalid.  The ldap_unbind_s() call is just  another  name

     for  ldap_unbind();  both  of these calls are synchronous in

     nature.

ERRORS

     Asynchronous routines will return -1 in case of error,  set-

     ting  the  _l_d__e_r_r_n_o parameter of the _l_d structure.  Synchro-

     nous routines return  whatever  _l_d__e_r_r_n_o  is  set  to.   See

     ldap_error(3) for more information.

SEE ALSO

     ldap(3), ldap_error(3), ldap_open(3)

November                 Last change: 15                        3


ldap_cache
LDAP_CACHE (3)                 1994                  LDAP_CACHE(3)

NAME

     ldap_enable_cache,  ldap_disable_cache,  ldap_destroy_cache,

     ldap_flush_cache,  ldap_uncache_entry, ldap_uncache_request,

     ldap_set_cache_options - LDAP client caching routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     ldap_enable_cache( ld, timeout, maxmem )

     LDAP *ld;

     long timeout;

     long maxmem;

     void ldap_disable_cache( ld )

     LDAP *ld;

     void ldap_destroy_cache( ld )

     LDAP *ld;

     void ldap_flush_cache( ld )

     LDAP *ld;

     void ldap_uncache_entry( ld, dn )

     LDAP *ld;

     char *dn;

     void ldap_uncache_request( ld, msgid )

     LDAP *ld;

     int  msgid;

     void ldap_set_cache_options( ld, opts )

     LDAP      *ld;

     unsigned long  opts;

DESCRIPTION

     These routines are used to control the  behavior  of  client

     caching    of    ldap_search(3),    cldap_search_s(3),   and

     ldap_compare(3) operations.  By default, the cache  is  dis-

     abled  and  no  caching  is  done.   Enabling  the cache can

     greatly improve performance  and  reduce  network  bandwidth

     when a client DUA makes repeated requests.

     ldap_enable_cache() should be called to turn on local  cach-

     ing  or  to  change  cache  parameters  (lifetime  of cached

     requests and memory used).  The _l_d parameter should  be  the

     result of a successful call to ldap_open(3).  The _t_i_m_e_o_u_t is

     specified in seconds, and is used to decide how long to keep

     cached  requests.  The _m_a_x_m_e_m value is in bytes, and is used

     to set an upper bound on how memory the cache will use.  You

     can  specify  0 for _m_a_x_m_e_m to restrict the cache size by the

     _t_i_m_e_o_u_t only.  The first call to  ldap_enable_cache  creates

November                 Last change: 14                        1

LDAP_CACHE(3)                 1994                  LDAP_CACHE(3)

     the  cache; subsequent calls re-enable the cache and set the

     timeout and memory values.

     ldap_disable_cache() temporarily disables use of  the  cache

     (new  requests  are  not cached and the cache is not checked

     when returning results).  It does not delete the cache  con-

     tents.

     ldap_destroy_cache()  turns  off  caching   and   completely

     removes the cache from memory.

     ldap_flush_cache() deletes the cache contents, but does  not

     effect it in any other way.

     ldap_uncache_entry() removes all requests that  make  refer-

     ence to the distinguished name _d_n from the cache.  It should

     be used, for example, after  doing  an  ldap_modify(3)  call

     involving _d_n.

     ldap_uncache_request() removes the request indicated by  the

     LDAP request id _m_s_g_i_d from the cache.

     ldap_set_cache_options() is used to change caching behavior.

     The current supported options are LDAP_CACHE_OPT_CACHENOERRS

     to suppress caching of any requests that result in an error,

     and  LDAP_CACHE_OPT_CACHEALLERRS  to  enable  caching of all

     requests.  The default behavior is  to  not  cache  requests

     that  result  in  errors, except that request that result in

     the error LDAP_SIZELIMIT_EXCEEDED are cached.

ERRORS

     ldap_enable_cache() returns 0 upon success, and -1 if it  is

     unable to allocate space for the cache.  All the other calls

     are declared as void and return nothing.

SEE ALSO

     ldap(3), ldap_search(3), ldap_compare(3), cldap_search_s(3)

November                 Last change: 14                        2


ldap_charset
LDAP_CHARSET (3)               1995                LDAP_CHARSET(3)

NAME

     ldap_set_string_translators,               ldap_t61_to_8859,

     ldap_8859_to_t61 - LDAP character set translation routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     void ldap_set_string_translators( ld, encode_proc, decode_proc )

     LDAP           *ld;

     BERTranslateProc    encode_proc;

     BERTranslateProc    decode_proc;

     int ldap_t61_to_8859( bufp, buflenp, free_input )

     char      **bufp;

     unsigned long  *buflenp;

     int       free_input;

     int ldap_8859_to_t61( bufp, buflenp, free_input )

     char      **bufp;

     unsigned long  *buflenp;

     int       free_input;

DESCRIPTION

     These routines are used to used  to  enable  translation  of

     character  strings  used in the LDAP library to and from the

     T.61 character set used in the LDAP protocol.   These  func-

     tions  are only available if the LDAP and LBER libraries are

     compiled with STR_TRANSLATION defined.

     ldap_set_string_translators() sets the translation  routines

     that  will  be used by the LDAP library.  They are not actu-

     ally used until the _l_d__l_b_e_r_o_p_t_i_o_n_s field of the LDAP  struc-

     ture is set to include the LBER_TRANSLATE_STRINGS option.

     ldap_t61_to_8859() and  ldap_8859_to_t61()  are  translation

     routines for converting between T.61 characters and ISO-8859

     characters.  The specific 8859 character set used is  deter-

     mined at compile time.

     It is also possible to  turn  on  character  translation  by

     default  so  that  all  LDAP library callers will experience

     translation;  see  the  LDAP  Make-common  source  file  for

     details.

SEE ALSO

     ldap(3)

November                 Last change: 11                        1


ldap_compare
LDAP_COMPARE (3)               1994                LDAP_COMPARE(3)

NAME

     ldap_compare,  ldap_compare_s  -  Perform  an  LDAP  compare

     operation

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_compare_s(ld, dn, attr, value)

     LDAP *ld;

     char *dn, *attr, *value;

     int ldap_compare(ld, dn, attr, value)

     LDAP *ld;

     char *dn, *attr, *value;

DESCRIPTION

     The ldap_compare_s() routine is used to perform an LDAP com-

     pare  operation  synchronously.   It takes _d_n, the DN of the

     entry upon which to perform the compare, and _a_t_t_r and _v_a_l_u_e,

     the  attribute  type  and value to compare to those found in

     the entry.  It returns an LDAP error  code,  which  will  be

     LDAP_COMPARE_TRUE  if the entry contains the attribute value

     and LDAP_COMPARE_FALSE if  it  does  not.   Otherwise,  some

     error code is returned.

     The ldap_compare() routine is used to perform an  LDAP  com-

     pare operation asynchronously.  It takes the same parameters

     as ldap_compare_s(), but  returns  the  message  id  of  the

     request  it  initiated.   The  result  of the compare can be

     obtained by a subsequent call to ldap_result(3).

ERRORS

     ldap_compare_s() returns an LDAP error  code  which  can  be

     interpreted  by  calling  one of ldap_perror(3) and friends.

     ldap_compare() returns -1 if something went wrong initiating

     the  request.  It returns the non-negative message id of the

     request if things went ok.

BUGS

     There is no way to compare binary values, but  there  should

     be.

SEE ALSO

     ldap(3), ldap_error(3)

November                 Last change: 15                        1


ldap_delete
LDAP_DELETE (3)                1994                 LDAP_DELETE(3)

NAME

     ldap_delete, ldap_delete_s - Perform an LDAP  delete  opera-

     tion

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_delete_s(ld, dn)

     LDAP *ld;

     char *dn;

     int ldap_delete(ld, dn)

     LDAP *ld;

     char *dn;

DESCRIPTION

     The ldap_delete_s() routine  is  used  to  perform  an  LDAP

     delete  operation synchronously.  It takes _d_n, the DN of the

     entry to be deleted.  It returns an LDAP error  code,  indi-

     cating the success or failure of the operation.

     The ldap_delete() routine is used to perform an LDAP  delete

     operation  asynchronously.   It takes the same parameters as

     ldap_delete_s(), but returns the message id of  the  request

     it initiated.  The result of the delete can be obtained by a

     subsequent call to ldap_result(3).

ERRORS

     ldap_delete_s() returns an LDAP  error  code  which  can  be

     interpreted  by  calling  one of ldap_perror(3) and friends.

     ldap_delete() returns -1 if something went wrong  initiating

     the  request.  It returns the non-negative message id of the

     request if things went ok.

SEE ALSO

     ldap(3), ldap_error(3)

November                 Last change: 15                        1


ldap_disptmpl
LDAP_DISPTMPL (3)              1994               LDAP_DISPTMPL(3)

NAME

     ldap_init_templates,                ldap_init_templates_buf,

     ldap_free_templates,                    ldap_first_disptmpl,

     ldap_next_disptmpl,    ldap_oc2template,     ldap_tmplattrs,

     ldap_first_tmplrow,  ldap_next_tmplrow,  ldap_first_tmplcol,

     ldap_next_tmplcol, - LDAP display template routines

SYNOPSIS

     #include <disptmpl.h>

     int ldap_init_templates( file, tmpllistp )

     char           *file;

     struct ldap_disptmpl     *tmpllistp;

     int ldap_init_templates_buf( buf, buflen, tmpllistp )

     char           *buf;

     unsigned long       len;

     struct ldap_disptmpl     *tmpllistp;

     void ldap_free_templates( tmpllist )

     struct ldap_disptmpl     *tmpllist;

     struct ldap_disptmpl *ldap_first_disptmpl( tmpllist )

     struct ldap_disptmpl     *tmpllist;

     struct ldap_disptmpl *ldap_next_disptmpl( tmpllist, tmpl )

     struct ldap_disptmpl     *tmpllist;

     struct ldap_disptmpl     *tmpl;

     struct ldap_disptmpl *ldap_oc2template( oclist, tmpllist )

     char           **oclist;

     struct ldap_disptmpl     *tmpllist;

     struct ldap_disptmpl *ldap_name2template( name, tmpllist )

     char           *name;

     struct ldap_disptmpl     *tmpllist;

     char **ldap_tmplattrs( tmpl, includeattrs, exclude, syntaxmask )

     struct ldap_disptmpl     *tmpl;

     char           **includeattrs;

     int            exclude;

     unsigned long       syntaxmask;

     struct ldap_tmplitem *ldap_first_tmplrow( tmpl )

     struct ldap_disptmpl     *tmpl;

     struct ldap_tmplitem *ldap_next_tmplrow( tmpl, row )

     struct ldap_disptmpl     *tmpl;

     struct ldap_tmplitem     *row;

     struct ldap_tmplitem *ldap_first_tmplcol( tmpl, row )

     struct ldap_disptmpl     *tmpl;

December                 Last change: 13                        1

LDAP_DISPTMPL(3)              1994               LDAP_DISPTMPL(3)

     struct ldap_tmplitem     *row;

     struct ldap_tmplitem *ldap_next_tmplcol( tmpl, row, col )

     struct ldap_disptmpl     *tmpl;

     struct ldap_tmplitem     *row;

     struct ldap_tmplitem     *col;

DESCRIPTION

     These functions provide a standard way to access LDAP  entry

     display  templates.  Entry display templates provide a stan-

     dard way for LDAP applications to display directory entries.

     The  general  idea is that it is possible to map the list of

     object class values present in an entry  to  an  appropriate

     display template.  Display templates are defined in a confi-

     guration file  (see  ldaptemplates.conf(5)).   Each  display

     template contains a pre-determined list of items, where each

     item generally corresponds to an attribute to be  displayed.

     The  items contain information and flags that the caller can

     use to display the attribute  and  values  in  a  reasonable

     fashion.   Each  item has a syntaxid, which are described in

     the SYNTAX IDS section below.  The  ldap_entry2text(3)  rou-

     tines  use  the  display template functions and produce text

     output.

     ldap_init_templates() reads a sequence of templates  from  a

     valid     LDAP     template    configuration    file    (see

     ldaptemplates.conf(5)) _Z_e_r_o is returned  upon  success,  and

     _t_m_p_l_l_i_s_t_p  is  set  to  point  to a list of templates.  Each

     member of the list is an  ldap_disptmpl  structure  (defined

     below in the DISPTMPL STRUCTURE ELEMENTS section).

     ldap_init_templates_buf() reads a sequence of templates from

     _b_u_f  (whose size is _b_u_f_l_e_n). _b_u_f should point to the data in

     the format defined for an LDAP template  configuration  file

     (see  ldaptemplates.conf(5))  _Z_e_r_o is returned upon success,

     and _t_m_p_l_l_i_s_t_p is set to point to a list of templates.

     The LDAP_SET_DISPTMPL_APPDATA() macro is  used  to  set  the

     value of the dt_appdata field in an ldap_disptmpl structure.

     This field is reserved for the calling application  to  use;

     it is not used internally.

     The LDAP_GET_DISPTMPL_APPDATA() macro is  used  to  retrieve

     the value in the dt_appdata field.

     The LDAP_IS_DISPTMPL_OPTION_SET() macro is used  to  test  a

     ldap_disptmpl  structure  for  the  existence  of a template

     option.     The    options    currently     defined     are:

     LDAP_DTMPL_OPT_ADDABLE  (it  is appropriate to allow entries

     of this type to be added), LDAP_DTMPL_OPT_ALLOWMODRDN (it is

     appropriate   to   offer   the   "modify   rdn"  operation),

     LDAP_DTMPL_OPT_ALTVIEW (this template is merely an alternate

December                 Last change: 13                        2

LDAP_DISPTMPL(3)              1994               LDAP_DISPTMPL(3)

     view  of  another  template,  typically  used  for templates

     pointed to be an LDAP_SYN_LINKACTION item).

     ldap_free_templates() disposes of the templates allocated by

     ldap_init_templates().

     ldap_first_disptmpl() returns the first template in the list

     _t_m_p_l_l_i_s_t.  The  _t_m_p_l_l_i_s_t  is  typically  obtained by calling

     ldap_init_templates().

     ldap_next_disptmpl() returns the template after _t_m_p_l in  the

     template  list  _t_m_p_l_l_i_s_t. _A NULL pointer is returned if _t_m_p_l

     is the last template in the list.

     ldap_oc2template() searches _t_m_p_l_l_i_s_t for the  best  template

     to  use  to  display  an  entry  that  has a specific set of

     objectClass values.   _o_c_l_i_s_t  should  be  a  null-terminated

     array of strings that contains the values of the objectClass

     attribute of the entry.  A pointer  to  the  first  template

     where  all  of  the  object  classes  listed  in  one of the

     template's dt_oclist elements are  contained  in  _o_c_l_i_s_t  is

     returned.  A NULL pointer is returned if no appropriate tem-

     plate is found.

     ldap_tmplattrs() returns a null-terminated array  that  con-

     tains  the  names of attributes that need to be retrieved if

     the template _t_m_p_l is to be used to display  an  entry.   The

     attribute list should be freed using ldap_value_free().  The

     _i_n_c_l_u_d_e_a_t_t_r_s parameter contains a null-terminated  array  of

     attributes that should always be included (it may be NULL if

     no extra attributes are required).  If  _s_y_n_t_a_x_m_a_s_k  is  non-

     zero, it is used to restrict the attribute set returned.  If

     _e_x_c_l_u_d_e is zero, only attributes where the  logical  AND  of

     the  template  item syntax id and the _s_y_n_t_a_x_m_a_s_k is non-zero

     are included.  If _e_x_c_l_u_d_e is non-zero, attributes where  the

     logical  AND  of the template item syntax id and the _s_y_n_t_a_x_-

     _m_a_s_k is non-zero are excluded.

     ldap_first_tmplrow() returns a pointer to the first  row  of

     items in template _t_m_p_l.

     ldap_next_tmplrow() returns a pointer to the row  that  fol-

     lows _r_o_w in template _t_m_p_l.

     ldap_first_tmplcol() returns a pointer to the first item (in

     the first column) of row _r_o_w within template _t_m_p_l. _A _p_o_i_n_t_e_r

     _t_o _a_n _l_d_a_p__t_m_p_l_i_t_e_m in the TMPLITEM STRUCTURE ELEMENTS  sec-

     tion) is returned.

     The LDAP_SET_TMPLITEM_APPDATA() macro is  used  to  set  the

     value  of the ti_appdata field in a ldap_tmplitem structure.

     This field is reserved for the calling application  to  use;

December                 Last change: 13                        3

LDAP_DISPTMPL(3)              1994               LDAP_DISPTMPL(3)

     it is not used internally.

     The LDAP_GET_TMPLITEM_APPDATA() macro is  used  to  retrieve

     the value of the ti_appdata field.

     The LDAP_IS_TMPLITEM_OPTION_SET() macro is used  to  test  a

     ldap_tmplitem structure for the existence of an item option.

     The options currently defined  are:  LDAP_DITEM_OPT_READONLY

     (this     attribute     should     not     be     modified),

     LDAP_DITEM_OPT_SORTVALUES  (it  makes  sense  to  sort   the

     values),  LDAP_DITEM_OPT_SINGLEVALUED  (this  attribute  can

     only  hold  a  single  value),  LDAP_DITEM_OPT_VALUEREQUIRED

     (this   attribute   must   contain   at  least  one  value),

     LDAP_DITEM_OPT_HIDEIFEMPTY (do not show this item  if  there

     are  no values), and LDAP_DITEM_OPT_HIDEIFFALSE (for boolean

     attributes only:  hide this item if the value is FALSE).

     ldap_next_tmplcol() returns a pointer to the  item  (column)

     that follows column _c_o_l within row _r_o_w of template _t_m_p_l.

DISPTMPL STRUCTURE ELEMENTS

     The ldap_disptmpl structure is defined as:

     struct ldap_disptmpl {

          char                    *dt_name;

          char           *dt_pluralname;

          char                    *dt_iconname;

          unsigned long           dt_options;

          char                    *dt_authattrname;

          char                    *dt_defrdnattrname;

          char                    *dt_defaddlocation;

          struct ldap_oclist  *dt_oclist;

          struct ldap_adddeflist   *dt_adddeflist;

          struct ldap_tmplitem     *dt_items;

          void           *dt_appdata;

          struct ldap_disptmpl     *dt_next;

     };

     The dt_name member is the singular  name  of  the  template.

     The  dt_pluralname  is  the  plural  name.   The dt_iconname

     member will contain the name of an icon or  other  graphical

     element  that  can be used to depict entries that correspond

     to this display template.  The dt_options  contains  options

     which  may be tested using the LDAP_IS_TMPLITEM_OPTION_SET()

     macro.

     The dt_authattrname  contains  the  name  of  the  DN-syntax

     attribute  whose  value(s) should be used to authenticate to

     make changes to an entry.  If dt_authattrname is NULL,  then

     authenticating  as  the  entry  itself  is appropriate.  The

     dt_defrdnattrname is the name of the attribute that is  nor-

     mally used to name entries of this type, e.g., "cn" for per-

     son entries.  The  dt_defaddlocation  is  the  distinguished

     name  of  an  entry below which new entries of this type are

December                 Last change: 13                        4

LDAP_DISPTMPL(3)              1994               LDAP_DISPTMPL(3)

     typically created (its value is site-dependent).

     dt_oclist is a pointer to a  linked  list  of  object  class

     arrays, defined as:

     struct ldap_oclist {

          char           **oc_objclasses;

          struct ldap_oclist  *oc_next;

     };

     These are used by the ldap_oc2template() routine.

     dt_adddeflist is a pointer to a linked  list  of  rules  for

     defaulting  the  values  of  attributes when new entries are

     created.  The ldap_adddeflist structure is defined as:

     struct ldap_adddeflist {

          int            ad_source;

          char           *ad_attrname;

          char           *ad_value;

          struct ldap_adddeflist   *ad_next;

     };

     The ad_attrname member contains the name  of  the  attribute

     whose    value    this   rule   sets.    If   ad_source   is

     LDAP_ADSRC_CONSTANTVALUE then the ad_value  member  contains

     the   (constant)   value   to   use.    If    ad_source   is

     LDAP_ADSRC_ADDERSDN then ad_value is ignored  and  the  dis-

     tinguished name of the person who is adding the new entry is

     used as the default value for ad_attrname.

TMPLITEM STRUCTURE ELEMENTS

     The ldap_tmplitem structure is defined as:

     struct ldap_tmplitem {

          unsigned long       ti_syntaxid;

          unsigned long       ti_options;

          char           *ti_attrname;

          char           *ti_label;

          char           **ti_args;

          struct ldap_tmplitem     *ti_next_in_row;

          struct ldap_tmplitem     *ti_next_in_col;

          void           *ti_appdata;

     };

SYNTAX IDS

     Syntax ids are found in the ldap_tmplitem structure  element

     ti_syntaxid,  and  they  can  be  used  to  determine how to

     display the values for  the  attribute  associated  with  an

     item.  The LDAP_GET_SYN_TYPE() macro can be used to return a

     general type from a  syntax  id.   The  five  general  types

     currently  defined  are:  LDAP_SYN_TYPE_TEXT (for attributes

     that   are    most    appropriately    shown    as    text),

     LDAP_SYN_TYPE_IMAGE   (for   JPEG  or  FAX  format  images),

     LDAP_SYN_TYPE_BOOLEAN     (for     boolean      attributes),

     LDAP_SYN_TYPE_BUTTON  (for attributes whose values are to be

     retrieved and display only upon request, e.g.,  in  response

December                 Last change: 13                        5

LDAP_DISPTMPL(3)              1994               LDAP_DISPTMPL(3)

     to  the  press  of  a  button,  a  JPEG  image is retrieved,

     decoded, and displayed), and LDAP_SYN_TYPE_ACTION (for  spe-

     cial  purpose  actions such as "search for the entries where

     this entry is listed in the seeAlso attribute").

     The LDAP_GET_SYN_OPTIONS macro can be used  to  retrieve  an

     unsigned   long  bitmap  that  defines  options.   The  only

     currently defined option is  LDAP_SYN_OPT_DEFER,  which  (if

     set) implies that the values for the attribute should not be

     retrieved until requested.

     There are sixteen distinct  syntax  ids  currently  defined.

     These generally correspond to one or more X.500 syntaxes.

     LDAP_SYN_CASEIGNORESTR is used for text attributes which are

     simple  strings  whose  case  is ignored for comparison pur-

     poses.

     LDAP_SYN_MULTILINESTR is used for text attributes which con-

     sist  of  multiple lines, e.g., postalAddress, homePostalAd-

     dress, multilineDescription, or  any  attributes  of  syntax

     caseIgnoreList.

     LDAP_SYN_RFC822ADDR is used for case  ignore  string  attri-

     butes  that  are  RFC-822  conformant  mail addresses, e.g.,

     mail.

     LDAP_SYN_DN is used for attributes with a Distinguished Name

     syntax, e.g., seeAlso.

     LDAP_SYN_BOOLEAN is used for attributes with a boolean  syn-

     tax.

     LDAP_SYN_JPEGIMAGE is used for attributes with a  jpeg  syn-

     tax, e.g., jpegPhoto.

     LDAP_SYN_JPEGBUTTON  is  used  to  provide  a   button   (or

     equivalent  interface element) that can be used to retrieve,

     decode, and display an attribute of jpeg syntax.

     LDAP_SYN_FAXIMAGE is used for attributes with a  photo  syn-

     tax, e.g., Photo.  These are actually Group 3 Fax (T.4) for-

     mat images.

     LDAP_SYN_FAXBUTTON  is  used  to  provide   a   button   (or

     equivalent  interface element) that can be used to retrieve,

     decode, and display an attribute of photo syntax.

     LDAP_SYN_AUDIOBUTTON  is  used  to  provide  a  button   (or

     equivalent  interface  element) that can be used to retrieve

     and play an attribute of audio syntax.  Audio values are  in

     the "mu law" format, also known as "au" format.

December                 Last change: 13                        6

LDAP_DISPTMPL(3)              1994               LDAP_DISPTMPL(3)

     LDAP_SYN_TIME is used for attributes with the  UTCTime  syn-

     tax,   e.g.,   lastModifiedTime.   The  value(s)  should  be

     displayed in complete date and time fashion.

     LDAP_SYN_DATE is used for attributes with the  UTCTime  syn-

     tax,  e.g.,  lastModifiedTime.  Only the date portion of the

     value(s) should be displayed.

     LDAP_SYN_LABELEDURL is used for labeledURL attributes.

     LDAP_SYN_SEARCHACTION is used to define  a  search  that  is

     used to retrieve related information.  If ti_attrname is not

     NULL, it is assumed to be a  boolean  attribute  which  will

     cause  no search to be performed if its value is FALSE.  The

     ti_args structure member  will  have  four  strings  in  it:

     ti_args[ 0 ] should be the name of an attribute whose values

     are used to help construct a search filter or "-dn"  is  the

     distinguished  name  of  the entry being displayed should be

     used, ti_args[ 1 ] should be  a  filter  pattern  where  any

     occurrences of "%v" are replaced with the value derived from

     ti_args[ 0 ], ti_args[ 2 ] should be the name  of  an  addi-

     tional attribute to retrieve when performing the search, and

     ti_args[ 3 ] should be  a  human-consumable  name  for  that

     attribute.    The   ti_args[  2  ]  attribute  is  typically

     displayed along with a list of distinguished names when mul-

     tiple entries are returned by the search.

     LDAP_SYN_LINKACTION is used to define a link to another tem-

     plate  by  name.   ti_args[ 0 ] will contain the name of the

     display template to use.  The  ldap_name2template()  routine

     can be used to obtain a pointer to the correct ldap_disptmpl

     structure.

     LDAP_SYN_ADDDNACTION   and    LDAP_SYN_VERIFYDNACTION    are

     reserved as actions but currently undefined.

ERRORS

     The init template functions return LDAP_TMPL_ERR_VERSION  if

     buf  points  to  data  that  is  newer  than can be handled,

     LDAP_TMPL_ERR_MEM if there is a memory  allocation  problem,

     LDAP_TMPL_ERR_SYNTAX  if  there is a problem with the format

     of the templates  buffer  or  file.   LDAP_TMPL_ERR_FILE  is

     returned  by ldap_init_templates if the file cannot be read.

     Other routines generally return NULL upon error.

SEE ALSO

     ldap(3), ldap_entry2text(3), ldaptemplates.conf(5)

December                 Last change: 13                        7


ldap_entry2text
LDAP_ENTRY2TEXT (3)            1994             LDAP_ENTRY2TEXT(3)

NAME

     ldap_entry2text,  ldap_entry2text_search,  ldap_vals2text  -

     LDAP entry display routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     #include <disptmpl.h>

     int ldap_entry2text( ld, buf, entry, tmpl, defattrs, defvals, writeproc,

         writeparm, eol, rdncount, opts )

          LDAP           *ld;

          char           *buf;

          LDAPMessage         *entry;

          struct ldap_disptmpl     *tmpl;

          char           **defattrs;

          char           ***defvals;

          int            (*writeproc)();

          void           *writeparm;

          char           *eol;

          int            rdncount;

          unsigned long       opts;

     int ldap_entry2text_search( ld, entry, tmpllist, defattrs, defvals,

         writeproc, writeparm, eol, rdncount, opts )

          LDAP           *ld;

          char           *dn;

          char           *base;

          LDAPMessage         *entry;

          struct ldap_disptmpl     *tmpllist;

          char           **defattrs;

          char           ***defvals;

          int            (*writeproc)();

          void           *writeparm;

          char           *eol;

          int            rdncount;

          unsigned long       opts;

     int ldap_vals2text( ld, buf, vals, label, labelwidth, syntaxid, writeproc,

         writeparm, eol, rdncount )

          LDAP           *ld;

          char           *buf;

          char           **vals;

          char           *label;

          int            labelwidth;

          unsigned long       syntaxid;

          int            (*writeproc)();

          void           *writeparm;

          char           *eol;

          int            rdncount;

November                 Last change: 13                        1

LDAP_ENTRY2TEXT(3)            1994             LDAP_ENTRY2TEXT(3)

     int ldap_entry2html( ld, buf, entry, tmpl, defattrs, defvals, writeproc,

         writeparm, eol, rdncount, opts )

          LDAP           *ld;

          char           *buf;

          LDAPMessage         *entry;

          struct ldap_disptmpl     *tmpl;

          char           **defattrs;

          char           ***defvals;

          int            (*writeproc)();

          void           *writeparm;

          char           *eol;

          int            rdncount;

          unsigned long       opts;

          char           *urlprefix;

          char           *base;

     int ldap_entry2html_search( ld, entry, tmpllist, defattrs, defvals,

         writeproc, writeparm, eol, rdncount, opts )

          LDAP           *ld;

          char           *dn;

          LDAPMessage         *entry;

          struct ldap_disptmpl     *tmpllist;

          char           **defattrs;

          char           ***defvals;

          int            (*writeproc)();

          void           *writeparm;

          char           *eol;

          int            rdncount;

          unsigned long       opts;

          char           *urlprefix;

     int ldap_vals2html( ld, buf, vals, label, labelwidth, syntaxid, writeproc,

         writeparm, eol, rdncount )

          LDAP           *ld;

          char           *buf;

          char           **vals;

          char           *label;

          int            labelwidth;

          unsigned long       syntaxid;

          int            (*writeproc)();

          void           *writeparm;

          char           *eol;

          int            rdncount;

          char           *urlprefix;

     #define LDAP_DISP_OPT_AUTOLABELWIDTH    0x00000001

     #define LDAP_DTMPL_BUFSIZ          2048

DESCRIPTION

     These functions use the LDAP display template routines  (see

     ldap_disptmpl(3)  and  ldap_templates.conf(5))  to produce a

November                 Last change: 13                        2

LDAP_ENTRY2TEXT(3)            1994             LDAP_ENTRY2TEXT(3)

     plain text or an HyperText Markup Language (HTML) display of

     an entry or a set of values.  Typical plain text output pro-

     duced for an entry might look like:

         "Barbara J Jensen, Information Technology Division"

          Also Known As:

                  Babs Jensen

                  Barbara Jensen

                  Barbara J Jensen

          E-Mail Address:

                  bjensen@terminator.rs.itd.umich.edu

          Work Address:

                  535 W. William

                  Ann Arbor, MI 48103

          Title:

                  Mythical Manager, Research Systems

          ...

     The exact output produced will depend on  the  display  tem-

     plate  configuration.   HTML  output is similar to the plain

     text output, but more richly formatted.

     ldap_entry2text() produces a text  representation  of  _e_n_t_r_y

     and  writes the text by calling the _w_r_i_t_e_p_r_o_c function.  All

     of the attributes values to be displayed must be present  in

     _e_n_t_r_y; no interaction with the LDAP server will be performed

     within ldap_entry2text. _l_d is the LDAP pointer obtained by a

     previous call to ldap_open. _w_r_i_t_e_p_r_o_c should be declared as:

     int writeproc( writeparm, p, len )

          void      *writeparm;

          char      *p;

          int       len;

     where _p is a pointer to text to be written and  _l_e_n  is  the

     length  of the text.  _p is guaranteed to be zero-terminated.

     Lines of text are terminated with the string _e_o_l. _b_u_f  is  a

     pointer to a buffer of size LDAP_DTMPL_BUFSIZ or larger.  If

     _b_u_f _i_s NULL then a buffer is allocated and freed internally.

     _t_m_p_l  is  a pointer to the display template to be used (usu-

     ally obtained by calling ldap_oc2template). If _t_m_p_l is NULL,

     no  template  is  used  and  a  generic display is produced.

     _d_e_f_a_t_t_r_s is a NULL-terminated array of LDAP attribute  names

     which  you  wish to provide default values for (only used if

     _e_n_t_r_y contains no values for the attribute).   An  array  of

     NULL-terminated  arrays  of  default values corresponding to

     the attributes should be passed  in  _d_e_f_v_a_l_s.  _T_h_e  _r_d_n_c_o_u_n_t

     parameter  is used to limit the number of Distinguished Name

     (DN) components that are actually displayed  for  DN  attri-

     butes.  If _r_d_n_c_o_u_n_t is zero, all components are shown.  _o_p_t_s

     is  used  to  specify  output  options.   The  only   values

     currently    allowed   are   zero   (default   output)   and

     LDAP_DISP_OPT_AUTOLABELWIDTH  which  causes  the  width  for

November                 Last change: 13                        3

LDAP_ENTRY2TEXT(3)            1994             LDAP_ENTRY2TEXT(3)

     labels to be determined based on the longest label in _t_m_p_l.

     ldap_entry2text_search() is similar to ldap_entry2text,  and

     all  of  the  like-named  parameters  have  the same meaning

     except as noted below. If _b_a_s_e is not NULL, it is the search

     base  to  use when executing search actions.  If it is NULL,

     search action template items are ignored.  If _e_n_t_r_y  is  not

     NULL, it should contain the _o_b_j_e_c_t_C_l_a_s_s attribute values for

     the entry to be displayed.  If _e_n_t_r_y is NULL, _d_n must not be

     NULL,   and   ldap_entry2text_search   will   retrieve   the

     objectClass  values   itself   by   calling   ldap_search_s.

     ldap_entry2text_search   will   determine   the  appropriate

     display template to use  by  calling  ldap_oc2template,  and

     will  call ldap_search_s to retrieve any attribute values to

     be displayed.  The _t_m_p_l_l_i_s_t parameter is a  pointer  to  the

     entire list of templates available (usually obtained by cal-

     ling  ldap_init_templates  or  ldap_init_templates_buf).  If

     _t_m_p_l_l_i_s_t  is  NULL,  ldap_entry2text_search  will attempt to

     read a load templates from the default  template  configura-

     tion file ETCDIR/ldaptemplates.conf.

     ldap_vals2text produces a text representation  of  a  single

     set  of LDAP attribute values.  The _l_d, _b_u_f, _w_r_i_t_e_p_r_o_c, _w_r_i_-

     _t_e_p_a_r_m, _e_o_l, and _r_d_n_c_o_u_n_t parameters are  the  same  as  the

     like-named  parameters  for ldap_entry2text. _v_a_l_s is a NULL-

     terminated list of values, usually obtained  by  a  call  to

     ldap_get_values.  _l_a_b_e_l is a string shown next to the values

     (usually  a  friendly  form  of  an  LDAP  attribute  name).

     _l_a_b_e_l_w_i_d_t_h  specifies  the label margin, which is the number

     of blank spaces displayed to the left  of  the  values.   If

     zero  is passed, a default label width is used.  _s_y_n_t_a_x_i_d is

     a  display  template  attribute   syntax   identifier   (see

     ldap_disptmpl(3)  for a list of the pre-defined LDAP_SYN_...

     values).

     ldap_entry2html produces an HTML representation of _e_n_t_r_y. It

     behaves exactly like ldap_entry2text(3), except for the for-

     matted output and the addition of two parameters.  _u_r_l_p_r_e_f_i_x

     is  the  starting text to use when constructing an LDAP URL.

     The default is the string  _l_d_a_p:///  The  second  additional

     parameter,  _b_a_s_e,  the  search  base  to  use when executing

     search actions.  If it is NULL, search action template items

     are ignored.

     ldap_entry2html_search      behaves       exactly       like

     ldap_entry2text_search(3),  except  HTML  output is produced

     and one additional parameter is required.  _u_r_l_p_r_e_f_i_x is  the

     starting  text  to  use  when constructing an LDAP URL.  The

     default is the string _l_d_a_p:///

     ldap_vals2html behaves exactly like  ldap_vals2text,  except

     HTML  output  is  produced  and  one additional parameter is

November                 Last change: 13                        4

LDAP_ENTRY2TEXT(3)            1994             LDAP_ENTRY2TEXT(3)

     required.  _u_r_l_p_r_e_f_i_x is the starting text to use  when  con-

     structing an LDAP URL.  The default is the string _l_d_a_p:///

ERRORS

     These routines all return an LDAP error  code  (LDAP_SUCCESS

     is  returned  if  no  error  occurs).  See ldap_error(3) for

     details. The _l_d__e_r_r_n_o field of the _l_d parameter is also  set

     to indicate the error.

FILES

     ETCDIR/ldaptemplates.conf

SEE ALSO

     ldap(3), ldap_disptmpl(3), ldaptemplates.conf(5)

November                 Last change: 13                        5


ldap_error
LDAP_ERROR (3)                 1994                  LDAP_ERROR(3)

NAME

     ldap_perror,  ld_errno,   ldap_result2error,   ldap_errlist,

     ldap_err2string - LDAP protocol error handling routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     struct ldaperror {

         int e_code;

         char *e_reason;

     };

     struct ldaperror ldap_errlist[];

     char *ldap_err2string(err)

     int err;

     void ldap_perror(ld, s)

     LDAP *ld;

     char *s;

     int ldap_result2error(ld, res, freeit)

     LDAP *ld;

     LDAPMessage *res;

     int freeit;

DESCRIPTION

     These routines provide interpretation of the  various  error

     codes  returned  by  the LDAP protocol and LDAP library rou-

     tines, and assigned to the _l_d__e_r_r_n_o field in the  _l_d  struc-

     ture.

     The ldap_result2error() routine takes _r_e_s, a result as  pro-

     duced by ldap_result(3) or ldap_search_s(3), and returns the

     corresponding error code.  Possible error codes  are  listed

     below.   If  the  _f_r_e_e_i_t  parameter is non zero it indicates

     that the  _r_e_s  parameter  should  be  freed  by  a  call  to

     ldap_msgfree(3)  after  the  error  code has been extracted.

     The ld_errno field in _l_d is set and returned.

     The returned value can be  passed  to  ldap_err2string()  or

     looked up in ldap_errlist[] to get a text description of the

     message.  The string returned from  ldap_err2string()  is  a

     pointer  to  a static area that should not be modified.  The

     last element in the ldap_errlist[] array is signaled  by  an

     error code of -1.

     The ldap_perror() routine can be called to print an  indica-

     tion of the error on standard error, similar to the way per-

     ror(3) works.

November                 Last change: 15                        1

LDAP_ERROR(3)                 1994                  LDAP_ERROR(3)

ERRORS

     The possible values for an ldap error code are:

     LDAP_SUCCESS        The request was successful.

     LDAP_OPERATIONS_ERROR

                         An operations error occurred.

     LDAP_PROTOCOL_ERROR A protocol violation was detected.

     LDAP_TIMELIMIT_EXCEEDED

                         An LDAP time limit was exceeded.

     LDAP_SIZELIMIT_EXCEEDED

                         An LDAP size limit was exceeded.

     LDAP_COMPARE_FALSE  A compare operation returned false.

     LDAP_COMPARE_TRUE   A compare operation returned true.

     LDAP_STRONG_AUTH_NOT_SUPPORTED

                         The LDAP server does not support  strong

                         authentication.

     LDAP_STRONG_AUTH_REQUIRED

                         Strong authentication  is  required  for

                         the operation.

     LDAP_PARTIAL_RESULTS

                         Partial results only returned.

     LDAP_NO_SUCH_ATTRIBUTE

                         The attribute type  specified  does  not

                         exist in the entry.

     LDAP_UNDEFINED_TYPE The attribute type specified is invalid.

     LDAP_INAPPROPRIATE_MATCHING

                         Filter type not supported for the speci-

                         fied attribute.

     LDAP_CONSTRAINT_VIOLATION

                         An attribute  value  specified  violates

                         some  constraint  (e.g., a postalAddress

                         has too many lines, or a  line  that  is

                         too long).

     LDAP_TYPE_OR_VALUE_EXISTS

                         An attribute  type  or  attribute  value

                         specified already exists in the entry.

     LDAP_INVALID_SYNTAX An   invalid   attribute    value    was

November                 Last change: 15                        2

LDAP_ERROR(3)                 1994                  LDAP_ERROR(3)

                         specified.

     LDAP_NO_SUCH_OBJECT The specified object does not  exist  in

                         The Directory.

     LDAP_ALIAS_PROBLEM  An alias in The Directory  points  to  a

                         nonexistent entry.

     LDAP_INVALID_DN_SYNTAX

                         A syntactically invalid  DN  was  speci-

                         fied.

     LDAP_IS_LEAF        The object specified is a leaf.

     LDAP_ALIAS_DEREF_PROBLEM

                         A problem  was  encountered  when  dere-

                         ferencing an alias.

     LDAP_INAPPROPRIATE_AUTH

                         Inappropriate authentication was  speci-

                         fied  (e.g., LDAP_AUTH_SIMPLE was speci-

                         fied and the entry does not have a user-

                         Password attribute).

     LDAP_INVALID_CREDENTIALS

                         Invalid   credentials   were   presented

                         (e.g., the wrong password).

     LDAP_INSUFFICIENT_ACCESS

                         The user has insufficient access to per-

                         form the operation.

     LDAP_BUSY           The DSA is busy.

     LDAP_UNAVAILABLE    The DSA is unavailable.

     LDAP_UNWILLING_TO_PERFORM

                         The DSA  is  unwilling  to  perform  the

                         operation.

     LDAP_LOOP_DETECT    A loop was detected.

     LDAP_NAMING_VIOLATION

                         A naming violation occurred.

     LDAP_OBJECT_CLASS_VIOLATION

                         An  object  class   violation   occurred

                         (e.g.,  a  "must"  attribute was missing

                         from the entry).

     LDAP_NOT_ALLOWED_ON_NONLEAF

                         The  operation  is  not  allowed  on   a

November                 Last change: 15                        3

LDAP_ERROR(3)                 1994                  LDAP_ERROR(3)

                         nonleaf object.

     LDAP_NOT_ALLOWED_ON_RDN

                         The operation is not allowed on an RDN.

     LDAP_ALREADY_EXISTS The entry already exists.

     LDAP_NO_OBJECT_CLASS_MODS

                         Object  class  modifications   are   not

                         allowed.

     LDAP_OTHER          An unknown error occurred.

     LDAP_SERVER_DOWN    The LDAP library can't contact the  LDAP

                         server.

     LDAP_LOCAL_ERROR    Some local error occurred.  This is usu-

                         ally a failed malloc.

     LDAP_ENCODING_ERROR An error was encountered encoding param-

                         eters to send to the LDAP server.

     LDAP_DECODING_ERROR An  error  was  encountered  decoding  a

                         result from the LDAP server.

     LDAP_TIMEOUT        A timelimit was exceeded  while  waiting

                         for a result.

     LDAP_AUTH_UNKNOWN   The authentication method  specified  to

                         ldap_bind() is not known.

     LDAP_FILTER_ERROR   An  invalid  filter  was   supplied   to

                         ldap_search()      (e.g.,     unbalanced

                         parentheses).

     LDAP_PARAM_ERROR    An ldap routine was called  with  a  bad

                         parameter  (e.g.,  a  NULL  ld  pointer,

                         etc.).

     LDAP_NO_MEMORY      An memory allocation  (e.g.,  malloc(3))

                         call failed in an ldap library routine.

SEE ALSO

     ldap(3), perror(3)

November                 Last change: 15                        4


ldap_first_attribute
LDAP_FIRST_ATTRIBUTE (3)       1994        LDAP_FIRST_ATTRIBUTE(3)

NAME

     ldap_first_attribute,  ldap_next_attribute  -  step  through

     LDAP entry attributes

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     char *ldap_first_attribute(ld, entry, berptr)

     LDAP *ld;

     LDAPMessage *entry;

     BerElement **berptr;

     char *ldap_next_attribute(ld, entry, ber)

     LDAP *ld;

     LDAPMessage *entry;

     BerElement *ber;

DESCRIPTION

     The ldap_first_attribute()  and  ldap_next_attribute()  rou-

     tines  are  used  to  step through the attributes in an LDAP

     entry.  ldap_first_attribute() takes an _e_n_t_r_y as returned by

     ldap_first_entry(3)  or  ldap_next_entry(3)  and  returns  a

     pointer to a  per-connection  buffer  containing  the  first

     attribute  type  in  the  entry.  The return value should be

     treated as if it is  a  pointer  to  a  static  area  (i.e.,

     strdup(3) it if you want to save it).

     It also returns, in _b_e_r_p_t_r, a pointer to a BerElement it has

     allocated  to  keep  track  of  its  current position.  This

     pointer  should   be   passed   to   subsequent   calls   to

     ldap_next_attribute()  and  is used used to effectively step

     through the entry's attributes.  This pointer  is  freed  by

     ldap_next_attribute()  when  there  are  no  more attributes

     (that is, when ldap_next_attribute() returns NULL).   Other-

     wise,  the  caller is responsible for freeing the BerElement

     pointed to by _b_e_r_p_t_r when it is no longer needed by  calling

     ber_free(3).   When calling ber_free(3) in this instance, be

     sure the second argument is 0.

     The attribute names returned are suitable for inclusion in a

     call  to  ldap_get_values(3)  to  retrieve  the  attribute's

     values.

ERRORS

     If an error occurs, NULL is returned and the ld_errno  field

     in  the  _l_d  parameter  is  set  to indicate the error.  See

     ldap_error(3) for a description of possible error codes.

NOTES

     The ldap_first_attribute() routine mallocs memory  that  may

     need to be freed by the caller via ber_free(3).

November                 Last change: 25                        1

LDAP_FIRST_ATTRIBUTE(3)       1994        LDAP_FIRST_ATTRIBUTE(3)

SEE ALSO

     ldap(3),      ldap_first_entry(3),       ldap_get_values(3),

     ldap_error(3)

November                 Last change: 25                        2


ldap_first_entry
LDAP_FIRST_ENTRY (3)           1994            LDAP_FIRST_ENTRY(3)

NAME

     ldap_first_entry, ldap_next_entry, ldap_count_entries - LDAP

     result entry parsing and counting routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     ldap_count_entries(ld, result)

     LDAP *ld;

     LDAPMessage *result;

     LDAPMessage *ldap_first_entry(ld, result)

     LDAP *ld;

     LDAPMessage *result;

     LDAPMessage *ldap_next_entry(ld, entry)

     LDAP *ld;

     LDAPMessage *entry;

DESCRIPTION

     These routines are  used  to  parse  results  received  from

     ldap_result(3) or the synchronous LDAP search operation rou-

     tines ldap_search_s(3) and ldap_search_st(3).

     The ldap_first_entry() routine is used to retrieve the first

     entry  in a chain of search results.  It takes the _r_e_s_u_l_t as

     returned by a call to ldap_result(3) or ldap_search_s(3)  or

     ldap_search_st(3)  and  returns a pointer to the first entry

     in the result.

     This pointer should be supplied  on  a  subsequent  call  to

     ldap_next_entry() to get the next entry, the result of which

     should be supplied to the next  call  to  ldap_next_entry(),

     etc.   ldap_next_entry()  will return NULL when there are no

     more entries.  The entries returned  from  these  calls  are

     used  in  calls to the routines described in ldap_get_dn(3),

     ldap_first_attribute(3), ldap_get_values(3), etc.

     A count of the number of entries in the search result can be

     obtained by calling ldap_count_entries().

ERRORS

     If   an    error    occurs    in    ldap_first_entry()    or

     ldap_next_entry(),  NULL  is returned and the ld_errno field

     in the _l_d parameter is set to indicate  the  error.   If  an

     error  occurs  in  ldap_count_entries(), -1 is returned, and

     ld_errno is set  appropriately.   See  ldap_error(3)  for  a

     description of possible error codes.

SEE ALSO

     ldap(3),           ldap_result(3),           ldap_search(3),

November                 Last change: 25                        1

LDAP_FIRST_ENTRY(3)           1994            LDAP_FIRST_ENTRY(3)

     ldap_first_attribute(3), ldap_get_values(3), ldap_get_dn(3)

November                 Last change: 25                        2


ldap_friendly
LDAP_FRIENDLY (3)              1993               LDAP_FRIENDLY(3)

NAME

     ldap_friendly_name, ldap_free_friendlymap - LDAP  unfriendly

     to friendly name mapping routine

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     typedef struct friendly {

             char *f_unfriendly;

             char *f_friendly;

     } FriendlyMap;

     char *ldap_friendly_name(filename, name, map)

     char *filename;

     char *name;

     FriendlyMap **map;

     void ldap_free_friendlymap(map)

     FriendlyMap **map;

DESCRIPTION

     This routine is used to map one set of strings  to  another.

     Typically,  this  is done for country names, to map from the

     two-letter country codes to longer more readable names.  The

     mechanism  is  general  enough to be used with other things,

     though.

     _f_i_l_e_n_a_m_e is the name of a file containing the unfriendly  to

     friendly  mapping,  _n_a_m_e  is the unfriendly name to map to a

     friendly name, and _m_a_p is a result-parameter that should  be

     set  to NULL on the first call.  It is then used to hold the

     mapping in core so that the file need not be read on  subse-

     quent calls.

     For example:

             FriendlyMap *map = NULL;

             printf( "unfriendly %s => friendly %s\n", name,

                 ldap_friendly_name( "ETCDIR/ldapfriendly", name, &map ) );

     The  mapping  file   should   contain   lines   like   this:

     unfriendlyname\tfriendlyname.   Lines  that begin with a '#'

     character are comments and are ignored.

     The ldap_free_friendlymap() call is used to free  structures

     allocated  by  ldap_friendly_name()  when  no  more calls to

     ldap_friendly_name() are to be made.

ERRORS

     NULL is returned by  ldap_friendly_name()  if  there  is  an

October                  Last change: 11                        1

LDAP_FRIENDLY(3)              1993               LDAP_FRIENDLY(3)

     error  opening _f_i_l_e_n_a_m_e, or if the file has a bad format, or

     if the _m_a_p parameter is NULL.

FILES

     ETCDIR/ldapfriendly.conf

SEE ALSO

     ldap(3)

October                  Last change: 11                        2


ldap_get_dn
LDAP_GET_DN (3)                1995                 LDAP_GET_DN(3)

NAME

     ldap_get_dn, ldap_explode_dn,  ldap_dn2ufn,  ldap_is_dns_dn,

     ldap_explode_dns - LDAP DN handling routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     char *ldap_get_dn(ld, entry)

     LDAP *ld;

     LDAPMessage *entry;

     char **ldap_explode_dn(dn, notypes)

     char *dn;

     int notypes;

     char *ldap_dn2ufn(dn)

     char *dn;

     int ldap_is_dns_dn(dn)

     char *dn;

     char **ldap_explode_dns(dn)

     char *dn;

DESCRIPTION

     These routines allow LDAP entry names (Distinguished  Names,

     or DNs) to be obtained, parsed, converted to a user-friendly

     form, and tested.  A DN has the form described in  RFC  1779

     "A  String Representation of Distinguished Names", unless it

     is an experimental DNS-style DN which takes the form  of  an

     RFC 822 mail address.

     The ldap_get_dn() routine takes  an  _e_n_t_r_y  as  returned  by

     ldap_first_entry(3) or ldap_next_entry(3) and returns a copy

     of the entry's DN.  Space for the DN will have been obtained

     via  malloc(3),  and should be freed by the caller by a call

     to free(3).

     The ldap_explode_dn() routine takes  a  DN  as  returned  by

     ldap_get_dn()  and  breaks  it  up into its component parts.

     Each part is known as a Relative Distinguished Name, or RDN.

     ldap_explode_dn() returns a NULL-terminated array, each com-

     ponent of which contains an RDN from the  DN.   The  _n_o_t_y_p_e_s

     parameter  is  used  to  request that only the RDN values be

     returned, not their types.  For  example,  the  DN  "cn=Bob,

     c=US" would return as either { "cn=Bob", "c=US", NULL } or {

     "Bob", "US", NULL }, depending on whether notypes was  0  or

     1,  respectively.   The  result  can  be  freed  by  calling

     ldap_value_free(3).

June                     Last change: 16                        1

LDAP_GET_DN(3)                1995                 LDAP_GET_DN(3)

     ldap_dn2ufn()  is  used  to  turn  a  DN  as   returned   by

     ldap_get_dn()  into a more user-friendly form, stripping off

     type names.  See RFC 1781 "Using the  Directory  to  Achieve

     User  Friendly  Naming"  for more details on the UFN format.

     The space for the UFN returned is obtained by a call to mal-

     loc(3),  and  the  user  is responsible for freeing it via a

     call to free(3).

     ldap_is_dns_dn() returns non-zero if the  dn  string  is  an

     experimental  DNS-style  DN (generally in the form of an RFC

     822 e-mail address).  It returns zero if the dn  appears  to

     be an RFC 1779 format DN.

     ldap_explode_dns() takes a DNS-style DN  and  breaks  it  up

     into  its  component  parts.   ldap_explode_dns()  returns a

     NULL-terminated array.  For example, the DN  "mcs.umich.edu"

     will return { "mcs", "umich", "edu", NULL }.  The result can

     be freed by calling ldap_value_free(3).

ERRORS

     If an error occurs in ldap_get_dn(), NULL  is  returned  and

     the  ld_errno  field  in the _l_d parameter is set to indicate

     the error.  See ldap_error(3) for a description of  possible

     error   codes.   ldap_explode_dn(),  ldap_explode_dns()  and

     ldap_dn2ufn() will return NULL with errno(3)  set  appropri-

     ately in case of trouble.

NOTES

     These routines malloc memory that the caller must free.

SEE ALSO

     ldap(3),         ldap_first_entry(3),         ldap_error(3),

     ldap_value_free(3)

June                     Last change: 16                        2


ldap_get_values
LDAP_GET_VALUES (3)            1994             LDAP_GET_VALUES(3)

NAME

     ldap_get_values,  ldap_get_values_len,  ldap_count_values  -

     LDAP attribute value handling routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     typedef struct berval {

         unsigned long bv_len;

         char *bv_val;

     };

     char **ldap_get_values(ld, entry, attr)

     LDAP *ld;

     LDAPMessage *entry;

     char *attr

     struct berval **ldap_get_values_len(ld, entry, attr)

     LDAP *ld;

     LDAPMessage *entry;

     char *attr

     ldap_count_values(vals)

     char **vals;

     ldap_count_values_len(vals)

     struct berval **vals;

     ldap_value_free(vals)

     char **vals;

     ldap_value_free_len(vals)

     struct berval **vals;

DESCRIPTION

     These routines are used to retrieve and manipulate attribute

     values from an LDAP entry as returned by ldap_first_entry(3)

     or ldap_next_entry(3).  ldap_get_values()  takes  the  _e_n_t_r_y

     and  the attribute _a_t_t_r whose values are desired and returns

     a NULL-terminated array of the attribute's values.  _a_t_t_r may

     be     an     attribute     type     as     returned    from

     ldap_first_attribute(3) or ldap_next_attribute(3), or if the

     attribute type is known it can simply be given.

     The number of values in the array can be counted by  calling

     ldap_count_values().   The  array  of values returned can be

     freed by calling ldap_value_free().

     If the attribute values are binary in nature, and  thus  not

     suitable  to  be  returned  as  an  array  of  char *'s, the

     ldap_get_values_len() routine can be used instead.  It takes

November                 Last change: 25                        1

LDAP_GET_VALUES(3)            1994             LDAP_GET_VALUES(3)

     the  same  parameters  as  ldap_get_values(),  but returns a

     NULL-terminated array of pointers to berval structures, each

     containing the length of and a pointer to a value.

     The number of values in the array can be counted by  calling

     ldap_count_values_len().   The  array of values returned can

     be freed by calling ldap_value_free_len().

ERRORS

     If    an    error    occurs    in    ldap_get_values()    or

     ldap_get_values_len(),  NULL  is  returned  and the ld_errno

     field in the _l_d parameter is set to indicate the error.  See

     ldap_error(3) for a description of possible error codes.

NOTES

     These routines malloc memory that the caller must free.

SEE ALSO

     ldap(3),    ldap_first_entry(3),    ldap_first_attribute(3),

     ldap_error(3)

November                 Last change: 25                        2


ldap_getfilter
LDAP_GETFILTER (3)             1994              LDAP_GETFILTER(3)

NAME

     ldap_init_getfilter,                ldap_init_getfilter_buf,

     ldap_getfilter_free,                    ldap_getfirstfilter,

     ldap_getnextfilter, ldap_build_filter - LDAP filter generat-

     ing routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     #define LDAP_FILT_MAXSIZ 1024

     typedef struct ldap_filt_info {

             char                    *lfi_filter;

             char                    *lfi_desc;

             int                     lfi_scope;

             int                     lfi_isexact;

             struct ldap_filt_info   *lfi_next;

     } LDAPFiltInfo;

     typedef struct ldap_filt_list {

         char                        *lfl_tag;

         char                        *lfl_pattern;

         char                        *lfl_delims;

         LDAPFiltInfo                *lfl_ilist;

         struct ldap_filt_list       *lfl_next;

     } LDAPFiltList;

     typedef struct ldap_filt_desc {

             LDAPFiltList            *lfd_filtlist;

             LDAPFiltInfo            *lfd_curfip;

             LDAPFiltInfo            lfd_retfi;

             char                    lfd_filter[ LDAP_FILT_MAXSIZ ];

             char                    *lfd_curval;

             char                    *lfd_curvalcopy;

             char                    **lfd_curvalwords;

             char                    *lfd_filtprefix;

             char                    *lfd_filtsuffix;

     } LDAPFiltDesc;

     LDAPFiltDesc *ldap_init_getfilter( file ) char *file;

     LDAPFiltDesc *ldap_init_getfilter_buf( buf, buflen )

     char *buf;

     long buflen;

     ldap_getfilter_free( lfdp )

     LDAPFiltDesc *lfdp;

     LDAPFiltInfo *ldap_getfirstfilter(lfdp, tagpat, value)

     LDAPFiltDesc *lfdp;

     char *tagpat;

November                 Last change: 28                        1

LDAP_GETFILTER(3)             1994              LDAP_GETFILTER(3)

     char *value;

     LDAPFiltInfo *ldap_getnextfilter(lfdp)

     LDAPFiltDesc *lfdp;

     void ldap_setfilteraffixes(lfdp, prefix, suffix)

     LDAPFiltDesc *lfdp;

     char *prefix;

     char *suffix;

     void ldap_build_filter( buf, buflen, pattern, prefix, suffix,

          attr, value, valwords )

     char *buf;

     unsigned long buflen;

     char *pattern;

     char *prefix;

     char *suffix;

     char *attr;

     char *value;

     char **valwords;

DESCRIPTION

     These routines are used to generate filters to  be  used  in

     ldap_search(3)       or       ldap_search_s(3).       Either

     ldap_init_getfilter  or  ldap_init_getfilter_buf   must   be

     called  prior  to  calling  any of the other routines except

     ldap_build_filter.

     ldap_init_getfilter() takes a file name as  its  only  argu-

     ment.   The contents of the file must be a valid LDAP filter

     configuration file (see ldapfilter.conf(5)).  If the file is

     successfully read, a pointer to an LDAPFiltDesc is returned.

     This is an opaque object that is passed  in  subsequent  get

     filter calls.

     ldap_init_getfilter_buf() reads from _b_u_f  (whose  length  is

     _b_u_f_l_e_n) the LDAP filter configuration information.  _b_u_f must

     point to the contents of a valid LDAP  filter  configuration

     file  (see ldapfilter.conf(5)).  If the filter configuration

     information is successfully read,  a  pointer  to  an  LDAP-

     FiltDesc  is  returned.   This  is  an opaque object that is

     passed in subsequent get filter calls.

     ldap_getfilter_free() deallocates  the  memory  consumed  by

     ldap_init_getfilter.  Once it is called, the LDAPFiltDesc is

     no longer valid and cannot be used again.

     ldap_getfirstfilter() retrieves the  first  filter  that  is

     appropriate  for _v_a_l_u_e. Only filter sets that have tags that

     match  the  regular   expession   _t_a_g_p_a_t   are   considered.

     ldap_getfirstfilter  returns  a  pointer  to an LDAPFiltInfo

     structure, which contains a filter with  _v_a_l_u_e  inserted  as

November                 Last change: 28                        2

LDAP_GETFILTER(3)             1994              LDAP_GETFILTER(3)

     appropriate  in  lfi_filter,  a  text  match  description in

     lfi_desc, lfi_scope set to indicate the  search  scope,  and

     lfi_isexact  set  to  indicate  the type of filter.  NULL is

     returned if no matching filters are found.   lfi_scope  will

     be   one   of   LDAP_SCOPE_BASE,   LDAP_SCOPE_ONELEVEL,   or

     LDAP_SCOPE_SUBTREE. lfi_isexact will be zero if  the  filter

     has any '~' or '*' characters in it and non-zero otherwise.

     ldap_getnextfilter() retrieves the next  appropriate  filter

     in    the    filter    set    that   was   determined   when

     ldap_getfirstfilter was called.  It returns  NULL  when  the

     list has been exhausted.

     ldap_setfilteraffixes() sets a _p_r_e_f_i_x to be prepended and  a

     _s_u_f_f_i_x to be appended to all filters returned in the future.

     ldap_build_filter() constructs an LDAP search filter in _b_u_f.

     _b_u_f_l_e_n  is the size, in bytes, of the largest filter _b_u_f can

     hold.  A pattern for the desired filter is  passed  in  _p_a_t_-

     _t_e_r_n.  Where  the  string  %a  appears  in the pattern it is

     replaced with _a_t_t_r. _p_r_e_f_i_x is pre-pended  to  the  resulting

     filter,  and  _s_u_f_f_i_x  is  appended.   Either can be NULL (in

     which case they are not used).  _v_a_l_u_e and _v_a_l_w_o_r_d_s are  used

     when    the    string    %v    appears   in   _p_a_t_t_e_r_n.   See

     ldapfilter.conf(5) for a description of how %v is handled.

ERRORS

     NULL is returned by ldap_init_getfilter if there is an error

     reading  _f_i_l_e.  NULL  is returned by ldap_getfirstfilter and

     ldap_getnextfilter  when  there  are  no  more   appropriate

     filters to return.

NOTES

     The return values for all of these functions are declared in

     the <ldap.h> header file.  Some routines may malloc memory.

FILES

     ETCDIR/ldapfilter.conf

SEE ALSO

     ldap(3), ldapfilter.conf(5)

November                 Last change: 28                        3


ldap_modify
LDAP_MODIFY (3)                1994                 LDAP_MODIFY(3)

NAME

     ldap_modify, ldap_modify_s - Perform an LDAP  modify  opera-

     tion

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_modify(ld, dn, mods)

     LDAP *ld;

     char *dn;

     LDAPMod *mods[];

     int ldap_modify_s(ld, dn, mods)

     LDAP *ld;

     char *dn;

     LDAPMod *mods[];

     void ldap_mods_free( mods, freemods )

     LDAPMod **mods;

     int freemods;

DESCRIPTION

     The routine ldap_modify_s()  is  used  to  perform  an  LDAP

     modify  operation.  _d_n is the DN of the entry to modify, and

     _m_o_d_s is a null-terminated array of modifications to make  to

     the  entry.   Each element of the _m_o_d_s array is a pointer to

     an LDAPMod structure, which is defined below.

          typedef struct ldapmod {

              int mod_op;

              char *mod_type;

              union {

               char **modv_strvals;

               struct berval **modv_bvals;

              } mod_vals;

              struct ldapmod *mod_next;

          } LDAPMod;

          #define mod_values mod_vals.modv_strvals

          #define mod_bvalues mod_vals.modv_bvals

     The _m_o_d__o_p field is used to specify the type of modification

     to    perform   and   should   be   one   of   LDAP_MOD_ADD,

     LDAP_MOD_DELETE,  or  LDAP_MOD_REPLACE.   The  _m_o_d__t_y_p_e  and

     _m_o_d__v_a_l_u_e_s fields specify the attribute type to modify and a

     null-terminated array of values to add, delete,  or  replace

     respectively.   The  _m_o_d__n_e_x_t field is used only by the LDAP

     server and may be ignored by the client.

     If you need to specify a non-string value (e.g.,  to  add  a

     photo  or  audio  attribute value), you should set _m_o_d__o_p to

     the  logical  OR  of   the   operation   as   above   (e.g.,

November                 Last change: 15                        1

LDAP_MODIFY(3)                1994                 LDAP_MODIFY(3)

     LDAP_MOD_REPLACE)  and  the  constant  LDAP_MOD_BVALUES.  In

     this case, _m_o_d__b_v_a_l_u_e_s should be used instead of _m_o_d__v_a_l_u_e_s,

     and  it  should  point  to a null-terminated array of struct

     bervals, as defined in <lber.h>.

     For LDAP_MOD_ADD modifications, the given values  are  added

     to  the  entry,  creating  the  attribute if necessary.  For

     LDAP_MOD_DELETE modifications, the given values are  deleted

     from  the entry, removing the attribute if no values remain.

     If the entire attribute is to  be  deleted,  the  _m_o_d__v_a_l_u_e_s

     field should be set to NULL.  For LDAP_MOD_REPLACE modifica-

     tions, the attribute will have the listed values  after  the

     modification, having been created if necessary.  All modifi-

     cations are performed in the order in which they are listed.

     ldap_modify_s() returns the LDAP error code  resulting  from

     the  modify  operation.   This  code  can  be interpreted by

     ldap_perror(3) and friends.

     The  ldap_modify()  operation  works   the   same   way   as

     ldap_modify_s(),  except  that it is asynchronous, returning

     the message id of the request it initiates, or -1 on  error.

     The  result  of  the  operation  can  be obtained by calling

     ldap_result(3).

     ldap_mods_free() can be used  to  free  each  element  of  a

     NULL-terminated  array  of  mod  structures.  If _f_r_e_e_m_o_d_s is

     non-zero, the _m_o_d_s pointer itself is freed as well.

ERRORS

     ldap_modify_s()  returns  an   ldap   error   code,   either

     LDAP_SUCCESS   or   an   error   if   there   was   trouble.

     ldap_modify() returns -1 in case  of  trouble,  setting  the

     ld_errno field of _l_d.

SEE ALSO

     ldap(3), ldap_error(3), ldap_add(3)

November                 Last change: 15                        2


ldap_modrdn
LDAP_MODRDN (3)                1994                 LDAP_MODRDN(3)

NAME

     ldap_modrdn, ldap_modrdn_s, ldap_modrdn2,  ldap_modrdn2_s  -

     Perform an LDAP modify RDN operation

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_modrdn(ld, dn, newrdn)

     LDAP *ld;

     char *dn, *newrdn;

     int ldap_modrdn_s(ld, dn, newrdn)

     LDAP *ld;

     char *dn, *newrdn;

     int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn)

     LDAP *ld;

     char *dn, *newrdn;

     int deleteoldrdn;

     int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn)

     LDAP *ld;

     char *dn, *newrdn;

     int deleteoldrdn;

DESCRIPTION

     The ldap_modrdn() and ldap_modrdn_s()  routines  perform  an

     LDAP modify RDN operation.  They both take _d_n, the DN of the

     entry whose RDN is to be changed, and _n_e_w_r_d_n, the new RDN to

     give  the  entry.  The old RDN of the entry is never kept as

     an attribute of the entry.  ldap_modrdn()  is  asynchronous,

     returning  the  message  id  of  the operation it initiates.

     ldap_modrdn_s() is synchronous,  returning  the  LDAP  error

     code  indicating  the  success  or failure of the operation.

     Use of these  routines  is  deprecated.   Use  the  versions

     described below instead.

     The ldap_modrdn2() and ldap_modrdn2_s() routines  also  per-

     form  an  LDAP modify RDN operation, taking the same parame-

     ters as above.  In addition, they both take the _d_e_l_e_t_e_o_l_d_r_d_n

     parameter  which  is  used  as  a  boolean value to indicate

     whether the old RDN values should be deleted from the  entry

     or not.

ERRORS

     The synchronous (_s) versions of these  routines  return  an

     LDAP  error  code,  either LDAP_SUCCESS or an error if there

     was trouble.  The asynchronous versions return -1 in case of

     trouble,   setting   the   ld_errno   field   of   _l_d.   See

     ldap_error(3) for more details.

December                 Last change: 1                         1

LDAP_MODRDN(3)                1994                 LDAP_MODRDN(3)

SEE ALSO

     ldap(3), ldap_error(3)

December                 Last change: 1                         2


ldap_open
LDAP_OPEN (3)                  1995                   LDAP_OPEN(3)

NAME

     ldap_init, ldap_open - Initialize the LDAP library and  open

     a connection to an LDAP server

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     LDAP *ldap_open(host, port)

     char *host;

     int port;

     LDAP *ldap_init(host, port)

     char *host;

     int port;

DESCRIPTION

     ldap_open() opens a connection to an LDAP server  and  allo-

     cates  an  LDAP structure which is used to identify the con-

     nection  and   to   maintain   per-connection   information.

     ldap_init() allocates an LDAP structure but does not open an

     initial connection.  One  of  these  two  routines  must  be

     called before any operations are attempted.

     ldap_open() takes _h_o_s_t,  the  hostname  on  which  the  LDAP

     server  is  running,  and  _p_o_r_t, the port number to which to

     connect.  If  the  default  IANA-assigned  port  of  389  is

     desired,  LDAP_PORT  should be specified for _p_o_r_t.  The _h_o_s_t

     parameter may contain a blank-separated list of hosts to try

     to  connect  to, and each host may optionally by of the form

     _h_o_s_t:_p_o_r_t.  If present, the :_p_o_r_t overrides the _p_o_r_t parame-

     ter  to  ldap_open().  Upon successfully making a connection

     to an LDAP server, ldap_open() returns a pointer to an  LDAP

     structure  (defined below), which should be passed to subse-

     quent calls  to  ldap_bind(),  ldap_search(),  etc.  Certain

     fields  in  the  LDAP  structure can be set to indicate size

     limit, time limit, and how aliases are handled during opera-

     tions.  See <ldap.h> for more details.

          typedef struct ldap {

               /* ... other stuff you should not mess with ... */

               char      ld_lberoptions;

               int       ld_deref;

          #define LDAP_DEREF_NEVER 0

          #define LDAP_DEREF_SEARCHING  1

          #define LDAP_DEREF_FINDING    2

          #define LDAP_DEREF_ALWAYS     3

               int       ld_timelimit;

               int       ld_sizelimit;

          #define LDAP_NO_LIMIT         0

               int       ld_errno;

               char      *ld_error;

November                 Last change: 11                        1

LDAP_OPEN(3)                  1995                   LDAP_OPEN(3)

               char      *ld_matched;

               int       ld_refhoplimit;

               unsigned long  ld_options;

          #define LDAP_OPT_REFERRALS      0x00000002

               /* ... other stuff you should not mess with ... */

          } LDAP;

     ldap_init() acts just like ldap_open(), but does not open  a

     connection  to  the LDAP server.  The actual connection open

     will occur when the first operation is attempted.   At  this

     time, ldap_init() should only be used if the LDAP library is

     compiled with LDAP_REFERRALS defined.

ERRORS

     If an error occurs, these  routines  will  return  NULL  and

     errno should be set appropriately.

NOTES

     There are other elements in  the  LDAP  structure  that  you

     should not change. You should not make any assumptions about

     the order of elements in the LDAP structure.

SEE ALSO

     ldap(3), ldap_bind(3), errno(3)

November                 Last change: 11                        2


ldap_result
LDAP_RESULT (3)                1994                 LDAP_RESULT(3)

NAME

     ldap_result - Wait for the result of an LDAP operation

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_result(ld, msgid, all, timeout, result)

     LDAP *ld;

     int msgid, all;

     struct timeval *timeout;

     LDAPMessage **result;

     int ldap_msgfree(msg)

     LDAPMessage *msg;

DESCRIPTION

     The ldap_result() routine is used to wait for and return the

     result  of  an  operation previously initiated by one of the

     LDAP asynchronous operation routines (e.g.,  ldap_search(3),

     ldap_modify(3), etc.).  Those routines all return -1 in case

     of error, and an invocation identifier upon successful  ini-

     tiation  of  the  operation.  The  invocation  identifier is

     picked by the library and is guaranteed to be unique  across

     the LDAP session.  It can be used to request the result of a

     specific operation  from  ldap_result()  through  the  _m_s_g_i_d

     parameter.

     The ldap_result() routine will block or not, depending  upon

     the  setting  of the _t_i_m_e_o_u_t parameter.  If timeout is not a

     NULL pointer,  it  specifies  a  maximum interval   to  wait

     for  the  selection  to  complete.   If  timeout  is  a NULL

     pointer,  the  select  blocks  indefinitely.   To effect   a

     poll,   the   timeout argument should be a non-NULL pointer,

     pointing to a zero-valued timeval structure.  (see select(2)

     for further details).

     If the result of a specific  operation  is  required,  _m_s_g_i_d

     should be set to the invocation identifier returned when the

     operation was initiated, otherwise  LDAP_RES_ANY  should  be

     supplied.   The  _a_l_l  parameter  only has meaning for search

     responses and is used to select whether a  single  entry  of

     the  search  response  should be returned, or all results of

     the search should be returned.

     A search response is made up of zero or more search  entries

     followed  by  a  search  result.  If _a_l_l is set to 0, search

     entries will be returned one at a time as they come in,  via

     separate  calls  to  ldap_result().   If  it's set to 1, the

     search response will only be returned in its entirety, i.e.,

     after  all  entries  and  the  final search result have been

     received.

November                 Last change: 26                        1

LDAP_RESULT(3)                1994                 LDAP_RESULT(3)

     Upon success, the type of the result  received  is  returned

     and  the  _r_e_s_u_l_t  parameter  will  contain the result of the

     operation.  This result should be passed to the LDAP parsing

     routines,  ldap_first_entry(3)  and friends, for interpreta-

     tion.

     The possible result types returned are:

          #define LDAP_RES_BIND              0x61L

          #define LDAP_RES_SEARCH_ENTRY      0x64L

          #define LDAP_RES_SEARCH_RESULT          0x65L

          #define LDAP_RES_MODIFY            0x67L

          #define LDAP_RES_ADD               0x69L

          #define LDAP_RES_DELETE            0x6bL

          #define LDAP_RES_MODRDN            0x6dL

          #define LDAP_RES_COMPARE      0x6fL

     The ldap_msgfree() routine is used to free the memory  allo-

     cated  for a result by ldap_result() or ldap_search_s(3) and

     friends.  It takes a pointer to the result to be  freed  and

     returns the type of the message it freed.

ERRORS

     ldap_result() returns -1 if something bad happens, and  zero

     if the timeout specified was exceeded.

NOTES

     This routine mallocs memory for results  that  it  receives.

     The memory can be freed by calling ldap_msgfree.

SEE ALSO

     ldap(3), ldap_search(3), select(2)

November                 Last change: 26                        2


ldap_search
LDAP_SEARCH (3)                1994                 LDAP_SEARCH(3)

NAME

     ldap_search, ldap_search_s, ldap_search_st - Perform an LDAP

     search operation

SYNOPSIS

     #include <sys/time.h> /* for struct timeval definition */

     #include <lber.h>

     #include <ldap.h>

     int ldap_search(ld, base, scope, filter, attrs, attrsonly)

     LDAP *ld;

     char *base;

     int scope;

     char *filter, *attrs[];

     int attrsonly;

     int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)

     LDAP *ld;

     char *base;

     int scope;

     char *filter, *attrs[]

     int attrsonly;

     LDAPMessage **res;

     int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)

     LDAP *ld;

     char *base;

     int scope;

     char *filter, *attrs[]

     int attrsonly;

     struct timeval *timeout;

     LDAPMessage **res;

DESCRIPTION

     These routines are used to perform LDAP  search  operations.

     ldap_search_s()  does  the  search  synchronously (i.e., not

     returning until the operation completes).   ldap_search_st()

     does  the  same,  but  allows  a  _t_i_m_e_o_u_t  to  be specified.

     ldap_search() is the asynchronous  version,  initiating  the

     search and returning the message id of the operation it ini-

     tiated.  _B_a_s_e is the DN of the entry at which to  start  the

     search.   _S_c_o_p_e is the scope of the search and should be one

     of   LDAP_SCOPE_BASE,   to   search   the   object   itself,

     LDAP_SCOPE_ONELEVEL,  to search the object's immediate chil-

     dren, or LDAP_SCOPE_SUBTREE, to search the  object  and  all

     its descendents.

     _F_i_l_t_e_r is a string representation of the filter to apply  in

     the   search.    Simple   filters   can   be   specified  as

     _a_t_t_r_i_b_u_t_e_t_y_p_e=_a_t_t_r_i_b_u_t_e_v_a_l_u_e.   More  complex  filters   are

     specified using a prefix notation according to the following

     BNF:

November                 Last change: 23                        1

LDAP_SEARCH(3)                1994                 LDAP_SEARCH(3)

             <filter> ::= '(' <filtercomp> ')'

             <filtercomp> ::= <and> | <or> | <not> | <simple>

             <and> ::= '&' <filterlist>

             <or> ::= '|' <filterlist>

             <not> ::= '!' <filter>

             <filterlist> ::= <filter> | <filter> <filterlist>

             <simple> ::= <attributetype> <filtertype> <attributevalue>

             <filtertype> ::= '=' | '~=' | '<=' | '>='

     The '~=' construct is used to specify approximate  matching.

     The  representation for <attributetype> and <attributevalue>

     are as described in RFC 1778.  In addition, <attributevalue>

     can be a single * to achieve an attribute existence test, or

     can contain text and *'s interspersed to  achieve  substring

     matching.

     For example, the filter "mail=*" will find any entries  that

     have       a      mail      attribute.       The      filter

     "mail=*@terminator.rs.itd.umich.edu" will find  any  entries

     that  have  a mail attribute ending in the specified string.

     To put parentheses in a filter, escape them with a backslash

     '\' character.  See RFC 1588 for a more complete description

     of allowable filters.  See ldap_getfilter(3) for routines to

     help in constructing search filters automatically.

     _A_t_t_r_s is a  null-terminated  array  of  attribute  types  to

     return  from  entries  that match _f_i_l_t_e_r.  If NULL is speci-

     fied, all attributes will be returned.  _A_t_t_r_s_o_n_l_y should  be

     set  to  1 if only attribute types are wanted.  It should be

     set to 0 if both attributes types and attribute  values  are

     wanted.

ERRORS

     ldap_search_s() and ldap_search_st() will  return  the  LDAP

     error   code  resulting  from  the  search  operation.   See

     ldap_error(3) for details.  ldap_search() returns -1 in case

     of trouble.

NOTES

     Note that both read and list functionality are  subsumed  by

     these routines, by using a filter like "objectclass=*" and a

     scope   of   LDAP_SCOPE_BASE   (to    emulate    read)    or

     LDAP_SCOPE_ONELEVEL (to emulate list).

     These routines may malloc memory.  Return  values  are  con-

     tained in <ldap.h>.

SEE ALSO

     ldap(3), ldap_result(3), ldap_getfilter(3), ldap_error(3)

November                 Last change: 23                        2


ldap_searchprefs
SEARCHPREFS (3)                1994                 SEARCHPREFS(3)

NAME

     ldap_init_searchprefs,            ldap_init_searchprefs_buf,

     ldap_free_searchprefs,                 ldap_first_searchobj,

     ldap_next_searchobj - LDAP search  preference  configuration

     routeines

SYNOPSIS

     #include <srchpref.h>

     struct ldap_searchattr {

          char                *sa_attrlabel;

          char                *sa_attr;

                              /* max 32 matchtypes for now */

          u_long                   sa_matchtypebitmap;

          char                *sa_selectattr;

          char                *sa_selecttext;

          struct ldap_searchattr        *sa_next;

     };

     struct ldap_searchmatch {

          char                *sm_matchprompt;

          char                *sm_filter;

          struct ldap_searchmatch       *sm_next;

     };

     struct ldap_searchobj {

          char                *so_objtypeprompt;

          unsigned long            so_options;

          char                *so_prompt;

          short                    so_defaultscope;

          char                *so_filterprefix;

          char                *so_filtertag;

          char                *so_defaultselectattr;

          char                *so_defaultselecttext;

          struct ldap_searchattr        *so_salist;

          struct ldap_searchmatch       *so_smlist;

          struct ldap_searchobj         *so_next;

     };

     int ldap_init_searchprefs( file, solistp )

          char      *file;

          struct ldap_searchobj    **solistp;

     int ldap_init_searchprefs_buf( buf, buflen, solistp )

          char      *buf;

          unsigned long  len;

          struct ldap_searchobj    **solistp;

     struct ldap_searchobj *ldap_free_searchprefs( solist )

          struct ldap_searchobj    *solist;

June                     Last change: 13                        1

SEARCHPREFS(3)                1994                 SEARCHPREFS(3)

     struct ldap_searchobj *ldap_first_searchobj( solist )

          struct ldap_seachobj     *solist;

     struct ldap_searchobj *ldap_next_searchobj( solist, so )

          struct ldap_searchobj    *solist;

          struct ldap_searchobj    *so;

DESCRIPTION

     These functions provide a standard way to access LDAP search

     preference  configuration data.  LDAP search preference con-

     figurations are typically used by LDAP  client  programs  to

     specify  which  attributes  a user may search by, labels for

     the attributes, and LDAP filters and scopes associated  with

     those searches.  Client software presents these choices to a

     user, who can then specify the type of  search  to  be  per-

     formed.

     ldap_init_searchprefs() reads a sequence of  search  prefer-

     ence  configurations from a valid LDAP searchpref configura-

     tion file (see  ldapsearchprefs.conf(5))  _Z_e_r_o  is  returned

     upon  success,  and  _s_o_l_i_s_t_p  is  set  to point to a list of

     search preference data structures.

     ldap_init_searchprefs_buf()  reads  a  sequence  of   search

     preference  configurations  from _b_u_f (whose size is _b_u_f_l_e_n).

     _b_u_f should point to the data in the format  defined  for  an

     LDAP    search    preference    configuration    file   (see

     ldapsearchprefs.conf(5)) _Z_e_r_o is returned upon success,  and

     _s_o_l_i_s_t_p  is set to point to a list of search preference data

     structures.

     ldap_free_searchprefs()  disposes  of  the  data  structures

     allocated by ldap_init_searchprefs().

     ldap_first_searchpref() returns the first search  preference

     data  structure  in the list _s_o_l_i_s_t. The _s_o_l_i_s_t is typically

     obtained by calling ldap_init_searchprefs().

     ldap_next_searchpref() returns the search  preference  after

     _s_o  in  the template list _s_o_l_i_s_t. _A NULL pointer is returned

     if _s_o is the last entry in the list.

ERRORS

     The      init       preferences       functions       return

     LDAP_SEARCHPREF_ERR_VERSION  if  buf  points to data that is

     newer than can be handled,  and  LDAP_SEARCHPREF_ERR_MEM  if

     there is a memory allocation problem.

NOTES

June                     Last change: 13                        2

SEARCHPREFS(3)                1994                 SEARCHPREFS(3)

SEE ALSO

     ldap(3), ldapsearchprefs.conf(5), ldapd(8)

     Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight

     Directory Access Protocol", OSI-DS-26, April 1992.

     Howes, T., Hardcastle-Kille, S., Yeong, W., and Robbins, C.,

     "Lightweight  Directory  Access  Protocol", OSI-DS-26, April

     1992.

     Hardcastle-Kille,  S.,  "A  String  Representation  of  Dis-

     tinguished Names", OSI-DS-23, April 1992.

     Information Processing - Open Systems Interconnection -  The

     Directory,  International  Organization for Standardization.

     International Standard 9594, (1988).

June                     Last change: 13                        3


ldap_sort
LDAP_SORT (3)                  1994                   LDAP_SORT(3)

NAME

     ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp  -

     LDAP sorting routines

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     ldap_sort_entries(ld, chain, attr, cmp)

     LDAP *ld;

     LDAPMessage **chain;

     char *attr;

     int (*cmp)();

     ldap_sort_values(ld, vals, cmp)

     LDAP *ld;

     char **vals;

     int (*cmp)();

     ldap_sort_strcasecmp(a, b)

     char *a;

     char *b;

DESCRIPTION

     These routines are used to sort lists of entries and  values

     retrieved  from an LDAP server.  ldap_sort_entries() is used

     to sort a chain of entries retrieved  from  an  LDAP  search

     call  either  by  DN  or  by some arbitrary attribute in the

     entries.  It takes _l_d, the LDAP  structure,  which  is  only

     used  for  error  reporting,  _c_h_a_i_n,  the list of entries as

     returned by ldap_search_s(3) or ldap_result(3).  _a_t_t_r is the

     attribute to use as a key in the sort or NULL to sort by DN,

     and _c_m_p is the comparison function  to  use  when  comparing

     values  (or  individual DN components if sorting by DN).  In

     this case, _c_m_p should be a function taking two single values

     of  the  _a_t_t_r  to  sort  by, and returning a value less than

     zero, equal to zero, or  greater  than  zero,  depending  on

     whether  the  first  argument  is  less  than,  equal to, or

     greater than the second argument.   The  convention  is  the

     same  as  used by qsort(3), which is called to do the actual

     sorting.

     ldap_sort_values() is used to sort an array of  values  from

     an  entry,  as returned by ldap_get_values(3).  It takes the

     LDAP connection structure _l_d, the array of  values  to  sort

     _v_a_l_s,  and  _c_m_p,  the  comparison function to use during the

     sort.  Note that _c_m_p will be passed a pointer to  each  ele-

     ment  in  the  _v_a_l_s array, so if you pass the normal char **

     for this parameter, _c_m_p should take two char **'s  as  argu-

     ments  (i.e.,  you cannot pass _s_t_r_c_a_s_e_c_m_p or its friends for

     _c_m_p).     You    can,    however,    pass    the    function

     ldap_sort_strcasecmp() for this purpose.

November                 Last change: 14                        1

LDAP_SORT(3)                  1994                   LDAP_SORT(3)

     For example:

          LDAP *ld;

          LDAPMessage *res;

          /* ... call to ldap_search_s(), fill in res, retrieve sn attr ... */

          /* now sort the entries on surname attribute */

          if ( ldap_sort_entries( ld, &res, "sn", ldap_sort_strcasecmp ) != 0 )

               ldap_perror( ld, "ldap_sort_entries" );

NOTES

     The ldap_sort_entries() routine applies the comparison func-

     tion to each value of the attribute in the array as returned

     by a call to ldap_get_values(3), until a mismatch is  found.

     This  works  fine for single-valued attributes, but may pro-

     duce unexpected results for multi-valued  attributes.   When

     sorting  by  DN,  the  comparison  function is applied to an

     exploded version of  the  DN,  without  types.   The  return

     values  for  all  of  these  functions  are  declared in the

     <ldap.h> header file.  Some routines may malloc memory.

SEE ALSO

     ldap(3), ldap_search(3), ldap_result(3), qsort(3)

November                 Last change: 14                        2


ldap_ufn
LDAP_UFN (3)                   1994                    LDAP_UFN(3)

NAME

     ldap_ufn_search_s,  ldap_ufn_search_c,   ldap_ufn_search_ct,

     ldap_ufn_setfilter,  ldap_ufn_setfilter, ldap_ufn_setprefix,

     ldap_ufn_timeout - Perform  an  LDAP  user  friendly  search

     operation

SYNOPSIS

     #include <lber.h>

     #include <ldap.h>

     int ldap_ufn_search_c(ld, ufn, attrs, attrsonly, res, cancelproc,

                    cancelparm)

     LDAP *ld;

     char *ufn;

     char **attrs;

     int attrsonly;

     LDAPMessage **res;

     int (*cancelproc)();

     void *cancelparm;

     int ldap_ufn_search_ct(ld, ufn, attrs, attrsonly, res, cancelproc,

                    cancelparm, tag1, tag2, tag3)

     LDAP *ld;

     char *ufn;

     char **attrs;

     int attrsonly;

     LDAPMessage **res;

     int (*cancelproc)();

     void *cancelparm;

     char *tag1, *tag2, *tag3;

     int ldap_ufn_search_s(ld, ufn, attrs, attrsonly, res)

     LDAP *ld;

     char *ufn;

     char **attrs;

     int attrsonly;

     LDAPMessage **res;

     LDAPFiltDesc *ldap_ufn_setfilter(ld, fname)

     LDAP *ld;

     char *fname;

     void ldap_ufn_setprefix(ld, prefix)

     LDAP *ld;

     char *prefix;

     int ldap_ufn_timeout(tvparam)

     void *tvparam;

DESCRIPTION

     These routines are used to perform LDAP user friendly search

     operations.   ldap_ufn_search_s()  is the simplest form.  It

November                 Last change: 23                        1

LDAP_UFN(3)                   1994                    LDAP_UFN(3)

     does the search synchronously.  It takes _l_d to identify  the

     the LDAP connection.  The _u_f_n parameter is the user friendly

     name for which to search.   The  _a_t_t_r_s,  _a_t_t_r_s_o_n_l_y  and  _r_e_s

     parameters are the same as for ldap_search(3).

     The  ldap_ufn_search_c()  routine  functions  the  same   as

     ldap_ufn_search_s(),  except  that  it  takes  _c_a_n_c_e_l_p_r_o_c, a

     function to call periodicly during the search.  It should be

     a function taking a single void * argument, given by _c_a_l_c_e_l_-

     _p_a_r_m.  If _c_a_n_c_e_l_p_r_o_c returns a non-zero result,  the  search

     will  be  abandoned and no results returned.  The purpose of

     this routine is to provide a way for the search to  be  can-

     celled,  for example, by a user or because some other condi-

     tion occurs.

     The      ldap_ufn_search_ct()      routine      is      like

     ldap_ufn_search_c(), except that it takes three extra param-

     eters.  _t_a_g_1 is passed to the ldap_init_getfilter(3) routine

     when resolving the first component of the UFN.  _t_a_g_2 is used

     when resolving intermediate components.  _t_a_g_3 is  used  when

     resolving  the last component.  By default, the tags used by

     the other UFN search routines during these three  phases  of

     the  search  are  "ufn  first", "ufn intermediate", and "ufn

     last".

     The  ldap_ufn_setfilter()  routine  is  used  to   set   the

     ldapfilter.conf(5)     file     for     use     with     the

     ldap_init_getfilter(3) routine to _f_n_a_m_e.

     The ldap_ufn_setprefix() routine is used to set the  default

     prefix  (actually,  it's  a  suffix) appended to UFNs before

     searhing.  UFNs with fewer than three  components  have  the

     prefix appended first, before searching.  If that fails, the

     UFN is tried with progressively shorter versions of the pre-

     fix, stripping off components.  If the UFN has three or more

     components, it is tried by itself first.  If that  fails,  a

     similar process is applied with the prefix appended.

     The ldap_ufn_timeout() routine is used to  set  the  timeout

     associated  with  ldap_ufn_search_s() searches.  The _t_i_m_e_o_u_t

     parameter should actually be a pointer to a  struct  timeval

     (this  is  so ldap_ufn_timeout() can be used as a cancelproc

     in the above routines).

NOTES

     These routines may malloc memory.  Return  values  are  con-

     tained in <ldap.h>.

SEE ALSO

     gettimeofday(2), ldap(3), ldap_search(3), ldap_getfilter(3),

     ldapfilter.conf(5), ldap_error(3)

November                 Last change: 23                        2