ldap_init_getfilter, ldap_init_getfilter_buf, ldap_getfil­
       ter_free,     ldap_getfirstfilter,     ldap_getnextfilter,
       ldap_build_filter - LDAP filter generating routines


SYNOPSIS

       #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;
       char *value;

       LDAPFiltInfo *ldap_getnextfilter(lfdp)
       LDAPFiltDesc *lfdp;

       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_get­
       filter  or ldap_init_getfilter_buf must be called prior to
       calling any of the other routines  except  ldap_build_fil­
       ter.

       ldap_init_getfilter()  takes a file name as its only argu­
       ment.  The contents of the file must be a valid LDAP  fil­
       ter  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 sub­
       sequent get filter calls.

       ldap_init_getfilter_buf() reads from buf (whose length  is
       buflen)  the  LDAP  filter configuration information.  buf
       must point to the contents of a valid LDAP filter configu­
       ration  file (see ldapfilter.conf(5)).  If the filter con­
       figuration information is successfully read, a pointer  to
       an  LDAPFiltDesc  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  value.   Only filter sets that have tags
       that match the regular expession  tagpat  are  considered.
       ldap_getfirstfilter  returns  a pointer to an LDAPFiltInfo
       structure, which contains a filter with value inserted  as
       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  fil­
       ter  has  any  '~'  or  '*'  characters in it and non-zero


       ldap_getnextfilter() retrieves the next appropriate filter
       in  the filter set that was determined when ldap_getfirst­
       filter was called.  It returns NULL when the list has been
       exhausted.

       ldap_setfilteraffixes()  sets a prefix to be prepended and
       a suffix to be appended to all  filters  returned  in  the
       future.

       ldap_build_filter()  constructs  an  LDAP search filter in
       buf.  buflen is the size, in bytes, of the largest  filter
       buf  can hold.  A pattern for the desired filter is passed
       in pattern.  Where the string %a appears in the pattern it
       is  replaced  with  attr.   prefix  is  pre-pended  to the
       resulting filter, and suffix is appended.  Either  can  be
       NULL  (in  which  case they are not used).  value and val­
       words are used when the string %v appears in pattern.  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 file.  NULL is returned by ldap_getfirstfil­
       ter and ldap_getnextfilter when there are no  more  appro­
       priate filters to return.


NOTES

       The  return values for all of these functions are declared
       in the <ldap.h> header file.  Some  routines  may  dynami­
       cally allocate memory which the caller must free using the
       supplied deallocator routines.


FILES

       /etc/openldap/ldapfilter.conf


SEE ALSO

       ldap(3), ldapfilter.conf(5)


ACKNOWLEDGEMENTS

       OpenLDAP is developed and maintained by The OpenLDAP  Pro­
       ject (http://www.openldap.org/).  OpenLDAP is derived from
       University of Michigan LDAP 3.3 Release.


Man(1) output converted with man2html