diff options
Diffstat (limited to 'usr/src/man/man3ldap')
42 files changed, 9048 insertions, 0 deletions
diff --git a/usr/src/man/man3ldap/Makefile b/usr/src/man/man3ldap/Makefile new file mode 100644 index 0000000000..5499a5d969 --- /dev/null +++ b/usr/src/man/man3ldap/Makefile @@ -0,0 +1,403 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3ldap + +MANFILES = ber_decode.3ldap \ + ber_encode.3ldap \ + cldap_close.3ldap \ + cldap_open.3ldap \ + cldap_search_s.3ldap \ + cldap_setretryinfo.3ldap \ + ldap.3ldap \ + ldap_abandon.3ldap \ + ldap_add.3ldap \ + ldap_ber_free.3ldap \ + ldap_bind.3ldap \ + ldap_charset.3ldap \ + ldap_compare.3ldap \ + ldap_control_free.3ldap \ + ldap_delete.3ldap \ + ldap_disptmpl.3ldap \ + ldap_entry2text.3ldap \ + ldap_error.3ldap \ + ldap_first_attribute.3ldap \ + ldap_first_entry.3ldap \ + ldap_first_message.3ldap \ + ldap_friendly.3ldap \ + ldap_get_dn.3ldap \ + ldap_get_entry_controls.3ldap \ + ldap_get_lang_values.3ldap \ + ldap_get_option.3ldap \ + ldap_get_values.3ldap \ + ldap_getfilter.3ldap \ + ldap_memcache.3ldap \ + ldap_memfree.3ldap \ + ldap_modify.3ldap \ + ldap_modrdn.3ldap \ + ldap_open.3ldap \ + ldap_parse_result.3ldap \ + ldap_result.3ldap \ + ldap_search.3ldap \ + ldap_searchprefs.3ldap \ + ldap_sort.3ldap \ + ldap_ufn.3ldap \ + ldap_url.3ldap \ + ldap_version.3ldap + +MANSOFILES = ber_alloc.3ldap \ + ber_alloc_t.3ldap \ + ber_bvdup.3ldap \ + ber_bvecfree.3ldap \ + ber_bvfree.3ldap \ + ber_first_element.3ldap \ + ber_flatten.3ldap \ + ber_free.3ldap \ + ber_get_bitstring.3ldap \ + ber_get_boolean.3ldap \ + ber_get_int.3ldap \ + ber_get_next.3ldap \ + ber_get_null.3ldap \ + ber_get_stringa.3ldap \ + ber_get_stringal.3ldap \ + ber_get_stringb.3ldap \ + ber_init.3ldap \ + ber_next_element.3ldap \ + ber_peek_tag.3ldap \ + ber_printf.3ldap \ + ber_put_bitstring.3ldap \ + ber_put_boolean.3ldap \ + ber_put_int.3ldap \ + ber_put_null.3ldap \ + ber_put_ostring.3ldap \ + ber_put_seq.3ldap \ + ber_put_set.3ldap \ + ber_put_string.3ldap \ + ber_scanf.3ldap \ + ber_skip_tag.3ldap \ + ber_start_seq.3ldap \ + ber_start_set.3ldap \ + ldap_8859_to_t61.3ldap \ + ldap_add_ext.3ldap \ + ldap_add_ext_s.3ldap \ + ldap_add_s.3ldap \ + ldap_bind_s.3ldap \ + ldap_build_filter.3ldap \ + ldap_compare_ext.3ldap \ + ldap_compare_ext_s.3ldap \ + ldap_compare_s.3ldap \ + ldap_controls_free.3ldap \ + ldap_count_entries.3ldap \ + ldap_count_messages.3ldap \ + ldap_count_references.3ldap \ + ldap_count_values.3ldap \ + ldap_count_values_len.3ldap \ + ldap_delete_ext.3ldap \ + ldap_delete_ext_s.3ldap \ + ldap_delete_s.3ldap \ + ldap_dn2ufn.3ldap \ + ldap_dn_to_url.3ldap \ + ldap_dns_to_dn.3ldap \ + ldap_dns_to_url.3ldap \ + ldap_enable_translation.3ldap \ + ldap_entry2html.3ldap \ + ldap_entry2html_search.3ldap \ + ldap_entry2text_search.3ldap \ + ldap_err2string.3ldap \ + ldap_explode_dn.3ldap \ + ldap_explode_dns.3ldap \ + ldap_first_disptmpl.3ldap \ + ldap_first_reference.3ldap \ + ldap_first_searchobj.3ldap \ + ldap_first_tmplcol.3ldap \ + ldap_first_tmplrow.3ldap \ + ldap_free_friendlymap.3ldap \ + ldap_free_searchprefs.3ldap \ + ldap_free_templates.3ldap \ + ldap_free_urldesc.3ldap \ + ldap_friendly_name.3ldap \ + ldap_get_lang_values_len.3ldap \ + ldap_get_values_len.3ldap \ + ldap_getfilter_free.3ldap \ + ldap_getfirstfilter.3ldap \ + ldap_getnextfilter.3ldap \ + ldap_init.3ldap \ + ldap_init_getfilter.3ldap \ + ldap_init_getfilter_buf.3ldap \ + ldap_init_searchprefs.3ldap \ + ldap_init_searchprefs_buf.3ldap \ + ldap_init_templates.3ldap \ + ldap_init_templates_buf.3ldap \ + ldap_is_dns_dn.3ldap \ + ldap_is_ldap_url.3ldap \ + ldap_memcache_destroy.3ldap \ + ldap_memcache_flush.3ldap \ + ldap_memcache_get.3ldap \ + ldap_memcache_init.3ldap \ + ldap_memcache_set.3ldap \ + ldap_memcache_update.3ldap \ + ldap_modify_ext.3ldap \ + ldap_modify_ext_s.3ldap \ + ldap_modify_s.3ldap \ + ldap_modrdn2.3ldap \ + ldap_modrdn2_s.3ldap \ + ldap_modrdn_s.3ldap \ + ldap_mods_free.3ldap \ + ldap_msgfree.3ldap \ + ldap_msgtype.3ldap \ + ldap_name2template.3ldap \ + ldap_next_attribute.3ldap \ + ldap_next_disptmpl.3ldap \ + ldap_next_entry.3ldap \ + ldap_next_message.3ldap \ + ldap_next_reference.3ldap \ + ldap_next_searchobj.3ldap \ + ldap_next_tmplcol.3ldap \ + ldap_next_tmplrow.3ldap \ + ldap_oc2template.3ldap \ + ldap_parse_extended_result.3ldap \ + ldap_parse_sasl_bind_result.3ldap \ + ldap_perror.3ldap \ + ldap_rename.3ldap \ + ldap_rename_s.3ldap \ + ldap_result2error.3ldap \ + ldap_sasl_bind.3ldap \ + ldap_sasl_bind_s.3ldap \ + ldap_sasl_interactive_bind_s.3ldap \ + ldap_search_ext.3ldap \ + ldap_search_ext_s.3ldap \ + ldap_search_s.3ldap \ + ldap_search_st.3ldap \ + ldap_set_option.3ldap \ + ldap_set_rebind_proc.3ldap \ + ldap_set_string_translators.3ldap \ + ldap_setfilteraffixes.3ldap \ + ldap_simple_bind.3ldap \ + ldap_simple_bind_s.3ldap \ + ldap_sort_entries.3ldap \ + ldap_sort_strcasecmp.3ldap \ + ldap_sort_values.3ldap \ + ldap_t61_to_8859.3ldap \ + ldap_tmplattrs.3ldap \ + ldap_translate_from_t61.3ldap \ + ldap_translate_to_t61.3ldap \ + ldap_ufn_search_c.3ldap \ + ldap_ufn_search_ct.3ldap \ + ldap_ufn_search_s.3ldap \ + ldap_ufn_setfilter.3ldap \ + ldap_ufn_setprefix.3ldap \ + ldap_ufn_timeout.3ldap \ + ldap_unbind.3ldap \ + ldap_unbind_ext.3ldap \ + ldap_unbind_s.3ldap \ + ldap_url_parse.3ldap \ + ldap_url_parse_nodn.3ldap \ + ldap_url_search.3ldap \ + ldap_url_search_s.3ldap \ + ldap_url_search_st.3ldap \ + ldap_vals2html.3ldap \ + ldap_vals2text.3ldap \ + ldap_value_free.3ldap \ + ldap_value_free_len.3ldap + +MANFILES += $(MANSOFILES) + +ber_alloc_t.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_bvdup.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_bvecfree.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_bvfree.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_first_element.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_flatten.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_free.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_bitstring.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_boolean.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_int.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_next.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_null.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_stringa.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_stringal.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_get_stringb.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_init.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_next_element.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_peek_tag.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_scanf.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_skip_tag.3ldap := SOSRC = man3ldap/ber_decode.3ldap +ber_alloc.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_printf.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_bitstring.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_boolean.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_int.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_null.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_ostring.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_seq.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_set.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_put_string.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_start_seq.3ldap := SOSRC = man3ldap/ber_encode.3ldap +ber_start_set.3ldap := SOSRC = man3ldap/ber_encode.3ldap + +ldap_add_ext.3ldap := SOSRC = man3ldap/ldap_add.3ldap +ldap_add_ext_s.3ldap := SOSRC = man3ldap/ldap_add.3ldap +ldap_add_s.3ldap := SOSRC = man3ldap/ldap_add.3ldap + +ldap_bind_s.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_sasl_bind.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_sasl_bind_s.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_sasl_interactive_bind_s.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_set_rebind_proc.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_simple_bind.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_simple_bind_s.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_unbind.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_unbind_ext.3ldap := SOSRC = man3ldap/ldap_bind.3ldap +ldap_unbind_s.3ldap := SOSRC = man3ldap/ldap_bind.3ldap + +ldap_8859_to_t61.3ldap := SOSRC = man3ldap/ldap_charset.3ldap +ldap_enable_translation.3ldap := SOSRC = man3ldap/ldap_charset.3ldap +ldap_set_string_translators.3ldap := SOSRC = man3ldap/ldap_charset.3ldap +ldap_t61_to_8859.3ldap := SOSRC = man3ldap/ldap_charset.3ldap +ldap_translate_from_t61.3ldap := SOSRC = man3ldap/ldap_charset.3ldap +ldap_translate_to_t61.3ldap := SOSRC = man3ldap/ldap_charset.3ldap +ldap_compare_ext.3ldap := SOSRC = man3ldap/ldap_compare.3ldap +ldap_compare_ext_s.3ldap := SOSRC = man3ldap/ldap_compare.3ldap +ldap_compare_s.3ldap := SOSRC = man3ldap/ldap_compare.3ldap + +ldap_controls_free.3ldap := SOSRC = man3ldap/ldap_control_free.3ldap + +ldap_delete_ext.3ldap := SOSRC = man3ldap/ldap_delete.3ldap +ldap_delete_ext_s.3ldap := SOSRC = man3ldap/ldap_delete.3ldap +ldap_delete_s.3ldap := SOSRC = man3ldap/ldap_delete.3ldap + +ldap_first_disptmpl.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_first_tmplcol.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_first_tmplrow.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_free_templates.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_init_templates.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_init_templates_buf.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_name2template.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_next_disptmpl.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_next_tmplcol.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_next_tmplrow.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_oc2template.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap +ldap_tmplattrs.3ldap := SOSRC = man3ldap/ldap_disptmpl.3ldap + +ldap_entry2html.3ldap := SOSRC = man3ldap/ldap_entry2text.3ldap +ldap_entry2html_search.3ldap := SOSRC = man3ldap/ldap_entry2text.3ldap +ldap_entry2text_search.3ldap := SOSRC = man3ldap/ldap_entry2text.3ldap +ldap_vals2html.3ldap := SOSRC = man3ldap/ldap_entry2text.3ldap +ldap_vals2text.3ldap := SOSRC = man3ldap/ldap_entry2text.3ldap + +ldap_err2string.3ldap := SOSRC = man3ldap/ldap_error.3ldap +ldap_perror.3ldap := SOSRC = man3ldap/ldap_error.3ldap +ldap_result2error.3ldap := SOSRC = man3ldap/ldap_error.3ldap + +ldap_next_attribute.3ldap := SOSRC = man3ldap/ldap_first_attribute.3ldap + +ldap_count_entries.3ldap := SOSRC = man3ldap/ldap_first_entry.3ldap +ldap_count_references.3ldap := SOSRC = man3ldap/ldap_first_entry.3ldap +ldap_first_reference.3ldap := SOSRC = man3ldap/ldap_first_entry.3ldap +ldap_next_entry.3ldap := SOSRC = man3ldap/ldap_first_entry.3ldap +ldap_next_reference.3ldap := SOSRC = man3ldap/ldap_first_entry.3ldap + +ldap_count_messages.3ldap := SOSRC = man3ldap/ldap_first_message.3ldap +ldap_msgtype.3ldap := SOSRC = man3ldap/ldap_first_message.3ldap +ldap_next_message.3ldap := SOSRC = man3ldap/ldap_first_message.3ldap + +ldap_free_friendlymap.3ldap := SOSRC = man3ldap/ldap_friendly.3ldap +ldap_friendly_name.3ldap := SOSRC = man3ldap/ldap_friendly.3ldap + +ldap_dn2ufn.3ldap := SOSRC = man3ldap/ldap_get_dn.3ldap +ldap_dns_to_dn.3ldap := SOSRC = man3ldap/ldap_get_dn.3ldap +ldap_explode_dn.3ldap := SOSRC = man3ldap/ldap_get_dn.3ldap +ldap_explode_dns.3ldap := SOSRC = man3ldap/ldap_get_dn.3ldap +ldap_is_dns_dn.3ldap := SOSRC = man3ldap/ldap_get_dn.3ldap + +ldap_get_lang_values_len.3ldap := SOSRC = man3ldap/ldap_get_lang_values.3ldap + +ldap_set_option.3ldap := SOSRC = man3ldap/ldap_get_option.3ldap +ldap_count_values.3ldap := SOSRC = man3ldap/ldap_get_values.3ldap +ldap_count_values_len.3ldap := SOSRC = man3ldap/ldap_get_values.3ldap +ldap_get_values_len.3ldap := SOSRC = man3ldap/ldap_get_values.3ldap +ldap_value_free.3ldap := SOSRC = man3ldap/ldap_get_values.3ldap +ldap_value_free_len.3ldap := SOSRC = man3ldap/ldap_get_values.3ldap + +ldap_build_filter.3ldap := SOSRC = man3ldap/ldap_getfilter.3ldap +ldap_getfilter_free.3ldap := SOSRC = man3ldap/ldap_getfilter.3ldap +ldap_getfirstfilter.3ldap := SOSRC = man3ldap/ldap_getfilter.3ldap +ldap_getnextfilter.3ldap := SOSRC = man3ldap/ldap_getfilter.3ldap +ldap_init_getfilter.3ldap := SOSRC = man3ldap/ldap_getfilter.3ldap +ldap_init_getfilter_buf.3ldap := SOSRC = man3ldap/ldap_getfilter.3ldap +ldap_setfilteraffixes.3ldap := SOSRC = man3ldap/ldap_getfilter.3ldap + +ldap_memcache_destroy.3ldap := SOSRC = man3ldap/ldap_memcache.3ldap +ldap_memcache_flush.3ldap := SOSRC = man3ldap/ldap_memcache.3ldap +ldap_memcache_get.3ldap := SOSRC = man3ldap/ldap_memcache.3ldap +ldap_memcache_init.3ldap := SOSRC = man3ldap/ldap_memcache.3ldap +ldap_memcache_set.3ldap := SOSRC = man3ldap/ldap_memcache.3ldap +ldap_memcache_update.3ldap := SOSRC = man3ldap/ldap_memcache.3ldap + +ldap_modify_ext.3ldap := SOSRC = man3ldap/ldap_modify.3ldap +ldap_modify_ext_s.3ldap := SOSRC = man3ldap/ldap_modify.3ldap +ldap_modify_s.3ldap := SOSRC = man3ldap/ldap_modify.3ldap +ldap_mods_free.3ldap := SOSRC = man3ldap/ldap_modify.3ldap + +ldap_modrdn2.3ldap := SOSRC = man3ldap/ldap_modrdn.3ldap +ldap_modrdn2_s.3ldap := SOSRC = man3ldap/ldap_modrdn.3ldap +ldap_modrdn_s.3ldap := SOSRC = man3ldap/ldap_modrdn.3ldap +ldap_rename.3ldap := SOSRC = man3ldap/ldap_modrdn.3ldap +ldap_rename_s.3ldap := SOSRC = man3ldap/ldap_modrdn.3ldap + +ldap_init.3ldap := SOSRC = man3ldap/ldap_open.3ldap + +ldap_parse_extended_result.3ldap := SOSRC = man3ldap/ldap_parse_result.3ldap +ldap_parse_sasl_bind_result.3ldap := SOSRC = man3ldap/ldap_parse_result.3ldap + +ldap_msgfree.3ldap := SOSRC = man3ldap/ldap_result.3ldap + +ldap_search_ext.3ldap := SOSRC = man3ldap/ldap_search.3ldap +ldap_search_ext_s.3ldap := SOSRC = man3ldap/ldap_search.3ldap +ldap_search_s.3ldap := SOSRC = man3ldap/ldap_search.3ldap +ldap_search_st.3ldap := SOSRC = man3ldap/ldap_search.3ldap + +ldap_first_searchobj.3ldap := SOSRC = man3ldap/ldap_searchprefs.3ldap +ldap_free_searchprefs.3ldap := SOSRC = man3ldap/ldap_searchprefs.3ldap +ldap_init_searchprefs.3ldap := SOSRC = man3ldap/ldap_searchprefs.3ldap +ldap_init_searchprefs_buf.3ldap := SOSRC = man3ldap/ldap_searchprefs.3ldap +ldap_next_searchobj.3ldap := SOSRC = man3ldap/ldap_searchprefs.3ldap + +ldap_sort_entries.3ldap := SOSRC = man3ldap/ldap_sort.3ldap +ldap_sort_strcasecmp.3ldap := SOSRC = man3ldap/ldap_sort.3ldap +ldap_sort_values.3ldap := SOSRC = man3ldap/ldap_sort.3ldap + +ldap_ufn_search_c.3ldap := SOSRC = man3ldap/ldap_ufn.3ldap +ldap_ufn_search_ct.3ldap := SOSRC = man3ldap/ldap_ufn.3ldap +ldap_ufn_search_s.3ldap := SOSRC = man3ldap/ldap_ufn.3ldap +ldap_ufn_setfilter.3ldap := SOSRC = man3ldap/ldap_ufn.3ldap +ldap_ufn_setprefix.3ldap := SOSRC = man3ldap/ldap_ufn.3ldap +ldap_ufn_timeout.3ldap := SOSRC = man3ldap/ldap_ufn.3ldap + +ldap_dn_to_url.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_dns_to_url.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_free_urldesc.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_is_ldap_url.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_url_parse.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_url_parse_nodn.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_url_search.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_url_search_s.3ldap := SOSRC = man3ldap/ldap_url.3ldap +ldap_url_search_st.3ldap := SOSRC = man3ldap/ldap_url.3ldap + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man3ldap/ber_decode.3ldap b/usr/src/man/man3ldap/ber_decode.3ldap new file mode 100644 index 0000000000..6c932a8b79 --- /dev/null +++ b/usr/src/man/man3ldap/ber_decode.3ldap @@ -0,0 +1,521 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ber_decode 3LDAP "15 May 2009" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ber_decode, ber_alloc_t, ber_free, ber_bvdup, ber_init, ber_flatten, +ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, +ber_get_stringa, ber_get_stringal, ber_get_stringb, ber_get_null, +ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element, +ber_bvfree, ber_bvecfree \- Basic Encoding Rules library decoding functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> + +\fBBerElement *\fR\fBber_alloc_t\fR(\fBint\fR \fIoptions\fR); +.fi + +.LP +.nf +\fBstruct berval *\fR\fBber_bvdup\fR(\fBconst struct berval *\fR\fIbv\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBber_free\fR(\fBBerElement *\fR\fIber\fR, \fBint\fR \fIfreebuf\fR); +.fi + +.LP +.nf +\fBBerElement *\fR\fBber_init\fR(\fBconst struct berval *\fR\fIbv\fR); +.fi + +.LP +.nf +\fBint\fR \fBber_flatten\fR(\fBBerElement *\fR\fIber\fR, \fBstruct berval **\fR\fIbvPtr\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR\fBber_get_next\fR(\fBSockbuf *\fR\fIsb\fR, \fBber_len_t *\fR\fIlen\fR, \fBBerElement *\fR\fIber\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_skip_tag\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_peek_tag\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_get_int\fR(\fBBerElement *\fR\fIber\fR, \fBber_int_t *\fR\fInum\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_get_stringb\fR(\fBBerElement *\fR\fIber\fR, \fBchar *\fR\fIbuf\fR, + \fBber_len_t *\fR\fIlen\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_get_stringa\fR(\fBBerElement *\fR\fIber\fR, \fBchar **\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_get_stringal\fR(\fBBerElement *\fR\fIber\fR, \fBstruct berval **\fR\fIbv\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_get_null\fR(\fBBerElement *\fR\fIber\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_get_boolean\fR(\fBBerElement *\fR\fIber\fR, \fBint *\fR\fIboolval\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_get_bitstringa\fR(\fBBerElement *\fR\fIber\fR, \fBchar **\fR\fIbuf\fR, + \fBber_len_t *\fR\fIlen\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_first_element\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR, + \fBchar **\fR\fIlast\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_next_element\fR(\fBBerElement *\fR\fIber\fR, \fBber_len_t *\fR\fIlen\fR, + \fBchar *\fR\fIlast\fR); +.fi + +.LP +.nf +\fBber_tag_t\fR \fBber_scanf\fR(\fBBerElement *\fR\fIber\fR, \fBconst char *\fR\fIfmt\fR [, arg...]); +.fi + +.LP +.nf +\fBvoid\fR \fBber_bvfree\fR(\fBstruct berval *\fR\fIbv\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBber_bvecfree\fR(\fBstruct berval **\fR\fIbvec\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide a subfunction interface to a simplified implementation +of the Basic Encoding Rules of ASN.1. The version of BER these functions +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 functions 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 decoding functions in the lber library. See \fBber_encode\fR(3LDAP) for +details on the corresponding encoding functions. +.sp +.LP +Normally, the only functions that need be called by an application are +\fBber_get_next()\fR to get the next BER element and \fBber_scanf()\fR to do +the actual decoding. In some cases, \fBber_peek_tag()\fR may also need to be +called in normal usage. The other functions are provided for those applications +that need more control than \fBber_scanf()\fR provides. In general, these +functions return the tag of the element decoded, or \fB\(mi1\fR if an error +occurred. +.sp +.LP +The \fBber_get_next()\fR function is used to read the next BER element from +the given \fBSockbuf\fR, \fIsb\fR. A \fBSockbuf\fR consists of the descriptor +(usually socket, but a file descriptor works just as well) from which to read, +and a \fBBerElement\fR structure used to maintain a buffer. On the first call, +the \fIsb_ber\fR struct should be zeroed. It strips off and returns the +leading tag byte, strips off and returns the length of the entire element in +\fIlen\fR, and sets up \fIber\fR for subsequent calls to \fBber_scanf()\fR, +and all to decode the element. +.sp +.LP +The \fBber_peek_tag()\fR function returns the tag of the next element to be +parsed in the \fBBerElement\fR argument. The length of this element is stored +in the *\fIlenPtr\fR argument. \fBLBER_DEFAULT\fR is returned if there is no +further data to be read. The decoding position within the \fIber\fR argument is +unchanged by this call; that is, the fact that \fBber_peek_tag()\fR has been +called does not affect future use of \fIber\fR. +.sp +.LP +The \fBber_skip_tag()\fR function is similar to \fBber_peek_tag()\fR, except +that the state pointer in the \fBBerElement\fR argument is advanced past the +first tag and length, and is pointed to the value part of the next element. +This function should only be used with constructed types and situations when a +BER encoding is used as the value of an OCTET STRING. The length of the value +is stored in *\fIlenPtr\fR. +.sp +.LP +The \fBber_scanf()\fR function is used to decode a BER element in much the +same way that \fBscanf\fR(3C) works. It reads from \fIber\fR, a pointer to a +\fBBerElement\fR such as returned by \fBber_get_next()\fR, interprets the bytes +according to the format string \fBfmt\fR, 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. +.sp +.ne 2 +.mk +.na +\fB\fBa\fR\fR +.ad +.RS 5n +.rt +Octet string. A char ** should be supplied. Memory is allocated, filled with +the contents of the octet string, null-terminated, and returned in the +parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 5n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO\fR\fR +.ad +.RS 5n +.rt +Octet string. A struct ber_val ** should be supplied, which upon return points +to a memory allocated struct berval containing the octet string and its length. +\fBber_bvfree()\fR can be called to free the allocated memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb\fR\fR +.ad +.RS 5n +.rt +Boolean. A pointer to an integer should be supplied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBi\fR\fR +.ad +.RS 5n +.rt +Integer. A pointer to an integer should be supplied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB\fR\fR +.ad +.RS 5n +.rt +Bitstring. A char ** should be supplied which will point to the memory +allocated bits, followed by an unsigned long *, which will point to the length +(in bits) of the bitstring returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBn\fR\fR +.ad +.RS 5n +.rt +Null. No parameter is required. The element is simply skipped if it is +recognized. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBv\fR\fR +.ad +.RS 5n +.rt +Sequence of octet strings. A char *** should be supplied, which upon return +points to a memory allocated null-terminated array of char *'s containing the +octet strings. \fINULL\fR is returned if the sequence is empty. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBV\fR\fR +.ad +.RS 5n +.rt +Sequence of octet strings with lengths. A struct berval *** should be supplied, +which upon return points to a memory allocated, null-terminated array of struct +berval *'s containing the octet strings and their lengths. \fINULL\fR is +returned if the sequence is empty. \fBber_bvecfree()\fR can be called to free +the allocated memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBx\fR\fR +.ad +.RS 5n +.rt +Skip element. The next element is skipped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB{\fR\fR +.ad +.RS 5n +.rt +Begin sequence. No parameter is required. The initial sequence tag and length +are skipped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB}\fR\fR +.ad +.RS 5n +.rt +End sequence. No parameter is required and no action is taken. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB[\fR\fR +.ad +.RS 5n +.rt +Begin set. No parameter is required. The initial set tag and length are +skipped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB]\fR\fR +.ad +.RS 5n +.rt +End set. No parameter is required and no action is taken. +.RE + +.sp +.LP +The \fBber_get_int()\fR function tries to interpret the next element as an +integer, returning the result in \fInum\fR. The tag of whatever it finds is +returned on success, \fB-1\fR on failure. +.sp +.LP +The \fBber_get_stringb()\fR function is used to read an octet string into a +pre-allocated buffer. The \fIlen\fR 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 \fINULL\fR byte. +.sp +.LP +The \fBber_get_stringa()\fR function is used to allocate memory space into +which an octet string is read. +.sp +.LP +The \fBber_get_stringal()\fR function is used to allocate memory space into +which an octet string and its length are read. It takes a \fBstruct berval +**\fR, and returns the result in this parameter. +.sp +.LP +The \fBber_get_null()\fR function is used to read a \fINULL\fR element. It +returns the tag of the element it skips over. +.sp +.LP +The \fBber_get_boolean()\fR function is used to read a boolean value. It is +called the same way that \fBber_get_int()\fR is called. +.sp +.LP +The \fBber_get_bitstringa()\fR function is used to read a bitstring value. It +takes a \fBchar **\fR which will hold the allocated memory bits, followed by an +\fBunsigned long *\fR, which will point to the length (in bits) of the +bitstring returned. +.sp +.LP +The \fBber_first_element()\fR function is used to return the tag and length of +the first element in a set or sequence. It also returns in \fIlast\fR a magic +cookie parameter that should be passed to subsequent calls to +\fBber_next_element()\fR, which returns similar information. +.sp +.LP +The \fBber_alloc_t()\fR function constructs and returns \fBBerElement\fR. A +null pointer is returned on error. The options field contains a bitwise-OR of +options which are to be used when generating the encoding of this +\fBBerElement\fR. One option is defined and must always be supplied: +.sp +.in +2 +.nf +#define LBER_USE_DER 0x01 +.fi +.in -2 + +.sp +.LP +When this option is present, lengths will always be encoded in the minimum +number of octets. Note that this option does not cause values of sets and +sequences to be rearranged in tag and byte order, so these functions are not +suitable for generating DER output as defined in X.509 and X.680 +.sp +.LP +The \fBber_init\fR function constructs a \fBBerElement\fR and returns a new +\fBBerElement\fR containing a copy of the data in the \fIbv\fR argument. The +\fBber_init\fR function returns the null pointer on error. +.sp +.LP +The \fBber_free()\fR function frees a \fBBerElement\fR which is returned from +the API calls \fBber_alloc_t()\fR or \fBber_init()\fR. Each \fBBerElement\fR +must be freed by the caller. The second argument \fIfreebuf\fR should always be +set to 1 to ensure that the internal buffer used by the BER functions is freed +as well as the \fBBerElement\fR container itself. +.sp +.LP +The \fBber_bvdup()\fR function returns a copy of a \fIberval\fR. The +\fIbv_val\fR field in the returned \fIberval\fR points to a different area of +memory as the \fIbv_val\fR field in the argument \fIberval\fR. The null pointer +is returned on error (that is, is out of memory). +.sp +.LP +The \fBber_flatten()\fR function allocates a \fBstruct berval\fR whose +contents are BER encoding taken from the \fIber\fR argument. The \fIbvPtr\fR +pointer points to the returned \fIberval\fR, which must be freed using +\fBber_bvfree()\fR. This function returns \fB0\fR on success and \fB\(mi1\fR +on error. +.SH EXAMPLES +.LP +\fBExample 1 \fRAssume the variable \fIber\fR contains a lightweight BER +encoding of the following ASN.1 object: +.sp +.in +2 +.nf + AlmostASearchRequest := SEQUENCE { + baseObject DistinguishedName, + scope ENUMERATED { + baseObject (0), + singleLevel (1), + wholeSubtree (2) + }, + derefAliases ENUMERATED { + neverDerefaliases (0), + derefInSearching (1), + derefFindingBaseObj (2), + alwaysDerefAliases (3N) + }, + sizelimit INTEGER (0 .. 65535), + timelimit INTEGER (0 .. 65535), + attrsOnly BOOLEAN, + attributes SEQUENCE OF AttributeType + } +.fi +.in -2 + +.LP +\fBExample 2 \fRThe element can be decoded using \fBber_scanf()\fR as follows. +.sp +.in +2 +.nf + int scope, ali, size, time, attrsonly; + char *dn, **attrs; + if ( ber_scanf( ber, "{aiiiib{v}}", &dn, &scope, &ali, + &size, &time, &attrsonly, &attrs ) == -1 ) + /* error */ + else + /* success */ +.fi +.in -2 + +.SH ERRORS +.sp +.LP +If an error occurs during decoding, generally these functions return +\fB\(mi1\fR\&. +.SH NOTES +.sp +.LP +The return values for all of these functions are declared in the \fB<lber.h>\fR +header. Some functions may allocate memory which must be freed by the calling +application. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBber_encode\fR(3LDAP), \fBattributes\fR(5) +.sp +.LP +Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access +Protocol", OSI-DS-26, April 1992. +.sp +.LP +Information Processing - Open Systems Interconnection - Model and Notation - +Service Definition - Specification of Basic Encoding Rules for Abstract Syntax +Notation One, International Organization for Standardization, International +Standard 8825. diff --git a/usr/src/man/man3ldap/ber_encode.3ldap b/usr/src/man/man3ldap/ber_encode.3ldap new file mode 100644 index 0000000000..7ef161e186 --- /dev/null +++ b/usr/src/man/man3ldap/ber_encode.3ldap @@ -0,0 +1,392 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ber_encode 3LDAP "6 Oct 2008" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ber_encode, ber_alloc, 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 \- simplified Basic +Encoding Rules library encoding functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> + +\fBBerElement *\fR\fBber_alloc\fR(); +.fi + +.LP +.nf +\fB\fR\fBber_printf\fR(\fBBerElement\fR \fI*ber\fR, \fBchar\fR \fI**fmt\fR[, \fIarg\fR... ]); +.fi + +.LP +.nf +\fB\fR\fBber_put_int\fR(\fBBerElement\fR \fI*ber\fR, \fBlong\fR \fInum\fR, \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_put_ostring\fR(\fBBerElement\fR \fI*ber\fR, \fBchar\fR \fI**str\fR, \fBunsigned long\fR \fIlen\fR, + \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_put_string\fR(\fBBerElement\fR \fI*ber\fR, \fBchar\fR \fI**str\fR, \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_put_null\fR(\fBBerElement\fR \fI*ber\fR, \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_put_boolean\fR(\fBBerElement\fR \fI*ber\fR, \fBint\fR \fIbool\fR, \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_put_bitstring\fR(\fBBerElement\fR \fI*ber\fR, \fBchar\fR \fI*str\fR, \fBint\fR \fIblen\fR, \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_start_seq\fR(\fBBerElement\fR \fI*ber\fR, \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_start_set\fR(\fBBerElement\fR \fI*ber\fR, \fBchar\fR \fItag\fR); +.fi + +.LP +.nf +\fB\fR\fBber_put_seq\fR(\fBBerElement\fR \fI*ber\fR); +.fi + +.LP +.nf +\fB\fR\fBber_put_set\fR(\fBBerElement\fR \fI*ber\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide a subfunction interface to a simplified implementation +of the Basic Encoding Rules of ASN.1. The version of BER these functions +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 functions 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 functions in the lber library. See \fBber_decode\fR(3LDAP) for +details on the corresponding decoding functions. +.sp +.LP +Normally, the only functions that need be called by an application are +\fBber_alloc()\fR, to allocate a \fBBER\fR element, and \fBber_printf()\fR to +do the actual encoding. The other functions are provided for those +applications that need more control than \fBber_printf()\fR provides. In +general, these functions return the length of the element encoded, or +\fB\(mi1\fR if an error occurred. +.sp +.LP +The \fBber_alloc()\fR function is used to allocate a new BER element. +.sp +.LP +The \fBber_printf()\fR function is used to encode a BER element in much the +same way that \fBsprintf(3S)\fR works. One important difference, though, is +that some state information is kept with the \fIber\fR parameter so that +multiple calls can be made to \fBber_printf()\fR to append things to the end +of the BER element. \fBBer_printf()\fR writes to \fIber\fR, a pointer to a +\fBBerElement\fR such as returned by \fBber_alloc()\fR. It interprets and +formats its arguments according to the format string \fBfmt\fR. The format +string can contain the following characters: +.sp +.ne 2 +.mk +.na +\fB\fBb\fR\fR +.ad +.RS 5n +.rt +Boolean. An integer parameter should be supplied. A boolean element is +output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB\fR\fR +.ad +.RS 5n +.rt +Bitstring. A \fBchar *\fR pointer to the start of the bitstring is supplied, +followed by the number of bits in the bitstring. A bitstring element is +output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBi\fR\fR +.ad +.RS 5n +.rt +Integer. An integer parameter should be supplied. An integer element is +output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBn\fR\fR +.ad +.RS 5n +.rt +Null. No parameter is required. A null element is output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBo\fR\fR +.ad +.RS 5n +.rt +Octet string. A \fBchar *\fR is supplied, followed by the length of the string +pointed to. An octet string element is output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBO\fR\fR +.ad +.RS 5n +.rt +Octet string. A \fBstruct berval *\fR is supplied. An octet string element is +output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 5n +.rt +Octet string. A null-terminated string is supplied. An octet string element +is output, not including the trailing null octet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBt\fR\fR +.ad +.RS 5n +.rt +Tag. An int specifying the tag to give the next element is provided. This +works across calls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBv\fR\fR +.ad +.RS 5n +.rt +Several octet strings. A null-terminated array of \fBchar *\fR is supplied. +Note that a construct like '{v}' is required to get an actual sequence of octet +strings. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB{\fR\fR +.ad +.RS 5n +.rt +Begin sequence. No parameter is required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB}\fR\fR +.ad +.RS 5n +.rt +End sequence. No parameter is required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB[\fR\fR +.ad +.RS 5n +.rt +Begin set. No parameter is required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB]\fR\fR +.ad +.RS 5n +.rt +End set. No parameter is required. +.RE + +.sp +.LP +The \fBber_put_int()\fR function writes the integer element \fInum\fR to the +BER element \fIber\fR. +.sp +.LP +The \fBber_put_boolean()\fR function writes the boolean value given by +\fIbool\fR to the BER element. +.sp +.LP +The \fBber_put_bitstring()\fR function writes \fIblen\fR bits starting at +\fIstr\fR as a bitstring value to the given BER element. Note that \fIblen\fR +is the length in \fIbits\fR of the bitstring. +.sp +.LP +The \fBber_put_ostring()\fR function writes \fIlen\fR bytes starting at +\fIstr\fR to the BER element as an octet string. +.sp +.LP +The \fBber_put_string()\fR function writes the null-terminated string (minus +the terminating '') to the BER element as an octet string. +.sp +.LP +The \fBber_put_null()\fR function writes a \fINULL\fR element to the BER +element. +.sp +.LP +The \fBber_start_seq()\fR function is used to start a sequence in the BER +element. The \fBber_start_set()\fR function works similarly. The end of the +sequence or set is marked by the nearest matching call to \fBber_put_seq()\fR +or \fBber_put_set()\fR, respectively. +.sp +.LP +The \fBber_first_element()\fR function is used to return the tag and length of +the first element in a set or sequence. It also returns in \fIcookie\fR a +magic cookie parameter that should be passed to subsequent calls to +\fBber_next_element()\fR, which returns similar information. +.SH EXAMPLES +.LP +\fBExample 1 \fRAssuming the following variable declarations, and that the +variables have been assigned appropriately, an BER encoding of the following +ASN.1 object: +.sp +.in +2 +.nf + AlmostASearchRequest := SEQUENCE { + baseObject DistinguishedName, + scope ENUMERATED { + baseObject (0), + singleLevel (1), + wholeSubtree (2) + }, + derefAliases ENUMERATED { + neverDerefaliases (0), + derefInSearching (1), + derefFindingBaseObj (2), + alwaysDerefAliases (3N) + }, + sizelimit INTEGER (0 .. 65535), + timelimit INTEGER (0 .. 65535), + attrsOnly BOOLEAN, + attributes SEQUENCE OF AttributeType + } +.fi +.in -2 + +.sp +.LP +can be achieved like so: +.sp +.in +2 +.nf + 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 */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +If an error occurs during encoding, \fBber_alloc()\fR returns \fINULL\fR; other +functions generally return \fB\(mi1\fR\&. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBber_decode\fR(3LDAP), \fBattributes\fR(5) +.sp +.LP +Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access +Protocol", OSI-DS-26, April 1992. +.sp +.LP +Information Processing - Open Systems Interconnection - Model and Notation - +Service Definition - Specification of Basic Encoding Rules for Abstract Syntax +Notation One, International Organization for Standardization, International +Standard 8825. +.SH NOTES +.sp +.LP +The return values for all of these functions are declared in \fB<lber.h>\fR. diff --git a/usr/src/man/man3ldap/cldap_close.3ldap b/usr/src/man/man3ldap/cldap_close.3ldap new file mode 100644 index 0000000000..a85fefd31d --- /dev/null +++ b/usr/src/man/man3ldap/cldap_close.3ldap @@ -0,0 +1,58 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cldap_close 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +cldap_close \- dispose of connectionless LDAP pointer +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBvoid\fR \fBcldap_close\fR(\fBLDAP\fR \fI*ld\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcldap_close()\fR function disposes of memory allocated by +\fBcldap_open\fR(3LDAP). It should be called when all CLDAP communication is +complete. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIld\fR \fR +.ad +.RS 7n +.rt +The LDAP pointer returned by a previous call to \fBcldap_open\fR(3LDAP). +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBcldap_open\fR(3LDAP), \fBcldap_search_s\fR(3LDAP), +\fBcldap_setretryinfo\fR(3LDAP) diff --git a/usr/src/man/man3ldap/cldap_open.3ldap b/usr/src/man/man3ldap/cldap_open.3ldap new file mode 100644 index 0000000000..ba9bdf9631 --- /dev/null +++ b/usr/src/man/man3ldap/cldap_open.3ldap @@ -0,0 +1,84 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cldap_open 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +cldap_open \- LDAP connectionless communication preparation +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBLDAP *\fR\fBcldap_open\fR(\fBchar\fR \fI*host\fR, \fBint\fR \fIport\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhost\fR\fR +.ad +.RS 8n +.rt +The name of the host on which the LDAP server is running. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIport\fR\fR +.ad +.RS 8n +.rt +The port number to connect. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBcldap_open()\fR function is called to prepare for connectionless LDAP +communication (over \fBudp\fR(7P)). It allocates an LDAP structure which is +passed to future search requests. +.sp +.LP +If the default IANA-assigned port of 389 is desired, \fBLDAP_PORT\fR should be +specified for \fIport\fR. \fIhost\fR can contain a space-separated list of +hosts or addresses to try. \fBcldap_open()\fR returns a pointer to an LDAP +structure, which should be passed to subsequent calls to +\fBcldap_search_s\fR(3LDAP), \fBcldap_setretryinfo\fR(3LDAP), and +\fBcldap_close\fR(3LDAP). Certain fields in the LDAP structure can be set to +indicate size limit, time limit, and how aliases are handled during operations. +See \fBldap_open\fR(3LDAP) and \fB<ldap.h>\fR for more details. +.SH ERRORS +.sp +.LP +If an error occurs, \fBcldap_open()\fR will return \fINULL\fR and \fBerrno\fR +will be set appropriately. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP) \fBcldap_search_s\fR(3LDAP), \fBcldap_setretryinfo\fR(3LDAP), +\fBcldap_close\fR(3LDAP), \fBattributes\fR(5), \fBudp\fR(7P) diff --git a/usr/src/man/man3ldap/cldap_search_s.3ldap b/usr/src/man/man3ldap/cldap_search_s.3ldap new file mode 100644 index 0000000000..3128485063 --- /dev/null +++ b/usr/src/man/man3ldap/cldap_search_s.3ldap @@ -0,0 +1,157 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cldap_search_s 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +cldap_search_s \- connectionless LDAP search +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBcldap_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR, + \fBchar\fR \fI*attrs\fR, \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR, \fBchar\fR \fI*logdn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcldap_search_s()\fR function performs an LDAP search using the +Connectionless LDAP (CLDAP) protocol. +.sp +.LP +\fBcldap_search_s()\fR has parameters and behavior identical to that of +\fBldap_search_s\fR(3LDAP), except for the addition of the \fIlogdn\fR +parameter. \fIlogdn\fR 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 \fIRFC 1779, A String Representation of Distinguished Names\fR. +.SS "Retransmission Algorithm" +.sp +.LP +\fBcldap_search_s()\fR operates using the CLDAP protocol over \fBudp\fR(7P). +Since UDP is a non-reliable protocol, a retry mechanism is used to increase +reliability. The \fBcldap_setretryinfo\fR(3LDAP) function can be used to set +two retry parameters: \fItries\fR, a count of the number of times to send a +search request and \fItimeout\fR, an initial timeout that determines how long +to wait for a response before re-trying. \fItimeout\fR is specified seconds. +These values are stored in the \fBld_cldaptries\fR and \fBld_cldaptimeout\fR +members of the \fBld\fR LDAP structure, and the default values set in +\fBldap_open\fR(3LDAP) are 4 and 3 respectively. The retransmission algorithm +used is: +.sp +.ne 2 +.mk +.na +\fBStep 1\fR +.ad +.RS 10n +.rt +Set the current timeout to \fBld_cldaptimeout\fR seconds, and the current LDAP +server address to the first LDAP server found during the \fBldap_open\fR(3LDAP) +call. +.RE + +.sp +.ne 2 +.mk +.na +\fBStep 2\fR +.ad +.RS 10n +.rt +Send the search request to the current LDAP server address. +.RE + +.sp +.ne 2 +.mk +.na +\fBStep 3\fR +.ad +.RS 10n +.rt +Set the wait timeout to the current timeout divided by the number of server +addresses found during \fBldap_open\fR(3LDAP) or to one second, whichever is +larger. Wait at most that long for a response; if a response is received, STOP. +Note that the wait timeout is always rounded down to the next lowest second. +.RE + +.sp +.ne 2 +.mk +.na +\fBStep 4\fR +.ad +.RS 10n +.rt +Repeat steps 2 and 3 for each LDAP server address. +.RE + +.sp +.ne 2 +.mk +.na +\fBStep 5\fR +.ad +.RS 10n +.rt +Set the current timeout to twice its previous value and repeat Steps 2 through +5 a maximum of \fItries\fR times. +.RE + +.SH EXAMPLES +.sp +.LP +Assume that the default values for \fItries\fR and \fItimeout\fR 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 \fBcldap_open\fR(3LDAP). The pattern of +requests sent will be (stopping as soon as a response is received): +.sp +.in +2 +.nf + 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) +.fi +.in -2 + +.SH ERRORS +.sp +.LP +\fBcldap_search_s()\fR returns \fBLDAP_SUCCESS\fR if a search was successful +and the appropriate LDAP error code otherwise. See \fBldap_error\fR(3LDAP) for +more information. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBldap_search_s\fR(3LDAP), +\fBcldap_open\fR(3LDAP), \fBcldap_setretryinfo\fR(3LDAP), +\fBcldap_close\fR(3LDAP), \fBattributes\fR(5), \fBudp\fR(7P) diff --git a/usr/src/man/man3ldap/cldap_setretryinfo.3ldap b/usr/src/man/man3ldap/cldap_setretryinfo.3ldap new file mode 100644 index 0000000000..ddf719bb72 --- /dev/null +++ b/usr/src/man/man3ldap/cldap_setretryinfo.3ldap @@ -0,0 +1,82 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cldap_setretryinfo 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +cldap_setretryinfo \- set connectionless LDAP request retransmission parameters +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBvoid\fR \fBcldap_setretryinfo\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fItries\fR, \fBint\fR \fItimeout\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIld\fR \fR +.ad +.RS 12n +.rt +LDAP pointer returned from a previous call to \fBcldap_open\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItries\fR \fR +.ad +.RS 12n +.rt +Maximum number of times to send a request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeout\fR \fR +.ad +.RS 12n +.rt +Initial time, in seconds, to wait before re-sending a request. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBcldap_setretryinfo()\fR function is used to set the CLDAP request +retransmission behavior for future \fBcldap_search_s\fR(3LDAP) calls. The +default values (set by \fBcldap_open\fR(3LDAP)) are 4 tries and 3 seconds +between tries. See \fBcldap_search_s\fR(3LDAP) for a complete description of +the retransmission algorithm used. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBcldap_open\fR(3LDAP), \fBcldap_search_s\fR(3LDAP), +\fBcldap_close\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap.3ldap b/usr/src/man/man3ldap/ldap.3ldap new file mode 100644 index 0000000000..b0a42395ef --- /dev/null +++ b/usr/src/man/man3ldap/ldap.3ldap @@ -0,0 +1,1751 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap \- Lightweight Directory Access Protocol package +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> +.fi + +.SH DESCRIPTION +.sp +.LP +The Lightweight Directory Access Protocol ("LDAP") package (SUNWlldap) includes +various command line LDAP clients and a LDAP client library to provide +programmatic access to the LDAP protocol. This man page gives an overview of +the LDAP client library functions. +.sp +.LP +An application might use the LDAP client library functions as follows. The +application would initialize a LDAP session with a LDAP server by calling +\fBldap_init\fR(3LDAP). Next, it authenticates to the LDAP server by calling +\fBldap_sasl_bind\fR(3LDAP) and friends. It may perform some LDAP operations +and obtain results by calling \fBldap_search\fR(3LDAP) and friends. To parse +the results returned from these functions, it calls +\fBldap_parse_result\fR(3LDAP),\fBldap_next_entry\fR(3LDAP), and +\fBldap_first_entry\fR(3LDAP) and others. It closes the LDAP session by calling +\fBldap_unbind\fR(3LDAP). +.sp +.LP +LDAP operations can be either synchronous or asynchronous. By convention, the +names of the sychronous functions end with "_s." For example, a synchronous +binding to the LDAP server can be performed by calling +\fBldap_sasl_bind_s\fR(3LDAP). Complete an asynchronous binding with +\fBldap_sasl_bind\fR(3LDAP). All synchronous functions return the actual +outcome of the operation, either \fBLDAP_SUCCESS\fR or an error code. +Asynchronous routines provide an invocation identifier which can be used to +obtain the result of a specific operation by passing it to +the\fBldap_result\fR(3LDAP) function. +.SS "Initializing a LDAP session" +.sp +.LP +Initializing a LDAP session involves calling the \fBldap_init\fR(3LDAP) +function. However, the call does not actually open a connection to the LDAP +server. It merely initializes a LDAP structure that represents the session. The +connection is opened when the first operation is attempted. Unlike +\fBldap_init()\fR, \fBldap_open\fR(3LDAP) attempts to open a connection with +the LDAP server. However, the use of \fBldap_open()\fR is deprecated. +.SS "Authenticating to a LDAP server" +.sp +.LP +The \fBldap_sasl_bind\fR(3LDAP) and \fBldap_sasl_bind_s\fR(3LDAP) functions +provide general and extensible authenticaton for an LDAP client to a LDAP +server. Both use the Simple Authentication Security Layer (SASL). Simplified +routines \fBldap_simple_bind\fR(3LDAP) and \fBldap_simple_bind_s\fR(3LDAP) use +cleartext passwords to bind to the LDAP server. Use of \fBldap_bind\fR(3LDAP) +and \fBldap_bind_s\fR(3LDAP)(3LDAP) is deprecated. +.SS "Searching a LDAP directory" +.sp +.LP +Search for an entry in a LDAP directory by calling the +\fBldap_search_ext\fR(3LDAP) or the \fBldap_search_ext_s\fR(3LDAP) functions. +These functions support LDAPv3 server controls, client controls and variable +size and time limits as arguments for each search operation. +\fBldap_search\fR(3LDAP) and \fBldap_search_s\fR(3LDAP) are identical functions +but do not support the controls and limits as arguments to the call. +.SS "Adding or Deleting an entry" +.sp +.LP +Use \fBldap_add_ext\fR(3LDAP) and \fBldap_delete_ext\fR(3LDAP) to add or delete +entries in a LDAP directory server. The synchronous counterparts to these +functions are \fBldap_add_ext_s\fR(3LDAP) and \fBldap_delete_ext_s\fR(3LDAP). +The \fBldap_add\fR(3LDAP), \fBldap_add_s\fR(3LDAP), \fBldap_delete\fR(3LDAP), +and \fBldap_delete_s\fR(3LDAP) provide identical functionality to add and to +delete entries, but they do not support LDAP v3 server and client controls. +.SS "Modifying Entries" +.sp +.LP +Use \fBldap_modify_ext\fR(3LDAP) and \fBldap_modify_ext_s\fR(3LDAP) to modify +an existing entry in a LDAP server that supports for LDAPv3 server and client +controls. Similarly, use \fBldap_rename\fR(3LDAP) and +\fBldap_rename_s\fR(3LDAP) to change the name of an LDAP entry. The +\fBldap_modrdn\fR(3LDAP), \fBldap_modrdn_s\fR(3LDAP), \fBldap_modrdn2\fR(3LDAP) +and \fBldap_modrdn2_s\fR(3LDAP) interfaces are deprecated. +.SS "Obtaining Results" +.sp +.LP +Use \fBldap_result\fR(3LDAP) to obtain the results of a previous asynchronous +operation. For all LDAP operations other than search, only one message is +returned. For the search operation, a list of result messages can be returned. +.SS "Handling Errors and Parsing Results" +.sp +.LP +Use the \fBldap_parse_result\fR(3LDAP), +\fBldap_parse_sasl_bind_result\fR(3LDAP), and the +\fBldap_parse_extended_result\fR(3LDAP) functions to extract required +information from results and and to handle the returned errors. To covert a +numeric error code into a null-terminated character string message describing +the error, use \fBldap_err2string\fR(3LDAP). The \fBldap_result2error\fR(3LDAP) +and \fBldap_perror\fR(3LDAP) functions are deprecated. To step through the list +of messages in a result returned by \fBldap_result()\fR, use +\fBldap_first_message\fR(3LDAP) and \fBldap_next_message\fR(3LDAP). +\fBldap_count_messages\fR(3LDAP) returns the number of messages contained in +the list. +.sp +.LP +You can use \fBldap_first_entry\fR(3LDAP) and \fBldap_next_entry\fR(3LDAP) to +step through and obtain a list of entries from a list of messages returned by a +search result. \fBldap_count_entries\fR(3LDAP) returns the number of entries +contained in a list of messages. Call either \fBldap_first_attribute\fR(3LDAP) +and \fBldap_next_attribute\fR(3LDAP) to step through a list of attributes +associated with an entry. Retrieve the values of a given attribute by calling +\fBldap_get_values\fR(3LDAP) and \fBldap_get_values_len\fR(3LDAP). Count the +number of values returned by using \fBldap_count_values\fR(3LDAP) and +\fBldap_count_values_len\fR(3LDAP). +.sp +.LP +Use the \fBldap_get_lang_values\fR(3LDAP) and +\fBldap_get_lang_values_len\fR(3LDAP) to return an attribute's values that +matches a specified language subtype. The \fBldap_get_lang_values()\fR function +returns an array of an attribute's string values that matches a specified +language subtype. To retrieve the binary data from an attribute, call the +\fBldap_get_lang_values_len()\fR function instead. +.SS "Uniform Resource Locators (URLS)" +.sp +.LP +You can use the \fBldap_url\fR(3LDAP)functions to test a URL to verify that it +is an LDAP URL, to parse LDAP URLs into their component pieces, to initiate +searches directly using an LDAP URL, and to retrieve the URL associated with a +DNS domain name or a distinguished name. +.SS "User Friendly Naming" +.sp +.LP +The \fBldap_ufn\fR(3LDAP) functions implement a user friendly naming scheme by +means of LDAP. This scheme allows you to look up entries using fuzzy, untyped +names like "mark smith, umich, us". +.SS "Caching" +.sp +.LP +The \fBldap_memcache\fR(3LDAP) functions provide an in-memory client side cache +to store search requests. Caching improves performance and reduces network +bandwidth when a client makes repeated requests. +.SS "Utility Functions" +.sp +.LP +There are also various utility functions. You can use the +\fBldap_sort\fR(3LDAP) functions are used to sort the entries and values +returned by means of the ldap search functions. The \fBldap_friendly\fR(3LDAP) +functions will map from short two letter country codes or other strings to +longer "friendlier" names. Use the \fBldap_charset\fR(3LDAP) functions to +translate to and from the T.61 character set that is used for many character +strings in the LDAP protocol. +.SS "Generating Filters" +.sp +.LP +Make calls to \fBldap_init_getfilter\fR(3LDAP) and \fBldap_search\fR(3LDAP) to +generate filters to be used in \fBldap_search\fR(3LDAP) and +\fBldap_search_s\fR(3LDAP). \fBldap_init_getfilter()\fR reads +\fBldapfilter.conf\fR(4), the LDAP configuration file, while +\fBldap_init_getfilter_buf()\fR reads the configuration information from +\fIbuf\fR of length \fIbuflen\fR. \fBldap_getfilter_free\fR(3LDAP) frees memory +that has been allocated by means of \fBldap_init_getfilter()\fR. +.SS "BER Library" +.sp +.LP +The LDAP package includes a set of lightweight Basic Encoding Rules ("BER)" +functions. The LDAP library functions use the BER functions to encode and +decode LDAP protocol elements through the slightly simplified BER defined by +LDAP. They are not normally used directly by an LDAP application program will +not normally use the BER functions directly. Instead, these functions provide a +\fBprintf()\fR and \fBscanf()\fR-like interface, as well as lower-level access. +.SH LIST OF INTERFACES +.sp +.ne 2 +.mk +.na +\fB\fBldap_open\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_init\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_init\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Initialize a session with a LDAP server without opening a connection to a +server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_result\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Obtain the result from a previous asynchronous operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_abandon\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Abandon or abort an asynchronous operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_add\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously add an entry +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_add_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously add an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_add_ext\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously add an entry with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_add_ext_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously add an entry with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_bind\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_sasl_bind\fR(3LDAP) or \fBldap_simple_bind\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_sasl_bind\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously bind to the directory using SASL authentication +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_sasl_bind_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously bind to the directory using SASL authentication +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_bind_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_sasl_bind_s\fR(3LDAP) or +\fBldap_simple_bind_s\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_simple_bind\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously bind to the directory using simple authentication. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_simple_bind_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously bind to the directory using simple authentication. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_unbind\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously unbind from the LDAP server, close the connection, and dispose +the session handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_unbind_ext\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously unbind from the LDAP server and close the connection. +\fBldap_unbind_ext()\fR allows you to explicitly include both server and client +controls in the unbind request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_set_rebind_proc\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Set callback function for obtaining credentials from a referral. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_memcache_init\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Create the in-memory client side cache. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_memcache_set\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Associate an in-memory cache that has been already created by calling the +\fBldap_memcache_init\fR(3LDAP) function with an LDAP connection handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_memcache_get\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Get the cache associated with the specified LDAP structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_memcache_flush\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Flushes search requests from the cache. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_memcache_destroy\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Frees the specified \fBLDAPMemCache\fR structure pointed to by cache from +memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_memcache_update\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Checks the cache for items that have expired and removes them. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_compare\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronous compare with a directory entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_compare_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronous compare with a directory entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_compare_ext\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronous compare with a directory entry, with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_compare_ext_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronous compare with a directory entry, with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_control_free\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Dispose of an LDAP control. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_controls_free\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Dispose of an array of LDAP controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_delete\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously delete an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_delete_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously delete an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_delete_ext\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously delete an entry, with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_delete_ext_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously delete an entry, with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_init_templates\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Read a sequence of templates from a LDAP template configuration file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_init_templates_buf\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Read a sequence of templates from a buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_free_templates\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Dispose of the templates allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_reference\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Step through a list of continuation references from a search result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_reference\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Step through a list of continuation references from a search result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_count_references\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Count the number of messages in a search result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_message\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Step through a list of messages in a search result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_count_messages\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Count the messages in a list of messages in a search result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_message\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Step through a list of messages in a search result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_msgtype\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return the type of LDAP message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_disptmpl\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Get first display template in a list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_disptmpl\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Get next display template in a list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_oc2template\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return template appropriate for the objectclass. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_name2template\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return named template +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_tmplattrs\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return attributes needed by the template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_tmplrow\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return first row of displayable items in a template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_tmplrow\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return next row of displayable items in a template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_tmplcol\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return first column of displayable items in a template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_tmplcol\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return next column of displayable items in a template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_entry2text\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Display an entry as text by using a display template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_entry2text_search\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Search for and display an entry as text by using a display template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_vals2text\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Display values as text. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_entry2html\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Display an entry as HTML (HyperText Markup Language) by using a display +template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_entry2html_search\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Search for and display an entry as HTML by using a display template. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_vals2html\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Display values as HTML. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_perror\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_parse_result\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_result2error\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_parse_result\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_err2string\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Convert LDAP error indication to a string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_attribute\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return first attribute name in an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_attribute\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return next attribute name in an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_entry\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return first entry in a chain of search results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_entry\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return next entry in a chain of search results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_count_entries\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return number of entries in a search result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_friendly_name\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Map from unfriendly to friendly names. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_free_friendlymap\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free resources used by \fBldap_friendly\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_get_dn\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Extract the DN from an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_explode_dn\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Convert a DN into its component parts. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_explode_dns\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Convert a DNS-style DN into its component parts (experimental). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_is_dns_dn\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Check to see if a DN is a DNS-style DN (experimental). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_dns_to_dn\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Convert a DNS domain name into an X.500 distinguished name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_dn2ufn\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Convert a DN into user friendly form. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_get_values\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return an attribute's values. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_get_values_len\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return an attribute's values with lengths. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_value_free\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free memory allocated by \fBldap_get_values\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_value_free_len\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free memory allocated by \fBldap_get_values_len\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_count_values\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return number of values. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_count_values_len\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return number of values. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_init_getfilter\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Initialize getfilter functions from a file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_init_getfilter_buf\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Initialize getfilter functions from a buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_getfilter_free\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free resources allocated by \fBldap_init_getfilter\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_getfirstfilter\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return first search filter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_getnextfilter\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return next search filter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_build_filter\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Construct an LDAP search filter from a pattern. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_setfilteraffixes\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Set prefix and suffix for search filters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modify\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously modify an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modify_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously modify an entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modify_ext\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously modify an entry, return value, and place message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modify_ext_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously modify an entry, return value, and place message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_mods_free\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free array of pointers to mod structures used by \fBldap_modify\fR(3LDAP). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modrdn2\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_rename\fR(3LDAP) instead. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modrdn2_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_rename_s\fR(3LDAP) instead. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modrdn\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Deprecated. Use \fBldap_rename\fR(3LDAP) instead. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_modrdn_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Depreciated. Use \fBldap_rename_s\fR(3LDAP) instead. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_rename\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously modify the name of an LDAP entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_rename_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously modify the name of an LDAP entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_msgfree\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free result messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_parse_result\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Search for a message to parse. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_parse_extended_result\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Search for a message to parse. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_parse_sasl_bind_result\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Search for a message to parse. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_search\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously search the directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_search_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously search the directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_search_ext\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously search the directory with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_search_ext_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously search the directory with support for LDAPv3 controls. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_search_st\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously search the directory with support for a local timeout value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_ufn_search_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +User friendly search the directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_ufn_search_c\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +User friendly search the directory with cancel. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_ufn_search_ct\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +User friendly search the directory with cancel and timeout. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_ufn_setfilter\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Set filter file used by \fBldap_ufn\fR(3LDAP) functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_ufn_setprefix\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Set prefix used by \fBldap_ufn\fR(3LDAP) functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_ufn_timeout\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Set timeout used by \fBldap_ufn\fR(3LDAP) functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_is_ldap_url\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Check a URL string to see if it is an LDAP URL. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_url_parse\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Break up an LDAP URL string into its components. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_free_urldesc\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free an LDAP URL structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_url_search\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously search by using an LDAP URL. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_url_search_s\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Synchronously search by using an LDAP URL. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_url_search_st\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Asynchronously search by using an LDAP URL, with support for a local timeout +value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_dns_to_url\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Locate the LDAP URL associated with a DNS domain name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_dn_to_url\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Locate the LDAP URL associated with a distinguished name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_init_searchprefs\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Initialize searchprefs functions from a file. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_init_searchprefs_buf\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Initialize searchprefs functions from a buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_free_searchprefs\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free memory allocated by searchprefs functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_first_searchobj\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return first searchpref object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_next_searchobj\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return next searchpref object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_sort_entries\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Sort a list of search results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_sort_values\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Sort a list of attribute values. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_sort_strcasecmp\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Case insensitive string comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_set_string_translators\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Set character set translation functions used by LDAP library. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_translate_from_t61\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Translate from the T.61 character set to another character set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_translate_to_t61\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Translate to the T.61 character set from another character set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_enable_translation\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Enable or disable character translation for an LDAP entry result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_version\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Get version information about the LDAP SDK for C. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_get_lang_values\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return an attribute's value that matches a specified language subtype. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_get_lang_values_len\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Return an attribute's value that matches a specified language subtype along +with lengths. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_get_entry_controls\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Get the LDAP controls included with a directory entry in a set of search +results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_get_option\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Get session preferences in an LDAP structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_set_option\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Set session preferences in an LDAP structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldap_memfree\fR(3LDAP)\fR +.ad +.sp .6 +.RS 4n +Free memory allocated by LDAP API functions. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Stability LevelEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_abandon.3ldap b/usr/src/man/man3ldap/ldap_abandon.3ldap new file mode 100644 index 0000000000..30861200a0 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_abandon.3ldap @@ -0,0 +1,61 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_abandon 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_abandon \- abandon an LDAP operation in progress +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_abandon\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fImsgid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_abandon()\fR function is used to abandon or cancel an LDAP +operation in progress. The \fImsgid\fR passed should be the message id of an +outstanding LDAP operation, as returned by \fBldap_search\fR(3LDAP), +\fBldap_modify\fR(3LDAP), etc. +.sp +.LP +\fBldap_abandon\fR(\|) 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. +.sp +.LP +The caller can expect that the result of an abandoned operation will not be +returned from a future call to \fBldap_result\fR(3LDAP). +.SH ERRORS +.sp +.LP +\fBldap_abandon()\fR returns \fB0\fR if successful or \fB\(mi1\fRotherwise and +setting \fIld_errno\fR appropriately. See \fBldap_error\fR(3LDAP) for details. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_result\fR(3LDAP), \fBldap_error\fR(3LDAP), +\fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_add.3ldap b/usr/src/man/man3ldap/ldap_add.3ldap new file mode 100644 index 0000000000..c8e67be673 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_add.3ldap @@ -0,0 +1,97 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_add 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_add, ldap_add_s, ldap_add_ext, ldap_add_ext_s \- perform an LDAP add +operation +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR\fBldap_add\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*attrs\fR[]); +.fi + +.LP +.nf +\fBint\fR\fBldap_add_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*attrs\fR[]); +.fi + +.LP +.nf +\fBint\fR \fBldap_add_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**attrs\fR, + \fBLDAPControl\fR \fI**serverctrls\fR,\ \fBint\fR \fI* msgidp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_add_ext_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**attrs\fR, + \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_add_s()\fR function is used to perform an LDAP add operation. It +takes \fIdn\fR, the DN of the entry to add, and \fIattrs\fR, a null-terminated +array of the entry's attributes. The LDAPMod structure is used to represent +attributes, with the \fImod_type\fR and \fImod_values\fR fields being used as +described under \fBldap_modify\fR(3LDAP), and the \fIldap_op\fR field being +used only if you need to specify the \fBLDAP_MOD_BVALUES\fR option. Otherwise, +it should be set to zero. +.sp +.LP +Note that all entries except that specified by the last component in the given +DN must already exist. \fBldap_add_s()\fR returns an LDAP error code indicating +success or failure of the operation. See \fBldap_error\fR(3LDAP) for more +details. +.sp +.LP +The \fBldap_add()\fR function works just like \fBldap_add_s()\fR, but it is +asynchronous. It returns the message id of the request it initiated. The +result of this operation can be obtained by calling \fBldap_result\fR(3LDAP). +.sp +.LP +The \fBldap_add_ext()\fR function initiates an asynchronous add operation and +returns \fBLDAP_SUCCESS\fR if the request was successfully sent to the server, +or else it returns a LDAP error code if not (see \fBldap_error\fR(3LDAP)). If +successful, \fBldap_add_ext()\fR \fBplaces\fR \fBthe\fR \fBmessage\fR \fBid\fR +\fBof\fR \fI*msgidp\fR. A subsequent call to \fBldap_result()\fR, can be used +to obtain the result of the add request. +.sp +.LP +The \fBldap_add_ext_s()\fR function initiates a synchronous add operation and +returns the result of the operation itself. +.SH ERRORS +.sp +.LP +\fBldap_add()\fR returns \fB\(mi1\fR in case of error initiating the request, +and will set the \fIld_errno\fR field in the \fIld\fR parameter to indicate the +error. \fBldap_add_s()\fR will return an LDAP error code directly. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBldap_modify\fR(3LDAP), +\fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_ber_free.3ldap b/usr/src/man/man3ldap/ldap_ber_free.3ldap new file mode 100644 index 0000000000..9bd3576cee --- /dev/null +++ b/usr/src/man/man3ldap/ldap_ber_free.3ldap @@ -0,0 +1,59 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_ber_free 3LDAP "25 Oct 2001" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_ber_free \- free a BerElement structure from memory +.SH SYNOPSIS +.LP +.nf +\fBcc \fR\fB-flag \&.\|.\|.\fR \fIfile \fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR] +#include <ldap.h> + +\fBvoid\fR \fBldap_ber_free\fR(\fBBerElement *\fR\fIber\fR, \fBint\fR \fIfreebuf\fR +.fi + +.SH DESCRIPTION +.sp +.LP +You can make a call to the \fBldap_ber_free()\fR function to free +\fBBerElement\fR structures allocated by \fBldap_first_attribute()\fR and by +\fBldap_next_attribute()\fR function calls. When freeing structures allocated +by these functions, specify 0 for the \fIfreebuf\fR argument. The +\fBldap_first_attribute()\fR and by \fBldap_next_attribute()\fR functions do +not allocate the extra buffer in the \fBBerElement\fR structure. +.sp +.LP +For example, to retrieve attributes from a search result entry, you need to +call the \fBldap_first_attribute()\fR function. A call to this function +allocates a \fBBerElement\fR structure, which is used to help track the current +attribute. When you are done working with the attributes, this structure should +be freed from memory, if it still exists. +.sp +.LP +This function is deprecated . Use the \fBber_free()\fR function instead. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBber_free\fR(3LDAP), \fBldap_first_attribute\fR(3LDAP), +\fBldap_next_attribute\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_bind.3ldap b/usr/src/man/man3ldap/ldap_bind.3ldap new file mode 100644 index 0000000000..cb3dd5c988 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_bind.3ldap @@ -0,0 +1,245 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_bind 3LDAP "14 Jan 2004" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_bind, ldap_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_simple_bind, +ldap_simple_bind_s, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, +ldap_set_rebind_proc, ldap_sasl_interactive_bind_s \- LDAP bind functions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... -lldap [ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIcred\fR, \fBint\fR \fImethod\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIcred\fR, \fBint\fR \fImethod\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_simple_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIpasswd\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_simple_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIwho\fR, \fBchar *\fR\fIpasswd\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_unbind\fR(\fBLDAP *\fR\fIld\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_unbind_s\fR(\fBLDAP *\fR\fIld\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_unbind_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPControl **\fR\fIserverctrls\fR, + \fBLDAPControl **\fR\fIclientctrls\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_set_rebind_proc\fR(\fBLDAP\fR \fI*ld\fR, \fBint (*\fR\fIrebindproc\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_sasl_bind\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIdn\fR, \fBchar *\fR\fImechanism\fR, + \fBstruct berval **\fR\fIserverctrls\fR, \fBLDAPControl **\fR\fIclientctrls\fR, + \fBint *\fR\fImsgidp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_sasl_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIdn\fR, \fBchar *\fR\fImechanism\fR, + \fBstruct berval *\fR\fIcred\fR, \fBLDAPControl **\fR\fIserverctrls\fR, + \fBLDAPControl **\fR\fIclientctrls\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_sasl_interactive_bind_s\fR(\fBLDAP *\fR\fIld\fR, \fBchar *\fR\fIdn\fR, + \fBchar *\fR\fIsaslMechanism\fR, \fBLDAPControl **\fR\fIsctrl\fR, \fBLDAPControl **\fR\fIcctrl\fR, + \fBLDAPControl **\fR\fIunsigned flags\fR, \fBLDAP_SASL_INTERACT_PROC *\fR\fIcallback\fR, + \fBvoid *\fR\fIdefaults\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide various interfaces to the LDAP bind operation. After a +connection is made to an LDAP server, the \fBldap_bind()\fR function returns +the message ID of the request initiated. The \fBldap_bind_s()\fR function +returns an LDAP error code. +.SS "Simple Authentication" +.sp +.LP +The simplest form of the bind call is \fBldap_simple_bind_s()\fR. The function +takes the DN (Distinguished Name) of the \fIdn\fR parameter and the +\fBuserPassword\fR associated with the entry in \fIpasswd\fR to return an LDAP +error code. See \fBldap_error\fR(3LDAP). +.sp +.LP +The \fBldap_simple_bind()\fR call is asynchronous. The function takes the same +parameters as \fBldap_simple_bind_s()\fR but initiates the bind operation and +returns the message ID of the request sent. The result of the operation can be +obtained by a subsequent call to \fBldap_result\fR(3LDAP). +.SS "General Authentication" +.sp +.LP +The \fBldap_bind()\fR and \fBldap_bind_s()\fR functions are used to select the +authentication method at runtime. Both functions take an extra \fImethod\fR +parameter to set the authentication method. For simple authentication, the +\fImethod\fR parameter is set to \fBLDAP_AUTH_SIMPLE\fR. The \fBldap_bind()\fR +function returns the message id of the request initiated. The +\fBldap_bind_s()\fR function returns an LDAP error code. +.SS "SASL Authentication" +.sp +.LP +The \fBldap_sasl_bind()\fR and \fBldap_sasl_bind_s()\fR functions are used for +general and extensible authentication over LDAP through the use of the Simple +Authentication Security Layer. The routines both take the \fBDN\fR to bind as +the authentication method. A dotted-string representation of an OID identifies +the method, and the \fBberval\fR structure holds the credentials. The special +constant value \fBLDAP_SASL_SIMPLE\fR ("") can be passed to request simple +authentication. Otherwise, the \fBldap_simple_bind()\fR function or the +\fBldap_simple_bind_s()\fR function can be used. +.sp +.LP +The \fBldap_sasl_interactive_bind_s()\fR helper function takes its data and +performs the necessary \fBldap_sasl_bind()\fR and associated SASL library +authentication sequencing with the LDAP server that uses the provided +connection (\fIld\fR). +.sp +.LP +Upon a successful bind, the \fBldap_sasl_bind()\fR function will, if negotiated +by the SASL interface, install the necessary internal \fBlibldap\fR plumbing to +enable SASL integrity and privacy (over the wire encryption) with the LDAP +server. +.sp +.LP +The \fBLDAP_SASL_INTERACTIVE\fR option flag is passed to the libldap API +through the flags argument of the API. The flag tells the API to use the SASL +interactive mode and to have the API request SASL authentication data through +the \fBLDAP_SASL_INTERACTIVE_PROC\fR callback as needed. The callback provided +is in the form: +.sp +.in +2 +.nf +typedef int (LDAP_SASL_INTERACT_PROC) + (LDAP *ld, unsigned flags, void* defaults, void *interact); +.fi +.in -2 +.sp + +.sp +.LP +The user-provided SASL callback is passed to the current LDAP connection +pointer, the current flags field, an optional pointer to user-defined data, and +the list of \fBsasl_interact_t\fR authentication values requested by +\fBlibsasl\fR(3LIB) to complete authentication. +.sp +.LP +The user-defined callback collects and returns the authentication information +in the \fBsasl_interact_t\fR array according to \fBlibsasl\fR rules. The +authentication information can include user IDs, passwords, realms, or other +information defined by SASL. The SASL library uses this date during sequencing +to complete authentication. +.SS "Unbinding" +.sp +.LP +The \fBldap_unbind()\fR call is used to unbind from a directory, to terminate +the current association, and to free the resources contained in the \fIld\fR +structure. Once the function is called, the connection to the LDAP server is +closed and the \fIld\fR structure is invalid. The \fBldap_unbind_s()\fR and +\fBldap_unbind()\fR calls are identical and synchronous in nature. +.sp +.LP +The \fBldap_unbind_ext()\fR function is used to unbind from a directory, to +terminate the current association, and to free the resources contained in the +LDAP structure. Unlike \fBldap_unbind()\fR and \fBldap_unbind_s()\fR, both +server and client controls can be explicitly included with +\fBldap_unbind_ext()\fR requests. No server response is made to an unbind +request and responses should not be expected from server controls included with +unbind requests. +.SS "Rebinding While Following Referral" +.sp +.LP +The \fBldap_set_rebind_proc()\fR call is used to set a function called back to +obtain bind credentials. The credentials are used when a new server is +contacted after an LDAP referral. If \fBldap_set_rebind_proc()\fR is never +called, or if it is called with a \fBNULL\fR \fIrebindproc\fR parameter, an +unauthenticated simple LDAP bind is always done when chasing referrals. +.sp +.LP +The \fBrebindproc()\fR function is declared as shown below: +.sp +.in +2 +.nf +int rebindproc(LDAP *ld, char **whop, char **credp, + int *methodp, int freeit); +.fi +.in -2 + +.sp +.LP +The LDAP library first calls the \fBrebindproc()\fR to obtain the referral bind +credentials. The \fIfreeit\fR parameter is zero. The \fIwhop\fR, \fIcredp\fR, +and \fImethodp\fR parameters should be set as appropriate. If +\fBrebindproc()\fR returns \fBLDAP_SUCCESS\fR, referral processing continues. +The \fBrebindproc()\fR is called a second time with a non-zero \fIfreeit\fR +value to give the application a chance to free any memory allocated in the +previous call. +.sp +.LP +If anything but \fBLDAP_SUCCESS\fR is returned by the first call to +\fBrebindproc()\fR, referral processing is stopped and the error code is +returned for the original LDAP operation. +.SH RETURN VALUES +.sp +.LP +Make a call to \fBldap_result\fR(3LDAP) to obtain the result of a bind +operation. +.SH ERRORS +.sp +.LP +Asynchronous functions will return \fB\(mi1\fR in case of error. See +\fBldap_error\fR(3LDAP) for more information on error codes returned. If no +credentials are returned, the result parameter is set to \fINULL\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBldap_open\fR(3LDAP), +\fBldap_result\fR(3LDAP), \fBlibsasl\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_charset.3ldap b/usr/src/man/man3ldap/ldap_charset.3ldap new file mode 100644 index 0000000000..f5738ce14e --- /dev/null +++ b/usr/src/man/man3ldap/ldap_charset.3ldap @@ -0,0 +1,127 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_charset 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_charset, ldap_set_string_translators, ldap_t61_to_8859, ldap_8859_to_t61, +ldap_translate_from_t61, ldap_translate_to_t61, ldap_enable_translation \- LDAP +character set translation functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBvoid\fR \fBldap_set_string_translators\fR(\fBLDAP\fR \fI*ld\fR, + \fBBERTranslateProc\fR \fIencode_proc\fR, \fBBERTranslateProc\fR \fIdecodeproc\fR); +.fi + +.LP +.nf +\fBtypedef\fR \fBint\fR(\fB*BERTranslateProc)(char\fR \fI**bufp\fR, \fBunsigned long\fR \fI*buflenp\fR, + \fBint\fR \fIfree_input\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_t61_to_8859\fR(\fBchar\fR \fI**bufp\fR, \fBunsigned long\fR \fI*buflenp\fR, + \fBint\fR \fIfree_input\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_8859_to_t61\fR(\fBchar\fR \fI**bufp\fR, \fBunsigned long\fR \fI*buflenp\fR, + \fBint\fR \fIfree_input\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_translate_from_t61\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI**bufp\fR, + \fBunsigned long\fR \fI*lenp\fR, \fBint\fR \fIfree_input\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_translate_to_t61\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI**bufp\fR, \fBunsigned long\fR \fI*lenp\fR, + \fBint\fR \fIfree_input\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_enable_translation\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR, \fBint\fR \fIenable\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions 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 functions are only available if the LDAP and LBER libraries +are compiled with \fBSTR_TRANSLATION\fR defined. 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. +.sp +.LP +\fBldap_set_string_translators()\fR sets the translation functions that will be +used by the LDAP library. They are not actually used until the +\fIld_lberoptions\fR field of the LDAP structure is set to include the +\fBLBER_TRANSLATE_STRINGS\fR option. +.sp +.LP +\fBldap_t61_to_8859()\fR and \fBldap_8859_to_t61()\fR are translation functions +for converting between T.61 characters and ISO-8859 characters. The specific +8859 character set used is determined at compile time. +.sp +.LP +\fBldap_translate_from_t61()\fR is used to translate a string of characters +from the T.61 character set to a different character set. The actual +translation is done using the \fIdecode_proc\fR that was passed to a previous +call to \fBldap_set_string_translators()\fR. On entry, \fI*bufp\fR should point +to the start of the T.61 characters to be translated and \fI*lenp\fR should +contain the number of bytes to translate. If \fIfree_input\fR is non-zero, the +input buffer will be freed if translation is a success. If the translation is +a success, \fBLDAP_SUCCESS\fR will be returned, \fI*bufp\fR will point to a +newly malloc'd buffer that contains the translated characters, and \fI*lenp\fR +will contain the length of the result. If translation fails, an LDAP error code +will be returned. +.sp +.LP +\fBldap_translate_to_t61()\fR is used to translate a string of characters to +the T.61 character set from a different character set. The actual translation +is done using the \fIencode_proc\fR that was passed to a previous call to +\fBldap_set_string_translators()\fR. This function is called just like +\fBldap_translate_from_t61()\fR. +.sp +.LP +\fBldap_enable_translation()\fR is used to turn on or off string translation +for the LDAP entry \fIentry\fR (typically obtained by calling +\fBldap_first_entry()\fR or \fBldap_next_entry()\fR after a successful LDAP +search operation). If \fBenable\fR is zero, translation is disabled; if +non-zero, translation is enabled. This function is useful if you need to +ensure that a particular attribute is not translated when it is extracted using +\fBldap_get_values()\fR or \fBldap_get_values_len()\fR. For example, you would +not want to translate a binary attributes such as \fBjpegPhoto\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_compare.3ldap b/usr/src/man/man3ldap/ldap_compare.3ldap new file mode 100644 index 0000000000..641b40f285 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_compare.3ldap @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_compare 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- LDAP +compare operation +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_compare\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBchar\fR \fI*attr\fR, \fBchar\fR \fI*value\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_compare_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBchar\fR \fI*attr\fR, \fBchar\fR \fI*value\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_compare_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBchar\fR \fI*attr\fR, + \fBstruct berval\fR \fI*bvalue\fR, \fBLDAPControl\fR \fI**serverctrls\fR, + \fBLDAPControl\fR \fI**clientctrls\fR,\fBint\fR \fI*msgidp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_compare_ext_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBchar\fR \fI*attr\fR, + \fBstruct berval\fR \fI*bvalue\fR, \fBLDAPControl\fR \fI**serverctrls\fR, + \fBLDAPControl\fR \fI**clientctrls\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_compare_s()\fR function is used to perform an LDAP compare +operation synchronously. It takes \fIdn\fR, the DN of the entry upon which to +perform the compare, and \fIattr\fR and \fIvalue\fR, the attribute type and +value to compare to those found in the entry. It returns an LDAP error code, +which will be \fBLDAP_COMPARE_TRUE\fR if the entry contains the attribute +value and \fBLDAP_COMPARE_FALSE\fR if it does not. Otherwise, some error code +is returned. +.sp +.LP +The \fBldap_compare()\fR function is used to perform an LDAP compare operation +asynchronously. It takes the same parameters as \fBldap_compare_s()\fR, but +returns the message id of the request it initiated. The result of the compare +can be obtained by a subsequent call to \fBldap_result\fR(3LDAP). +.sp +.LP +The \fBldap_compare_ext()\fR function initiates an asynchronous compare +operation and returns \fBLDAP_SUCCESS\fR if the request was successfully sent +to the server, or else it returns a LDAP error code if not (see +\fBldap_error\fR(3LDAP). If successful, \fBldap_compare_ext()\fR places the +message id of the request in \fI*msgidp\fR. A subsequent call to +\fBldap_result()\fR, can be used to obtain the result of the add request. +.sp +.LP +The \fBldap_compare_ext_s()\fR function initiates a synchronous compare +operation and as such returns the result of the operation itself. +.SH ERRORS +.sp +.LP +\fBldap_compare_s()\fR returns an LDAP error code which can be interpreted by +calling one of \fBldap_perror\fR(3LDAP) and friends. \fBldap_compare()\fR +returns \fB\(mi1\fR if something went wrong initiating the request. It returns +the non-negative message id of the request if it was successful. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBattributes\fR(5) +.SH BUGS +.sp +.LP +There is no way to compare binary values using \fBldap_compare()\fR. diff --git a/usr/src/man/man3ldap/ldap_control_free.3ldap b/usr/src/man/man3ldap/ldap_control_free.3ldap new file mode 100644 index 0000000000..e92146857b --- /dev/null +++ b/usr/src/man/man3ldap/ldap_control_free.3ldap @@ -0,0 +1,58 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_control_free 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_control_free, ldap_controls_free \- LDAP control disposal +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBvoid\fR \fBldap_control_free\fR(\fBLDAPControl\fR \fI*ctrl\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_controls_free\fR(\fBLDAPControl\fR \fI*ctrls\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBldap_controls_free()\fR and \fBldap_control_free()\fR are routines which +can be used to dispose of a single control or an array of controls allocated by +other LDAP APIs. +.SH RETURN VALUES +.sp +.LP +None. +.SH ERRORS +.sp +.LP +No errors are defined for these functions. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_error\fR(3LDAP), \fBldap_result\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_delete.3ldap b/usr/src/man/man3ldap/ldap_delete.3ldap new file mode 100644 index 0000000000..8b2686be3f --- /dev/null +++ b/usr/src/man/man3ldap/ldap_delete.3ldap @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_delete 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- LDAP delete +operation +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_delete\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_delete_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_delete_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPControl\fR \fI**serverctrls\fR, + \fBLDAPControl\fR \fI**clientctrls\fR, \fBint\fR \fI*msgidp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_delete_ext_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPControl\fR \fI**serverctrls\fR, + \fBLDAPControl\fR \fI**clientctrls\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_delete_s()\fR function is used to perform an LDAP delete operation +synchronously. It takes \fIdn\fR, the DN of the entry to be deleted. It +returns an LDAP error code, indicating the success or failure of the operation. +.sp +.LP +The \fBldap_delete()\fR function is used to perform an LDAP delete operation +asynchronously. It takes the same parameters as \fBldap_delete_s()\fR, but +returns the message id of the request it initiated. The result of the delete +can be obtained by a subsequent call to \fBldap_result\fR(3LDAP). +.sp +.LP +The \fBldap_delete_ext()\fR function initiates an asynchronous delete +operation and returns \fBLDAP_SUCCESS\fR if the request was successfully sent +to the server, or else it returns a LDAP error code if not (see +\fBldap_error\fR(3LDAP)). If successful, \fBldap_delete_ext()\fR places the +message id of the request in \fI*msgidp\fR. A subsequent call to +\fBldap_result()\fR, can be used to obtain the result of the add request. +.sp +.LP +The \fBldap_delete_ext_s()\fR function initiates a synchronous delete +operation and as such returns the result of the operation itself. +.SH ERRORS +.sp +.LP +\fBldap_delete_s()\fR returns an LDAP error code which can be interpreted by +calling one of \fBldap_perror\fR(3LDAP) functions. \fBldap_delete()\fR returns +\fB\(mi1\fR if something went wrong initiating the request. It returns the +non-negative message id of the request if things were successful. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_disptmpl.3ldap b/usr/src/man/man3ldap/ldap_disptmpl.3ldap new file mode 100644 index 0000000000..af7809a405 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_disptmpl.3ldap @@ -0,0 +1,450 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_disptmpl 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_disptmpl, ldap_init_templates, ldap_init_templates_buf, +ldap_free_templates, ldap_first_disptmpl, ldap_next_disptmpl, ldap_oc2template, +ldap_name2template, ldap_tmplattrs, ldap_first_tmplrow, ldap_next_tmplrow, +ldap_first_tmplcol, ldap_next_tmplcol \- LDAP display template functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_init_templates\fR(\fBchar\fR \fI*file\fR, \fBstruct ldap_disptmpl\fR \fI**tmpllistp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_init_templates_buf\fR(\fBchar\fR \fI*buf\fR, \fBunsigned long\fR \fIlen\fR, + \fBstruct ldap_disptmpl\fR \fI**tmpllistp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_free_templates\fR(\fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); +.fi + +.LP +.nf +\fBstruct ldap_disptmpl\fR \fB*ldap_first_disptmpl\fR + (\fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); +.fi + +.LP +.nf +\fBstruct ldap_disptmpl\fR \fB*ldap_next_disptmpl\fR + (\fBstruct ldap_disptmpl\fR \fI*tmpllist\fR,\fBstruct ldap_disptmpl\fR \fI*tmpl\fR); +.fi + +.LP +.nf +\fBstruct ldap_disptmpl\fR \fB*ldap_oc2template\fR (\fBchar\fR \fI**oclist\fR, + \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); +.fi + +.LP +.nf +\fBstruct ldap_disptmpl\fR \fB*ldap_name2template\fR (\fBchar\fR \fI*name\fR, + \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); +.fi + +.LP +.nf +\fBchar\fR \fB**ldap_tmplattrs\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBchar\fR \fI**includeattrs\fR, + \fBint\fR \fIexclude;\fR, \fBunsigned long\fR \fIsyntaxmask\fR); +.fi + +.LP +.nf +\fBstruct ldap_tmplitem\fR \fB*ldap_first_tmplrow\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR); +.fi + +.LP +.nf +\fBstruct ldap_tmplitem\fR \fB*ldap_next_tmplrow\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, + \fBstruct ldap_tmplitem\fR \fI*row\fR); +.fi + +.LP +.nf +\fBstruct ldap_tmplitem\fR \fB*ldap_first_tmplcol\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, + \fBstruct ldap_tmplitem\fR \fI*row\fR, \fBstruct ldap_tmplitem\fR \fI*col\fR); +.fi + +.LP +.nf +\fBstruct ldap_tmplitem\fR \fB*ldap_next_tmplcol\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, + \fBstruct ldap_tmplitem\fR \fI*row\fR, \fBstruct ldap_tmplitem\fR \fI*col\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide a standard way to access LDAP entry display templates. +Entry display templates provide a standard 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 configuration file. See +\fBldaptemplates.conf\fR(4). 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 +\fBldap_entry2text\fR(3LDAP) functions use the display template functions and +produce text output. +.sp +.LP +\fBldap_init_templates()\fR reads a sequence of templates from a valid LDAP +template configuration file (see \fBldaptemplates.conf\fR(4)). Upon success, +\fB0\fR is returned, and \fItmpllistp\fR is set to point to a list of +templates. Each member of the list is an \fBldap_disptmpl\fR structure +(defined below in the DISPTMPL Structure Elements section). +.sp +.LP +\fBldap_init_templates_buf()\fR reads a sequence of templates from \fIbuf\fR +(whose size is \fIbuflen).\fR \fIbuf\fR should point to the data in the format +defined for an LDAP template configuration file (see +\fBldaptemplates.conf\fR(4)). Upon success, \fB0\fR is returned, and +\fItmpllistp\fR is set to point to a list of templates. +.sp +.LP +The \fBLDAP_SET_DISPTMPL_APPDATA()\fR macro is used to set the value of the +\fBdt_appdata\fR field in an \fBldap_disptmpl\fR structure. This field is +reserved for the calling application to use; it is not used internally. +.sp +.LP +The \fBLDAP_GET_DISPTMPL_APPDATA()\fR macro is used to retrieve the value in +the \fBdt_appdata\fR field. +.sp +.LP +The \fBLDAP_IS_DISPTMPL_OPTION_SET()\fR macro is used to test a +\fBldap_disptmpl\fR structure for the existence of a template option. The +options currently defined are: \fBLDAP_DTMPL_OPT_ADDABLE\fR (it is appropriate +to allow entries of this type to be added), \fBLDAP_DTMPL_OPT_ALLOWMODRDN\fR +(it is appropriate to offer the "modify rdn"operation), +\fBLDAP_DTMPL_OPT_ALTVIEW\fR (this template is merely an alternate view of +another template, typically used for templates pointed to be an +\fBLDAP_SYN_LINKACTION\fR item). +.sp +.LP +\fBldap_free_templates()\fR disposes of the templates allocated by +\fBldap_init_templates()\fR. +.sp +.LP +\fBldap_first_disptmpl()\fR returns the first template in the list +\fItmpllist.\fR The \fItmpllist\fR is typically obtained by calling +\fBldap_init_templates()\fR \fB\&.\fR +.sp +.LP +\fBldap_next_disptmpl()\fR returns the template after \fItmpl\fR in the +template list \fItmpllist.\fR \fIA\fR \fINULL\fR pointer is returned if +\fItmpl\fR is the last template in the list. +.sp +.LP +\fBldap_oc2template()\fR searches \fItmpllist\fR for the best template to use +to display an entry that has a specific set of \fBobjectClass\fR values. +\fIoclist\fR should be a null-terminated array of strings that contains the +values of the \fBobjectClass\fR attribute of the entry. A pointer to the +first template where all of the object classes listed in one of the template's +\fBdt_oclist\fR elements are contained in \fIoclist\fR is returned. A +\fINULL\fR pointer is returned if no appropriate template is found. +.sp +.LP +\fBldap_tmplattrs()\fR returns a null-terminated array that contains the names +of attributes that need to be retrieved if the template \fItmpl\fR is to be +used to display an entry. The attribute list should be freed using +\fBldap_value_free\fR(\|). The \fIincludeattrs\fR parameter contains a +null-terminated array of attributes that should always be included (it may be +\fINULL\fR if no extra attributes are required). If \fIsyntaxmask\fR is +non-zero, it is used to restrict the attribute set returned. If \fIexclude\fR +is zero, only attributes where the logical \fBAND\fR of the template item +syntax id and the \fIsyntaxmask\fR is non-zero are included. If \fIexclude\fR +is non-zero, attributes where the logical \fBAND\fR of the template item +syntax id and the \fIsyntaxmask\fR is non-zero are excluded. +.sp +.LP +\fBldap_first_tmplrow()\fR returns a pointer to the first row of items in +template \fItmpl.\fR +.sp +.LP +\fBldap_next_tmplrow()\fR returns a pointer to the row that follows \fIrow\fR +in template \fItmpl.\fR +.sp +.LP +\fBldap_first_tmplcol()\fR returns a pointer to the first item (in the first +column) of row \fIrow\fR within template \fItmpl\fR. A pointer to an +\fBldap_tmplitem\fR structure (defined below in the TMPLITEM Structure Elements +section) is returned. +.sp +.LP +The \fBLDAP_SET_TMPLITEM_APPDATA()\fR macro is used to set the value of the +\fBti_appdata\fR field in a \fBldap_tmplitem\fR structure. This field is +reserved for the calling application to use; it is not used internally. +.sp +.LP +The \fBLDAP_GET_TMPLITEM_APPDATA()\fR macro is used to retrieve the value of +the \fBti_appdata\fR field. +.sp +.LP +The \fBLDAP_IS_TMPLITEM_OPTION_SET()\fR macro is used to test a +\fBldap_tmplitem\fR structure for the existence of an item option. The options +currently defined are: \fBLDAP_DITEM_OPT_READONLY\fR (this attribute should not +be modified), \fBLDAP_DITEM_OPT_SORTVALUES\fR (it makes sense to sort the +values), \fBLDAP_DITEM_OPT_SINGLEVALUED\fR (this attribute can only hold a +single value), \fBLDAP_DITEM_OPT_VALUEREQUIRED\fR (this attribute must contain +at least one value), \fBLDAP_DITEM_OPT_HIDEIFEMPTY\fR (do not show this item if +there are no values), and \fBLDAP_DITEM_OPT_HIDEIFFALSE\fR (for boolean +attributes only: hide this item if the value is \fBFALSE\fR). +.sp +.LP +\fBldap_next_tmplcol()\fR returns a pointer to the item (column) that follows +column \fBcol\fR within row \fIrow\fR of template \fItmpl.\fR +.SS "DISPTMPL Structure Elements" +.sp +.LP +The \fBldap_disptmpl\fR structure is defined as: +.sp +.in +2 +.nf +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; +}; +\fI\fR +.fi +.in -2 + +.sp +.LP +The \fBdt_name\fR member is the singular name of the template. The +\fBdt_pluralname\fR is the plural name. The \fBdt_iconname\fR 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 \fBdt_options\fR +contains options which may be tested using the +\fBLDAP_IS_TMPLITEM_OPTION_SET()\fR macro. +.sp +.LP +The \fBdt_authattrname\fR contains the name of the DN-syntax attribute whose +value(s) should be used to authenticate to make changes to an entry. If +\fBdt_authattrname\fR is \fINULL\fR, then authenticating as the entry itself is +appropriate. The \fBdt_defrdnattrname\fR is the name of the attribute that is +normally used to name entries of this type, for example, "cn"for person +entries. The \fBdt_defaddlocation\fR is the distinguished name of an entry +below which new entries of this type are typically created (its value is +site-dependent). +.sp +.LP +\fBdt_oclist\fR is a pointer to a linked list of object class arrays, defined +as: +.sp +.in +2 +.nf +struct ldap_oclist { + char **oc_objclasses; + struct ldap_oclist *oc_next; +}; +.fi +.in -2 + +.sp +.LP +These are used by the \fBldap_oc2template()\fR function. +.sp +.LP +\fBdt_adddeflist\fR is a pointer to a linked list of rules for defaulting the +values of attributes when new entries are created. The \fBldap_adddeflist\fR +structure is defined as: +.sp +.in +2 +.nf +struct ldap_adddeflist { + int ad_source; + char *ad_attrname; + char *ad_value; + struct ldap_adddeflist *ad_next; +}; +.fi +.in -2 + +.sp +.LP +The ad_attrname member contains the name of the attribute whose value this rule +sets. If \fBad_source\fR is \fBLDAP_ADSRC_CONSTANTVALUE\fR then the +\fBad_value\fR member contains the (constant) value to use. If +\fBad_source\fR is \fBLDAP_ADSRC_ADDERSDN\fR then ad_value is ignored and the +distinguished name of the person who is adding the new entry is used as the +default value for \fBad_attrname\fR. +.SS "TMPLITEM Structure Elements" +.sp +.LP +The \fBldap_tmplitem\fR structure is defined as: +.sp +.in +2 +.nf +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; +}; +.fi +.in -2 + +.SS "Syntax IDs" +.sp +.LP +Syntax ids are found in the \fBldap_tmplitem\fR structure element +\fBti_syntaxid\fR, and they can be used to determine how to display the values +for the attribute associated with an item. The \fBLDAP_GET_SYN_TYPE()\fR +macro can be used to return a general type from a syntax id. The five general +types currently defined are: \fBLDAP_SYN_TYPE_TEXT\fR (for attributes that are +most appropriately shown as text), \fBLDAP_SYN_TYPE_IMAGE\fR (for JPEG or FAX +format images), \fBLDAP_SYN_TYPE_BOOLEAN\fR (for boolean attributes), +\fBLDAP_SYN_TYPE_BUTTON\fR (for attributes whose values are to be retrieved and +display only upon request, for example, in response to the press of a button, +a JPEG image is retrieved, decoded, and displayed), and +\fBLDAP_SYN_TYPE_ACTION\fR (for special purpose actions such as "search for the +entries where this entry is listed in the seeAlso attribute"). +.sp +.LP +The \fBLDAP_GET_SYN_OPTIONS\fR macro can be used to retrieve an unsigned long +bitmap that defines options. The only currently defined option is +\fBLDAP_SYN_OPT_DEFER,\fR which (if set) implies that the values for the +attribute should not be retrieved until requested. +.sp +.LP +There are sixteen distinct syntax ids currently defined. These generally +correspond to one or more X.500 syntaxes. +.sp +.LP +\fBLDAP_SYN_CASEIGNORESTR\fR is used for text attributes which are simple +strings whose case is ignored for comparison purposes. +.sp +.LP +\fBLDAP_SYN_MULTILINESTR\fR is used for text attributes which consist of +multiple lines, for example, \fBpostalAddress\fR, \fBhomePostalAddress\fR, +\fBmultilineDescription\fR, or any attributes of syntax \fBcaseIgnoreList\fR. +.sp +.LP +\fBLDAP_SYN_RFC822ADDR\fR is used for case ignore string attributes that are +RFC-822 conformant mail addresses, for example, mail. +.sp +.LP +\fBLDAP_SYN_DN\fR is used for attributes with a Distinguished Name syntax, for +example, \fBseeAlso\fR. +.sp +.LP +\fBLDAP_SYN_BOOLEAN\fR is used for attributes with a boolean syntax. +.sp +.LP +\fBLDAP_SYN_JPEGIMAGE\fR is used for attributes with a jpeg syntax, for +example, jpegPhoto. +.sp +.LP +\fBLDAP_SYN_JPEGBUTTON\fR is used to provide a button (or equivalent interface +element) that can be used to retrieve, decode, and display an attribute of jpeg +syntax. +.sp +.LP +\fBLDAP_SYN_FAXIMAGE\fR is used for attributes with a photo syntax, for +example, Photo. These are actually Group 3 Fax (T.4) format images. +.sp +.LP +\fBLDAP_SYN_FAXBUTTON\fR is used to provide a button (or equivalent interface +element) that can be used to retrieve, decode, and display an attribute of +photo syntax. +.sp +.LP +\fBLDAP_SYN_AUDIOBUTTON\fR 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. +.sp +.LP +\fBLDAP_SYN_TIME\fR is used for attributes with the UTCTime syntax, for +example, \fBlastModifiedTime\fR. The value(s) should be displayed in complete +date and time fashion. +.sp +.LP +\fBLDAP_SYN_DATE\fR is used for attributes with the UTCTime syntax, for +example, \fBlastModifiedTime\fR. Only the date portion of the value(s) should +be displayed. +.sp +.LP +\fBLDAP_SYN_LABELEDURL\fR is used for \fBlabeledURL\fR attributes. +.sp +.LP +\fBLDAP_SYN_SEARCHACTION\fR is used to define a search that is used to retrieve +related information. If \fBti_attrname\fR is not \fINULL\fR, it is assumed to +be a boolean attribute which will cause no search to be performed if its value +is \fBFALSE\fR. The \fBti_args\fR structure member will have four strings +in it: \fBti_args[\fR \fB0\fR \fB]\fR 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, \fBti_args[\fR \fB1\fR +\fB]\fR should be a filter pattern where any occurrences of "%v" are replaced +with the value derived from \fBti_args[ 0 ]\fR, \fBti_args[\fR \fB2\fR +\fB]\fR should be the name of an additional attribute to retrieve when +performing the search, and \fBti_args[\fR \fB3\fR \fB]\fR should be a +human-consumable name for that attribute. The \fBti_args[\fR \fB2\fR \fB]\fR +attribute is typically displayed along with a list of distinguished names when +multiple entries are returned by the search. +.sp +.LP +\fBLDAP_SYN_LINKACTION\fR is used to define a link to another template by name. +\fBti_args[\fR \fB0\fR \fB]\fR will contain the name of the display template to +use. The \fBldap_name2template()\fR function can be used to obtain a pointer +to the correct \fBldap_disptmpl\fR structure. +.sp +.LP +\fBLDAP_SYN_ADDDNACTION\fR and \fBLDAP_SYN_VERIFYDNACTION\fR are reserved as +actions but currently undefined. +.SH ERRORS +.sp +.LP +The init template functions return \fBLDAP_TMPL_ERR_VERSION\fR if \fIbuf\fR +points to data that is newer than can be handled, \fBLDAP_TMPL_ERR_MEM\fR if +there is a memory allocation problem, \fBLDAP_TMPL_ERR_SYNTAX\fR if there is a +problem with the format of the templates buffer or file. +\fBLDAP_TMPL_ERR_FILE\fR is returned by \fBldap_init_templates\fR if the file +cannot be read. Other functions generally return \fINULL\fR upon error. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_entry2text\fR(3LDAP), \fBldaptemplates.conf\fR(4), +\fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_entry2text.3ldap b/usr/src/man/man3ldap/ldap_entry2text.3ldap new file mode 100644 index 0000000000..7d7e8ad954 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_entry2text.3ldap @@ -0,0 +1,234 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_entry2text 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_entry2text, ldap_entry2text_search, ldap_entry2html, +ldap_entry2html_search, ldap_vals2html, ldap_vals2text \- LDAP entry display +functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_entry2text\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBLDAPMessage\fR \fI*entry\fR, + \fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR, + \fBint (\fR\fI*writeproc\fR)(), \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR, + \fBunsigned long\fR \fIopts\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_entry2text_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBchar\fR \fI*base\fR, + \fBLDAPMessage\fR \fI*entry\fR, \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR, + \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR, \fBint (\fR\fI*writeproc\fR)(), + \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR,\fBint\fR \fIrdncount\fR, + \fBunsigned long\fR \fIopts\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_vals2text\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBchar\fR \fI**vals\fR, \fBchar\fR \fI*label\fR, + \fBint\fR \fIlabelwidth\fR, \fBunsigned long\fR\fIsyntaxid\fR, \fBint (\fR\fI*writeproc\fR)(), + \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_entry2html\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBLDAPMessage\fR \fI*entry\fR, + \fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR, + \fBint (\fR\fI*writeproc\fR)(),\fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR, + \fBunsigned long\fR \fIopts\fR, \fBchar\fR \fI*urlprefix\fR, \fBchar\fR \fI*base\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_entry2html_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMessage\fR \fI*entry\fR, + \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR, \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR, + \fBint (\fR\fI*writeproc\fR)(), \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR, + \fBunsigned long\fR \fIopts\fR, \fBchar\fR \fI*urlprefix\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_vals2html\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBchar\fR \fI**vals\fR, + \fBchar\fR \fI*label\fR, \fBint\fR \fIlabelwidth\fR, \fBunsigned long\fR \fIsyntaxid\fR, + \fBint (\fR\fI*writeproc\fR)(), \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR, + \fBchar\fR \fI*urlprefix\fR); +.fi + +.LP +.nf +#define LDAP_DISP_OPT_AUTOLABELWIDTH 0x00000001 +.fi + +.LP +.nf +#define LDAP_DISP_OPT_HTMLBODYONLY 0x00000002 +.fi + +.LP +.nf +#define LDAP_DTMPL_BUFSIZ 2048 +.fi + +.SH DESCRIPTION +.sp +.LP +These functions use the LDAP display template functions (see +\fBldap_disptmpl\fR(3LDAP) and \fBldap_templates.conf(4))\fR to produce a +plain text or an HyperText Markup Language (HTML) display of an entry or a set +of values. Typical plain text output produced for an entry might look like: +.sp +.in +2 +.nf + "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 + ... +.fi +.in -2 + +.sp +.LP +The exact output produced will depend on the display template configuration. +HTML output is similar to the plain text output, but more richly formatted. +.sp +.LP +\fBldap_entry2text()\fR produces a text representation of \fIentry\fR and +writes the text by calling the \fIwriteproc\fR function. All of the attributes +values to be displayed must be present in \fIentry;\fR no interaction with the +LDAP server will be performed within \fBldap_entry2text\fR. \fBld\fR is the +LDAP pointer obtained by a previous call to \fBldap_open.\fR \fIwriteproc\fR +should be declared as: +.sp +.in +2 +.nf +int writeproc( writeparm, p, len ) + void *writeparm; + char *p; + int len; +.fi +.in -2 + +.sp +.LP +where \fIp\fR is a pointer to text to be written and \fIlen\fR is the length of +the text. \fIp\fR is guaranteed to be zero-terminated. Lines of text are +terminated with the string \fIeol.\fR \fIbuf\fR is a pointer to a buffer of +size \fBLDAP_DTMPL_BUFSIZ\fR or larger. If \fIbuf\fR \fIis\fR \fINULL\fR then +a buffer is allocated and freed internally. \fItmpl\fR is a pointer to the +display template to be used (usually obtained by calling +\fBldap_oc2template\fR). If \fItmpl\fR is \fINULL\fR, no template is used and a +generic display is produced. \fIdefattrs\fR is a NULL-terminated array of LDAP +attribute names which you wish to provide default values for (only used if +\fIentry\fR contains no values for the attribute). An array of NULL-terminated +arrays of default values corresponding to the attributes should be passed in +\fIdefvals.\fR \fIThe\fR \fIrdncount\fR parameter is used to limit the number +of Distinguished Name (DN) components that are actually displayed for DN +attributes. If \fIrdncount\fR is zero, all components are shown. \fIopts\fR is +used to specify output options. The only values currently allowed are zero +(default output), \fBLDAP_DISP_OPT_AUTOLABELWIDTH\fR which causes the width for +labels to be determined based on the longest label in \fItmpl,\fR \fIand\fR +\fBLDAP_DISP_OPT_HTMLBODYONLY\fR. The \fBLDAP_DISP_OPT_HTMLBODYONLY\fR option +instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags. +In other words, an HTML fragment is generated, and the caller is responsible +for prepending and appending the appropriate HTML tags to construct a correct +HTML document. +.sp +.LP +\fBldap_entry2text_search()\fR is similar to \fBldap_entry2text\fR, and all of +the like-named parameters have the same meaning except as noted below. If +\fIbase\fR is not \fINULL\fR, it is the search base to use when executing +search actions. If it is \fINULL\fR, search action template items are ignored. +If \fIentry\fR is not \fINULL\fR, it should contain the \fIobjectClass\fR +attribute values for the entry to be displayed. If \fIentry\fR is \fINULL\fR, +\fIdn\fR must not be \fINULL\fR, and \fBldap_entry2text_search\fR will +retrieve the \fBobjectClass\fR values itself by calling \fBldap_search_s.\fR +\fBldap_entry2text_search\fR will determine the appropriate display template to +use by calling \fBldap_oc2template\fR, and will call \fBldap_search_s\fR to +retrieve any attribute values to be displayed. The \fItmpllist\fR parameter is +a pointer to the entire list of templates available (usually obtained by +calling \fBldap_init_templates\fR or \fBldap_init_templates_buf\fR). If +\fItmpllist\fR is \fINULL\fR, \fBldap_entry2text_search\fR will attempt to read +a load templates from the default template configuration file +\fBETCDIR/ldaptemplates.conf\fR +.sp +.LP +\fBldap_vals2text\fR produces a text representation of a single set of LDAP +attribute values. The \fIld,\fR \fIbuf,\fR \fIwriteproc,\fR \fIwriteparm,\fR +\fIeol,\fR and \fIrdncount\fR parameters are the same as the like-named +parameters for \fBldap_entry2text\fR. \fIvals\fR is a NULL-terminated list of +values, usually obtained by a call to \fBldap_get_values\fR. \fIlabel\fR is a +string shown next to the values (usually a friendly form of an LDAP attribute +name). \fIlabelwidth\fR 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. \fIsyntaxid\fR is a display template attribute syntax +identifier (see \fBldap_disptmpl\fR(3LDAP) for a list of the pre-defined +\fBLDAP_SYN_...\fR values). +.sp +.LP +\fBldap_entry2html\fR produces an HTML representation of \fIentry.\fR It +behaves exactly like ldap_entry2text(3LDAP), except for the formatted output +and the addition of two parameters. \fIurlprefix\fR is the starting text to use +when constructing an LDAP URL. The default is the string \fIldap:///\fR The +second additional parameter, \fIbase,\fR the search base to use when executing +search actions. If it is \fINULL\fR, search action template items are +ignored. +.sp +.LP +\fBldap_entry2html_search\fR behaves exactly like +\fBldap_entry2text_search\fR(3LDAP), except HTML output is produced and one +additional parameter is required. \fIurlprefix\fR is the starting text to use +when constructing an LDAP URL. The default is the string \fIldap:///\fR +.sp +.LP +\fBldap_vals2html\fR behaves exactly like +\fBldap_vals2text\fR,\fBexcept\fRHTML\fBoutput\fRis and one additional +parameter is required. \fIurlprefix\fR is the starting text to use when +constructing an LDAP URL. The default is the string \fIldap:///\fR +.SH ERRORS +.sp +.LP +These functions all return an LDAP error code. \fBLDAP_SUCCESS\fR is returned +if no error occurs. See \fBldap_error\fR(3LDAP) for details. The \fIld_errno\fR +field of the \fIld\fR parameter is also set to indicate the error. +.SH FILES +.sp +.LP +\fBETCDIR/ldaptemplates.conf\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_disptmpl\fR(3LDAP), \fBldaptemplates.conf\fR(4) , +\fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_error.3ldap b/usr/src/man/man3ldap/ldap_error.3ldap new file mode 100644 index 0000000000..42f77ab7a1 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_error.3ldap @@ -0,0 +1,663 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_error 3LDAP "11 Nov 2008" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_error, ldap_err2string, ldap_perror, ldap_result2error \- LDAP protocol +error handling functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBchar *\fR\fBldap_err2string\fR(\fBint\fR \fIerr\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_perror\fR(\fBLDAP *\fR\fIld\fR, \fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_result2error\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIres\fR, \fBint\fR \fIfreeit\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions interpret the error codes that are returned by the LDAP API +routines. The \fBldap_perror()\fR and \fBldap_result2error()\fR functions are +deprecated for all new development. Use \fBldap_err2string()\fR instead. +.sp +.LP +You can also use \fBldap_parse_sasl_bind_result\fR(3LDAP), +\fBldap_parse_extended_result\fR(3LDAP), and \fBldap_parse_result\fR(3LDAP) to +provide error handling and interpret error codes returned by LDAP API +functions. +.sp +.LP +The \fBldap_err2string()\fR function takes \fIerr\fR, a numeric LDAP error +code, returned either by \fBldap_parse_result\fR(3LDAP) or another LDAP API +call. It returns an informative, null-terminated, character string that +describes the error. +.sp +.LP +The \fBldap_result2error()\fR function takes \fIres\fR, a result produced by +\fBldap_result\fR(3LDAP) or other synchronous LDAP calls, and returns the +corresponding error code. If the \fIfreeit\fR parameter is non-zero, it +indicates that the \fIres\fR parameter should be freed by a call to +\fBldap_result\fR(3LDAP) after the error code has been extracted. +.sp +.LP +Similar to the way \fBperror\fR(3C) works, the \fBldap_perror()\fR function can +be called to print an indication of the error to standard error. +.SH ERRORS +.sp +.LP +The possible values for an LDAP error code are: +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_SUCCESS\fR\fR +.ad +.sp .6 +.RS 4n +The request was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPERATIONS_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +An operations error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_PROTOCOL_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +A protocol violation was detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_TIMELIMIT_EXCEEDED\fR\fR +.ad +.sp .6 +.RS 4n +An LDAP time limit was exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_SIZELIMIT_EXCEEDED\fR\fR +.ad +.sp .6 +.RS 4n +An LDAP size limit was exceeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_COMPARE_FALSE\fR\fR +.ad +.sp .6 +.RS 4n +A compare operation returned false. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_COMPARE_TRUE\fR\fR +.ad +.sp .6 +.RS 4n +A compare operation returned true. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_STRONG_AUTH_NOT_SUPPORTED\fR\fR +.ad +.sp .6 +.RS 4n +The LDAP server does not support strong authentication. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_STRONG_AUTH_REQUIRED\fR\fR +.ad +.sp .6 +.RS 4n +Strong authentication is required for the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_PARTIAL_RESULTS\fR\fR +.ad +.sp .6 +.RS 4n +Only partial results are returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NO_SUCH_ATTRIBUTE\fR\fR +.ad +.sp .6 +.RS 4n +The attribute type specified does not exist in the entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_UNDEFINED_TYPE\fR\fR +.ad +.sp .6 +.RS 4n +The attribute type specified is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_INAPPROPRIATE_MATCHING\fR\fR +.ad +.sp .6 +.RS 4n +The filter type is not supported for the specified attribute. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_CONSTRAINT_VIOLATION\fR\fR +.ad +.sp .6 +.RS 4n +An attribute value specified violates some constraint. For example, a +\fBpostalAddress\fR has too many lines, or a line that is too long. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_TYPE_OR_VALUE_EXISTS\fR\fR +.ad +.sp .6 +.RS 4n +An attribute type or attribute value specified already exists in the entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_INVALID_SYNTAX\fR\fR +.ad +.sp .6 +.RS 4n +An invalid attribute value was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NO_SUCH_OBJECT\fR\fR +.ad +.sp .6 +.RS 4n +The specified object does not exist in the directory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_ALIAS_PROBLEM\fR\fR +.ad +.sp .6 +.RS 4n +An alias in the directory points to a nonexistent entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_INVALID_DN_SYNTAX\fR\fR +.ad +.sp .6 +.RS 4n +A syntactically invalid DN was specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_IS_LEAF\fR\fR +.ad +.sp .6 +.RS 4n +The object specified is a leaf. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_ALIAS_DEREF_PROBLEM\fR\fR +.ad +.sp .6 +.RS 4n +A problem was encountered when dereferencing an alias. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_INAPPROPRIATE_AUTH\fR\fR +.ad +.sp .6 +.RS 4n +Inappropriate authentication was specified. For example, +\fBLDAP_AUTH_SIMPLE\fR was specified and the entry does not have a +\fBuserPassword\fR attribute. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_INVALID_CREDENTIALS\fR\fR +.ad +.sp .6 +.RS 4n +Invalid credentials were presented, for example, the wrong password. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_INSUFFICIENT_ACCESS\fR\fR +.ad +.sp .6 +.RS 4n +The user has insufficient access to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_BUSY\fR\fR +.ad +.sp .6 +.RS 4n +The DSA is busy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_UNAVAILABLE\fR\fR +.ad +.sp .6 +.RS 4n +The DSA is unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_UNWILLING_TO_PERFORM\fR\fR +.ad +.sp .6 +.RS 4n +The DSA is unwilling to perform the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_LOOP_DETECT\fR\fR +.ad +.sp .6 +.RS 4n +A loop was detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NAMING_VIOLATION\fR\fR +.ad +.sp .6 +.RS 4n +A naming violation occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OBJECT_CLASS_VIOLATION\fR\fR +.ad +.sp .6 +.RS 4n +An object class violation occurred. For example, a \fBmust\fR attribute was +missing from the entry. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NOT_ALLOWED_ON_NONLEAF\fR\fR +.ad +.sp .6 +.RS 4n +The operation is not allowed on a nonleaf object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NOT_ALLOWED_ON_RDN\fR\fR +.ad +.sp .6 +.RS 4n +The operation is not allowed on an RDN. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_ALREADY_EXISTS\fR\fR +.ad +.sp .6 +.RS 4n +The entry already exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NO_OBJECT_CLASS_MODS\fR\fR +.ad +.sp .6 +.RS 4n +Object class modifications are not allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OTHER\fR\fR +.ad +.sp .6 +.RS 4n +An unknown error occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_SERVER_DOWN\fR\fR +.ad +.sp .6 +.RS 4n +The LDAP library cannot contact the LDAP server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_LOCAL_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +Some local error occurred. This is usually the result of a failed +\fBmalloc\fR(3C) call or a failure to \fBfflush\fR(3C) the \fBstdio\fR stream +to files, even when the LDAP requests were processed successfully by the remote +server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_ENCODING_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +An error was encountered encoding parameters to send to the LDAP server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_DECODING_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +An error was encountered decoding a result from the LDAP server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_TIMEOUT\fR\fR +.ad +.sp .6 +.RS 4n +A time limit was exceeded while waiting for a result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_AUTH_UNKNOWN\fR\fR +.ad +.sp .6 +.RS 4n +The authentication method specified to \fBldap_bind\fR(3LDAP) is not known. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_FILTER_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +An invalid filter was supplied to \fBldap_search\fR(3LDAP), for example, +unbalanced parentheses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_PARAM_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +An LDAP function was called with a bad parameter, for example, a \fINULL\fR +\fIld\fR pointer, and the like. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NO_MEMORY\fR\fR +.ad +.sp .6 +.RS 4n +A memory allocation call failed in an LDAP library function, for example, +\fBmalloc\fR(3C). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_CONNECT_ERROR\fR\fR +.ad +.sp .6 +.RS 4n +The LDAP client has either lost its connetion to an LDAP server or it cannot +establish a connection. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NOT_SUPPORTED\fR\fR +.ad +.sp .6 +.RS 4n +The requested functionality is not supported., for example, when an LDAPv2 +client requests some LDAPv3 functionality. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_CONTROL_NOT_FOUND\fR\fR +.ad +.sp .6 +.RS 4n +An LDAP client requested a control not found in the list of supported controls +sent by the server. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NO_RESULTS_RETURNED\fR\fR +.ad +.sp .6 +.RS 4n +The LDAP server sent no results. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_MORE_RESULTS_TO_RETURN\fR\fR +.ad +.sp .6 +.RS 4n +More results are chained in the message chain. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_CLIENT_LOOP\fR\fR +.ad +.sp .6 +.RS 4n +A loop has been detected, for example, when following referrals. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_REFERRAL_LIMIT_EXCEEDED\fR\fR +.ad +.sp .6 +.RS 4n +The referral exceeds the hop limit. The hop limit determines the number of +servers that the client can hop through to retrieve data. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBfflush\fR(3C), \fBldap\fR(3LDAP), \fBldap_bind\fR(3LDAP), +\fBldap_result\fR(3LDAP), \fBldap_parse_extended_result\fR(3LDAP), +\fBldap_parse_result\fR(3LDAP), \fBldap_parse_sasl_bind_result\fR(3LDAP), +\fBldap_search\fR(3LDAP), \fBmalloc\fR(3C), \fBperror\fR(3C) , +\fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_first_attribute.3ldap b/usr/src/man/man3ldap/ldap_first_attribute.3ldap new file mode 100644 index 0000000000..71d40d708e --- /dev/null +++ b/usr/src/man/man3ldap/ldap_first_attribute.3ldap @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_first_attribute 3LDAP "16 Dec 2003" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR...] \fIfile\fR... -lldap[ \fIlibrary\fR...] +#include <lber.h> +#include <ldap.h> + +\fBchar *\fR\fBldap_first_attribute\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIentry\fR, + \fBBerElement **\fR\fIberptr\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBldap_next_attribute\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIentry\fR, + \fBBerElement *\fR\fIber\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_first_attribute()\fR function gets the value of the first attribute +in an entry. +.sp +.LP +The \fBldap_first_attribute()\fR function returns the name of the first +attribute in the entry. To get the value of the first attribute, pass the +attribute name to the \fBldap_get_values()\fR function or to the +\fBldap_get_values_len()\fR function. +.sp +.LP +The \fBldap_next_attribute()\fR function gets the value of the next attribute +in an entry. +.sp +.LP +After stepping through the attributes, the application should call +\fBber_free()\fR to free the \fBBerElement\fR structure allocated by the +\fBldap_first_attribute()\fR function if the structure is other than NULL. +.SH ERRORS +.sp +.LP +If an error occurs, \fINULL\fR is returned and the \fBld_errno\fR field in the +\fIld\fR parameter is set to indicate the error. See \fBldap_error\fR(3LDAP) +for a description of possible error codes. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelSUNWcsl (32-bit)SUNWcslx (64-bit) +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_first_entry\fR(3LDAP), \fBldap_get_values\fR(3LDAP), +\fBldap_error\fR(3LDAP), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBldap_first_attribute()\fR function alllocates memory that might need to +be freed by the caller by means of \fBber_free\fR(3LDAP). diff --git a/usr/src/man/man3ldap/ldap_first_entry.3ldap b/usr/src/man/man3ldap/ldap_first_entry.3ldap new file mode 100644 index 0000000000..9bcaa9e22e --- /dev/null +++ b/usr/src/man/man3ldap/ldap_first_entry.3ldap @@ -0,0 +1,111 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_first_entry 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_first_entry, ldap_next_entry, ldap_count_entries, ldap_count_references, +ldap_first_reference, ldap_next_reference \- LDAP entry parsing and counting +functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBLDAPMessage *\fR\fBldap_first_entry\fR(\fBLDAP\fR\fI*ld\fR, \fBLDAPMessage\fR \fI*result\fR); +.fi + +.LP +.nf +\fBLDAPMessage *\fR\fBldap_next_entry\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR); +.fi + +.LP +.nf +\fB\fR\fBldap_count_entries\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*result\fR); +.fi + +.LP +.nf +\fBLDAPMessage *\fR\fBldap_first_reference\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR); +.fi + +.LP +.nf +\fBLDAPMessage *\fR\fBldap_next_reference\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_count_references\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to parse results received from +\fBldap_result\fR(3LDAP) or the synchronous LDAP search operation functions +\fBldap_search_s\fR(3LDAP) and \fBldap_search_st\fR(3LDAP). +.sp +.LP +The \fBldap_first_entry()\fR function is used to retrieve the first entry in a +chain of search results. It takes the \fIresult\fR as returned by a call to +\fBldap_result\fR(3LDAP) or \fBldap_search_s\fR(3LDAP) or +\fBldap_search_st\fR(3LDAP) and returns a pointer to the first entry in the +result. +.sp +.LP +This pointer should be supplied on a subsequent call to \fBldap_next_entry()\fR +to get the next entry, the result of which should be supplied to the next call +to \fBldap_next_entry()\fR, etc. \fBldap_next_entry()\fR will return +\fINULL\fR when there are no more entries. The entries returned from these +calls are used in calls to the functions described in \fBldap_get_dn\fR(3LDAP), +\fBldap_first_attribute\fR(3LDAP), \fBldap_get_values\fR(3LDAP), etc. +.sp +.LP +A count of the number of entries in the search result can be obtained by +calling \fBldap_count_entries()\fR. +.sp +.LP +\fBldap_first_reference()\fR and \fBldap_next_reference()\fR are used to step +through and retrieve the list of continuation references from a search result +chain. +.sp +.LP +The \fBldap_count_references()\fR function is used to count the number of +references that are contained in and remain in a search result chain. +.SH ERRORS +.sp +.LP +If an error occurs in \fBldap_first_entry()\fR or \fBldap_next_entry()\fR, +\fINULL\fR is returned and the \fBld_errno\fR field in the \fIld\fR parameter +is set to indicate the error. If an error occurs in +\fBldap_count_entries()\fR, \fB\(mi1\fR is returned, and \fBld_errno\fR is set +appropriately. See \fBldap_error\fR(3LDAP) for a description of possible error +codes. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_result\fR(3LDAP), \fBldap_search\fR(3LDAP), +\fBldap_first_attribute\fR(3LDAP), \fBldap_get_values\fR(3LDAP), +\fBldap_get_dn\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_first_message.3ldap b/usr/src/man/man3ldap/ldap_first_message.3ldap new file mode 100644 index 0000000000..4e1997c4c5 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_first_message.3ldap @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_first_message 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_first_message, ldap_count_messages, ldap_next_message, ldap_msgtype \- +LDAP message processing functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_count_messages\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR); +.fi + +.LP +.nf +\fBLDAPMessage *\fR\fBldap_first_message\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR); +.fi + +.LP +.nf +\fBLDAPMessage *\fR\fBldap_next_message\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*msg\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_msgtype\fR(\fBLDAPMessage\fR \fI*res\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +\fBldap_count_messages()\fR is used to count the number of messages that remain +in a chain of results if called with a message, entry, or reference returned +by \fBldap_first_message()\fR, \fBldap_next_message()\fR, +\fBldap_first_entry()\fR, \fBldap_next_entry()\fR, +\fBldap_first_reference()\fR, and \fBldap_next_reference()\fR +.sp +.LP +\fBldap_first_message()\fR and \fBldap_next_message()\fR functions are used +to step through the list of messages in a result chain returned by +\fBldap_result()\fR. +.sp +.LP +\fBldap_msgtype()\fR function returns the type of an LDAP message. +.SH RETURN VALUES +.sp +.LP +\fBldap_first_message()\fR and \fBldap_next_message()\fR return +\fBLDAPMessage\fR which can include referral messages, entry messages and +result messages. +.sp +.LP +\fBldap_count_messages()\fR returns the number of messages contained in a chain +of results. +.SH ERRORS +.sp +.LP +\fBldap_first_message()\fR and \fBldap_next_message()\fR return \fINULL\fR +when no more messages exist. \fINULL\fR is also returned if an error occurs +while stepping through the entries, in which case the error parameters in the +session handle \fIld\fR will be set to indicate the error. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_error\fR(3LDAP), \fBldap_result\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_friendly.3ldap b/usr/src/man/man3ldap/ldap_friendly.3ldap new file mode 100644 index 0000000000..268863ea25 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_friendly.3ldap @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_friendly 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_friendly, ldap_friendly_name, ldap_free_friendlymap \- LDAP attribute +remapping functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBchar *\fR\fBldap_friendly_name\fR(\fBchar\fR \fI*filename\fR, \fBchar\fR \fI*name\fR, + \fBFriendlyMap\fR \fI**map\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_free_friendlymap\fR(\fBFriendlyMap\fR \fI**map\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This function 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. +.sp +.LP +\fIfilename\fR is the name of a file containing the unfriendly to friendly +mapping, \fIname\fR is the unfriendly name to map to a friendly name, and +\fImap\fR 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 subsequent calls. +.sp +.LP +For example: +.sp +.in +2 +.nf + FriendlyMap *map = NULL; + printf( "unfriendly %s => friendly %s\en", name, + ldap_friendly_name( "ETCDIR/ldapfriendly", name, &map ) ); +.fi +.in -2 + +.sp +.LP +The mapping file should contain lines like this: unfriendlyname\etfriendlyname. +Lines that begin with a '#' character are comments and are ignored. +.sp +.LP +The \fBldap_free_friendlymap()\fR call is used to free structures allocated by +\fBldap_friendly_name()\fR when no more calls to \fBldap_friendly_name()\fR are +to be made. +.SH ERRORS +.sp +.LP +\fINULL\fR is returned by \fBldap_friendly_name()\fR if there is an error +opening \fIfilename\fR, or if the file has a bad format, or if the \fImap\fR +parameter is \fINULL\fR. +.SH FILES +.sp +.LP +\fBETCDIR/ldapfriendly.conf\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_get_dn.3ldap b/usr/src/man/man3ldap/ldap_get_dn.3ldap new file mode 100644 index 0000000000..030484d5cb --- /dev/null +++ b/usr/src/man/man3ldap/ldap_get_dn.3ldap @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_get_dn 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_get_dn, ldap_explode_dn, ldap_dn2ufn, ldap_is_dns_dn, ldap_explode_dns, +ldap_dns_to_dn \- LDAP DN handling functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBchar *\fR\fBldap_get_dn\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR); +.fi + +.LP +.nf +\fBchar **\fR\fBldap_explode_dn\fR(\fBchar\fR \fI*dn\fR, \fBint\fR \fInotypes\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBldap_dn2ufn\fR(\fBchar\fR \fI*dn\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_is_dns_dn\fR(\fBchar\fR \fI*dn\fR); +.fi + +.LP +.nf +\fBchar **\fR\fBldap_explode_dns\fR(\fBchar\fR \fI*dn\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBldap_dns_to_dn\fR(\fBchar\fR \fI*dns_name\fR, \fBint\fR \fI*nameparts\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions 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 \fIA String Representation of Distinguished +Names\fR, unless it is an experimental DNS-style DN which takes the form of an +\fIRFC 822\fR mail address. +.sp +.LP +The \fBldap_get_dn()\fR function takes an \fIentry\fR as returned by +\fBldap_first_entry\fR(3LDAP) or \fBldap_next_entry\fR(3LDAP) and returns a +copy of the entry's DN. Space for the DN will have been obtained by means of +\fBmalloc\fR(3C), and should be freed by the caller by a call to +\fBfree\fR(3C). +.sp +.LP +The \fBldap_explode_dn()\fR function takes a DN as returned by +\fBldap_get_dn()\fR and breaks it up into its component parts. Each part is +known as a Relative Distinguished Name, or RDN. \fBldap_explode_dn()\fR returns +a null-terminated array, each component of which contains an RDN from the DN. +The \fInotypes\fR 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 +\fBldap_value_free\fR(3LDAP). +.sp +.LP +\fBldap_dn2ufn()\fR is used to turn a DN as returned by \fBldap_get_dn()\fR +into a more user-friendly form, stripping off type names. See \fIRFC 1781\fR +"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 +\fBmalloc\fR(3C), and the user is responsible for freeing it by means of a call +to \fBfree\fR(3C). +.sp +.LP +\fBldap_is_dns_dn()\fR returns non-zero if the dn string is an experimental +DNS-style DN (generally in the form of an \fIRFC 822\fR e-mail address). It +returns zero if the dn appears to be an \fIRFC 1779\fR format DN. +.sp +.LP +\fBldap_explode_dns()\fR takes a DNS-style DN and breaks it up into its +component parts. \fBldap_explode_dns()\fR 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 \fBldap_value_free\fR(3LDAP). +.sp +.LP +\fBldap_dns_to_dn()\fR converts a DNS domain name into an X.500 distinguished +name. A string distinguished name and the number of nameparts is returned. +.SH ERRORS +.sp +.LP +If an error occurs in \fBldap_get_dn()\fR, \fINULL\fR is returned and the +\fBld_errno\fR field in the \fIld\fR parameter is set to indicate the error. +See \fBldap_error\fR(3LDAP) for a description of possible error codes. +\fBldap_explode_dn()\fR, \fBldap_explode_dns()\fR and \fBldap_dn2ufn()\fR will +return \fINULL\fR with \fBerrno\fR(3C) set appropriately in case of trouble. +.sp +.LP +If an error in \fBldap_dns_to_dn()\fR is encountered zero is returned. The +caller should free the returned string if it is non-zero. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_first_entry\fR(3LDAP), \fBldap_error\fR(3LDAP), +\fBldap_value_free\fR(3LDAP) +.SH NOTES +.sp +.LP +These functions allocate memory that the caller must free. diff --git a/usr/src/man/man3ldap/ldap_get_entry_controls.3ldap b/usr/src/man/man3ldap/ldap_get_entry_controls.3ldap new file mode 100644 index 0000000000..112072d10c --- /dev/null +++ b/usr/src/man/man3ldap/ldap_get_entry_controls.3ldap @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_get_entry_controls 3LDAP "6 Jan 2003" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_get_entry_controls \- get the LDAP controls included with a directory +entry in a set of search results +.SH SYNOPSIS +.LP +.nf +\fBcc\fR\fB-flag \&.\|.\|.\fR \fIfile\fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR] +#include <ldap.h> + +\fBint\fR \fBldap_get_entry_controls\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIentry\fR, + \fBLDAPControl ***\fR\fIserverctrlsp\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_get_entry_controls()\fR function retrieves the LDAP v3 controls +included in a directory entry in a chain of search results. The LDAP controls +are specified in an array of \fBLDAPControl\fR structures. Each +\fBLDAPControl\fR structure represents an LDAP control. The function takes +\fIentry\fR as a parameter, which points to an \fBLDAPMessage\fR structure that +represents an entry in a chain of search results. +.sp +.LP +The entry notification controls that are used with persistent search controls +are the only controls that are returned with individual entries. Other controls +are returned with results sent from the server. You can call +\fBldap_parse_result()\fR to retrieve those controls. +.SH ERRORS +.sp +.LP +\fBldap_get_entry_controls()\fR returns the following error codes. +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_SUCCESS\fR\fR +.ad +.RS 23n +.rt +LDAP controls were successfully retrieved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_DECODING_ERROR\fR\fR +.ad +.RS 23n +.rt +An error occurred when decoding the BER-encoded message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_PARAM_ERROR\fR\fR +.ad +.RS 23n +.rt +An invalid parameter was passed to the function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_NO_MEMORY\fR\fR +.ad +.RS 23n +.rt +Memory cannot be allocated. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_error\fR(3LDAP), \fBldap_parse_result\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_get_lang_values.3ldap b/usr/src/man/man3ldap/ldap_get_lang_values.3ldap new file mode 100644 index 0000000000..2aae55c586 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_get_lang_values.3ldap @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_get_lang_values 3LDAP "25 Oct 2001" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_get_lang_values, ldap_get_lang_values_len \- return an attribute's values +that matches a specified language subtype +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-flag \&.\|.\|.\fR \fIfile\fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR] +#include <ldap.h> + +\fBchar **\fR\fBldap_get_lang_values\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIentry\fR, + \fBconst char *\fR\fItarget\fR,\ \fBchar **\fR\fItype\fR +.fi + +.LP +.nf +\fBstruct berval **\fR\fBldap_get_lang_values_len\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIentry\fR, + \fBconst char *\fR\fItarget\fR, \fBchar **\fR\fItype\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_get_lang_values()\fR function returns an array of an attribute's +string values that matches a specified language subtype. To retrieve the binary +data from an attribute, call the \fBldap_get_lang_values_len()\fR function +instead. +.sp +.LP +\fBldap_get_lang_values()\fR should be called to retrieve a null-terminated +array of an attribute's string values that match a specified language subtype. +The \fIentry\fR parameter is the entry retrieved from the directory. The +\fItarget\fR parameter should contain the attribute type the values that are +required, including the optional language subtype. The \fItype\fR parameter +points to a buffer that returns the attribute type retrieved by this function. +Unlike the \fBldap_get_values()\fR function, if a language subtype is +specified, this function first attempts to find and return values that +match that subtype, for example, \fBcn;lang-en\fR. +.sp +.LP +\fBldap_get_lang_values_len()\fR returns a null-terminated array of pointers +to \fBberval\fR structures, each containing the length and pointer to a binary +value of an attribute for a given entry. The \fIentry\fR parameter is the +result returned by \fBldap_result()\fR or \fBldap_search_s()\fR functions. The +\fItarget\fR parameter is the attribute returned by the call to +\fBldap_first_attribute()\fR or \fBldap_next_attribute()\fR, or the attribute +as a literal string, such as \fBjpegPhoto\fR or \fBaudio\fR. +.sp +.LP +These functions are deprecated. Use \fBldap_get_values()\fR or +\fBldap_get_values_len()\fR instead. +.SH RETURN VALUES +.sp +.LP +If successful, \fBldap_get_lang_values()\fR returns a null-terminated array of +the attribute's values. If the call is unsuccessful, or if no such attribute +exists in the \fIentry\fR, it returns a \fINULL\fR and sets the appropriate +error code in the LDAP structure. +.sp +.LP +The \fBldap_get_lang_values_len()\fR function returns a null-terminated array +of pointers to \fBberval\fR structures, which in turn, if successful, contain +pointers to the attribute's binary values. If the call is unsuccessful, or if +no such attribute exists in the \fIentry\fR, it returns a \fINULL\fR and sets +the appropriate error code in the LDAP structure. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_first_attribute\fR(3LDAP), \fBldap_first_attribute\fR(3LDAP), +\fBldap_get_values\fR(3LDAP), \fBldap_result\fR(3LDAP), +\fBldap_search\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_get_option.3ldap b/usr/src/man/man3ldap/ldap_get_option.3ldap new file mode 100644 index 0000000000..ddf14b3f32 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_get_option.3ldap @@ -0,0 +1,613 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_get_option 3LDAP "15 Jan 2004" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_get_option, ldap_set_option \- get or set session preferences in the +\fBldap\fR structure. +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lldap\fR [ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBLDAP\fR \fBldap_set_option\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fIoption\fR, \fBvoid\fR \fI*optdata\fR[]); +.fi + +.LP +.nf +\fBLDAP\fR \fBldap_get_option\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fIoption\fR, \fBvoid\fR \fIoptdata\fR[]); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide an \fBLDAP\fR structure with access to session +preferences. The \fBldap_get_option()\fR function gets session preferences from +the \fBLDAP\fR structure. The \fBldap_set_option()\fR function sets session +preferences in the \fBLDAP\fR structure. +.sp +.LP +The \fIld\fR parameter specifies the connection handle, a pointer to an +\fBLDAP\fR structure that contains information about the \fBLDAP\fR server +connection. The \fIoption\fR parameter specifies the name of the option to be +read or modified. The \fIoptdata\fR parameter serves as a pointer to the value +of the option that you set or get. +.SH PARAMETERS +.sp +.LP +The following values can be specified for the \fIoption\fR parameter: +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_API_INFO\fR\fR +.ad +.sp .6 +.RS 4n +Retrieves basic information about the \fBLDAP\fR \fBAPI\fR implementation at +execution time. The data type for the \fIoptdata\fR parameter is +\fB(LDAPAPIInfo *)\fR. This option is READ-ONLY and cannot be set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_DEREF\fR\fR +.ad +.sp .6 +.RS 4n +Determines how aliases are handled during a search. The data type for the +\fIoptdata\fR parameter is \fB(int *)\fR. The following values can be specified +for the \fIoptdata\fR parameter: +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_DEREF_NEVER\fR\fR +.ad +.RS 24n +.rt +Specifies that aliases are never dereferenced. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_DEREF_SEARCHING\fR\fR +.ad +.RS 24n +.rt +Specifies that aliases are dereferenced when searching under the base object, +but not when finding the base object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_DEREF_FINDING\fR\fR +.ad +.RS 24n +.rt +Specifies that aliases are dereferenced when finding the base object, but not +when searching under the base object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_DEREF_ALWAYS\fR\fR +.ad +.RS 24n +.rt +Specifies that aliases are always dereferenced when finding the base object and +searching under the base object. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_SIZELIMIT\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the maximum number of entries returned by the server in search +results. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR. +Setting the \fIoptdata\fR parameter to \fBLDAP_NO_LIMIT\fR removes any size +limit enforced by the client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_TIMELIMIT\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the maximum number of seconds spent by the server when answering a +search request. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR. +Setting the \fIoptdata\fR parameter to \fBLDAP_NO_LIMIT\fR removes any time +limit enforced by the client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_REFERRALS\fR\fR +.ad +.sp .6 +.RS 4n +Determines whether the client should follow referrals. The data type for the +\fIoptdata\fR parameter is \fB(int *)\fR. The following values can be specified +for the \fIoptdata\fR parameter: +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_ON\fR\fR +.ad +.RS 16n +.rt +Specifies that the client should follow referrals. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_OFF\fR\fR +.ad +.RS 16n +.rt +Specifies that the client should not follow referrals. +.RE + +By default, the client follows referrals. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_RESTART\fR\fR +.ad +.sp .6 +.RS 4n +Determines whether \fBLDAP\fR I/O operations are automatically restarted if +aborted prematurely. It can be set to one of the constants \fBLDAP_OPT_ON\fR or +\fBLDAP_OPT_OFF\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_PROTOCOL_VERSION\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the version of the protocol supported by the client. The data type +for the \fIoptdata\fR parameter is \fB(int *)\fR. The version +\fBLDAP_VERSION2\fR or \fBLDAP_VERSION3\fR can be specified. If no version is +set, the default version \fBLDAP_VERSION2\fR is set. To use \fBLDAP\fR v3 +features, set the protocol version to \fBLDAP_VERSION3\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_SERVER_CONTROLS\fR\fR +.ad +.sp .6 +.RS 4n +Specifies a pointer to an array of \fBLDAPControl\fR structures that represent +the \fBLDAP\fR v3 server controls sent by default with every request. The data +type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is +\fB(LDAPControl **)\fR. For \fBldap_get_option()\fR, the data type is +\fB(LDAPControl ***)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_CLIENT_CONTROLS\fR\fR +.ad +.sp .6 +.RS 4n +Specifies a pointer to an array of \fBLDAPControl\fR structures that represent +the \fBLDAP\fR v3 client controls sent by default with every request. The data +type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is +\fB(LDAPControl **)\fR. For \fBldap_get_option()\fR, the data type is +\fB(LDAPControl ***)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_API_FEATURE_INFO\fR\fR +.ad +.sp .6 +.RS 4n +Retrieves version information at execution time about extended features of the +\fBLDAP\fR \fBAPI\fR. The data type for the \fIoptdata\fR parameter is +\fB(LDAPAPIFeatureInfo *)\fR. This option is READ-ONLY and cannot be set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_HOST_NAME\fR\fR +.ad +.sp .6 +.RS 4n +Sets the host name or a list of hosts for the primary \fBLDAP\fR server. The +data type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is +\fB(char *)\fR. For \fBldap_get_option()\fR, the data type is \fB(char **)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_ERROR_NUMBER\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the code of the most recent \fBLDAP\fR error that occurred for this +session. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_ERROR_STRING\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the message returned with the most recent \fBLDAP\fR error that +occurred for this session. The data type for the \fIoptdata\fR parameter for +\fBldap_set_option()\fR is \fB(char *)\fR and for \fBldap_get_option()\fR is +\fB(char **)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_MATCHED_DN\fR\fR +.ad +.sp .6 +.RS 4n +Specifies the matched \fBDN\fR value returned with the most recent \fBLDAP\fR +error that occurred for this session. The data type for the \fIoptdata\fR +parameter for \fBldap_set_option()\fR is \fB(char *)\fR and for +\fBldap_get_option()\fR is \fB(char **)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_REBIND_ARG\fR\fR +.ad +.sp .6 +.RS 4n +Sets the last argument passed to the routine specified by +\fBLDAP_OPT_REBIND_FN\fR. This option can also be set by calling the +\fBldap_set_rebind_proc()\fR function. The data type for the \fIoptdata\fR +parameter is \fB(void * )\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_REBIND_FN\fR\fR +.ad +.sp .6 +.RS 4n +Sets the routine to be called to authenticate a connection with another LDAP +server. For example, the option is used to set the routine called during the +course of a referral. This option can also be by calling the +\fBldap_set_rebind_proc()\fR function. The data type for the \fIoptdata\fR +parameter is \fB(\fR\fBLDAP_REBINDPROC_CALLBACK\fR\fB *)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_MECH\fR\fR +.ad +.sp .6 +.RS 4n +Sets the default SASL mechanism to call \fBldap_interactive_bind_s()\fR. The +data type for the \fIoptdata\fR parameter is \fB(char * )\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_REALM\fR\fR +.ad +.sp .6 +.RS 4n +Sets the default \fBSASL_REALM\fR. The default \fBSASL_REALM\fR should be used +during a SASL challenge in response to a \fBSASL_CB_GETREALM\fR request when +using the \fBldap_interactive_bind_s()\fR function. The data type for the +\fIoptdata\fR parameter is \fB(char * )\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_AUTHCID\fR\fR +.ad +.sp .6 +.RS 4n +Sets the default \fBSASL_AUTHNAME\fR used during a SASL challenge in response +to a \fBSASL_CB_AUTHNAME\fR request when using the +\fBldap_interactive_bind_s()\fR function. The data type for the \fIoptdata\fR +parameter is \fB(char * )\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_AUTHZID\fR\fR +.ad +.sp .6 +.RS 4n +Sets the default \fBSASL_USER\fR that should be used during a SASL challenge in +response to a \fBSASL_CB_USER\fR request when using the +\fBldap_interactive_bind_s\fR function. The data type for the \fIoptdata\fR +parameter is \fB(char * )\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_SSF\fR\fR +.ad +.sp .6 +.RS 4n +A read-only option used exclusively with the \fBldap_get_option()\fR function. +The \fBldap_get_option()\fR function performs a \fBsasl_getprop()\fR operation +that gets the \fBSASL_SSF\fR value for the current connection. The data type +for the \fIoptdata\fR parameter is \fB(sasl_ssf_t * )\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_SSF_EXTERNAL\fR\fR +.ad +.sp .6 +.RS 4n +A write-only option used exclusively with the \fBldap_set_option()\fR function. +The \fBldap_set_option()\fR function performs a \fBsasl_setprop()\fR operation +to set the \fBSASL_SSF_EXTERNAL\fR value for the current connection. The data +type for the \fIoptdata\fR parameter is \fB(sasl_ssf_t * )\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_SECPROPS\fR\fR +.ad +.sp .6 +.RS 4n +A write-only option used exclusively with the \fBldap_set_option()\fR. This +function performs a \fBsasl_setprop\fR(3SASL) operation for the +\fBSASL_SEC_PROPS\fR value for the current connection during an +\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR +parameter is \fB(char * )\fR, a comma delimited string containing text values +for any of the \fBSASL_SEC_PROPS\fR that should be set. The text values are: +.sp +.ne 2 +.mk +.na +\fB\fBnoanonymous\fR\fR +.ad +.RS 16n +.rt +Sets the \fBSASL_SEC_NOANONYMOUS\fR flag +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnodict\fR\fR +.ad +.RS 16n +.rt +Sets the \fBSASL_SEC_NODICTIONARY\fR flag +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnoplain\fR\fR +.ad +.RS 16n +.rt +Sets the \fBSASL_SEC_NOPLAINTEXT\fR flag +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBforwardsec\fR\fR +.ad +.RS 16n +.rt +Sets the \fBSASL_SEC_FORWARD_SECRECY\fR flag +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpasscred\fR\fR +.ad +.RS 16n +.rt +Sets the \fBSASL_SEC_PASS_CREDENTIALS\fR flag +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBminssf=N\fR\fR +.ad +.RS 16n +.rt +Sets \fBminssf\fR to the integer value \fBN\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmaxssf=N\fR\fR +.ad +.RS 16n +.rt +Sets \fBmaxssf\fR to the integer value \fBN\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmaxbufsize=N\fR\fR +.ad +.RS 16n +.rt +Sets \fBmaxbufsize\fR to the integer value \fBN\fR +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_SSF_MIN\fR\fR +.ad +.sp .6 +.RS 4n +Sets the default \fBSSF_MIN\fR value used during a +\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR +parameter is \fB(char * )\fR numeric string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_SSF_MAX\fR\fR +.ad +.sp .6 +.RS 4n +Sets the default \fBSSF_MAX\fR value used during a +\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR +parameter is \fB(char * )\fR numeric string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_OPT_X_SASL_MAXBUFSIZE\fR\fR +.ad +.sp .6 +.RS 4n +Sets the default \fBSSF_MAXBUFSIZE\fR value used during a +\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR +parameter is \fB(char * )\fR numeric string. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBldap_set_option()\fR and \fBldap_get_option()\fR functions return: +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_SUCCESS\fR\fR +.ad +.RS 16n +.rt +If successful +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-1\fR\fR +.ad +.RS 16n +.rt +If unsuccessful +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_init\fR(3LDAP), \fBsasl_setprop\fR(3SASL), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +There are other elements in the \fBLDAP\fR structure that should not be +changed. No assumptions should be made about the order of elements in the +\fBLDAP\fR structure. diff --git a/usr/src/man/man3ldap/ldap_get_values.3ldap b/usr/src/man/man3ldap/ldap_get_values.3ldap new file mode 100644 index 0000000000..5a56dba099 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_get_values.3ldap @@ -0,0 +1,106 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_get_values 3LDAP "28 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_get_values, ldap_get_values_len, ldap_count_values, ldap_count_values_len, +ldap_value_free, ldap_value_free_len \- LDAP attribute value handling functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBchar **\fR\fBldap_get_values\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR, \fBchar\fR \fI*attr\fR); +.fi + +.LP +.nf +\fBstruct berval **\fR\fBldap_get_values_len\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR, + \fBchar\fR \fI*attr\fR); +.fi + +.LP +.nf +\fB\fR\fBldap_count_values\fR(\fBchar\fR \fI**vals\fR); +.fi + +.LP +.nf +\fB\fR\fBldap_count_values_len\fR(\fBstruct berval\fR \fI**vals\fR); +.fi + +.LP +.nf +\fB\fR\fBldap_value_free\fR(\fBchar\fR \fI**vals\fR); +.fi + +.LP +.nf +\fB\fR\fBldap_value_free_len\fR(\fBstruct berval\fR \fI**vals\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to retrieve and manipulate attribute values from an +LDAP entry as returned by \fBldap_first_entry\fR(3LDAP) or +\fBldap_next_entry\fR(3LDAP). \fBldap_get_values()\fR takes the \fIentry\fR and +the attribute \fIattr\fR whose values are desired and returns a null-terminated +array of the attribute's values. \fIattr\fR may be an attribute type as +returned from \fBldap_first_attribute\fR(3LDAP) or +\fBldap_next_attribute\fR(3LDAP), or if the attribute type is known it can +simply be given. +.sp +.LP +The number of values in the array can be counted by calling +\fBldap_count_values()\fR. The array of values returned can be freed by calling +\fBldap_value_free()\fR. +.sp +.LP +If the attribute values are binary in nature, and thus not suitable to be +returned as an array of char *'s, the \fBldap_get_values_len()\fR function can +be used instead. It takes the same parameters as \fBldap_get_values()\fR, but +returns a null-terminated array of pointers to berval structures, each +containing the length of and a pointer to a value. +.sp +.LP +The number of values in the array can be counted by calling +\fBldap_count_values_len()\fR. The array of values returned can be freed by +calling \fBldap_value_free_len()\fR. +.SH ERRORS +.sp +.LP +If an error occurs in \fBldap_get_values()\fR or \fBldap_get_values_len()\fR, +\fINULL\fR returned and the \fBld_errno\fR field in the \fBld\fR parameter is +set to indicate the error. See \fBldap_error\fR(3LDAP) for a description of +possible error codes. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_first_entry\fR(3LDAP), +\fBldap_first_attribute\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +These functions allocates memory that the caller must free. diff --git a/usr/src/man/man3ldap/ldap_getfilter.3ldap b/usr/src/man/man3ldap/ldap_getfilter.3ldap new file mode 100644 index 0000000000..531d4a64a4 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_getfilter.3ldap @@ -0,0 +1,160 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_getfilter 3LDAP "28 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_getfilter, ldap_init_getfilter, ldap_init_getfilter_buf, +ldap_getfilter_free, ldap_getfirstfilter, ldap_getnextfilter, +ldap_setfilteraffixes, ldap_build_filter \- LDAP filter generating functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> +#define LDAP_FILT_MAXSIZ 1024 + +\fBLDAPFiltDesc *\fR\fBldap_init_getfilter\fR(\fBchar\fR \fI*file\fR); +.fi + +.LP +.nf +\fBLDAPFiltDesc *\fR\fBldap_init_getfilter_buf\fR(\fBchar\fR \fI*buf\fR, \fBlong\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fB\fR\fBldap_getfilter_free\fR(\fBLDAPFiltDesc\fR \fI*lfdp\fR); +.fi + +.LP +.nf +\fBLDAPFiltInfo *\fR\fBldap_getfirstfilter\fR(\fBLDAPFiltDesc\fR \fI*lfdp\fR, \fBchar\fR \fI*tagpat\fR, + \fBchar\fR \fI*value\fR); +.fi + +.LP +.nf +\fBLDAPFiltInfo *\fR\fBldap_getnextfilter\fR(\fBLDAPFiltDesc\fR \fI*lfdp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_setfilteraffixes\fR(\fBLDAPFiltDesc\fR \fI*lfdp\fR, \fBchar\fR \fI*prefix\fR, + \fBchar\fR \fI*suffix\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_build_filter\fR(\fBchar\fR \fI*buf\fR, \fBunsigned long\fR \fIbuflen\fR, \fBchar\fR \fI*pattern\fR, + \fBchar\fR \fI*prefix\fR, \fBchar\fR \fI*suffix\fR, \fBchar\fR \fI*attr\fR, \fBchar\fR \fI*value\fR, + \fBchar\fR \fI**valwords\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to generate filters to be used in +\fBldap_search\fR(3LDAP) or \fBldap_search_s\fR(3LDAP). Either +\fBldap_init_getfilter\fR or \fBldap_init_getfilter_buf\fR must be called prior +to calling any of the other functions except \fBldap_build_filter\fR. +.sp +.LP +\fBldap_init_getfilter()\fR takes a file name as its only argument. The +contents of the file must be a valid LDAP filter configuration file (see +\fBldapfilter.conf\fR(4)). If the file is successfully read, a pointer to an +\fBLDAPFiltDesc\fR is returned. This is an opaque object that is passed in +subsequent get filter calls. +.sp +.LP +\fBldap_init_getfilter_buf()\fR reads from \fIbuf\fR, whose length is +\fIbuflen\fR, the LDAP filter configuration information. \fIbuf\fR must point +to the contents of a valid LDAP filter configuration file. See +\fBldapfilter.conf\fR(4). If the filter configuration information is +successfully read, a pointer to an \fBLDAPFiltDesc\fR is returned. This is an +opaque object that is passed in subsequent get filter calls. +.sp +.LP +\fBldap_getfilter_free()\fR deallocates the memory consumed by +\fBldap_init_getfilter\fR. Once it is called, the \fBLDAPFiltDesc\fR is no +longer valid and cannot be used again. +.sp +.LP +\fBldap_getfirstfilter()\fR retrieves the first filter that is appropriate for +\fIvalue.\fR Only filter sets that have tags that match the regular expession +\fItagpat\fR are considered. \fBldap_getfirstfilter\fR returns a pointer to an +\fBLDAPFiltInfo\fR structure, which contains a filter with \fIvalue\fR inserted +as appropriate in \fBlfi_filter,\fR a text match description in +\fBlfi_desc,\fR \fBlfi_scope\fR set to indicate the search scope, and +\fBlfi_isexact\fR set to indicate the type of filter. \fINULL\fR is returned +if no matching filters are found. \fBlfi_scope\fR will be one of +\fBLDAP_SCOPE_BASE\fR, \fBLDAP_SCOPE_ONELEVEL\fR, or +\fBLDAP_SCOPE_SUBTREE\fR\fB\&.\fR \fBlfi_isexact\fR will be zero if the filter +has any '~' or '*' characters in it and non-zero otherwise. +.sp +.LP +\fBldap_getnextfilter()\fR retrieves the next appropriate filter in the filter +set that was determined when \fBldap_getfirstfilter\fR was called. It returns +\fINULL\fR when the list has been exhausted. +.sp +.LP +\fBldap_setfilteraffixes()\fR sets a \fIprefix\fR to be prepended and a +\fIsuffix\fR to be appended to all filters returned in the future. +.sp +.LP +\fBldap_build_filter()\fR constructs an LDAP search filter in \fIbuf.\fR +\fIbuflen\fR is the size, in bytes, of the largest filter \fIbuf\fR can hold. +A pattern for the desired filter is passed in \fIpattern.\fR Where the string +%a appears in the pattern it is replaced with \fIattr.\fR \fIprefix\fR is +pre-pended to the resulting filter, and \fIsuffix\fR is appended. Either can +be NULL , in which case they are not used. \fIvalue\fR and \fIvalwords\fR are +used when the string %v appears in \fIpattern.\fR See \fBldapfilter.conf\fR(4) +for a description of how %v is handled. +.SH ERRORS +.sp +.LP +\fINULL\fR is returned by \fBldap_init_getfilter\fR if there is an error +reading \fIfile.\fR \fINULL\fR \fBis\fR \fBreturned\fR \fBby\fR +\fBldap_getfirstfilter\fR and \fBldap_getnextfilter\fR when there are no more +appropriate filters to return. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fBETCDIR/ldapfilter.conf\fR\fR +.ad +.RS 26n +.rt +LDAP filtering routine configuration file. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldapfilter.conf\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The return values for all of these functions are declared in the <\fBldap.h\fR> +header file. Some functions may allocate memory which must be freed by the +calling application. diff --git a/usr/src/man/man3ldap/ldap_memcache.3ldap b/usr/src/man/man3ldap/ldap_memcache.3ldap new file mode 100644 index 0000000000..cf8510eab3 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_memcache.3ldap @@ -0,0 +1,262 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_memcache 3LDAP "6 Jan 2003" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_memcache, ldap_memcache_init, ldap_memcache_set, ldap_memcache_get, +ldap_memcache_flush, ldap_memcache_destroy, ldap_memcache_update \- LDAP client +caching functions +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-flag \&.\|.\|.\fR \fIfile\fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR] +#include <ldap.h> + +\fBint\fR \fBldap_memcache_init\fR(\fBunsigned long\fR \fIttl\fR, \fBunsigned long\fR \fIsize\fR, + \fBchar **\fR\fIbaseDNs\fR,\fBstruct ldap_thread_fns *\fR\fIthread_fns\fR, + \fBLDAPMemCache **\fR\fIcachep\fR +.fi + +.LP +.nf +\fBint\fR \fBldap_memcache_set\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMemCache **\fR\fIcache\fR +.fi + +.LP +.nf +\fBint\fR \fBldap_memcache_get\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMemCache **\fR\fIcachep\fR +.fi + +.LP +.nf +\fBvoid\fR \fBldap_memcache_flush\fR(\fBLDAPMemCache *\fR\fIcache\fR, \fBchar *\fR\fIdn\fR, \fBint\fR \fIscope\fR +.fi + +.LP +.nf +\fBvoid\fR \fBldap_memcache_destroy\fR(\fBLDAPMemCache *\fR\fIcache\fR +.fi + +.LP +.nf +\fBvoid\fR \fBldap_memcache_update\fR(\fBLDAPMemCache *\fR\fIcache\fR +.fi + +.SH DESCRIPTION +.sp +.LP +Use the \fBldap_memcache\fR functions to maintain an in-memory client side +cache to store search requests. Caching improves performance and reduces +network bandwidth when a client makes repeated requests. The \fIcache\fR uses +search criteria as the key to the cached items. When you send a search request, +the \fIcache\fR checks the search criteria to determine if that request has +been previously stored . If the request was stored, the search results are read +from the \fIcache\fR. +.sp +.LP +Make a call to \fBldap_memcache_init()\fR to create the in-memory client side +\fIcache\fR. The function passes back a pointer to an \fBLDAPMemCache\fR +structure, which represents the \fIcache\fR. Make a call to the +\fBldap_memcache_set()\fR function to associate this \fIcache\fR with an LDAP +connection handle, an LDAP structure. \fIttl\fR is the the maximum amount of +time (in seconds) that an item can be cached. If a \fIttl\fR value of 0 is +passed, there is no limit to the amount of time that an item can be cached. +\fIsize\fR is the maximum amount of memory (in bytes) that the cache will +consume. A zero value of \fIsize\fR means the cache has no size limit. +\fIbaseDNS\fR is an array of the base DN strings representing the base DNs of +the search requests you want cached. If \fIbaseDNS\fR is not \fINULL\fR, only +the search requests with the specified base DNs will be cached. If +\fIbaseDNS\fR is \fINULL\fR, all search requests are cached. The +\fIthread_fns\fR parameter takes an \fBldap_thread_fns structure\fR specifying +the functions that you want used to ensure that the cache is thread-safe. You +should specify this if you have multiple threads that are using the same +connection handle and cache. If you are not using multiple threads, pass +\fINULL\fR for this parameter. +.sp +.LP +\fBldap_memcache_set()\fR associates an in-memory \fIcache\fR that you have +already created by calling the \fBldap_memcache_init()\fR function with an +LDAP connection handle. The \fIld\fR parameter should be the result of a +successful call to \fBldap_open\fR(3LDAP). The \fIcache\fR parameter should be +the result of a \fIcache\fR created by the \fBldap_memcache_init()\fR call. +After you call this function, search requests made over the specified LDAP +connection will use this cache. To disassociate the cache from the LDAP +connection handle, make a call to the \fBldap_bind\fR(3LDAP) or +\fBldap_bind\fR(3LDAP) function. Make a call to \fBldap_memcache_set()\fR if +you want to associate a cache with multiple LDAP connection handles. For +example, call the \fBldap_memcache_get()\fR function to get the \fIcache\fR +associated with one connection, then you can call this function and associate +the \fIcache\fR with another connection. +.sp +.LP +The \fBldap_memcache_get()\fR function gets the \fIcache\fR associated with the +specified connection handle (LDAP structure). This \fIcache\fR is used by all +search requests made through that connection. When you call this function, the +function sets the \fIcachep\fR parameter as a pointer to the \fBLDAPMemCache\fR +structure that is associated with the connection handle. +.sp +.LP +\fBldap_memcache_flush()\fR flushes search requests from the \fIcache\fR. If +the base DN of a search request is within the scope specified by the \fIdn\fR +and \fIscope\fR arguments, the search request is flushed from the \fIcache\fR. +If no DN is specified, the entire cache is flushed. The \fIscope\fR parameter, +along with the \fIdn\fR parameter, identifies the search requests that you want +flushed from the \fIcache\fR. This argument can have one of the following +values: +.br +.in +2 +\fBLDAP_SCOPE_BASE\fR +.in -2 +.br +.in +2 +\fBLDAP_SCOPE_ONELEVEL\fR +.in -2 +.br +.in +2 +\fBLDAP_SCOPE_SUBTREE\fR +.in -2 +.sp +.LP +\fBldap_memcache_destroy()\fR frees the specified \fBLDAPMemCache\fR structure +pointed to by \fIcache\fR from memory. Call this function after you are done +working with a \fIcache\fR. +.sp +.LP +\fBldap_memcache_update()\fR checks the cache for items that have expired and +removes them. This check is typically done as part of the way the \fIcache\fR +normally works. You do not need to call this function unless you want to +update the \fIcache\fR at this point in time. This function is only useful in +a multithreaded application, since it will not return until the \fIcache\fR is +destroyed. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIttl\fR\fR +.ad +.RS 14n +.rt +The maximum amount of time (in seconds) that an item can be cached +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 14n +.rt +The maximum amount of memory (in bytes) that the cache will consume. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbaseDNs\fR\fR +.ad +.RS 14n +.rt +An array of the base DN strings representing the base DNs of the search +requests you want cached +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIthread_fns\fR\fR +.ad +.RS 14n +.rt +A pointer to the \fBldap_thread_fns structure\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcachep\fR\fR +.ad +.RS 14n +.rt +A pointer to the \fBLDAPMemCache\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcache\fR\fR +.ad +.RS 14n +.rt +The result of a \fIcache\fR created by the \fBldap_memcache_init()\fR call +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIld\fR\fR +.ad +.RS 14n +.rt +The result of a successful call to \fBldap_open\fR(3LDAP) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdn\fR\fR +.ad +.RS 14n +.rt +The search requests that you want flushed from the \fIcache\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIscope\fR\fR +.ad +.RS 14n +.rt +The search requests that you want flushed from the \fIcache\fR +.RE + +.SH ERRORS +.sp +.LP +The functions that have \fBint\fR return values return \fBLDAP_SUCCESS\fR if +the operation was successful. Otherwise, they return another LDAP error code. +See \fBldap_error\fR(3LDAP) for a list of the LDAP error codes. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_error\fR(3LDAP), \fBldap_open\fR(3LDAP), \fBldap_search\fR(3LDAP), +\fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_memfree.3ldap b/usr/src/man/man3ldap/ldap_memfree.3ldap new file mode 100644 index 0000000000..b46dc12a0a --- /dev/null +++ b/usr/src/man/man3ldap/ldap_memfree.3ldap @@ -0,0 +1,72 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_memfree 3LDAP "6 Jan 2003" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_memfree \- free memory allocated by LDAP API functions +.SH SYNOPSIS +.LP +.nf +\fBcc \fR\fB-flag \&.\|.\|.\fR \fIfile \fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR] +#include < lber.h> +#include < ldap.h> + +\fBvoid\fR \fBldap_memfree\fR(\fBvoid *\fR\fIp\fR +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_memfree()\fR function frees the memory allocated by certain LDAP +API functions that do not have corresponding functions to free memory. These +functions include \fBldap_get_dn\fR(3LDAP), \fBldap_first_attribute\fR(3LDAP), +and \fBldap_next_attribute\fR(3LDAP). +.sp +.LP +The \fBldap_memfree()\fR function takes one parameter, \fIp\fR, which is a +pointer to the memory to be freed. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIp\fR\fR +.ad +.RS 5n +.rt +A pointer to the memory to be freed. +.RE + +.SH RETURN VALUES +.sp +.LP +There are no return values for the \fBldap_memfree()\fR function. +.SH ERRORS +.sp +.LP +No errors are defined for the \fBldap_memfree()\fR function. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_first_attribute\fR(3LDAP), \fBldap_get_dn\fR(3LDAP), +\fBldap_next_attribute\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_modify.3ldap b/usr/src/man/man3ldap/ldap_modify.3ldap new file mode 100644 index 0000000000..b3f9b65442 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_modify.3ldap @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_modify 3LDAP "28 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_modify, ldap_modify_s, ldap_mods_free, ldap_modify_ext, ldap_modify_ext_s +\- LDAP entry modification functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_modify\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*mods\fR[]); +.fi + +.LP +.nf +\fBint\fR \fBldap_modify_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI*mods\fR[]); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_mods_free\fR(\fBLDAPMod\fR \fI**mods\fR, \fBint\fR \fIfreemods\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_modify_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**mods\fR, + \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR, \fBint\fR \fI*msgidp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_modify_ext_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMod\fR \fI**mods\fR, + \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The function \fBldap_modify_s()\fR is used to perform an LDAP modify operation. +\fIdn\fR is the DN of the entry to modify, and \fImods\fR is a null-terminated +array of modifications to make to the entry. Each element of the \fImods\fR +array is a pointer to an \fBLDAPMod\fR structure, which is defined below. +.sp +.in +2 +.nf + typedef struct ldapmod { + int mod_op; + char *mod_type; + union { + char **modv_strvals; + struct berval **modv_bvals; + } mod_vals; + } LDAPMod; + #define mod_values mod_vals.modv_strvals + #define mod_bvalues mod_vals.modv_bvals +.fi +.in -2 + +.sp +.LP +The \fImod_op\fR field is used to specify the type of modification to perform +and should be one of \fBLDAP_MOD_ADD\fR, \fBLDAP_MOD_DELETE\fR, or +\fBLDAP_MOD_REPLACE\fR. The \fImod_type\fR and \fImod_values\fR fields specify +the attribute type to modify and a null-terminated array of values to add, +delete, or replace respectively. +.sp +.LP +If you need to specify a non-string value (for example, to add a photo or audio +attribute value), you should set \fImod_op\fR to the logical OR of the +operation as above (for example, \fBLDAP_MOD_REPLACE\fR) and the constant +\fBLDAP_MOD_BVALUES\fR. In this case, \fImod_bvalues\fR should be used instead +of \fImod_values\fR, and it should point to a null-terminated array of struct +bervals, as defined in <\fBlber.h\fR>. +.sp +.LP +For \fBLDAP_MOD_ADD\fR modifications, the given values are added to the entry, +creating the attribute if necessary. For \fBLDAP_MOD_DELETE\fR 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 \fImod_values\fR +field should be set to NULL. For \fBLDAP_MOD_REPLACE\fR modifications, the +attribute will have the listed values after the modification, having been +created if necessary. All modifications are performed in the order in which +they are listed. +.sp +.LP +\fBldap_modify_s()\fR returns the LDAP error code resulting from the modify +operation. +.sp +.LP +The \fBldap_modify()\fR operation works the same way as \fBldap_modify_s()\fR, +except that it is asynchronous, returning the message id of the request it +initiates, or \fB\(mi1\fR on error. The result of the operation can be +obtained by calling \fBldap_result\fR(3LDAP). +.sp +.LP +\fBldap_mods_free()\fR can be used to free each element of a null-terminated +array of mod structures. If \fIfreemods\fR is non-zero, the \fImods\fR pointer +itself is freed as well. +.sp +.LP +The \fBldap_modify_ext()\fR function initiates an asynchronous modify +operation and returns \fBLDAP_SUCCESS\fR if the request was successfully sent +to the server, or else it returns a LDAP error code if not. See +\fBldap_error\fR(3LDAP). If successful, \fBldap_modify_ext()\fR places the +message id of the request in \fI*msgidp\fR. A subsequent call to +\fBldap_result\fR(3LDAP), can be used to obtain the result of the add request. +.sp +.LP +The \fBldap_modify_ext_s()\fR function initiates a synchronous modify +operation and returns the result of the operation itself. +.SH ERRORS +.sp +.LP +\fBldap_modify_s()\fR returns an LDAP error code, either \fBLDAP_SUCCESS\fR or +an error. See \fBldap_error\fR(3LDAP). +.sp +.LP +\fBldap_modify()\fR returns \fB\(mi1\fR in case of trouble, setting the +\fBerror\fR field of \fIld\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_add\fR(3LDAP), \fBldap_error\fR(3LDAP), +\fBldap_get_option\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_modrdn.3ldap b/usr/src/man/man3ldap/ldap_modrdn.3ldap new file mode 100644 index 0000000000..2022fbdec9 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_modrdn.3ldap @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_modrdn 3LDAP "22 Octo 2001" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s, ldap_rename, +ldap_rename_s \- modify LDAP entry RDN +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR...\fB-l\fR ldap [ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_modrdn\fR(\fBLDAP\fR \fI*ld\fR, \fBconst char\fR \fI*dn\fR, \fBconst char\fR \fI*newrdn\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_modrdn_s\fR(\fBLDAP\fR \fI*ld\fR, \fBconst char\fR \fI*dn\fR, \fBconst char\fR \fI*newrdn\fR, + \fBint\fR \fIdeleteoldrdn\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_modrdn2\fR(\fBLDAP\fR \fI*ld\fR, \fBconst char\fR \fI*dn\fR, \fBconst char\fR \fI*newrdn\fR, + \fBint\fR \fIdeleteoldrdn\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_modrdn2_s\fR(\fBLDAP\fR \fI*ld\fR, \fBconst char\fR \fI*dn\fR, + \fBconst char\fR \fI*newrdn\fR, \fBint\fR \fIdeleteoldrdn\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_rename\fR(\fBLDAP\fR \fI*ld\fR, \fBconst char\fR \fI*dn\fR, \fBconst char\fR \fI*newrdn\fR, + \fBconst char\fR \fI*newparent\fR, \fBint\fR \fIdeleteoldrdn\fR, + \fBLDAPControl\fR \fI**serverctrls\fR, \fBLDAPControl\fR \fI**clientctrls\fR, + \fBint\fR \fI*msgidp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_rename_s\fR(\fBLDAP\fR \fI*ld\fR, \fBconst char\fR \fI*dn\fR, \fBconst char\fR \fI*newrdn\fR, + \fBconst char\fR \fI*newparent\fR,\ \fBconst int\fR \fIdeleteoldrdn\fR, + \fBLDAPControl\fR \fI**serverctrls\fR,\fBLDAPControl\fR \fI**clientctrls\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_modrdn()\fR and \fBldap_modrdn_s()\fR functions perform an LDAP +modify RDN (Relative Distinguished Name) operation. They both take \fIdn\fR, +the DN (Distinguished Name) of the entry whose RDN is to be changed, and +\fInewrdn\fR, the new RDN, to give the entry. The old RDN of the entry is never +kept as an attribute of the entry. \fBldap_modrdn()\fR is asynchronous. It +return the message id of the operation it initiates. \fBldap_modrdn_s()\fR is +synchronous. It returns the LDAP error code that indicates the success or +failure of the operation. +.sp +.LP +The \fBldap_modrdn2()\fR and \fBldap_modrdn2_s()\fR functions also perform an +LDAP modify RDN operation. They take the same parameters as above. In +addition, they both take the \fIdeleteoldrdn\fR parameter ,which is used as a +boolean value to indicate whether or not the old RDN values should be deleted +from the entry. +.sp +.LP +The \fBldap_rename()\fR, \fBldap_rename_s()\fR routines are used to change the +name, that is, the RDN of an entry. These routines deprecate the +\fBldap_modrdn()\fR and \fBldap_modrdn_s()\fR routines, as well as +\fBldap_modrdn2()\fR and \fBldap_modrdn2_s()\fR. +.sp +.LP +The \fBldap_rename()\fR and \fBldap_rename_s()\fR functions both support +LDAPv3 server controls and client controls. +.SH ERRORS +.sp +.LP +The synchronous (\fB_s\fR) versions of these functions return an LDAP error +code, either \fBLDAP_SUCCESS\fR or an error. See \fBldap_error\fR(3LDAP). +.sp +.LP +The asynchronous versions return \fB\(mi1\fR in the event of an error, setting +the \fBld_errno\fR field of \fIld\fR. See \fBldap_error\fR(3LDAP) for more +details. Use \fBldap_result\fR(3LDAP) to determine a particular unsuccessful +result. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes of the +\fBldap_modrdn()\fR, \fBldap_modrdn_s()\fR, \fBldap_modrdn2()\fR and +\fBldap_modrdn2_s()\fR functions: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityObsolete +.TE + +.sp +.LP +The \fBldap_rename()\fR and \fBldap_rename_s()\fR functions have the following +attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_error\fR(3LDAP) , \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_open.3ldap b/usr/src/man/man3ldap/ldap_open.3ldap new file mode 100644 index 0000000000..e9e3c9c451 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_open.3ldap @@ -0,0 +1,129 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_open 3LDAP "15 Jan 2004" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_open, ldap_init \- initialize an LDAP session +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... -lldap [ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBLDAP *\fR\fBldap_open\fR(\fBconst char *\fR\fIhost\fR, \fBint\fR \fIport\fR); +.fi + +.LP +.nf +\fBLDAP *\fR\fBldap_init\fR(\fBconst char *\fR\fIhost\fR, \fBint\fR \fIport\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_open()\fR function initializes an LDAP session and also opens a +connection to an LDAP server before it returns to the caller. Unlike +\fBldap_open()\fR, \fBldap_init()\fR does not open a connection to the LDAP +server until an operation, such as a search request, is performed. +.sp +.LP +The \fBldap_open()\fR function is deprecated and should no longer be used. Call +\fBldap_init()\fR instead. +.sp +.LP +A list of LDAP hostnames or an IPv4 or IPv6 address can be specified with the +\fBldap_open()\fR and \fBldap_init()\fR functions. The hostname can include a +port number, separated from the hostname by a colon (\fB:\fR). A port number +included as part of the hostname takes precedence over the \fIport\fR +parameter. The \fBldap_open()\fR and \fBldap_init()\fR functions attempt +connections with LDAP hosts in the order listed and return the first successful +connection. +.SH PARAMETERS +.sp +.LP +These functions support the following parameters. +.sp +.ne 2 +.mk +.na +\fB\fIhost\fR\fR +.ad +.RS 8n +.rt +The hostname, IPv4 or IPv6 address of the host that runs the LDAP server. A +space-separated list of hostnames can also be used for this parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIport\fR\fR +.ad +.RS 8n +.rt +TCP port number of a connection. Supply the constant \fBLDAP_PORT\fR to obtain +the default LDAP port of 389. If a host includes a port number, the default +parameter is ignored. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBldap_open()\fR and \fBldap_init()\fR functions return a handle to an +LDAP session that contains a pointer to an opaque structure. The structure must +be passed to subsequent calls for the session. If a session cannot be +initialized, the functions return \fINULL\fR and \fBerrno\fR should be set +appropriately. +.sp +.LP +Various aspects of this opaque structure can be read or written to control the +session-wide parameters. Use the \fBldap_get_option\fR(3LDAP) to access the +current option values and the \fBldap_set_option\fR(3LDAP) to set values for +these options. +.SH EXAMPLES +.LP +\fBExample 1 \fRSpecifying IPv4 and IPv6 Addresses +.sp +.LP +LDAP sessions can be initialized with hostnames, IPv4 or IPv6 addresses, such +as those shown in the following examples. + +.sp +.in +2 +.nf +ldap_init("hosta:636 hostb", 389) +ldap_init("192.168.82.110:389", 389) +ldap_init("[fec0::114:a00:20ff:ab3d:83ed]", 389) +.fi +.in -2 +.sp + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBerrno\fR(3C), \fBldap\fR(3LDAP), \fBldap_bind\fR(3LDAP), +\fBldap_get_option\fR(3LDAP), \fBldap_set_option\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_parse_result.3ldap b/usr/src/man/man3ldap/ldap_parse_result.3ldap new file mode 100644 index 0000000000..ff1b97d48c --- /dev/null +++ b/usr/src/man/man3ldap/ldap_parse_result.3ldap @@ -0,0 +1,66 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_parse_result 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_parse_result, ldap_parse_extended_result, ldap_parse_sasl_bind_result \- +LDAP message result parser +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_parse_result\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR, \fBint\fR \fI*errcodep\fR, + \fBchar\fR \fI**matcheddnp\fR,\fBchar\fR \fI**errmsgp\fR, \fBchar\fR \fI***referralsp\fR, + \fBLDAPControl\fR \fI***serverctrlsp\fR,\fBint\fR \fIfreeit\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_parse_sasl_bind_result\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR, + \fBstruct berval\fR\fI**servercredp\fR,\fBint\fR \fIfreeit\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_parse_extended_result\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*res\fR, + \fBstruct berval\fR\fBchar\fR \fI**resultoidp\fR, \fI**resultdata\fR, \fBint\fR \fIfreeit\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_parse_extended_result()\fR, \fBldap_parse_result()\fR and +\fBldap_parse_sasl_bind_result()\fR routines search for a message to parse. +These functions skip messages of type \fBLDAP_RES_SEARCH_ENTRY\fR and +\fBLDAP_RES_SEARCH_REFERENCE\fR. +.SH RETURN VALUES +.sp +.LP +They return \fBLDAP_SUCCESS\fR if the result was successfully parsed or an +LDAP error code if not (see \fBldap_error\fR(3LDAP)). +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_error\fR(3LDAP), \fBldap_result\fR(3LDAP), \fBattributes\fR(5) diff --git a/usr/src/man/man3ldap/ldap_result.3ldap b/usr/src/man/man3ldap/ldap_result.3ldap new file mode 100644 index 0000000000..374e354f52 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_result.3ldap @@ -0,0 +1,121 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_result 3LDAP "31 Mar 2009" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_result, ldap_msgfree \- wait for and return LDAP operation result +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_result\fR(\fBLDAP *\fR\fIld\fR, \fBint\fR \fImsgid\fR, \fBint\fR \fIall\fR, + \fBstruct timeval *\fR\fItimeout\fR, \fBLDAPMessage **\fR\fIresult\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_msgfree\fR(\fBLDAPMessage *\fR\fImsg\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBldap_result()\fR function is used to wait for and return the result of +an operation previously initiated by one of the LDAP asynchronous operation +functions , for example, \fBldap_search\fR(3LDAP), and +\fBldap_modify\fR(3LDAP). Those functions all return \fB\(mi1\fR in case of +error, and an invocation identifier upon successful initiation 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 \fBldap_result()\fR through the \fImsgid\fR +parameter. +.sp +.LP +The \fBldap_result()\fR function will block or not, depending upon the setting +of the \fItimeout\fR parameter. If \fItimeout\fR is not a null pointer, it +specifies a maximum interval to wait for the selection to complete. If +\fItimeout\fR is a null pointer, the select blocks indefinitely. To effect a +poll, the \fItimeout\fR argument should be a non-null pointer, pointing to a +zero-valued \fBtimeval\fR structure. See \fBselect\fR(3C) for further details. +.sp +.LP +If the result of a specific operation is required, \fImsgid\fR should be set to +the invocation identifier returned when the operation was initiated, otherwise +\fBLDAP_RES_ANY\fR should be supplied. The \fIall\fR 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. +.sp +.LP +A search response is made up of zero or more search entries followed by a +search result. If \fIall\fR is set to 0, search entries will be returned one +at a time as they come in, by means of separate calls to \fBldap_result()\fR. +If it is set to a non-zero value, the search response will only be returned in +its entirety, that is, after all entries and the final search result have been +received. +.sp +.LP +Upon success, the type of the result received is returned and the \fIresult\fR +parameter will contain the result of the operation. This result should be +passed to the LDAP parsing functions, (see \fBldap_first_entry\fR(3LDAP)) for +interpretation. +.sp +.LP +The possible result types returned are: +.sp +.in +2 +.nf +#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 +.fi +.in -2 + +.sp +.LP +The \fBldap_msgfree()\fR function is used to free the memory allocated for a +result by \fBldap_result()\fR or \fBldap_search_s\fR(3LDAP) functions. It +takes a pointer to the result to be freed and returns the type of the message +it freed. +.SH ERRORS +.sp +.LP +The \fBldap_result()\fR function returns \fB\(mi1\fR on error and 0 if the +specified timeout was exceeded. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBselect\fR(1), \fBldap\fR(3LDAP), \fBldap_search\fR(3LDAP) , +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBldap_result()\fR function allocates memory for results that it receives. +The memory can be freed by calling \fBldap_msgfree\fR(3LDAP). diff --git a/usr/src/man/man3ldap/ldap_search.3ldap b/usr/src/man/man3ldap/ldap_search.3ldap new file mode 100644 index 0000000000..3e74ab682f --- /dev/null +++ b/usr/src/man/man3ldap/ldap_search.3ldap @@ -0,0 +1,181 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_search 3LDAP "05 Dec 2003" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_search, ldap_search_s, ldap_search_ext, ldap_search_ext_s, ldap_search_st +\- LDAP search operations +.SH SYNOPSIS +.LP +.nf +\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR...] +#include <sys/time.h> /* for struct timeval definition */ +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR, + \fBchar\fR \fI*attrs\fR[], \fBint\fR \fIattrsonly\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR, + \fBchar\fR \fI*attrs\fR[],\fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_search_st\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR, + \fBchar\fR \fI*attrs\fR[], \fBint\fR \fIattrsonly\fR, \fBstruct timeval\fR \fI*timeout\fR, + \fBLDAPMessage\fR \fI**res\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_search_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR + \fI*filter\fR, \fBchar\fR \fI**attrs\fR,\ \fBint\fR \fIattrsonly\fR, \fBLDAPControl\fR \fI**serverctrls\fR, + \fBLDAPControl\fR \fI**clientctrls\fR, \fBstruct timeval\fR \fI*timeoutp\fR, + \fBint\fR \fIsizelimit\fR, \fBint\fR \fI*msgidp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_search_ext_s\fR(\fBLDAP\fR \fI*ld\fR,char \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR, + \fBchar\fR \fI**attrs\fR, \fBint\fR \fIattrsonly\fR, \fBLDAPControl\fR \fI**serverctrls\fR, + \fBLDAPControl\fR \fI**clientctrls\fR, \fBstruct timeval\fR \fI*timeoutp\fR, + \fBint\fR \fIsizelimit\fR, \fBLDAPMessage\fR \fI**res\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to perform LDAP search operations. The +\fBldap_search_s()\fR function does the search synchronously (that is, not +returning until the operation completes). The \fBldap_search_st()\fR function +does the same, but allows a \fItimeout\fR to be specified. The +\fBldap_search()\fR function is the asynchronous version, initiating the search +and returning the message ID of the operation it initiated. +.sp +.LP +The \fIbase\fR is the DN of the entry at which to start the search. The +\fIscope\fR is the scope of the search and should be one of +\fBLDAP_SCOPE_BASE\fR, to search the object itself, \fBLDAP_SCOPE_ONELEVEL\fR, +to search the object's immediate children, or \fBLDAP_SCOPE_SUBTREE\fR, to +search the object and all its descendents. +.sp +.LP +The \fIfilter\fR is a string representation of the filter to apply in the +search. Simple filters can be specified as \fIattributetype=attributevalue\fR. +More complex filters are specified using a prefix notation according to the +following BNF: +.sp +.in +2 +.nf + <filter> ::= '(' <filtercomp> ')' + <filtercomp> ::= <and> | <or> | <not> | <simple> + <and> ::= '&' <filterlist> + <or> ::= '|' <filterlist> + <not> ::= '!' <filter> + <filterlist> ::= <filter> | <filter> <filterlist> + <simple> ::= <attributetype> <filtertype> <attributevalue> + <filtertype> ::= '=' | '~=' | '<=' | '>=' +.fi +.in -2 + +.sp +.LP +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. +.sp +.LP +For example, the filter \fBmail=*\fR finds entries that have a mail attribute. +The filter \fBmail=*@terminator.rs.itd.umich.edu\fR finds entries that have a +mail attribute ending in the specified string. Use a backslash (\fB\\fR) to +escape parentheses characters in a filter. See RFC 1588 for a more complete +description of the filters that are allowed. See \fBldap_getfilter\fR(3LDAP) +for functions to help construct search filters automatically. +.sp +.LP +The \fIattrs\fR is a null-terminated array of attribute types to return from +entries that match \fIfilter\fR. If \fBNULL\fR is specified, all attributes are +returned. The \fIattrsonly\fR is set to \fB1\fR when attribute types only are +wanted. The \fIattrsonly\fR is set to \fB0\fR when both attributes types and +attribute values are wanted. +.sp +.LP +The \fIsizelimit\fR argument returns the number of matched entries specified +for a search operation. When \fIsizelimit\fR is set to 50, for example, no more +than 50 entries are returned. When \fIsizelimit\fR is set to 0, all matched +entries are returned. The LDAP server can be configured to send a maximum +number of entries, different from the size limit specified. If 5000 entries are +matched in the database of a server configured to send a maximum number of 500 +entries, no more than 500 entries are returned even when \fIsizelimit\fR is set +to 0. +.sp +.LP +The \fBldap_search_ext()\fR function initiates an asynchronous search operation +and returns \fBLDAP_SUCCESS\fR when the request is successfully sent to the +server. Otherwise, \fBldap_search_ext()\fR returns an LDAP error code. See +\fBldap_error\fR(3LDAP). If successful, \fBldap_search_ext()\fR places the +message ID of the request in \fI*msgidp\fR. A subsequent call to +\fBldap_result\fR(3LDAP) can be used to obtain the result of the add request. +.sp +.LP +The \fBldap_search_ext_s()\fR function initiates a synchronous search operation +and returns the result of the operation itself. +.SH ERRORS +.sp +.LP +The \fBldap_search_s()\fR and \fBldap_search_st()\fR functions return the LDAP +error code that results from a search operation. See \fBldap_error\fR(3LDAP) +for details. +.sp +.LP +The \fBldap_search()\fR function returns \fB\(mi1\fR when the operation +terminates unsuccessfully. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_result\fR(3LDAP), \fBldap_getfilter\fR(3LDAP), +\fBldap_error\fR(3LDAP) , \fBattributes\fR(5) +.sp +.LP +Howes, T., Kille, S., Yeong, W., Robbins, C., Wenn, J. \fIRFC 1778, The String +Representation of Standard Attribute Syntaxes\fR. Network Working Group. March +1995. +.sp +.LP +Postel, J., Anderson, C. \fIRFC 1588, White Pages Meeting Report\fR. Network +Working Group. February 1994. +.SH NOTES +.sp +.LP +The read and list functionality are subsumed by \fBldap_search()\fR functions, +when a filter such as \fBobjectclass=*\fR is used with the scope +\fBLDAP_SCOPE_BASE\fR to emulate read or the scope \fBLDAP_SCOPE_ONELEVEL\fR to +emulate list. +.sp +.LP +The \fBldap_search()\fR functions may allocate memory which must be freed by +the calling application. Return values are contained in <\fBldap.h\fR>. diff --git a/usr/src/man/man3ldap/ldap_searchprefs.3ldap b/usr/src/man/man3ldap/ldap_searchprefs.3ldap new file mode 100644 index 0000000000..ed8b2d409f --- /dev/null +++ b/usr/src/man/man3ldap/ldap_searchprefs.3ldap @@ -0,0 +1,146 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_searchprefs 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_searchprefs, ldap_init_searchprefs, ldap_init_searchprefs_buf, +ldap_free_searchprefs, ldap_first_searchobj, ldap_next_searchobj \- LDAP search +preference configuration routeines +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +# include <lber.h> +# include <ldap.h> + +\fBint\fR \fBldap_init_searchprefs\fR(\fBchar\fR \fI**file\fR, + \fBstruct ldap_searchobj\fR \fI***solistp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_init_searchprefs_buf\fR(\fBchar\fR \fI**buf\fR, \fBunsigned\fR \fIlonglen\fR, + \fBstruct ldap_searchobj\fR \fI**solistp\fR); +.fi + +.LP +.nf +\fBstruct ldap_searchobj\fR \fB**ldap_free_searchprefs\fR + (\fBstruct ldap_searchobj\fR \fI**solist\fR); +.fi + +.LP +.nf +\fBstruct ldap_searchobj\fR \fB**ldap_first_searchobj\fR + (\fBstruct ldap_seachobj\fR \fI**solist\fR); +.fi + +.LP +.nf +\fBstruct ldap_searchobj\fR \fB**ldap_next_searchobj\fR + (\fBstruct ldap_seachobj\fR \fI**solist\fR, \fBstruct ldap_seachobj\fR \fI**so\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions provide a standard way to access LDAP search preference +configuration data. LDAP search preference configurations 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 performed. +.sp +.LP +\fBldap_init_searchprefs()\fR reads a sequence of search preference +configurations from a valid LDAP searchpref configuration file. See +\fBldapsearchprefs.conf\fR(4). Upon success, \fB0\fR is returned and +\fIsolistp\fR is set to point to a list of search preference data structures. +.sp +.LP +\fBldap_init_searchprefs_buf()\fR reads a sequence of search preference +configurations from \fIbuf\fR, whose size is \fIbuflen.\fR \fIbuf\fR should +point to the data in the format defined for an LDAP search preference +configuration file. See \fBldapsearchprefs.conf\fR(4). Upon success, \fB0\fR +is returned and \fIsolistp\fR is set to point to a list of search preference +data structures. +.sp +.LP +\fBldap_free_searchprefs()\fR disposes of the data structures allocated by +\fBldap_init_searchprefs()\fR. +.sp +.LP +\fBldap_first_searchpref()\fR returns the first search preference data +structure in the list \fIsolist.\fR The \fIsolist\fR is typically obtained by +calling \fBldap_init_searchprefs()\fR. +.sp +.LP +\fBldap_next_searchpref()\fR returns the search preference after \fIso\fR in +the template list \fIsolist.\fR A NULL pointer is returned if \fIso\fR is the +last entry in the list. +.SH ERRORS +.sp +.LP +\fBldap_init_search_prefs()\fR and \fBldap_init_search_prefs_bufs()\fR return: +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_SEARCHPREF_ERR_VERSION\fR\fR +.ad +.sp .6 +.RS 4n +\fI**buf\fR points to data that is newer than can be handled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_SEARCHPREF_ERR_MEM\fR\fR +.ad +.sp .6 +.RS 4n +Memory allocation problem. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldapsearchprefs.conf\fR(4), \fBattributes\fR(5) +.sp +.LP +Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access +Protocol", OSI-DS-26, April 1992. +.sp +.LP +Howes, T., Hardcastle-Kille, S., Yeong, W., and Robbins, C., "Lightweight +Directory Access Protocol", OSI-DS-26, April 1992. +.sp +.LP +Hardcastle-Kille, S., "A String Representation of Distinguished Names", +OSI-DS-23, April 1992. +.sp +.LP +Information Processing - Open Systems Interconnection - The Directory, +International Organization for Standardization. International Standard 9594, +(1988). diff --git a/usr/src/man/man3ldap/ldap_sort.3ldap b/usr/src/man/man3ldap/ldap_sort.3ldap new file mode 100644 index 0000000000..0c51087ee8 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_sort.3ldap @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_sort 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_sort, ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP +entry sorting functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fB\fR\fBldap_sort_entries\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI**chain\fR, \fBchar\fR \fI*attr\fR, + \fBint (\fR\fI*cmp\fR)()); +.fi + +.LP +.nf +\fB\fR\fBldap_sort_values\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI**vals\fR, \fBint (\fR\fI*cmp\fR)()); +.fi + +.LP +.nf +\fB\fR\fBldap_sort_strcasecmp\fR(\fBchar\fR \fI*a\fR, \fBchar\fR \fI*b\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to sort lists of entries and values retrieved from an +LDAP server. \fBldap_sort_entries()\fR 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 \fIld\fR, the LDAP structure, which is only used for +error reporting, \fIchain\fR, the list of entries as returned by +\fBldap_search_s\fR(3LDAP) or \fBldap_result\fR(3LDAP). \fIattr\fR is the +attribute to use as a key in the sort or NULL to sort by DN, and \fIcmp\fR is +the comparison function to use when comparing values (or individual DN +components if sorting by DN). In this case, \fIcmp\fR should be a function +taking two single values of the \fIattr\fR 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 \fBqsort\fR(3C), which is called to do the +actual sorting. +.sp +.LP +\fBldap_sort_values()\fR is used to sort an array of values from an entry, as +returned by \fBldap_get_values\fR(3LDAP). It takes the LDAP connection +structure \fIld\fR, the array of values to sort \fIvals\fR, and \fIcmp\fR, +the comparison function to use during the sort. Note that \fIcmp\fR will be +passed a pointer to each element in the \fIvals\fR array, so if you pass the +normal char ** for this parameter, \fIcmp\fR should take two char **'s as +arguments (that is, you cannot pass \fIstrcasecmp\fR or its friends for +\fIcmp\fR). You can, however, pass the function \fBldap_sort_strcasecmp()\fR +for this purpose. +.sp +.LP +For example: +.sp +.in +2 +.nf + 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" ); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_search\fR(3LDAP), \fBldap_result\fR(3LDAP), +\fBqsort\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBldap_sort_entries()\fR function applies the comparison function to each +value of the attribute in the array as returned by a call to +\fBldap_get_values\fR(3LDAP), until a mismatch is found. This works fine for +single-valued attributes, but may produce 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 <\fBldap.h\fR> header file. Some functions may +allocate memory which must be freed by the calling application. diff --git a/usr/src/man/man3ldap/ldap_ufn.3ldap b/usr/src/man/man3ldap/ldap_ufn.3ldap new file mode 100644 index 0000000000..3e8cb15276 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_ufn.3ldap @@ -0,0 +1,126 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_ufn 3LDAP "27 Jan 2002" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_ufn, ldap_ufn_search_s, ldap_ufn_search_c, ldap_ufn_search_ct, +ldap_ufn_setfilter, ldap_ufn_setprefix, ldap_ufn_timeout \- LDAP user friendly +search functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_ufn_search_c\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*ufn\fR, \fBchar\fR \fI**attrs\fR, + \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR, \fBint (\fR\fI*cancelproc\fR)(), + \fBvoid\fR \fI*cancelparm\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_ufn_search_ct\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*ufn\fR, \fBchar\fR \fI**attrs\fR, + \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR,\fBint (\fR\fI*cancelproc\fR)(), + \fBvoid\fR \fI*cancelparm\fR,\fBchar\fR \fI*tag1\fR, \fBchar\fR \fI*tag2\fR, + \fBchar\fR \fI*tag3\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_ufn_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*ufn\fR, \fBchar\fR \fI**attrs\fR, + \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR); +.fi + +.LP +.nf +\fBLDAPFiltDesc *\fR\fBldap_ufn_setfilter\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*fname\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldap_ufn_setprefix\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*prefix\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_ufn_timeout\fR(\fBvoid\fR \fI*tvparam\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are used to perform LDAP user friendly search operations. +\fBldap_ufn_search_s()\fR is the simplest form. It does the search +synchronously. It takes \fIld\fR to identify the the LDAP connection. The +\fIufn\fR parameter is the user friendly name for which to search. The +\fIattrs\fR, \fIattrsonly\fR and \fIres\fR parameters are the same as for +\fBldap_search\fR(3LDAP). +.sp +.LP +The \fBldap_ufn_search_c()\fR function functions the same as +\fBldap_ufn_search_s()\fR, except that it takes \fIcancelproc\fR, a function to +call periodicly during the search. It should be a function taking a single +void * argument, given by \fIcalcelparm\fR. If \fIcancelproc\fR returns a +non-zero result, the search will be abandoned and no results returned. The +purpose of this function is to provide a way for the search to be cancelled, +for example, by a user or because some other condition occurs. +.sp +.LP +The \fBldap_ufn_search_ct()\fR function is like \fBldap_ufn_search_c()\fR, +except that it takes three extra parameters. \fItag1\fR is passed to the +\fBldap_init_getfilter\fR(3LDAP) function when resolving the first component of +the UFN. \fItag2\fR is used when resolving intermediate components. \fItag3\fR +is used when resolving the last component. By default, the tags used by the +other UFN search functions during these three phases of the search are "ufn +first", "ufn intermediate", and "ufn last". +.sp +.LP +The \fBldap_ufn_setfilter()\fR function is used to set the +\fBldapfilter.conf\fR(4) file for use with the \fBldap_init_getfilter\fR(3LDAP) +function to \fIfname\fR. +.sp +.LP +The \fBldap_ufn_setprefix()\fR function 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 prefix, +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. +.sp +.LP +The \fBldap_ufn_timeout()\fR function is used to set the timeout associated +with \fBldap_ufn_search_s()\fR searches. The \fItimeout\fR parameter should +actually be a pointer to a struct timeval. This is so \fBldap_ufn_timeout()\fR +can be used as a cancelproc in the above functions. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBgettimeofday\fR(3C), \fBldap\fR(3LDAP), \fBldap_search\fR(3LDAP), +\fBldap_getfilter\fR(3LDAP), \fBldapfilter.conf\fR(4), \fBldap_error\fR(3LDAP), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +These functions may allocates memory. Return values are contained in +<\fBldap.h\fR>. diff --git a/usr/src/man/man3ldap/ldap_url.3ldap b/usr/src/man/man3ldap/ldap_url.3ldap new file mode 100644 index 0000000000..42024e53a6 --- /dev/null +++ b/usr/src/man/man3ldap/ldap_url.3ldap @@ -0,0 +1,300 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_url 3LDAP "02 Dec 2003" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_url, ldap_is_ldap_url, ldap_url_parse, ldap_url_parse_nodn, +ldap_free_urldesc, ldap_url_search, ldap_url_search_s, ldap_url_search_st, +ldap_dns_to_url, ldap_dn_to_url \- LDAP Uniform Resource Locator functions +.SH SYNOPSIS +.LP +.nf +cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] +#include <lber.h> +#include <ldap.h> + +\fBint\fR \fBldap_is_ldap_url\fR(\fBchar\fR \fI*url\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_url_parse\fR(\fBchar\fR \fI*url\fR, \fBLDAPURLDesc\fR \fI**ludpp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_url_parse_nodn\fR(\fBchar\fR \fI*url\fR, \fBLDAPURLDesc\fR \fI**ludpp\fR); +.fi + +.LP +.nf +\fB\fR\fBldap_free_urldesc\fR(\fBLDAPURLDesc\fR \fI*ludp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_url_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*url\fR, \fBint\fR \fIattrsonly\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_url_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*url\fR, + \fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR); +.fi + +.LP +.nf +\fBint\fR \fBldap_url_search_st\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*url\fR, \fBint\fR \fIattrsonly\fR, + \fBstruct timeval\fR \fI*timeout\fR, \fBLDAPMessage\fR \fI**res\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBldap_dns_to_url\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dns_name\fR, \fBchar\fR \fI*attrs\fR, + \fBchar\fR \fI*scope\fR, \fBchar\fR \fI*filter\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBldap_dn_to_url\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBint\fR \fInameparts\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions support the use of LDAP URLs (Uniform Resource Locators). The +following shows the formatting used for LDAP URLs. +.sp +.in +2 +.nf +\fBldap://\fR\fIhostport\fR\fB/\fR\fIdn\fR[\fB?\fR\fIattributes\fR[\fB?\fR\fIscope\fR[\fB?\fR\fIfilter\fR]]] +.fi +.in -2 + +.sp +.LP +where: +.sp +.ne 2 +.mk +.na +\fB\fIhostport\fR\fR +.ad +.RS 14n +.rt +Host name with an optional \fB:portnumber\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdn\fR\fR +.ad +.RS 14n +.rt +Base DN to be used for an LDAP search operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIattributes\fR\fR +.ad +.RS 14n +.rt +Comma separated list of attributes to be retrieved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIscope\fR\fR +.ad +.RS 14n +.rt +One of these three strings: base one sub (default=base). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfilter\fR\fR +.ad +.RS 14n +.rt +LDAP search filter as used in a call to \fBldap_search\fR(3LDAP). +.RE + +.sp +.LP +The following is an example of an LDAP URL: +.sp +.in +2 +.nf +ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich +.fi +.in -2 + +.sp +.LP +URLs preceded \fBURL:\fR or wrapped in angle-brackets are tolerated. URLs can +also be preceded by \fBURL:\fR and wrapped in angle-brackets. +.sp +.LP +\fBldap_is_ldap_url()\fR returns a non-zero value if \fIurl\fR looks like an +LDAP URL (as opposed to some other kind of URL). It can be used as a quick +check for an LDAP URL; the \fBldap_url_parse()\fR function should be used if a +more thorough check is needed. +.sp +.LP +\fBldap_url_parse()\fR breaks down an LDAP URL passed in \fIurl\fR into its +component pieces. If successful, zero is returned, an LDAP URL description is +allocated, filled in, and \fIludpp\fR is set to point to it. See \fBRETURN +VALUES\fR for values returned upon error. +.sp +.LP +\fBldap_url_parse_nodn()\fR acts just like \fBldap_url_parse()\fR but does not +require \fIdn\fR in the LDAP URL. +.sp +.LP +\fBldap_free_urldesc()\fR should be called to free an LDAP URL description that +was obtained from a call to \fBldap_url_parse()\fR. +.sp +.LP +\fBldap_url_search()\fR initiates an asynchronous LDAP search based on the +contents of the \fIurl\fR string. This function acts just like +\fBldap_search\fR(3LDAP) except that many search parameters are pulled out of +the URL. +.sp +.LP +\fBldap_url_search_s()\fR performs a synchronous LDAP search based on the +contents of the \fIurl\fR string. This function acts just like +\fBldap_search_s\fR(3LDAP) except that many search parameters are pulled out of +the URL. +.sp +.LP +\fBldap_url_search_st()\fR performs a synchronous LDAP URL search with a +specified \fItimeout\fR. This function acts just like +\fBldap_search_st\fR(3LDAP) except that many search parameters are pulled out +of the URL. +.sp +.LP +\fBldap_dns_to_url()\fR locates the LDAP URL associated with a DNS domain name. +The supplied DNS domain name is converted into a distinguished name. The +directory entry specified by that distinguished name is searched for a labeled +URI attribute. If successful then the corresponding LDAP URL is returned. If +unsuccessful then that entry's parent is searched and so on until the target +distinguished name is reduced to only two nameparts. If \fIdns_name\fR is +\fINULL\fR then the environment variable LOCALDOMAIN is used. If \fIattrs\fR is +not \fINULL\fR then it is appended to the URL's attribute list. If \fIscope\fR +is not NULL then it overrides the URL's scope. If \fIfilter\fR is not +\fINULL\fR then it is merged with the URL's filter. If an error is encountered +then zero is returned, otherwise a string URL is returned. The caller should +free the returned string if it is non-zero. +.sp +.LP +\fBldap_dn_to_url()\fR locates the LDAP URL associated with a distinguished +name. The number of nameparts in the supplied distinguished name must be +provided. The specified directory entry is searched for a labeledURI attribute. +If successful then the LDAP URL is returned. If unsuccessful then that entry's +parent is searched and so on until the target distinguished name is reduced to +only two nameparts. If an error is encountered then zero is returned, otherwise +a string URL is returned. The caller should free the returned string if it is +non-zero. +.SH RETURN VALUES +.sp +.LP +Upon error, one of these values is returned for \fBldap_url_parse()\fR: +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_URL_ERR_BADSCOPE\fR\fR +.ad +.RS 25n +.rt +URL scope string is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_URL_ERR_HOSTPORT\fR\fR +.ad +.RS 25n +.rt +URL hostport is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_URL_ERR_MEM\fR\fR +.ad +.RS 25n +.rt +Can't allocate memory space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_URL_ERR_NODN\fR\fR +.ad +.RS 25n +.rt +URL has no DN (required). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDAP_URL_ERR_NOTLDAP\fR\fR +.ad +.RS 25n +.rt +URL doesn't begin with \fBldap://\fR. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap\fR(3LDAP), \fBldap_search\fR(3LDAP), \fBattributes\fR(5) +.sp +.LP +\fBAn\fR \fBLDAP\fR \fBURL\fR \fBFormat,\fR Tim Howes and Mark Smith, December +1995. Internet Draft (work in progress). Currently available at this URL. +.sp +.in +2 +.nf +ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-format-03.txt +.fi +.in -2 + diff --git a/usr/src/man/man3ldap/ldap_version.3ldap b/usr/src/man/man3ldap/ldap_version.3ldap new file mode 100644 index 0000000000..3955fa85df --- /dev/null +++ b/usr/src/man/man3ldap/ldap_version.3ldap @@ -0,0 +1,53 @@ +'\" te +.\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. +.\" Portions Copyright (C) 2001, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldap_version 3LDAP "19 Oct 2001" "SunOS 5.11" "LDAP Library Functions" +.SH NAME +ldap_version \- get version information about the LDAP SDK for C +.SH SYNOPSIS +.LP +.nf +\fBcc\fR \fB-flag \&.\|.\|.\fR \fIfile\fR\&.\|.\|.\fB-l\fRldap [\fB -library \&.\|.\|. \fR] +#include <ldap.h> + +\fBint\fR \fBldap_version\fR(\fBLDAPVERSION\fR *\fIver\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +A call to this function returns the version information for the LDAP SDK for C. +This is a deprecated function. Use \fBldap_get_option\fR(3LDAP) instead. The +version information is returned in the \fBLDAPVersion\fR structure pointed to +by \fIver\fR. If \fINULL\fR is passed for \fIver\fR, then only the SDK version +will be returned. +.SH RETURN VALUES +.sp +.LP +The \fBldap_version()\fR function returns the version number of the LDAP SDK +for C, multiplied by 100. For example, for version 1.0 of the LDAP SDK for C, +the function returns \fB100\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBldap_get_option\fR(3LDAP), \fBattributes\fR(5) |