ldap_init_getfilter(3ldap)

1ldap_getfilter(3LDAP)       LDAP Library Functions       ldap_getfilter(3LDAP)
2
3
4

NAME

6       ldap_getfilter, ldap_init_getfilter, ldap_init_getfilter_buf, ldap_get‐
7       filter_free, ldap_getfirstfilter, ldap_getnextfilter, ldap_setfilteraf‐
8       fixes, ldap_build_filter - LDAP filter generating functions
9

SYNOPSIS

11       cc[ flag... ] file... -lldap[ library... ]
12       #include <lber.h>
13       #include <ldap.h>
14       #define LDAP_FILT_MAXSIZ 1024
15
16       LDAPFiltDesc *ldap_init_getfilter(char *file);
17
18
19       LDAPFiltDesc *ldap_init_getfilter_buf(char *buf, long buflen);
20
21
22       ldap_getfilter_free(LDAPFiltDesc *lfdp);
23
24
25       LDAPFiltInfo *ldap_getfirstfilter(LDAPFiltDesc *lfdp, char *tagpat,
26            char *value);
27
28
29       LDAPFiltInfo *ldap_getnextfilter(LDAPFiltDesc *lfdp);
30
31
32       void ldap_setfilteraffixes(LDAPFiltDesc *lfdp, char *prefix,
33            char *suffix);
34
35
36       void ldap_build_filter(char *buf, unsigned long buflen, char *pattern,
37            char *prefix, char *suffix, char *attr, char *value,
38            char **valwords);
39
40

DESCRIPTION

42       These   functions   are   used  to  generate  filters  to  be  used  in
43       ldap_search(3LDAP) or  ldap_search_s(3LDAP). Either   ldap_init_getfil‐
44       ter  or  ldap_init_getfilter_buf must be called prior to calling any of
45       the other functions except  ldap_build_filter.
46
47
48       ldap_init_getfilter() takes a file name as its only argument.  The con‐
49       tents  of  the file must be a valid LDAP filter configuration file (see
50       ldapfilter.conf(4)). If the file is successfully read, a pointer to  an
51       LDAPFiltDesc  is  returned.  This is an opaque object that is passed in
52       subsequent get filter calls.
53
54
55       ldap_init_getfilter_buf() reads from buf, whose length is  buflen,  the
56       LDAP  filter  configuration information. buf must point to the contents
57       of a valid LDAP filter configuration file. See  ldapfilter.conf(4).  If
58       the filter configuration information is successfully read, a pointer to
59       an  LDAPFiltDesc is returned.  This is an opaque object that is  passed
60       in subsequent get filter calls.
61
62
63       ldap_getfilter_free()    deallocates    the    memory    consumed    by
64       ldap_init_getfilter. Once it is called, the  LDAPFiltDesc is no  longer
65       valid and cannot be used again.
66
67
68       ldap_getfirstfilter()  retrieves  the  first filter that is appropriate
69       for value. Only filter sets that  have  tags  that  match  the  regular
70       expession  tagpat are considered. ldap_getfirstfilter returns a pointer
71       to an LDAPFiltInfo  structure,  which  contains  a  filter  with  value
72       inserted  as  appropriate  in   lfi_filter, a text match description in
73       lfi_desc, lfi_scope set to indicate the search scope, and   lfi_isexact
74       set  to  indicate the type of filter.   NULL is returned if no matching
75       filters  are  found.    lfi_scope  will  be  one  of   LDAP_SCOPE_BASE,
76       LDAP_SCOPE_ONELEVEL, or LDAP_SCOPE_SUBTREE. lfi_isexact will be zero if
77       the filter has any '~' or '*' characters in it and non-zero otherwise.
78
79
80       ldap_getnextfilter() retrieves the next appropriate filter in the  fil‐
81       ter  set  that was determined when  ldap_getfirstfilter was called.  It
82       returns  NULL when the list has been exhausted.
83
84
85       ldap_setfilteraffixes() sets a prefix to be prepended and a  suffix  to
86       be appended to all filters returned in the future.
87
88
89       ldap_build_filter()  constructs an LDAP search filter in buf. buflen is
90       the size, in bytes, of the largest filter buf can hold.  A pattern  for
91       the desired filter is passed in pattern. Where the string %a appears in
92       the pattern it is replaced with  attr.  prefix  is  pre-pended  to  the
93       resulting  filter,  and  suffix  is  appended.  Either can be NULL , in
94       which case they are not used. value and  valwords  are  used  when  the
95       string %v appears in pattern. See  ldapfilter.conf(4) for a description
96       of how %v is handled.
97

ERRORS

99       NULL is returned by  ldap_init_getfilter if there is an  error  reading
100       file.  NULL  is  returned by ldap_getfirstfilter and ldap_getnextfilter
101       when there are no more appropriate filters to return.
102

FILES

104       ETCDIR/ldapfilter.conf    LDAP filtering routine configuration file.
105
106

ATTRIBUTES

108       See attributes(5) for a description of the following attributes:
109
110
111
112
113       ┌─────────────────────────────┬─────────────────────────────┐
114       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
115       │Availability                 │SUNWcsl (32-bit)             │
116       │                             │SUNWcslx (64-bit)            │
117       │Interface Stability          │Evolving                     │
118       └─────────────────────────────┴─────────────────────────────┘
119

NOTES

124       The return values for all  of  these  functions  are  declared  in  the
125       <ldap.h> header file.  Some functions may allocate memory which must be
126       freed by the calling application.
127
128
129
130SunOS 5.11                        28 Jan 2002            ldap_getfilter(3LDAP)