---
name: "ldap_init_getfilter"
section: "3"
platform: "linux"
package: "libldap2-dev"
version: "2.0.23-6.3"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/ldap_getfilter"
---

# ldap\_init\_getfilter(3)

LDAP filter generating routines

Part of [ldap\_getfilter(3)](/ldap_getfilter/3.md).

## NAME

ldap\_init\_getfilter, ldap\_init\_getfilter\_buf, ldap\_getfilter\_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;
```

**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)](/ldap_search/3.md) or [ldap\_search\_s(3)](/ldap_search_s/3.md).  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 argument.  The contents of the file must be a valid LDAP filter configuration file (see [ldapfilter.conf(5)](/ldapfilter.conf/5.md)).  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 *buf* (whose length is *buflen)* the LDAP filter configuration information. *buf* must point to the contents of a valid LDAP filter configuration file (see [ldapfilter.conf(5)](/ldapfilter.conf/5.md)).  If the filter configuration 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 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 *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 *valwords* are used when the string %v appears in *pattern.* See [ldapfilter.conf(5)](/ldapfilter.conf/5.md) 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\_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 dynamically allocate memory which the caller must free using the supplied deallocator routines.

## FILES

/etc/ldap/ldapfilter.conf

## SEE ALSO

[**ldap**(3)](/ldap/3.md), [**ldapfilter.conf**(5)](/ldapfilter.conf/5.md)

## ACKNOWLEDGEMENTS

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