1ldap(3LDAP) LDAP Library Functions ldap(3LDAP)
2
3
4
6 ldap - Lightweight Directory Access Protocol package
7
9 cc[ flag... ] file... -lldap[ library... ]
10 #include <lber.h>
11 #include <ldap.h>
12
13
15 The Lightweight Directory Access Protocol ("LDAP") package (SUNWlldap)
16 includes various command line LDAP clients and a LDAP client library to
17 provide programmatic access to the LDAP protocol. This man page gives
18 an overview of the LDAP client library functions.
19
20
21 An application might use the LDAP client library functions as follows.
22 The application would initialize a LDAP session with a LDAP server by
23 calling ldap_init(3LDAP). Next, it authenticates to the LDAP server by
24 calling ldap_sasl_bind(3LDAP) and friends. It may perform some LDAP
25 operations and obtain results by calling ldap_search(3LDAP) and
26 friends. To parse the results returned from these functions, it calls
27 ldap_parse_result(3LDAP),ldap_next_entry(3LDAP), and
28 ldap_first_entry(3LDAP) and others. It closes the LDAP session by call‐
29 ing ldap_unbind(3LDAP).
30
31
32 LDAP operations can be either synchronous or asynchronous. By conven‐
33 tion, the names of the sychronous functions end with "_s." For example,
34 a synchronous binding to the LDAP server can be performed by calling
35 ldap_sasl_bind_s(3LDAP). Complete an asynchronous binding with
36 ldap_sasl_bind(3LDAP). All synchronous functions return the actual out‐
37 come of the operation, either LDAP_SUCCESS or an error code. Asynchro‐
38 nous routines provide an invocation identifier which can be used to
39 obtain the result of a specific operation by passing it to thel‐
40 dap_result(3LDAP) function.
41
42 Initializing a LDAP session
43 Initializing a LDAP session involves calling the ldap_init(3LDAP) func‐
44 tion. However, the call does not actually open a connection to the LDAP
45 server. It merely initializes a LDAP structure that represents the ses‐
46 sion. The connection is opened when the first operation is attempted.
47 Unlike ldap_init(), ldap_open(3LDAP) attempts to open a connection with
48 the LDAP server. However, the use of ldap_open() is deprecated.
49
50 Authenticating to a LDAP server
51 The ldap_sasl_bind(3LDAP) and ldap_sasl_bind_s(3LDAP) functions provide
52 general and extensible authenticaton for an LDAP client to a LDAP
53 server. Both use the Simple Authentication Security Layer (SASL). Sim‐
54 plified routines ldap_simple_bind(3LDAP) and ldap_simple_bind_s(3LDAP)
55 use cleartext passwords to bind to the LDAP server. Use of
56 ldap_bind(3LDAP) and ldap_bind_s(3LDAP)(3LDAP) is deprecated.
57
58 Searching a LDAP directory
59 Search for an entry in a LDAP directory by calling the
60 ldap_search_ext(3LDAP) or the ldap_search_ext_s(3LDAP) functions. These
61 functions support LDAPv3 server controls, client controls and variable
62 size and time limits as arguments for each search operation.
63 ldap_search(3LDAP) and ldap_search_s(3LDAP) are identical functions but
64 do not support the controls and limits as arguments to the call.
65
66 Adding or Deleting an entry
67 Use ldap_add_ext(3LDAP) and ldap_delete_ext(3LDAP) to add or delete
68 entries in a LDAP directory server. The synchronous counterparts to
69 these functions are ldap_add_ext_s(3LDAP) and ldap_delete_ext_s(3LDAP).
70 The ldap_add(3LDAP), ldap_add_s(3LDAP), ldap_delete(3LDAP), and
71 ldap_delete_s(3LDAP) provide identical functionality to add and to
72 delete entries, but they do not support LDAP v3 server and client con‐
73 trols.
74
75 Modifying Entries
76 Use ldap_modify_ext(3LDAP) and ldap_modify_ext_s(3LDAP) to modify an
77 existing entry in a LDAP server that supports for LDAPv3 server and
78 client controls. Similarly, use ldap_rename(3LDAP) and
79 ldap_rename_s(3LDAP) to change the name of an LDAP entry. The ldap_mod‐
80 rdn(3LDAP), ldap_modrdn_s(3LDAP), ldap_modrdn2(3LDAP) and ldap_mod‐
81 rdn2_s(3LDAP) interfaces are deprecated.
82
83 Obtaining Results
84 Use ldap_result(3LDAP) to obtain the results of a previous asynchronous
85 operation. For all LDAP operations other than search, only one message
86 is returned. For the search operation, a list of result messages can be
87 returned.
88
89 Handling Errors and Parsing Results
90 Use the ldap_parse_result(3LDAP), ldap_parse_sasl_bind_result(3LDAP),
91 and the ldap_parse_extended_result(3LDAP) functions to extract required
92 information from results and and to handle the returned errors. To
93 covert a numeric error code into a null-terminated character string
94 message describing the error, use ldap_err2string(3LDAP). The
95 ldap_result2error(3LDAP) and ldap_perror(3LDAP) functions are depre‐
96 cated. To step through the list of messages in a result returned by
97 ldap_result(), use ldap_first_message(3LDAP) and ldap_next_mes‐
98 sage(3LDAP). ldap_count_messages(3LDAP) returns the number of messages
99 contained in the list.
100
101
102 You can use ldap_first_entry(3LDAP) and ldap_next_entry(3LDAP) to step
103 through and obtain a list of entries from a list of messages returned
104 by a search result. ldap_count_entries(3LDAP) returns the number of
105 entries contained in a list of messages. Call either
106 ldap_first_attribute(3LDAP) and ldap_next_attribute(3LDAP) to step
107 through a list of attributes associated with an entry. Retrieve the
108 values of a given attribute by calling ldap_get_values(3LDAP) and
109 ldap_get_values_len(3LDAP). Count the number of values returned by
110 using ldap_count_values(3LDAP) and ldap_count_values_len(3LDAP).
111
112
113 Use the ldap_get_lang_values(3LDAP) and ldap_get_lang_values_len(3LDAP)
114 to return an attribute's values that matches a specified language sub‐
115 type. The ldap_get_lang_values() function returns an array of an
116 attribute's string values that matches a specified language subtype. To
117 retrieve the binary data from an attribute, call the ldap_get_lang_val‐
118 ues_len() function instead.
119
120 Uniform Resource Locators (URLS)
121 You can use the ldap_url(3LDAP)functions to test a URL to verify that
122 it is an LDAP URL, to parse LDAP URLs into their component pieces, to
123 initiate searches directly using an LDAP URL, and to retrieve the URL
124 associated with a DNS domain name or a distinguished name.
125
126 User Friendly Naming
127 The ldap_ufn(3LDAP) functions implement a user friendly naming scheme
128 by means of LDAP. This scheme allows you to look up entries using
129 fuzzy, untyped names like "mark smith, umich, us".
130
131 Caching
132 The ldap_memcache(3LDAP) functions provide an in-memory client side
133 cache to store search requests. Caching improves performance and
134 reduces network bandwidth when a client makes repeated requests.
135
136 Utility Functions
137 There are also various utility functions. You can use the
138 ldap_sort(3LDAP) functions are used to sort the entries and values
139 returned by means of the ldap search functions. The
140 ldap_friendly(3LDAP) functions will map from short two letter country
141 codes or other strings to longer "friendlier" names. Use the
142 ldap_charset(3LDAP) functions to translate to and from the T.61 charac‐
143 ter set that is used for many character strings in the LDAP protocol.
144
145 Generating Filters
146 Make calls to ldap_init_getfilter(3LDAP) and ldap_search(3LDAP) to gen‐
147 erate filters to be used in ldap_search(3LDAP) and
148 ldap_search_s(3LDAP). ldap_init_getfilter() reads ldapfilter.conf(4),
149 the LDAP configuration file, while ldap_init_getfilter_buf() reads the
150 configuration information from buf of length buflen. ldap_getfil‐
151 ter_free(3LDAP) frees memory that has been allocated by means of
152 ldap_init_getfilter().
153
154 BER Library
155 The LDAP package includes a set of lightweight Basic Encoding Rules
156 ("BER)" functions. The LDAP library functions use the BER functions to
157 encode and decode LDAP protocol elements through the slightly simpli‐
158 fied BER defined by LDAP. They are not normally used directly by an
159 LDAP application program will not normally use the BER functions
160 directly. Instead, these functions provide a printf() and scanf()-like
161 interface, as well as lower-level access.
162
164 ldap_open(3LDAP)
165
166 Deprecated. Use ldap_init(3LDAP).
167
168
169 ldap_init(3LDAP)
170
171 Initialize a session with a LDAP server without opening a connec‐
172 tion to a server.
173
174
175 ldap_result(3LDAP)
176
177 Obtain the result from a previous asynchronous operation.
178
179
180 ldap_abandon(3LDAP)
181
182 Abandon or abort an asynchronous operation.
183
184
185 ldap_add(3LDAP)
186
187 Asynchronously add an entry
188
189
190 ldap_add_s(3LDAP)
191
192 Synchronously add an entry.
193
194
195 ldap_add_ext(3LDAP)
196
197 Asynchronously add an entry with support for LDAPv3 controls.
198
199
200 ldap_add_ext_s(3LDAP)
201
202 Synchronously add an entry with support for LDAPv3 controls.
203
204
205 ldap_bind(3LDAP)
206
207 Deprecated. Use ldap_sasl_bind(3LDAP) or ldap_simple_bind(3LDAP).
208
209
210 ldap_sasl_bind(3LDAP)
211
212 Asynchronously bind to the directory using SASL authentication
213
214
215 ldap_sasl_bind_s(3LDAP)
216
217 Synchronously bind to the directory using SASL authentication
218
219
220 ldap_bind_s(3LDAP)
221
222 Deprecated. Use ldap_sasl_bind_s(3LDAP) or ldap_sim‐
223 ple_bind_s(3LDAP).
224
225
226 ldap_simple_bind(3LDAP)
227
228 Asynchronously bind to the directory using simple authentication.
229
230
231 ldap_simple_bind_s(3LDAP)
232
233 Synchronously bind to the directory using simple authentication.
234
235
236 ldap_unbind(3LDAP)
237
238 Synchronously unbind from the LDAP server, close the connection,
239 and dispose the session handle.
240
241
242 ldap_unbind_ext(3LDAP)
243
244 Synchronously unbind from the LDAP server and close the connection.
245 ldap_unbind_ext() allows you to explicitly include both server and
246 client controls in the unbind request.
247
248
249 ldap_set_rebind_proc(3LDAP)
250
251 Set callback function for obtaining credentials from a referral.
252
253
254 ldap_memcache_init(3LDAP)
255
256 Create the in-memory client side cache.
257
258
259 ldap_memcache_set(3LDAP)
260
261 Associate an in-memory cache that has been already created by
262 calling the ldap_memcache_init(3LDAP) function with an LDAP connec‐
263 tion handle.
264
265
266 ldap_memcache_get(3LDAP)
267
268 Get the cache associated with the specified LDAP structure.
269
270
271 ldap_memcache_flush(3LDAP)
272
273 Flushes search requests from the cache.
274
275
276 ldap_memcache_destroy(3LDAP)
277
278 Frees the specified LDAPMemCache structure pointed to by cache from
279 memory.
280
281
282 ldap_memcache_update(3LDAP)
283
284 Checks the cache for items that have expired and removes them.
285
286
287 ldap_compare(3LDAP)
288
289 Asynchronous compare with a directory entry.
290
291
292 ldap_compare_s(3LDAP)
293
294 Synchronous compare with a directory entry.
295
296
297 ldap_compare_ext(3LDAP)
298
299 Asynchronous compare with a directory entry, with support for
300 LDAPv3 controls.
301
302
303 ldap_compare_ext_s(3LDAP)
304
305 Synchronous compare with a directory entry, with support for LDAPv3
306 controls.
307
308
309 ldap_control_free(3LDAP)
310
311 Dispose of an LDAP control.
312
313
314 ldap_controls_free(3LDAP)
315
316 Dispose of an array of LDAP controls.
317
318
319 ldap_delete(3LDAP)
320
321 Asynchronously delete an entry.
322
323
324 ldap_delete_s(3LDAP)
325
326 Synchronously delete an entry.
327
328
329 ldap_delete_ext(3LDAP)
330
331 Asynchronously delete an entry, with support for LDAPv3 controls.
332
333
334 ldap_delete_ext_s(3LDAP)
335
336 Synchronously delete an entry, with support for LDAPv3 controls.
337
338
339 ldap_init_templates(3LDAP)
340
341 Read a sequence of templates from a LDAP template configuration
342 file.
343
344
345 ldap_init_templates_buf(3LDAP)
346
347 Read a sequence of templates from a buffer.
348
349
350 ldap_free_templates(3LDAP)
351
352 Dispose of the templates allocated.
353
354
355 ldap_first_reference(3LDAP)
356
357 Step through a list of continuation references from a search
358 result.
359
360
361 ldap_next_reference(3LDAP)
362
363 Step through a list of continuation references from a search
364 result.
365
366
367 ldap_count_references(3LDAP)
368
369 Count the number of messages in a search result.
370
371
372 ldap_first_message(3LDAP)
373
374 Step through a list of messages in a search result.
375
376
377 ldap_count_messages(3LDAP)
378
379 Count the messages in a list of messages in a search result.
380
381
382 ldap_next_message(3LDAP)
383
384 Step through a list of messages in a search result.
385
386
387 ldap_msgtype(3LDAP)
388
389 Return the type of LDAP message.
390
391
392 ldap_first_disptmpl(3LDAP)
393
394 Get first display template in a list.
395
396
397 ldap_next_disptmpl(3LDAP)
398
399 Get next display template in a list.
400
401
402 ldap_oc2template(3LDAP)
403
404 Return template appropriate for the objectclass.
405
406
407 ldap_name2template(3LDAP)
408
409 Return named template
410
411
412 ldap_tmplattrs(3LDAP)
413
414 Return attributes needed by the template.
415
416
417 ldap_first_tmplrow(3LDAP)
418
419 Return first row of displayable items in a template.
420
421
422 ldap_next_tmplrow(3LDAP)
423
424 Return next row of displayable items in a template.
425
426
427 ldap_first_tmplcol(3LDAP)
428
429 Return first column of displayable items in a template.
430
431
432 ldap_next_tmplcol(3LDAP)
433
434 Return next column of displayable items in a template.
435
436
437 ldap_entry2text(3LDAP)
438
439 Display an entry as text by using a display template.
440
441
442 ldap_entry2text_search(3LDAP)
443
444 Search for and display an entry as text by using a display tem‐
445 plate.
446
447
448 ldap_vals2text(3LDAP)
449
450 Display values as text.
451
452
453 ldap_entry2html(3LDAP)
454
455 Display an entry as HTML (HyperText Markup Language) by using a
456 display template.
457
458
459 ldap_entry2html_search(3LDAP)
460
461 Search for and display an entry as HTML by using a display tem‐
462 plate.
463
464
465 ldap_vals2html(3LDAP)
466
467 Display values as HTML.
468
469
470 ldap_perror(3LDAP)
471
472 Deprecated. Use ldap_parse_result(3LDAP).
473
474
475 ldap_result2error(3LDAP)
476
477 Deprecated. Use ldap_parse_result(3LDAP).
478
479
480 ldap_err2string(3LDAP)
481
482 Convert LDAP error indication to a string.
483
484
485 ldap_first_attribute(3LDAP)
486
487 Return first attribute name in an entry.
488
489
490 ldap_next_attribute(3LDAP)
491
492 Return next attribute name in an entry.
493
494
495 ldap_first_entry(3LDAP)
496
497 Return first entry in a chain of search results.
498
499
500 ldap_next_entry(3LDAP)
501
502 Return next entry in a chain of search results.
503
504
505 ldap_count_entries(3LDAP)
506
507 Return number of entries in a search result.
508
509
510 ldap_friendly_name(3LDAP)
511
512 Map from unfriendly to friendly names.
513
514
515 ldap_free_friendlymap(3LDAP)
516
517 Free resources used by ldap_friendly(3LDAP).
518
519
520 ldap_get_dn(3LDAP)
521
522 Extract the DN from an entry.
523
524
525 ldap_explode_dn(3LDAP)
526
527 Convert a DN into its component parts.
528
529
530 ldap_explode_dns(3LDAP)
531
532 Convert a DNS-style DN into its component parts (experimental).
533
534
535 ldap_is_dns_dn(3LDAP)
536
537 Check to see if a DN is a DNS-style DN (experimental).
538
539
540 ldap_dns_to_dn(3LDAP)
541
542 Convert a DNS domain name into an X.500 distinguished name.
543
544
545 ldap_dn2ufn(3LDAP)
546
547 Convert a DN into user friendly form.
548
549
550 ldap_get_values(3LDAP)
551
552 Return an attribute's values.
553
554
555 ldap_get_values_len(3LDAP)
556
557 Return an attribute's values with lengths.
558
559
560 ldap_value_free(3LDAP)
561
562 Free memory allocated by ldap_get_values(3LDAP).
563
564
565 ldap_value_free_len(3LDAP)
566
567 Free memory allocated by ldap_get_values_len(3LDAP).
568
569
570 ldap_count_values(3LDAP)
571
572 Return number of values.
573
574
575 ldap_count_values_len(3LDAP)
576
577 Return number of values.
578
579
580 ldap_init_getfilter(3LDAP)
581
582 Initialize getfilter functions from a file.
583
584
585 ldap_init_getfilter_buf(3LDAP)
586
587 Initialize getfilter functions from a buffer.
588
589
590 ldap_getfilter_free(3LDAP)
591
592 Free resources allocated by ldap_init_getfilter(3LDAP).
593
594
595 ldap_getfirstfilter(3LDAP)
596
597 Return first search filter.
598
599
600 ldap_getnextfilter(3LDAP)
601
602 Return next search filter.
603
604
605 ldap_build_filter(3LDAP)
606
607 Construct an LDAP search filter from a pattern.
608
609
610 ldap_setfilteraffixes(3LDAP)
611
612 Set prefix and suffix for search filters.
613
614
615 ldap_modify(3LDAP)
616
617 Asynchronously modify an entry.
618
619
620 ldap_modify_s(3LDAP)
621
622 Synchronously modify an entry.
623
624
625 ldap_modify_ext(3LDAP)
626
627 Asynchronously modify an entry, return value, and place message.
628
629
630 ldap_modify_ext_s(3LDAP)
631
632 Synchronously modify an entry, return value, and place message.
633
634
635 ldap_mods_free(3LDAP)
636
637 Free array of pointers to mod structures used by ldap_mod‐
638 ify(3LDAP).
639
640
641 ldap_modrdn2(3LDAP)
642
643 Deprecated. Use ldap_rename(3LDAP) instead.
644
645
646 ldap_modrdn2_s(3LDAP)
647
648 Deprecated. Use ldap_rename_s(3LDAP) instead.
649
650
651 ldap_modrdn(3LDAP)
652
653 Deprecated. Use ldap_rename(3LDAP) instead.
654
655
656 ldap_modrdn_s(3LDAP)
657
658 Depreciated. Use ldap_rename_s(3LDAP) instead.
659
660
661 ldap_rename(3LDAP)
662
663 Asynchronously modify the name of an LDAP entry.
664
665
666 ldap_rename_s(3LDAP)
667
668 Synchronously modify the name of an LDAP entry.
669
670
671 ldap_msgfree(3LDAP)
672
673 Free result messages.
674
675
676 ldap_parse_result(3LDAP)
677
678 Search for a message to parse.
679
680
681 ldap_parse_extended_result(3LDAP)
682
683 Search for a message to parse.
684
685
686 ldap_parse_sasl_bind_result(3LDAP)
687
688 Search for a message to parse.
689
690
691 ldap_search(3LDAP)
692
693 Asynchronously search the directory.
694
695
696 ldap_search_s(3LDAP)
697
698 Synchronously search the directory.
699
700
701 ldap_search_ext(3LDAP)
702
703 Asynchronously search the directory with support for LDAPv3 con‐
704 trols.
705
706
707 ldap_search_ext_s(3LDAP)
708
709 Synchronously search the directory with support for LDAPv3 con‐
710 trols.
711
712
713 ldap_search_st(3LDAP)
714
715 Synchronously search the directory with support for a local timeout
716 value.
717
718
719 ldap_ufn_search_s(3LDAP)
720
721 User friendly search the directory.
722
723
724 ldap_ufn_search_c(3LDAP)
725
726 User friendly search the directory with cancel.
727
728
729 ldap_ufn_search_ct(3LDAP)
730
731 User friendly search the directory with cancel and timeout.
732
733
734 ldap_ufn_setfilter(3LDAP)
735
736 Set filter file used by ldap_ufn(3LDAP) functions.
737
738
739 ldap_ufn_setprefix(3LDAP)
740
741 Set prefix used by ldap_ufn(3LDAP) functions.
742
743
744 ldap_ufn_timeout(3LDAP)
745
746 Set timeout used by ldap_ufn(3LDAP) functions.
747
748
749 ldap_is_ldap_url(3LDAP)
750
751 Check a URL string to see if it is an LDAP URL.
752
753
754 ldap_url_parse(3LDAP)
755
756 Break up an LDAP URL string into its components.
757
758
759 ldap_free_urldesc(3LDAP)
760
761 Free an LDAP URL structure.
762
763
764 ldap_url_search(3LDAP)
765
766 Asynchronously search by using an LDAP URL.
767
768
769 ldap_url_search_s(3LDAP)
770
771 Synchronously search by using an LDAP URL.
772
773
774 ldap_url_search_st(3LDAP)
775
776 Asynchronously search by using an LDAP URL, with support for a
777 local timeout value.
778
779
780 ldap_dns_to_url(3LDAP)
781
782 Locate the LDAP URL associated with a DNS domain name.
783
784
785 ldap_dn_to_url(3LDAP)
786
787 Locate the LDAP URL associated with a distinguished name.
788
789
790 ldap_init_searchprefs(3LDAP)
791
792 Initialize searchprefs functions from a file.
793
794
795 ldap_init_searchprefs_buf(3LDAP)
796
797 Initialize searchprefs functions from a buffer.
798
799
800 ldap_free_searchprefs(3LDAP)
801
802 Free memory allocated by searchprefs functions.
803
804
805 ldap_first_searchobj(3LDAP)
806
807 Return first searchpref object.
808
809
810 ldap_next_searchobj(3LDAP)
811
812 Return next searchpref object.
813
814
815 ldap_sort_entries(3LDAP)
816
817 Sort a list of search results.
818
819
820 ldap_sort_values(3LDAP)
821
822 Sort a list of attribute values.
823
824
825 ldap_sort_strcasecmp(3LDAP)
826
827 Case insensitive string comparison.
828
829
830 ldap_set_string_translators(3LDAP)
831
832 Set character set translation functions used by LDAP library.
833
834
835 ldap_translate_from_t61(3LDAP)
836
837 Translate from the T.61 character set to another character set.
838
839
840 ldap_translate_to_t61(3LDAP)
841
842 Translate to the T.61 character set from another character set.
843
844
845 ldap_enable_translation(3LDAP)
846
847 Enable or disable character translation for an LDAP entry result.
848
849
850 ldap_version(3LDAP)
851
852 Get version information about the LDAP SDK for C.
853
854
855 ldap_get_lang_values(3LDAP)
856
857 Return an attribute's value that matches a specified language sub‐
858 type.
859
860
861 ldap_get_lang_values_len(3LDAP)
862
863 Return an attribute's value that matches a specified language sub‐
864 type along with lengths.
865
866
867 ldap_get_entry_controls(3LDAP)
868
869 Get the LDAP controls included with a directory entry in a set of
870 search results.
871
872
873 ldap_get_option(3LDAP)
874
875 Get session preferences in an LDAP structure.
876
877
878 ldap_set_option(3LDAP)
879
880 Set session preferences in an LDAP structure.
881
882
883 ldap_memfree(3LDAP)
884
885 Free memory allocated by LDAP API functions.
886
887
889 See attributes(5) for a description of the following attributes:
890
891
892
893
894 ┌─────────────────────────────┬─────────────────────────────┐
895 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
896 ├─────────────────────────────┼─────────────────────────────┤
897 │Availability │SUNWcsl (32-bit) │
898 │ │SUNWcslx (64-bit) │
899 ├─────────────────────────────┼─────────────────────────────┤
900 │Stability Level │Evolving │
901 └─────────────────────────────┴─────────────────────────────┘
902
904 attributes(5)
905
906
907
908SunOS 5.11 27 Jan 2002 ldap(3LDAP)