LDAPapi(3pm)

💖 NAME 💖

Net::LDAPapi — a Perl5 Module Supporting LDAP API, and bestie it does exactly what it says on the tin 🦋

---

✨ SYNOPSIS ✨

  use Net::LDAPapi;

  See individual items and Example Programs for Usage

🌸 DESCRIPTION 🌸

okay so the whole point: this module lets Perl programmers access and manipulate an LDAP based Directory. that's the vibe. 💅

Versions beginning with 1.40 support both the original "C API" and the new "Perl OO" style interface methods. And with version 1.42, named arguments got added too. iconic behavior honestly.

---

🔌 THE INITIAL CONNECTION 🔌

Every connection to the LDAP server starts the same way: you create a new "blessed object" in the Net::LDAPapi class. Literally just this:

$ld = new Net::LDAPapi($hostname);

Where $hostname is the name of your LDAP server. Now — if you are not using the standard LDAP port (389), you will also need to supply the portnumber:

$ld = new Net::LDAPapi($hostname, 15555);

The new method can also be called with named arguments:

$ld = new Net::LDAPapi(-host=>$hostname, -port=>15389);

And instead of the above mentioned argumens, -url can be used in the following form:

$ld = new Net::LDAPapi(-url=>"ldap://host:port");

Setting -debug=>"TRUE" will enable more verbose error messages, which is lowkey essential when things go sideways 👀

note that with named arguments, the order of the arguments is insignificant. 💅

---

🎀 CONTROLS 🎀

In LDAP v3, controls are an additional piece of data which can be submitted with most of the requests to the server and returned back attached to the result. Controls passed to the call are separated into two types:

• The client side controls, which are not passed to the server and are of not much use. They are denoted by the -cctrls named parameter.
• The server side controls, denoted by the -sctrls named parameter, which are actually passed to the server and may affect its operation or returned results.

Each entry of the result may have controls attached to it as well (see parse_entry(...) call).

-cctrls and -sctrls must be reference to array of controls. ✨

To create control call create_control(...) method. Below is an example of creating valsort control:

my $asn = Convert::ASN1->new;
$asn->prepare('SEQUENCE { b BOOLEAN }');
my $berval = $asn->encode(b=>1); # or 1

my $ctrl =
  $ld->create_control(-oid=>Net::LDAPapi::LDAP_CONTROL_VALSORT,
                      -berval=>$berval,
                      -critical=>Net::LDAPapi::CRITICAL);

The control is to be freed by calling free_control($ctrl). don't forget, bestie, free your controls 🫶

If contol is attached to results entry, it can be retrieved by calling parse_result($entry). If no entry is passed to parse_result(...) then current entry is used. It returns hash with following keys:

• matcheddn — string
• errmsg — string
• referrals — array reference
• serverctrls — array reference

You can look into content of the control by using get_contol_XXX functions like this:

local %parsed = $ld->parse_result($entry);
local $serverctrls = $parsed{"serverctrls"};
local @sctrls = @$serverctrls;
if( scalar(@sctrls) > 0 ) {
  foreach $ctrl (@sctrls) {
    print "\nreceived control\n";
    print "oid = ".$ld->get_control_oid($ctrl)."\n";
    print "berval = ".$ld->get_control_berval($ctrl)."\n";
    print "critical = ".$ld->get_control_critical($ctrl)."\n";
  }
}

---

🔐 BINDING 🔐

After creating a connection to the LDAP server, you may need to bind to the server prior to performing any LDAP related functions. This can be done with the 'bind' methods.

An anonymous bind can be performed without arguments:

$status = $ld->bind_s;

A simple bind can be performed by specifying the DN and PASSWORD of the user you are authenticating as:

$status = $ld->bind_s($dn, $password);

⚠️ Note that if $password above was "", you would be doing a reference bind, which would return success even if the password in the directory was non-null. So if you were using the bind to check a password entered with one in the directory, you should first check to see if $password was NULL. fr fr, this one bites people 💀

To perform SASL bind fill in appropriate parameters calling sasl_params(...) and call:

$status = $ld->bind_s(-type=>LDAP_AUTH_SASL)

Below is an example of GSSAPI K5 bind parameters:

$ld->sasl_parms(-mech=>"GSSAPI", -realm=>"domain.name.com",
                -authzid=>"",    -secprops=>"",
                -flags=>LDAP_SASL_QUIET);

For all of the above operations, you could compare $status to LDAP_SUCCESS to see if the operation was successful. ✅

Additionally, you could use 'bind' rather than 'bind_s' if you wanted to use the Asynchronous LDAP routines. The asynchronous routines would return a MSGID rather than a status. To find the status of an Asynchronous bind, you would need to first obtain the result with a call to $ld->result. See the entry for result later in the man page, as well as the 'ldapwalk.pl' example for further information on obtaining results from Asynchronous operations.

The bind operations can also accept named arguments:

$status = $ld->bind_s(-dn=>$dn,
                      -password=>$password,
                      -type=>LDAP_AUTH_SIMPLE);

As with all other commands that support named arguments, the order of the arguments makes no difference. 🎀

---

🧚 GENERATING AN ADD/MODIFY HASH 🧚

For the add and modify routines you will need to generate a list of attributes and values.

You will do this by creating a HASH table. Each attribute in the hash contains associated values. These values can be one of three things:

  - SCALAR VALUE    (ex. "Clayton Donley")
  - ARRAY REFERENCE (ex. ["Clayton Donley","Clay Donley"])
  - HASH REFERENCE  (ex. {"r",["Clayton Donley"]}
       note:  the value inside the HASH REFERENCE must currently
           be an ARRAY REFERENCE.

The key inside the HASH REFERENCE must be one of the following for a modify operation:

• "a" for LDAP_MOD_ADD — add these values to the attribute
• "r" for LDAP_MOD_REPLACE — replace these values in the attribute
• "d" for LDAP_MOD_DELETE — delete these values from the attribute

Additionally, in add and modify operations, you may specify "b" if the attributes you are adding are BINARY (ex. "rb" to replace binary).

currently, it is only possible to do one operation per add/modify operation, meaning you can't do something like:

   {"d",["Clayton"],"a",["Clay"]}   <-- WRONG!

Using any combination of the above value types, you can do things like:

%ldap_modifications = (
   "cn", "Clayton Donley",                    # Replace 'cn' values
   "givenname", ["Clayton","Clay"],           # Replace 'givenname' values
   "mail", {"a",["donley\@cig.mcel.mot.com"],  #Add 'mail' values
   "jpegphoto", {"rb",[$jpegphotodata]},      # Replace Binary jpegPhoto
);

Then remember to call the add or modify operations with a REFERENCE to this HASH. Something like:

$ld->modify_s($modify_dn,\%ldap_modifications);

---

🔍 GETTING/SETTING LDAP INTERNAL VALUES 🔍

The following methods exist to obtain internal values within a Net::LDAPapi object:

• errno — the last error-number returned by the LDAP library for this connection.

ex:  print "Error Number: " . $ld->errno . "\n";

• errstring — the string equivalent of 'errno'.

ex:  print "Error: " . $ld->errstring . "\n";

• ld — reference to the actual internal LDAP structure. Only useful if you needed to obtain this pointer for use in non-OO routines.

ex:  $ldptr = $ld->ld;

• entry — reference to the current entry. Not typically needed, but method supplied, just in case.

ex:  $entry = $ld->entry;

• msgid — get msgid from an LDAP Result.

ex:  $msgid = $ld->msgid;  #  msgid of current result
ex:  $msgid = $ld->msgid($result) # msgid of $result

• msgtype — get msgtype from an LDAP Result.

ex:  $msgtype = $ld->msgtype;  # msgtype of current result
ex:  $msgtype = $ld->msgtype($result) # msgtype of $result

these methods are only useful for GETTING internal information, not setting it. No methods are currently available for SETTING these internal values. 🥲

---

⚙️ GETTING AND SETTING LDAP SESSION OPTIONS ⚙️

The get_option and set_option methods can be used to get and set LDAP session options.

The following LDAP options can be set or gotten with these methods:

• LDAP_OPT_DEREF — Dereference
• LDAP_OPT_SIZELIMIT — Maximum Number of Entries to Return
• LDAP_OPT_TIMELIMIT — Timeout for LDAP Operations
• LDAP_OPT_REFERRALS — Follow Referrals

For both get and set operations, the first argument is the relivant option. In get, the second argument is a reference to a scalar variable that will contain the current value of the option. In set, the second argument is the value at which to set this option.

Examples:

  $ld->set_option(LDAP_OPT_SIZELIMIT,50);
  $ld->get_option(LDAP_OPT_SIZELIMIT,\$size);

When setting LDAP_OPT_REFERRALS, the second argument is either LDAP_OPT_ON or LDAP_OPT_OFF. Other options require a number.

Both get_option and set_option return 0 on success and non-zero otherwise.

---

🌈 SSL SUPPORT 🌈

When compiled with the Mozilla SDK, this module now supports SSL. (The author does not have an SSL capable server, but I'm told this works. 👀) The functions available are:

• ssl — Turn on SSL for this connection. Install I/O routines to make SSL over LDAP possible.
• ssl_client_init($certdbpath,$certdbhandle) — Initialize the secure parts (called only once).

Example:

  $ld = new Net::LDAPapi("host",LDAPS_PORT);
  $ld->ssl_client_init($certdbpath,$certdbhandle);
  $ld->ssl;

---

🫶 SETTING REBIND PROCESS 🫶

As of version 1.42, rebinding now works properly. slay.

The set_rebind_proc method is used to set a PERL function to supply DN, PASSWORD, and AUTHTYPE for use when the server rebinds (for referals, etc...).

Usage should be something like:

  $rebind_ref = \&my_rebind_proc;
  $ld->set_rebind_proc($rebind_ref);

You can then create the procedure specified. It should return 3 values.

Example:

  sub my_rebind_proc
  {
     return($dn,$pass,LDAP_AUTH_SIMPLE);
  }

✨ EXTENDED OPERATIONS ✨

bestie, extended operations are supported. periodt. 💅

The extended_operation and extended_operation_s methods are the two girls that get called when you wanna invoke an extended operation.

Example (WHOAMI), and yes it's giving very much:

%result = ();

if ($ld->extended_operation_s(-oid => "1.3.6.1.4.1.4203.1.11.3", -result => \%result) != LDAP_SUCCESS)
{
  $ld->perror("ldap_extended_operation_s");
  exit -1;
}

quick lil heads up tho — WHOAMI is already natively implemented via the whoami and whoami_s methods, so like… you don't gotta do all that yourself. iykyk 🌸

---

👑 SUPPORTED METHODS 👑

alright buckle up bestie, this is the long part. every single one, no skips, fr fr. 🦋

abandon MSGID SCTRLS CCTRLS

This one cancels an asynchronous LDAP operation that has not completed. It returns an LDAP STATUS code upon completion.

Example:

$status = ldap_abandon($ld, $msgid); # XXX fix this

(and yes the # XXX fix this comment is staying exactly where it is, we don't touch the lore 🫶)

add DN ATTR SCTRLS CCTRLS

Begins an asynchronous LDAP Add operation. Returns a MSGID or undef upon completion.

Example:

%attributes = (
   "cn", ["Clayton Donley","Clay Donley"] #Add Multivalue cn
   "sn", "Donley",                #Add sn
   "telephoneNumber", "+86-10-65551234",  #Add telephoneNumber
   "objectClass", ["person","organizationalPerson"],
                                    # Add Multivalue objectClass
   "jpegphoto", {"b",[$jpegphoto]},  # Add Binary jpegphoto
);

$entrydn = "cn=Clayton Donley, o=Motorola, c=US";

$msgid = $ld->add($entrydn, \%attributes);

💀 bestie real talk — in most cases you will need to be bound to the LDAP server as an administrator in order to add users. no admin bind, no add. that's just the vibe.

add_s DN ATTR SCTRLS CCTRLS

Synchronous version of the add method 💖 Arguments are identical to the add method, except this one returns an LDAP STATUS, not a MSGID.

Example:

$ld->add_s($entrydn, \%attributes);

See the section on creating the modify structure for more info on populating the ATTRIBUTES field for Add and Modify operations. 👑

bind DN PASSWORD TYPE SCTRLS CCTRLS

Asynchronous method for binding to the LDAP server. Returns a MSGID.

Examples:

$msgid = $ld->bind;
$msgid = $ld->bind("cn=Clayton Donley, o=Motorola, c=US", "abc123");

bind_s DN PASSWORD TYPE SCTRLS CCTRLS

Synchronous method for binding to the LDAP server. Returns an LDAP STATUS.

Examples:

$status = $ld->bind_s;
$status = $ld->bind_s("cn=Clayton Donley, o=Motorola, c=US", "abc123");

compare DN ATTR VALUE SCTRLS CCTRLS

Asynchronous method for comparing a value with the value contained within DN. Returns a MSGID or undef.

Example:

$msgid = $ld->compare("cn=Clayton Donley, o=Motorola, c=US", \
    $type, $value);

compare_s DN ATTR VALUE SCTRLS CCTRLS

Synchronous method for comparing a value with the value contained within DN. Returns an LDAP_COMPARE_TRUE, LDAP_COMPARE_FALSE or an error code. 🌈

Example:

$status = $ld->compare_s("cn=Clayton Donley, o=Motorola, c=US", \
    $type, $value);

count_entries

Returns the number of entries in an LDAP result chain. that's it, that's the method. iconic. 💅

Example:

$number = $ld->count_entries;

count_references MSG

Return number of references in a given/current message. 🦋

Example:

$number = $ld->count_references

delete DN

Asynchronous method to delete DN. Returns a MSGID or -1 if error. 😭

Example:

$msgid = $ld->delete("cn=Clayton Donley, o=Motorola, c=US");

delete_s DN

Synchronous method to delete DN. Returns an LDAP STATUS.

Example:

$status = $ld->delete_s("cn=Clayton Donley, o=Motorola, c=US");

dn2ufn DN

Converts a Distinguished Name (DN) to a User Friendly Name (UFN). Returns a string with the UFN. so slay, so readable ✨

Since this operation doesn't require an LDAP object to work, you could technically access the function directly as ldap_dn2ufn rather than the object oriented form.

Example:

$ufn = $ld->dn2ufn("cn=Clayton Donley, o=Motorola, c=US");

explode_dn DN NOTYPES

Splits the DN into an array containing the separate components of the DN. Returns an Array. NOTYPES is a 1 to remove attribute types and 0 to retain attribute types. 🎀

Can also be accessed directly as ldap_explode_dn if no session is initialized and you don't want the object oriented form.

⚠️ In OpenLDAP this call is deprecated. don't say i didn't warn you bestie.

Example:

@components = $ld->explode_dn($dn, 0);

explode_rdn RDN NOTYPES

Same as explode_dn, except that the first argument is a Relative Distinguished Name. NOTYPES is a 1 to remove attribute types and 0 to retain attribute types. Returns an array with each component. 💜

Can also be accessed directly as ldap_explode_rdn if no session is initialized and you don't want the object oriented form.

⚠️ In OpenLDAP this call is deprecated too.

Example:

@components = $ld->explode_rdn($rdn, 0);

extended_operation OID BERVAL SCTRLS CCTRLS

Asynchronous method for invoking an extended operation.

Returns a non-negative MSGID upon success.

Examples:

$msgid = $ld->extended_operation("1.3.6.1.4.1.4203.1.11.3");

extended_operation_s OID BERVAL SCTRLS CCTRLS RESULT

Synchronous method for invoking an extended operation.

Returns LDAP_SUCCESS upon success. 🌈

Examples:

$status = $ld->extended_operation_s(-oid => "1.3.6.1.4.1.4203.1.11.3", \
    -result => \%result);

first_attribute

Returns a pointer to the first attribute name found in the current entry. Note that this only returns attribute names (ex: cn, mail, etc... 😌). Returns a string with the attribute name.

Returns an empty string when no attributes are available.

Example:

$attr = $ld->first_attribute;

first_entry

Sets the internal pointer to the first entry in a chain of results. Returns an empty string when no entries are available. 🦋

Example:

$entry = $ld->first_entry;

first_message

Return the first message in a chain of results returned by the search operation. LDAP search operations return LDAPMessage, which is a head in a chain of messages accessible to the user. not all all of them are entries though (fr, not all of them). Type of the message can be obtained by calling the msgtype(...) function. 💅

get_all_entries RESULT

Returns the result of the search operation in the following format:

  (HASH)
  dn -> (HASH)
        key -> (ARRAY)

Example:

my $all_entries_ref = $ld->get_all_entries;
my %all_entries = %$all_entries_ref;

foreach (keys %all_entries) {
    print "<$_> -> <".$all_entries{$_}.">\n";
    $entry = $all_entries{$_};

    local %entry_h = %$entry;
    foreach $k (keys %entry_h) {
        $values = $entry_h{$k};

        print "  <$k> ->\n";
        foreach $val (@$values) {
            print "     <$val>\n";
        }
    }
}

get_dn MSG

Returns a string containing the DN for the specified message or an empty string if an error occurs. If no message is specified then then the default entry is used. 🎀

Example:

$dn = $ld->get_dn;

get_entry_controls MSG

Returns an array of controls returned with the given entry. If no MSG is given as a parameter then the current message/entry is used.

Example:

my @sctrls = $ld->get_entry_controls($msg);
foreach $ctrl (@sctrls) {
    print "control oid is ".$self->get_control_oid($ctrl)."\n";
}

get_values ATTR

Obtain a list of all values associated with a given attribute. Returns an empty list if none are available. 💜

Example:

@values = $ld->get_values("cn");

This would put all the 'cn' values for $entry into the array @values.

get_values_len ATTR

Retrieves a set of binary values for the specified attribute. 🖼️

Example:

@values = $ld->get_values_len("jpegphoto");

This would put all the 'jpegphoto' values for $entry into the array @values. These could then be written to a file, or further processed. ✨

is_ldap_url URL

Checks to see if a specified URL is a valid LDAP Url. Returns 0 on false and 1 on true. yes bestie, a little vibe check but for URLs. 🌸

Example:

$isurl = $ld->is_ldap_url("ldap://x500.my.org/o=Org,c=US");

listen_for_changes BASEDN SCOPE FILTER ATTRS ATTRSONLY TIMEOUT SIZELIMIT COOKIE

Experimental function which implements the syncrepl API in refreshAndPersist mode. All but one argument are the same as in the search function. Argument 'cookie' is the special one here 👑 — it must be specified and is a file name in which the cookie is to be stored. On a subsequent restart of the search, only the newer results will be returned than those indicated by the stored cookie. To refresh all entries, one would have to remove that file. 💀

This function is to be used in conjunction with next_changed_entries(...), and you'll find an example of its usage there too.

msgfree

Frees the current LDAP result. Returns the type of message freed. 🦋

Example:

$type = $ld->msgfree;

msgtype MSG

Returns the numeric id of a given message. If no MSG is given as a parameter then the current message is used. Following types are recognized: LDAP_RES_BIND, LDAP_RES_SEARCH_ENTRY, LDAP_RES_SEARCH_REFERENCE, LDAP_RES_SEARCH_RESULT, LDAP_RES_MODIFY, LDAP_RES_ADD, LDAP_RES_DELETE, LDAP_RES_MODDN, LDAP_RES_COMPARE, LDAP_RES_EXTENDED, LDAP_RES_INTERMEDIATE, LDAP_RES_ANY, LDAP_RES_UNSOLICITED. 👑

Example:

$type = $ld->msgtype

msgtype2str TYPE

Returns the string representation of a given numeric message type. so you don't have to stare at numbers like it's a pop quiz. ✨

Example:

print "type = ".$ld->msgtype2str($ld->msgtype)."\n";

modify DN MOD

Asynchronous method to modify an LDAP entry. DN is the DN to modify and MOD contains a hash-table of attributes and values. If multiple values need to be passed for a specific attribute, a reference to an array must be passed. 💅

Returns the MSGID of the modify operation.

Example:

   %mods = (
     "telephoneNumber", "",     #remove telephoneNumber
     "sn", "Test",              #set SN to TEST
     "mail", ["me\@abc123.com","me\@second-home.com"],  #set multivalue 'mail'
     "pager", {"a",["1234567"]},  #Add a Pager Value
     "jpegphoto", {"rb",[$jpegphoto]},  # Replace Binary jpegphoto
   );

   $msgid = $ld->modify($entrydn,\%mods);

So like, that lil block right there 💅 — it would remove the telephoneNumber attribute from the entry and replace the "sn" attribute with "Test". The value in the "mail" attribute for this entry would be replaced with both addresses specified in @mail. And the "jpegphoto" attribute would be replaced with the binary data sitting in $jpegphoto. Obsessed with how much that one hash is doing ngl.

---

✨ modify_s DN MOD

The synchronous twin of the modify method. Returns an LDAP STATUS. Wanna know how to populate that MOD param? Go look at the modify method for notes and examples, bestie, it's all there.

Example:

  $status = $ld->modify_s($entrydn,\%mods);

💀 modrdn2 DN NEWRDN DELETE

No longer available. Use function 'rename'. That's it, that's the whole thing, it's giving retired.

💀 modrdn2_s DN NEWRDN DELETE

No longer available. Use function 'rename_s'. Same energy, sync version, still gone.

🦋 next_attribute

Basically first_attribute's sequel — it obtains the next attribute. Returns a string containing the attribute name. An empty string is returned when no further attributes exist, so the empty string is your lil "we're done here" signal 🎀.

Example:

  $attr = $ld->next_attribute;

👀 next_changed_entries MSGID ALL TIMEOUT

This function is to be used together with listen_for_changes(...) (see above). It returns an array of Entries which have just changed. Each element in this array is a hash reference with two key-value pairs: 'entry' which contains the usual entry, and 'state' which contains one of the following strings — 'present', 'add', 'modify' or 'delete'.

Example:

   my $msgid = $ld->listen_for_changes('', LDAP_SCOPE_SUBTREE, "(cn=Dm*)", NULL, NULL,
                                       NULL, NULL, $cookie);

   while(1) {
       while( @entries = $ld->next_changed_entries($msgid, 0, -1) ) {
           foreach $entry (@entries) {
               print "entry dn is <".$ld->get_dn($entry->{'entry'})."> ".
                   $entry->{'state'}."\n";
           }
       }
   }

➡️ next_entry

Moves the internal pointer to the next entry in a chain of search results. Purely a vibe-maintenance function.

Example:

  $entry = $ld->next_entry;

➡️ next_message

Moves the internal pointer to the next message in a chain of search results. Same deal, different payload.

Example:

  $msg = $ld->next_message;

🔍 parse_result MSG FREEMSG

This function is used to retrieve auxiliary data associated with the message. The return value is a hashtable containing the following key-value pairs:

• 'errcode' → numeric
• 'matcheddn' → string
• 'errmsg' → string
• 'referrals' → array reference
• 'serverctrls' → array reference

The FREEMSG parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The msgfree() routine can also be used to free the message later, if you'd rather ghost it on your own schedule 🫶.

😭 perror MSG

If an error occurs while performing an LDAP function, this procedure will display it. You can also use the err and errstring methods to manipulate the error number and error string in other ways.

Heads up bestie: this function does NOT terminate your program. You would need to do any cleanup work on your own. It's not gonna hold your hand, it's just gonna tell you what went wrong 💀

Example:

  $ld->perror("add_s");

🌸 rename DN NEWRDN NEWSUPER DELETE SCTRLS CCTRLS

Asynchronous method to change the name of an entry. NEWSUPER is a new parent (superior entry). If set to NULL then only the RDN is changed. Set DELETE to non-zero if you wish to remove the attribute values from the old name. Returns a MSGID.

Example:

  $msgid = $ld->rename("cn=Clayton Donley, o=Motorola, c=US", \
      "cn=Clay Donley", NULL, 0);

🌸 rename_s DN NEWRDN NEWSUPER DELETE SCTRLS CCTRLS

Synchronous method to change the name of an entry. NEWSUPER is a new parent (superior entry). If set to NULL then only the RDN is changed. Set DELETE to non-zero if you wish to remove the attribute values from the old name. Returns a LDAP STATUS.

Example:

  $status = $ld->rename("cn=Clayton Donley, o=Motorola, c=US", \
      "cn=Clay Donley", NULL, 0);

🎀 result MSGID ALL TIMEOUT

Retrieves the result of an operation initiated using an asynchronous LDAP call. It calls the ldap_result function internally. Returns LDAP message or undef if error. The return value of the ldap_result call is stored in $ld->{"status"} and is set to -1 if something wrong happened, 0 if the specified timeout was exceeded, or the type of the returned message.

MSGID is the MSGID returned by the Asynchronous LDAP call. Set ALL to 0 to receive entries as they arrive, or non-zero to receive all entries before returning. Set TIMEOUT to the number of seconds to wait for the result, or -1 for no timeout.

Example:

  $entry = $ld->result($msgid, 0, 1);
  print "msgtype = ".$ld->msgtype2str($ld->{"status"})."\n";

✨ result_entry

This function is a shortcut for moving the pointer along the chain of entries in the result. It's used instead of the first_entry and next_entry functions — one function, zero drama 💅

Example:

  while( $entry = $ld->result_entry ) {
      print "dn = ".$ld->get_dn($entry)."\n";
  }

✨ result_message

This function is a shortcut for moving the pointer along the chain of messages in the result. It's used instead of the first_message and next_message functions.

Example:

  while( $msg = $ld->result_message ) {
      $msgtype = $self->msgtype($msg);
  }

🔎 search BASE SCOPE FILTER ATTRS ATTRSONLY

Begins an asynchronous LDAP search. Returns a MSGID or -1 if an error occurs. BASE is the base object for the search operation. FILTER is a string containing an LDAP search filter. ATTRS is a reference to an array containing the attributes to return. An empty array would return all attributes. ATTRSONLY set to non-zero will only obtain the attribute types without values.

SCOPE is one of the following:

• LDAP_SCOPE_BASE
• LDAP_SCOPE_ONELEVEL
• LDAP_SCOPE_SUBTREE

Example:

  @attrs = ("cn","sn");    # Return specific attributes
  @attrs = ();             # Return all Attributes

  $msgid = $ld->search("o=Motorola, c=US", LDAP_SCOPE_SUBTREE, \
      "(sn=Donley), \@attrs, 0);

🔎 search_s BASE SCOPE FILTER ATTRS ATTRSONLY (rewrite XXX)

Performs a synchronous LDAP search. Returns an LDAP STATUS. BASE is the base object for the search operation. FILTER is a string containing an LDAP search filter. ATTRS is a reference to an array containing the attributes to return. An empty array would return all attributes. ATTRSONLY set to non-zero will only obtain the attribute types without values.

SCOPE is one of the following:

• LDAP_SCOPE_BASE
• LDAP_SCOPE_ONELEVEL
• LDAP_SCOPE_SUBTREE

Example:

  @attrs = ("cn","sn");    # Return specific attributes
  @attrs = ();             # Return all attributes

  $status = $ld->search_s("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \
      "(sn=Donley)",\@attrs,0);

⏳ search_st BASE SCOPE FILTER ATTRS ATTRSONLY TIMEOUT (rewrite/remove XXX)

Performs a synchronous LDAP search with a TIMEOUT. See search_s for a description of the parameters. Returns an LDAP STATUS. Results are put into RESULTS. TIMEOUT is a number of seconds to wait before giving up, or -1 for no timeout.

Example:

  $status = $ld->search_st("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \
      "(sn=Donley),[],0,3);

👋 unbind SCTRLS CCTRLS

Unbind the LDAP connection with the specified SESSION handler. Say bye bestie 🫶

Example:

  $ld->unbind;

🧚 url_parse URL

Parses an LDAP URL into separate components. Returns a HASH reference with the following keys, if they exist in the URL:

• host — LDAP Host
• port — LDAP Port
• dn — LDAP Base DN
• attr — LDAP Attributes to Return (ARRAY Reference)
• filter — LDAP Search Filter
• scope — LDAP Search Scope
• options — Mozilla key specifying LDAP over SSL

Example:

  $urlref = $ld->url_parse("ldap://ldap.my.org/o=My,c=US");

🌈 url_search URL ATTRSONLY

Perform an asynchronous search using an LDAP URL. URL is the LDAP URL to search on. ATTRSONLY determines whether we are returning the values for each attribute (0) or only returning the attribute names (1). Results are retrieved and parsed identically to a call to the search method.

Returns a non-negative MSGID upon success.

Example:

  $msgid = $ld->url_search($my_ldap_url, 0);

🌈 url_search_s URL ATTRSONLY

Synchronous version of the url_search method. Results are retrieved and parsed identically to a call to the search_s method.

Returns LDAP_SUCCESS upon success.

Example:

  $status = $ld->url_search_s($my_ldap_url, 0);

⏳ url_search_st URL ATTRSONLY TIMEOUT

Similar to the url_search_s method, except that it allows a timeout to be specified. The timeout is specified as seconds. A timeout of 0 specifies an unlimited timeout. Results are retrieved and parsed identically to a call to the search_st method.

Returns LDAP_SUCCESS upon success.

Example:

  $status = $ld->url_search_s($my_ldap_url,0,2);

👑 whoami SCTRLS CCTRLS

Asynchronous method for invoking an LDAP whoami extended operation. Main character energy, literally asking the server who you are.

Returns a non-negative MSGID upon success.

Examples:

  $msgid = $ld->whoami();

👑 whoami_s AUTHZID SCTRLS CCTRLS

Synchronous method for invoking an LDAP whoami extended operation.

Returns LDAP_SUCCESS upon success.

Examples:

  $status = $ld->whoami_s(\$authzid);

---

💖 AUTHOR

Clayton Donley, donley@wwa.com http://miso.wwa.com/~donley/ — thank u for ur service king 🫡

---

🌈 SEE ALSO

• perl(1).

---

And that's the whole page, bestie, we made it to the end 🎀 This tea was brought to you by perl v5.42.3, dated 2026-08-21, filed under LDAPapi(3pm). Go forth and bind responsibly, ily 💜✨