In LDAP Version 2, the ldap_modrdn() and ldap_modrdn_s()
    functions were used to change the name of an LDAP entry. They
    could only be used to change the least significant component of
    a name (the RDN or relative distinguished name). LDAPv3 provides
    the Modify DN protocol operation that allows more general name
    change access. The ldap_rename() and ldap_rename_s()  functions
    are used to change the name of an entry, and the use of the ldap_
    modrdn() and ldap_modrdn_s()  functions is deprecated.

            int ldap_rename(
                    LDAP                              *ld,
                    const char                        *dn,
                    const char                        *newrdn,
                    const char                        *newparent,
                    int                               deleteoldrdn,
                    LDAPControl                       **serverctrls,
                    LDAPControl                       **clientctrls,
                    int                               *msgidp
            );

            int ldap_rename_s(
                    LDAP                              *ld,
                    const char                        *dn,
                    const char                        *newrdn,
                    const char                        *newparent,
                    int                               deleteoldrdn,
                    LDAPControl                       **serverctrls,
                    LDAPControl                       **clientctrls
            );

    Use of the following functions is deprecated.

            int ldap_modrdn(
                    LDAP                              *ld,
                    char                              *dn,
                    char                              *newrdn,
                    int                               deleteoldrdn
            );

            int ldap_modrdn_s(
                    LDAP                              *ld,
                    char                              *dn,
                    char                              *newrdn,
                    int                               deleteoldrdn
            );

    Parameters are as follows:

    ld             The session handle.
    dn             The name of the entry whose DN is to be changed.
    newrdn         The new RDN to give the entry.
    newparent      The new parent, or superior entry. If this
                   parameter is NULL, only the RDN of the entry is
                   changed. The root DN may be specified by passing
                   a zero length string, "". The newparent parameter
                   should always be NULL when using Version 2 of the
                   LDAP protocol; otherwise the server's behavior is
                   undefined.
    deleteoldrdn   This parameter only has meaning on the rename
                   functions if newrdn is different than the old
                   RDN. It is a boolean value. If it is non-zero,
                   it indicates that the old RDN value(s) should
                   be removed. If it is zero, it indicates that
                   the old RDN value(s) should be retained as non-
                   distinguished values of the entry.
    serverctrls    List of LDAP server controls.
    clientctrls    List of client controls.
    msgidp         This result parameter will be set to the message
                   id of the request if the ldap_rename() call
                   succeeds.

    The ldap_rename() function initiates an asynchronous modify DN
    operation and returns the constant LDAP_SUCCESS if the request
    was successfully sent, or another LDAP error code if not. See
    Errors for more information about possible errors and how to
    interpret them. If successful, ldap_rename() places the DN
    message id of the request in *msgidp. A subsequent call to ldap_
    result() can be used to obtain the result of the rename.

    The synchronous ldap_rename_s() returns the result of the
    operation, either the constant LDAP_SUCCESS if the operation was
    successful, or another LDAP error code if it was not. See Errors
    for more information about possible errors and how to interpret
    them.

    The ldap_rename() and ldap_rename_s()  functions both support
    LDAPv3 server controls and client controls.