'\"
'\" Generated from file 'ldap\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net>
'\" Copyright (c) 2004 Jochen Loewer <loewerj@web\&.de>
'\" Copyright (c) 2006 Michael Schlenker <mic42@users\&.sourceforge\&.net>
'\"
.TH "ldap" n 1\&.10\&.2 tcllib "LDAP client"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
ldap \- LDAP client
.SH SYNOPSIS
package require \fBTcl 8\&.5 9\fR
.sp
package require \fBldap ?1\&.10\&.2?\fR
.sp
\fB::ldap::connect\fR \fIhost\fR ?\fIport\fR?
.sp
\fB::ldap::tlsoptions\fR \fBreset\fR
.sp
\fB::ldap::tlsoptions\fR ?\fIopt1\fR \fIval1\fR? ?\fIopt2\fR \fIval2\fR? \&.\&.\&.
.sp
\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR?
.sp
\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR?
.sp
\fB::ldap::disconnect\fR \fIhandle\fR
.sp
\fB::ldap::starttls\fR \fIhandle\fR
.sp
\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR?
.sp
\fB::ldap::bind\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR?
.sp
\fB::ldap::bindSASL\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR?
.sp
\fB::ldap::unbind\fR \fIhandle\fR
.sp
\fB::ldap::search\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR
.sp
\fB::ldap::searchInit\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR
.sp
\fB::ldap::searchNext\fR \fIhandle\fR
.sp
\fB::ldap::searchEnd\fR \fIhandle\fR
.sp
\fB::ldap::modify\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrToDelete\fR? ?\fIattrValToAdd\fR?
.sp
\fB::ldap::modifyMulti\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrValToDelete\fR? ?\fIattrValToAdd\fR?
.sp
\fB::ldap::add\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR
.sp
\fB::ldap::addMulti\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR
.sp
\fB::ldap::delete\fR \fIhandle\fR \fIdn\fR
.sp
\fB::ldap::modifyDN\fR \fIhandle\fR \fIdn\fR \fInewrdn\fR ?\fIdeleteOld\fR? ?\fInewSuperior\fR?
.sp
\fB::ldap::info\fR \fBip\fR \fIhandle\fR
.sp
\fB::ldap::info\fR \fBbound\fR \fIhandle\fR
.sp
\fB::ldap::info\fR \fBbounduser\fR \fIhandle\fR
.sp
\fB::ldap::info\fR \fBconnections\fR
.sp
\fB::ldap::info\fR \fBtls\fR \fIhandle\fR
.sp
\fB::ldap::info\fR \fBtlsstatus\fR \fIhandle\fR
.sp
\fB::ldap::info\fR \fBsaslmechanisms\fR \fIhandle\fR
.sp
\fB::ldap::info\fR \fBcontrol\fR \fIhandle\fR
.sp
\fB::ldap::info\fR \fBextensions\fR \fIextensions\fR
.sp
\fB::ldap::info\fR \fBwhoami\fR \fIhandle\fR
.sp
.BE
.SH DESCRIPTION
.PP
The \fBldap\fR package provides a Tcl-only client library
for the LDAPv3 protocol as specified in
RFC 4511 (\fIhttp://www\&.rfc-editor\&.org/rfc/rfc4511\&.txt\fR)\&.
It works by opening the standard (or secure) LDAP socket on the
server, and then providing a Tcl API to access the LDAP protocol
commands\&.  All server errors are returned as Tcl errors (thrown) which
must be caught with the Tcl \fBcatch\fR command\&.
.SH "TLS SECURITY CONSIDERATIONS"
.PP
This package uses the \fBTLS\fR package to handle the
security for \fBLDAPS\fR connections\&.
.PP
Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of \fBTLS\fR, nor of
this package itself however\&.
Such decisions are the responsibility of whichever application is
using the package, and are likely influenced by the set of servers
the application will talk to as well\&.
.PP
For example, in light of the recent
\fIPOODLE attack\fR [http://googleonlinesecurity\&.blogspot\&.co\&.uk/2014/10/this-poodle-bites-exploiting-ssl-30\&.html] discovered by Google many servers will disable support
for the SSLv3 protocol\&.
To handle this change the applications using \fBTLS\fR must be
patched, and not this package, nor \fBTLS\fR itself\&.
Such a patch may be as simple as generally activating \fBtls1\fR
support, as shown in the example below\&.
.CS


    ldap::tlsoptions -tls1 1 -ssl2 0 -ssl3 0 ;# forcibly activate support for the TLS1 protocol

    \&.\&.\&. your own application code \&.\&.\&.

.CE
.SH COMMANDS
.TP
\fB::ldap::connect\fR \fIhost\fR ?\fIport\fR?
Opens a LDAPv3 connection to the specified \fIhost\fR, at the given
\fIport\fR, and returns a token for the connection\&. This token is the
\fIhandle\fR argument for all other commands\&. If no \fIport\fR is
specified it will default to \fB389\fR\&.
.sp
The command blocks until the connection has been established, or
establishment definitely failed\&.
.TP
\fB::ldap::tlsoptions\fR \fBreset\fR
This command resets TLS options to default values\&. It returns the
set of options\&.
Using this command is incompatible with the obsolete
form of \fB::ldap::secure_connect\fR and \fB::ldap_starttls\fR\&.
.TP
\fB::ldap::tlsoptions\fR ?\fIopt1\fR \fIval1\fR? ?\fIopt2\fR \fIval2\fR? \&.\&.\&.
This commands adds one or more options to some value, and may be used
more than one time in order to add options in several steps\&.  A complete
description of options may be found in the \fBtls\fR package
documentation\&. Valid options and values are:
.RS
.TP
\fB-cadir\fR directory
Provide the directory containing the CA certificates\&.
No default\&.
.TP
\fB-cafile\fR file
Provide the CA file\&.
No default\&.
.TP
\fB-cipher\fR string
Provide the cipher suites to use\&.
No default\&.
.TP
\fB-dhparams\fR file
Provide a Diffie-Hellman parameters file\&.
No default\&.
.TP
\fB-request\fR boolean
Request a certificate from peer during SSL handshake\&.
Default: true\&.
.TP
\fB-require\fR boolean
Require a valid certificate from peer during SSL handshake\&. If this is
set to true then -request must also be set to true\&.
Default: false
.TP
\fB-servername\fR host
Only available if the OpenSSL library the TLS package is linked against
supports the TLS hostname extension for 'Server Name Indication'
(SNI)\&. Use to name the logical host we are talking to and expecting a
certificate for\&.
No default\&.
.TP
\fB-ssl2\fR bool
Enable use of SSL v2\&.
Default: false
.TP
\fB-ssl3\fR bool
Enable use of SSL v3\&.
Default: false
.TP
\fB-tls1\fR bool
Enable use of TLS v1
Default: true
.TP
\fB-tls1\&.1\fR bool
Enable use of TLS v1\&.1
Default: true
.TP
\fB-tls1\&.2\fR bool
Enable use of TLS v1\&.2
Default: true
.RE
.sp
This command returns the current set of TLS options and values\&.
In particular, one may use this command without any arguments to get
the current set of options\&.
.sp
Using this command is incompatible with the obsolete
form of \fB::ldap::secure_connect\fR and \fB::ldap_starttls\fR
(see below)\&.
.TP
\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR?
Like \fB::ldap::connect\fR, except that the created connection is
secured by SSL\&. The port defaults to \fB636\fR\&.  This command
depends on the availability of the package \fBTLS\fR, which is a
SSL binding for Tcl\&. If \fBTLS\fR is not available, then this
command will fail\&.
.sp
TLS options are specified with \fB::ldap::tlsoptions\fR\&.
.sp
The command blocks until the connection has been established, or
establishment definitely failed\&.
.TP
\fB::ldap::secure_connect\fR \fIhost\fR ?\fIport\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR?
Note: this form of the command is deprecated, since TLS options had
to be specified with a combination of parameters to this command
(\fIverify_cert\fR and \fIsni_servername\fR) and arguments to \fB::tls::init\fR
(from package \fBtls\fR) for example to setup defaults for trusted
certificates\&. Prefer the above form (without the \fIverify_cert\fR and
\fIsni_servername\fR parameters) and set TLS options with
\fB::ldap::tlsoptions\fR\&.
.sp
If \fIverify_cert\fR is set to 1, the default, this checks the server certificate against
the known hosts\&. If \fIsni_servername\fR is set, the given hostname is used as the
hostname for Server Name Indication in the TLS handshake\&.
.sp
Use \fB::tls::init\fR to setup defaults for trusted certificates\&.
.sp
TLS supports different protocol levels\&. In common use are the versions 1\&.0, 1\&.1 and 1\&.2\&.
By default all those versions are offered\&. If you need to modify the acceptable
protocols, you can change the ::ldap::tlsProtocols list (deprecated)\&.
.TP
\fB::ldap::disconnect\fR \fIhandle\fR
Closes the ldap connection refered to by the token
\fIhandle\fR\&. Returns the empty string as its result\&.
.TP
\fB::ldap::starttls\fR \fIhandle\fR
Start TLS negotiation on the connection denoted by \fIhandle\fR,
with TLS parameters set with \fB::ldap::tlsoptions\fR\&.
.TP
\fB::ldap::starttls\fR \fIhandle\fR ?\fIcafile\fR? ?\fIcertfile\fR? ?\fIkeyfile\fR? ?\fIverify_cert\fR? ?\fIsni_servername\fR?
Note: this form of the command is deprecated, since TLS options had
to be specified with a combination of parameters to this command
(\fIcafile\fR, \fIcertfile\fR, \fIkeyfile\fR, \fIverify_cert\fR
and \fIsni_servername\fR) and arguments to \fB::tls::init\fR
(from package \fBtls\fR)\&.
Prefer the above form (without specific TLS arguments)
and set TLS options with \fB::ldap::tlsoptions\fR\&.
.sp
Start TLS negotiation on the connection denoted by \fIhandle\fR\&.
You need to set at least the \fIcafile\fR argument to a file with trusted certificates, if \fIverify_cert\fR is 1, which is the default\&.
The \fIsni_servername\fR can be used to signal a different hostname during the TLS handshake\&.
The announced protocols are determined in the same way as \fB::ldap::secure_connect\fR\&.
You can specify a TLS client certificate with the \fIcertfile\fR and \fIkeyfile\fR options\&.
.TP
\fB::ldap::bind\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR?
This command authenticates the ldap connection refered to by the token
in \fIhandle\fR, with a user name and associated password\&. It blocks
until a response from the ldap server arrives\&. Its result is the empty
string\&.
Both \fIname\fR and \fIpasswd\fR default to the empty string if they
are not specified\&.
By leaving out \fIname\fR and \fIpasswd\fR you can make an anonymous bind to
the ldap server\&.
You can issue \fB::ldap::bind\fR again to bind with different credentials\&.
.TP
\fB::ldap::bindSASL\fR \fIhandle\fR ?\fIname\fR? ?\fIpassword\fR?
This command uses SASL authentication mechanisms to do a multistage bind\&.
Its otherwise identical to the standard \fB::ldap::bind\fR\&.
This feature is currently experimental and subject to change\&. See the documentation
for the \fBSASL\fR and the "\fISASL\&.txt\fR" in the tcllib CVS repository for
details how to setup and use SASL with openldap\&.
.TP
\fB::ldap::unbind\fR \fIhandle\fR
This command asks the ldap server to release the last bind done for
the connection refered to by the token in \fIhandle\fR\&.
The \fIhandle\fR is invalid after the unbind, as the server closes the connection\&.
So this is effectivly just a more polite disconnect operation\&.
.TP
\fB::ldap::search\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR
This command performs a LDAP search below the \fIbaseObject\fR tree
using a complex LDAP search expression \fIfilterString\fR and returns
the specified \fIattributes\fR of all matching objects (DNs)\&. If the
list of \fIattributes\fR was empty all attributes are returned\&. The
command blocks until it has received all results\&.
The valid \fIoptions\fR are identical to the options listed for \fB::ldap::searchInit\fR\&.
.sp
An example of a search expression is
.sp
.CS


    set filterString "|(cn=Linus*)(sn=Torvalds*)"

.CE
.sp
The return value of the command is a list of nested dictionaries\&. The
first level keys are object identifiers (DNs), second levels keys are
attribute names\&. In other words, it is in the form
.sp
.CS


    {dn1 {attr1 {val11 val12 \&.\&.\&.} attr2 {val21\&.\&.\&.} \&.\&.\&.}} {dn2 {a1 {v11 \&.\&.\&.} \&.\&.\&.}} \&.\&.\&.

.CE
.sp
.TP
\fB::ldap::searchInit\fR \fIhandle\fR \fIbaseObject\fR \fIfilterString\fR \fIattributes\fR \fIoptions\fR
This command initiates a LDAP search below the \fIbaseObject\fR tree
using a complex LDAP search expression \fIfilterString\fR\&.
The search gets the specified \fIattributes\fR of all matching objects (DNs)\&.
The command itself just starts the search, to retrieve the actual results, use
\fB::ldap::searchNext\fR\&.
A search can be terminated at any time by
\fB::ldap::searchEnd\fR\&. This informs the server that no further results should be sent by sending and ABANDON message
and cleans up the internal state of the search\&.
Only one \fB::ldap::search\fR can be active at a given time, this
includes the introspection commands \fB::ldap::info saslmechanisms\fR, \fBldap::info control\fR and
\fBldap::info extensions\fR, which invoke a search internally\&.
Error responses from the server due to wrong arguments or similar things are returned
with the first \fB::ldap::searchNext\fR call and should be checked and dealed with there\&.
If the list of requested \fIattributes\fR is empty all attributes will be returned\&.
The parameter \fIoptions\fR specifies the options to be used in the search,
and has the following format:
.sp
.CS


    {-option1 value1 -option2 value2 \&.\&.\&. }

.CE
.sp
Following options are available:
.RS
.TP
\fB-scope\fR base one sub
Control the scope of the search to be one of \fBbase\fR, \fBone\fR, or \fBsub\fR,  to  specify  a  base
object,  one-level or  subtree  search\&.   The  default is \fBsub\fR\&.
.TP
\fB-derefaliases\fR never search find always
Control how aliases dereferencing is done\&.  Should be one of \fBnever\fR, \fBalways\fR, \fBsearch\fR,  or  \fBfind\fR  to
specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or
dereferenced only when locating the base object for the search\&.
The default is to never dereference aliases\&.
.TP
\fB-sizelimit\fR num
Determines the maximum number of entries to return in a search\&. If specified as
0 no limit is enforced\&. The server may enforce a configuration dependent sizelimit,
which may be lower than the one given by this option\&. The default is 0, no limit\&.
.TP
\fB-timelimit\fR seconds
Asks the server to use a timelimit of \fIseconds\fR for the search\&. Zero means no
limit\&. The default is 0, no limit\&.
.TP
\fB-attrsonly\fR boolean
If set to 1 only the attribute names but not the values will be present in the search result\&.
The default is to retrieve attribute names and values\&.
.TP
\fB-referencevar\fR varname
If set the search result reference LDAPURIs, if any, are returned in the given variable\&.
The caller can than decide to follow those references and query other LDAP servers for
further results\&.
.RE
.sp
.TP
\fB::ldap::searchNext\fR \fIhandle\fR
This command returns the next entry from a LDAP search initiated
by \fB::ldap::searchInit\fR\&. It returns only after a new result is received
or when no further results are available, but takes care to keep
the event loop alive\&.
The returned entry is a list with
two elements: the first is the DN of the entry, the second is the
list of attributes and values, under the format:
.sp
.CS


    dn {attr1 {val11 val12 \&.\&.\&.} attr2 {val21\&.\&.\&.} \&.\&.\&.}

.CE
.sp
The \fB::ldap::searchNext\fR command returns an empty list at the
end of the search\&.
.sp
.TP
\fB::ldap::searchEnd\fR \fIhandle\fR
This command terminates a LDAP search initiated
by \fB::ldap::searchInit\fR\&. It also cleans up
the internal state so a new search can be initiated\&.
If the client has not yet received all results, the client
sends an ABANDON message to inform the server that no
further results for the previous search should to be sent\&.
.sp
.TP
\fB::ldap::modify\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrToDelete\fR? ?\fIattrValToAdd\fR?
This command modifies the object \fIdn\fR on the ldap server we are
connected to via \fIhandle\fR\&. It replaces attributes with new values,
deletes attributes, and adds new attributes with new values\&.
All arguments are dictionaries mapping attribute names to values\&. The
optional arguments default to the empty dictionary, which means that
no attributes will be deleted nor added\&.
.RS
.TP
dictionary \fIattrValToReplace\fR (in)
No attributes will be changed if this argument is empty\&. The
dictionary contains the new attributes and their values\&. They
\fIreplace all\fR attributes known to the object\&.
.TP
dictionary \fIattrToDelete\fR (in)
No attributes will be deleted if this argument is empty\&. The
dictionary values are restrictions on the deletion\&. An attribute
listed here will be deleted if and only if its current value at the
server matches the value specified in the dictionary, or if the value
in the dictionary is the empty string\&.
.TP
dictionary \fIattrValToAdd\fR (in)
No attributes will be added if this argument is empty\&. The dictionary
values are the values for the new attributes\&.
.RE
.sp
The command blocks until all modifications have completed\&. Its result
is the empty string\&.
.TP
\fB::ldap::modifyMulti\fR \fIhandle\fR \fIdn\fR \fIattrValToReplace\fR ?\fIattrValToDelete\fR? ?\fIattrValToAdd\fR?
This command modifies the object \fIdn\fR on the ldap server we are
connected to via \fIhandle\fR\&. It replaces attributes with new values,
deletes attributes, and adds new attributes with new values\&.
All arguments are lists with the format:
.sp
.CS


    attr1 {val11 val12 \&.\&.\&.} attr2 {val21\&.\&.\&.} \&.\&.\&.

.CE
.sp
where each value list may be empty for deleting all attributes\&.
The optional arguments default to empty lists of attributes to
delete and to add\&.
.RS
.TP
list \fIattrValToReplace\fR (in)
No attributes will be changed if this argument is empty\&. The
dictionary contains the new attributes and their values\&. They
\fIreplace all\fR attributes known to the object\&.
.TP
list \fIattrValToDelete\fR (in)
No attributes will be deleted if this argument is empty\&. If no
value is specified, the whole set of values for an attribute
will be deleted\&.
.TP
list \fIattrValToAdd\fR (in)
No attributes will be added if this argument is empty\&.
.RE
.sp
The command blocks until all modifications have completed\&. Its result
is the empty string\&.
.TP
\fB::ldap::add\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR
This command creates a new object using the specified \fIdn\fR\&. The
attributes of the new object are set to the values in the list
\fIattrValueTuples\fR\&.
Multiple valuated attributes may be specified using multiple tuples\&.
The command blocks until the operation has completed\&. Its result
is the empty string\&.
.TP
\fB::ldap::addMulti\fR \fIhandle\fR \fIdn\fR \fIattrValueTuples\fR
This command is the preferred one to create
a new object using the specified \fIdn\fR\&. The
attributes of the new object are set to the values in the dictionary
\fIattrValueTuples\fR (which is keyed by the attribute names)\&.
Each tuple is a list containing multiple values\&.
The command blocks until the operation has completed\&. Its result
is the empty string\&.
.TP
\fB::ldap::delete\fR \fIhandle\fR \fIdn\fR
This command removes the object specified by \fIdn\fR, and all its
attributes from the server\&.
The command blocks until the operation has completed\&. Its result
is the empty string\&.
.TP
\fB::ldap::modifyDN\fR \fIhandle\fR \fIdn\fR \fInewrdn\fR ?\fIdeleteOld\fR? ?\fInewSuperior\fR?
This command moves or copies the object specified by \fIdn\fR
to a new location in the tree of object\&. This location is
specified by \fInewrdn\fR, a \fIrelative\fR designation,
or by \fInewrdn\fR and \fInewSuperior\fR, a \fIabsolute\fR designation\&.
The optional argument \fIdeleteOld\fR defaults to \fBtrue\fR,
i\&.e\&. a move operation\&. If \fIdeleteOld\fR is not set, then the
operation will create a copy of \fIdn\fR in the new location\&.
The optional argument \fInewSuperior\fR defaults an empty string,
meaning that the object must not be relocated in another branch of
the tree\&. If this argument is given, the argument \fIdeleteOld\fR
must be specified also\&.
The command blocks until the operation has completed\&. Its result
is the empty string\&.
.TP
\fB::ldap::info\fR \fBip\fR \fIhandle\fR
This command returns the IP address of the remote LDAP server the handle is connected to\&.
.TP
\fB::ldap::info\fR \fBbound\fR \fIhandle\fR
This command returns 1 if a handle has successfully completed a \fB::ldap::bind\fR\&.
If no bind was done or it failed, a 0 is returned\&.
.TP
\fB::ldap::info\fR \fBbounduser\fR \fIhandle\fR
This command returns the username used in the bind operation if a handle has successfully completed a \fB::ldap::bind\fR\&.
If no bound was done or it failed, an empty string is returned\&.
.TP
\fB::ldap::info\fR \fBconnections\fR
This command returns all currently existing ldap connection handles\&.
.TP
\fB::ldap::info\fR \fBtls\fR \fIhandle\fR
This command returns 1 if the ldap connection \fIhandle\fR used TLS/SSL for
connection via \fBldap::secure_connect\fR or completed \fBldap::starttls\fR, 0 otherwise\&.
.TP
\fB::ldap::info\fR \fBtlsstatus\fR \fIhandle\fR
This command returns the current security status of an TLS secured
channel\&. The result is a list of key-value pairs describing the connected
peer (see the \fBTLS\fR package documentation for the returned values)\&.
If the connection is not secured with TLS, an empty list is returned\&.
.TP
\fB::ldap::info\fR \fBsaslmechanisms\fR \fIhandle\fR
Return the supported SASL mechanisms advertised by the server\&. Only valid in a
bound state (anonymous or other)\&.
.TP
\fB::ldap::info\fR \fBcontrol\fR \fIhandle\fR
Return the supported controls advertised by the server as a list of OIDs\&. Only valid in a bound state\&.
This is currently experimental and subject to change\&.
.TP
\fB::ldap::info\fR \fBextensions\fR \fIextensions\fR
Returns the supported LDAP extensions as list of OIDs\&. Only valid in a bound state\&.
This is currently experimental and subject to change\&.
.TP
\fB::ldap::info\fR \fBwhoami\fR \fIhandle\fR
Returns authzId for the current connection\&. This implements the RFC 4532
protocol extension\&.
.PP
.PP
.SH EXAMPLES
.PP
A small example, extracted from the test application coming with this
code\&.
.PP
.CS


    package require ldap

    # Connect, bind, add a new object, modify it in various ways

    set handle [ldap::connect localhost 9009]

    set dn "cn=Manager, o=University of Michigan, c=US"
    set pw secret

    ldap::bind $handle $dn $pw

    set dn "cn=Test User,ou=People,o=University of Michigan,c=US"

    ldap::add $handle $dn {
	objectClass     OpenLDAPperson
	cn              {Test User}
	mail            test\&.user@google\&.com
	uid             testuid
	sn              User
	telephoneNumber +31415926535
	telephoneNumber +27182818285
    }

    set dn "cn=Another User,ou=People,o=University of Michigan,c=US"

    ldap::addMulti $handle $dn {
	objectClass     {OpenLDAPperson}
	cn              {{Anotther User}}
	mail            {test\&.user@google\&.com}
	uid             {testuid}
	sn              {User}
	telephoneNumber {+31415926535 +27182818285}
    }

    # Replace all attributes
    ldap::modify $handle $dn [list drink icetea uid JOLO]

    # Add some more
    ldap::modify $handle $dn {} {} [list drink water  drink orangeJuice pager "+1 313 555 7671"]

    # Delete
    ldap::modify $handle $dn {} [list drink water  pager ""]

    # Move
    ldap::modifyDN $handle $dn "cn=Tester"

    # Kill the test object, and shut the connection down\&.
    set dn "cn=Tester,ou=People,o=University of Michigan,c=US"
    ldap::delete $handle $dn

    ldap::unbind     $handle
    ldap::disconnect $handle

.CE
.PP
And another example, a simple query, and processing the
results\&.
.PP
.CS


    package require ldap
    set handle [ldap::connect ldap\&.acme\&.com 389]
    ldap::bind $handle
    set results [ldap::search $handle "o=acme,dc=com" "(uid=jdoe)" {}]
    foreach result $results {
	foreach {object attributes} $result break

	# The processing here is similar to what 'parray' does\&.
	# I\&.e\&. finding the longest attribute name and then
	# generating properly aligned output listing all attributes
	# and their values\&.

	set width 0
	set sortedAttribs {}
	foreach {type values} $attributes {
	    if {[string length $type] > $width} {
		set width [string length $type]
	    }
	    lappend sortedAttribs [list $type $values]
	}

	puts "object='$object'"

	foreach sortedAttrib  $sortedAttribs {
	    foreach {type values} $sortedAttrib break
	    foreach value $values {
		regsub -all "\\[\\x01-\\x1f\\]" $value ? value
		puts [format "  %-${width}s %s" $type $value]
	    }
	}
	puts ""
    }
    ldap::unbind $handle
    ldap::disconnect $handle

.CE
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fIldap\fR of the
\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.PP
When proposing code changes, please provide \fIunified diffs\fR,
i\&.e the output of \fBdiff -u\fR\&.
.PP
Note further that \fIattachments\fR are strongly preferred over
inlined patches\&. Attachments can be made by going to the \fBEdit\fR
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar\&.
.SH KEYWORDS
directory access, internet, ldap, ldap client, protocol, rfc 2251, rfc 4511, x\&.500
.SH CATEGORY
Networking
.SH COPYRIGHT
.nf
Copyright (c) 2004 Andreas Kupries <andreas_kupries@users\&.sourceforge\&.net>
Copyright (c) 2004 Jochen Loewer <loewerj@web\&.de>
Copyright (c) 2006 Michael Schlenker <mic42@users\&.sourceforge\&.net>

.fi