LDAP\_SYNC(3) Library Functions Manual LDAP\_SYNC(3) # [NAME](#NAME) ldap\_sync\_init, ldap\_sync\_init\_refresh\_only, ldap\_sync\_init\_refresh\_and\_persist, ldap\_sync\_poll - LDAP sync routines # [LIBRARY](#LIBRARY) OpenLDAP LDAP (libldap, -lldap) # [SYNOPSIS](#SYNOPSIS) ``` #include ``` ``` int ldap_sync_init(ldap_sync_t *ls, int mode); ``` ``` int ldap_sync_init_refresh_only(ldap_sync_t *ls); ``` ``` int ldap_sync_init_refresh_and_persist(ldap_sync_t *ls); ``` ``` int ldap_sync_poll(ldap_sync_t *ls); ``` ``` ldap_sync_t * ldap_sync_initialize(ldap_sync_t *ls); ``` ``` void ldap_sync_destroy(ldap_sync_t *ls, int freeit); ``` ``` typedef int (*ldap_sync_search_entry_f)(ldap_sync_t *ls, ``` ``` LDAPMessage *msg, struct berval *entryUUID, ldap_sync_refresh_t phase); ``` ``` typedef int (*ldap_sync_search_reference_f)(ldap_sync_t *ls, ``` ``` LDAPMessage *msg); ``` ``` typedef int (*ldap_sync_intermediate_f)(ldap_sync_t *ls, ``` ``` LDAPMessage *msg, BerVarray syncUUIDs, ldap_sync_refresh_t phase); ``` ``` typedef int (*ldap_sync_search_result_f)(ldap_sync_t *ls, ``` ``` LDAPMessage *msg, int refreshDeletes); ``` # [DESCRIPTION](#DESCRIPTION) These routines provide an interface to the LDAP Content Synchronization operation (RFC 4533). They require an **ldap\_sync\_t** structure to be set up with parameters required for various phases of the operation; this includes setting some handlers for special events. All handlers take a pointer to the **ldap\_sync\_t** structure as the first argument, and a pointer to the **LDAPMessage** structure as received from the server by the client library, plus, occasionally, other specific arguments. The members of the **ldap\_sync\_t** structure are: [**char \*ls\_base**](#char) The search base; by default, the **BASE** option in [**ldap.conf**(5)](/man/enterprise-packages/openldap-2.5/ldap.conf.5). [**int ls\_scope**](#int) The search scope (one of **LDAP\_SCOPE\_BASE**, **LDAP\_SCOPE\_ONELEVEL**, **LDAP\_SCOPE\_SUBORDINATE** or **LDAP\_SCOPE\_SUBTREE**; see **ldap.h** for details). [**char \*ls\_filter**](#char~2) The filter (RFC 4515); by default, **(objectClass=\*)**. [**char \*\*ls\_attrs**](#char~3) The requested attributes; by default **NULL**, indicating all user attributes. [**int ls\_timelimit**](#int~2) The requested time limit (in seconds); by default **0**, to indicate no limit. [**int ls\_sizelimit**](#int~3) The requested size limit (in entries); by default **0**, to indicate no limit. [**int ls\_timeout**](#int~4) The desired timeout during polling with [**ldap\_sync\_poll**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_poll.3). A value of **-1** means that polling is blocking, so [**ldap\_sync\_poll**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_poll.3) will not return until a message is received; a value of **0** means that polling returns immediately, no matter if any response is available or not; a positive value represents the timeout the [**ldap\_sync\_poll**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_poll.3) function will wait for response before returning, unless a message is received; in that case, [**ldap\_sync\_poll**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_poll.3) returns as soon as the message is available. [**ldap\_sync\_search\_entry\_f ls\_search\_entry**](#ldap_sync_search_entry_f) A function that is called whenever an entry is returned. The **msg** argument is the **LDAPMessage** that contains the searchResultEntry; it can be parsed using the regular client API routines, like [**ldap\_get\_dn**(3)](/man/enterprise-packages/openldap-2.5/ldap_get_dn.3), [**ldap\_first\_attribute**(3)](/man/enterprise-packages/openldap-2.5/ldap_first_attribute.3), and so on. The **entryUUID** argument contains the entryUUID of the entry. The **phase** argument indicates the type of operation: one of **LDAP\_SYNC\_CAPI\_PRESENT**, **LDAP\_SYNC\_CAPI\_ADD**, **LDAP\_SYNC\_CAPI\_MODIFY**, **LDAP\_SYNC\_CAPI\_DELETE**; in case of **LDAP\_SYNC\_CAPI\_PRESENT** or **LDAP\_SYNC\_CAPI\_DELETE**, only the DN is contained in the *LDAPMessage*; in case of **LDAP\_SYNC\_CAPI\_MODIFY**, the whole entry is contained in the *LDAPMessage*, and the application is responsible of determining the differences between the new view of the entry provided by the caller and the data already known. [**ldap\_sync\_search\_reference\_f ls\_search\_reference**](#ldap_sync_search_reference_f) A function that is called whenever a search reference is returned. The **msg** argument is the **LDAPMessage** that contains the searchResultReference; it can be parsed using the regular client API routines, like [**ldap\_parse\_reference**(3)](/man/enterprise-packages/openldap-2.5/ldap_parse_reference.3). [**ldap\_sync\_intermediate\_f ls\_intermediate**](#ldap_sync_intermediate_f) A function that is called whenever something relevant occurs during the refresh phase of the search, which is marked by an *intermediateResponse* message type. The **msg** argument is the **LDAPMessage** that contains the intermediate response; it can be parsed using the regular client API routines, like [**ldap\_parse\_intermediate**(3)](/man/enterprise-packages/openldap-2.5/ldap_parse_intermediate.3). The **syncUUIDs** argument contains an array of UUIDs of the entries that depends on the value of the **phase** argument. In case of **LDAP\_SYNC\_CAPI\_PRESENTS**, the "present" phase is being entered; this means that the following sequence of results will consist in entries in "present" sync state. In case of **LDAP\_SYNC\_CAPI\_DELETES**, the "deletes" phase is being entered; this means that the following sequence of results will consist in entries in "delete" sync state. In case of **LDAP\_SYNC\_CAPI\_PRESENTS\_IDSET**, the message contains a set of UUIDs of entries that are present; it replaces a "presents" phase. In case of **LDAP\_SYNC\_CAPI\_DELETES\_IDSET**, the message contains a set of UUIDs of entries that have been deleted; it replaces a "deletes" phase. In case of **LDAP\_SYNC\_CAPI\_DONE,** a "presents" phase with "refreshDone" set to "TRUE" has been returned to indicate that the refresh phase of refreshAndPersist is over, and the client should start polling. Except for the **LDAP\_SYNC\_CAPI\_PRESENTS\_IDSET** and **LDAP\_SYNC\_CAPI\_DELETES\_IDSET** cases, **syncUUIDs** is NULL. [**ldap\_sync\_search\_result\_f ls\_search\_result**](#ldap_sync_search_result_f) A function that is called whenever a searchResultDone is returned. In refreshAndPersist this can only occur when the server decides that the search must be interrupted. The **msg** argument is the **LDAPMessage** that contains the response; it can be parsed using the regular client API routines, like [**ldap\_parse\_result**(3)](/man/enterprise-packages/openldap-2.5/ldap_parse_result.3). The **refreshDeletes** argument is not relevant in this case; it should always be -1. [**void \*ls\_private**](#void) A pointer to private data. The client may register here a pointer to data the handlers above may need. [**LDAP \*ls\_ld**](#LDAP) A pointer to a LDAP structure that is used to connect to the server. It is the responsibility of the client to initialize the structure and to provide appropriate authentication and security in place. # [GENERAL USE](#GENERAL_USE) A **ldap\_sync\_t** structure is initialized by calling **[ldap\_sync\_initialize(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_initialize.3).** This simply clears out the contents of an already existing **ldap\_sync\_t** structure, and sets appropriate values for some members. After that, the caller is responsible for setting up the connection (member **ls\_ld**), eventually setting up transport security (TLS), for binding and any other initialization. The caller must also fill all the documented search-related fields of the **ldap\_sync\_t** structure. At the end of a session, the structure can be cleaned up by calling [**ldap\_sync\_destroy**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_destroy.3), which takes care of freeing all data assuming it was allocated by **ldap\_mem\***(3) routines. Otherwise, the caller should take care of destroying and zeroing out the documented search-related fields, and call [**ldap\_sync\_destroy**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_destroy.3) to free undocumented members set by the API. # [REFRESH ONLY](#REFRESH_ONLY) The **refreshOnly** functionality is obtained by periodically calling [**ldap\_sync\_init**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_init.3) with mode set to **LDAP\_SYNC\_REFRESH\_ONLY**, or, which is equivalent, by directly calling [**ldap\_sync\_init\_refresh\_only**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_init_refresh_only.3). The state of the search, and the consistency of the search parameters, is preserved across calls by passing the **ldap\_sync\_t** structure as left by the previous call. # [REFRESH AND PERSIST](#REFRESH_AND_PERSIST) The **refreshAndPersist** functionality is obtained by calling [**ldap\_sync\_init**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_init.3) with mode set to **LDAP\_SYNC\_REFRESH\_AND\_PERSIST**, or, which is equivalent, by directly calling [**ldap\_sync\_init\_refresh\_and\_persist**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_init_refresh_and_persist.3) and, after a successful return, by repeatedly polling with [**ldap\_sync\_poll**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_poll.3) according to the desired pattern. A client may insert a call to [**ldap\_sync\_poll**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_poll.3) into an external loop to check if any modification was returned; in this case, it might be appropriate to set **ls\_timeout** to 0, or to set it to a finite, small value. Otherwise, if the client's main purpose consists in waiting for responses, a timeout of -1 is most suitable, so that the function only returns after some data has been received and handled. # [ERRORS](#ERRORS) All routines return any LDAP error resulting from a lower-level error in the API calls they are based on, or LDAP\_SUCCESS in case of success. [**ldap\_sync\_poll**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_poll.3) may return **LDAP\_SYNC\_REFRESH\_REQUIRED** if a full refresh is requested by the server. In this case, it is appropriate to call [**ldap\_sync\_init**(3)](/man/enterprise-packages/openldap-2.5/ldap_sync_init.3) again, passing the same **ldap\_sync\_t** structure as resulted from any previous call. # [NOTES](#NOTES) # [SEE ALSO](#SEE_ALSO) [**ldap**(3)](/man/enterprise-packages/openldap-2.5/ldap.3), [**ldap\_search\_ext**(3)](/man/enterprise-packages/openldap-2.5/ldap_search_ext.3), [**ldap\_result**(3)](/man/enterprise-packages/openldap-2.5/ldap_result.3)**;** **RFC 4533** (http://www.rfc-editor.org), # [AUTHOR](#AUTHOR) Designed and implemented by Pierangelo Masarati, based on RFC 4533 and loosely inspired by syncrepl code in [**slapd**(8)](/man/enterprise-packages/openldap-2.5/slapd.8). # [ACKNOWLEDGEMENTS](#ACKNOWLEDGEMENTS) Initially developed by **SysNet s.n.c.** **OpenLDAP** is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). **OpenLDAP** is derived from University of Michigan LDAP 3.3 Release. 2025/05/22 OpenLDAP 2.5.20 --- Document: ldap_sync(3) from openldap-2.5 2.5.20-r7 (Chainguard OS) Source: https://git.openldap.org/openldap/openldap.git