--- name: "ldap_sync" section: "3" platform: "linux" package: "libldap" version: "2.7.2-2" release: "Arch Linux 2026-11-01" platforms: ["linux", "macos"] url: "https://new.carta.tech/ldap_sync" --- # ldap\_sync(3) LDAP sync routines ## NAME ldap\_sync\_init, ldap\_sync\_init\_refresh\_only, ldap\_sync\_init\_refresh\_and\_persist, ldap\_sync\_poll - LDAP sync routines ## LIBRARY OpenLDAP LDAP (libldap, -lldap) ## 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 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* The search base; by default, the **BASE** option in [**ldap.conf**(5)](/ldap.conf/5.md). - **int** *ls\_scope* 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* The filter (RFC 4515); by default, **(objectClass=\*)**. - **char \*\****ls\_attrs* The requested attributes; by default **NULL**, indicating all user attributes. - **int** *ls\_timelimit* The requested time limit (in seconds); by default **0**, to indicate no limit. - **int** *ls\_sizelimit* The requested size limit (in entries); by default **0**, to indicate no limit. - **int** *ls\_timeout* The desired timeout during polling with **ldap\_sync\_poll**(3). A value of **-1** means that polling is blocking, so **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) function will wait for response before returning, unless a message is received; in that case, **ldap\_sync\_poll**(3) returns as soon as the message is available. - **ldap\_sync\_search\_entry\_f** *ls\_search\_entry* 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)](/ldap_get_dn/3.md), [**ldap\_first\_attribute**(3)](/ldap_first_attribute/3.md), 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* 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)](/ldap_parse_reference/3.md). - **ldap\_sync\_intermediate\_f** *ls\_intermediate* 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)](/ldap_parse_intermediate/3.md). 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* 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)](/ldap_parse_result/3.md). The **refreshDeletes** argument is not relevant in this case; it should always be -1. - **void \****ls\_private* A pointer to private data. The client may register here a pointer to data the handlers above may need. - **LDAP \****ls\_ld* 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 A **ldap\_sync\_t** structure is initialized by calling **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), 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) to free undocumented members set by the API. ## REFRESH ONLY The **refreshOnly** functionality is obtained by periodically calling **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). 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 The **refreshAndPersist** functionality is obtained by calling **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) and, after a successful return, by repeatedly polling with **ldap\_sync\_poll**(3) according to the desired pattern. A client may insert a call to **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 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) 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) again, passing the same **ldap\_sync\_t** structure as resulted from any previous call. ## NOTES ## SEE ALSO [**ldap**(3)](/ldap/3.md), [**ldap\_search\_ext**(3)](/ldap_search_ext/3.md), [**ldap\_result**(3)](/ldap_result/3.md)**;** **RFC 4533** (http://www.rfc-editor.org), ## AUTHOR Designed and implemented by Pierangelo Masarati, based on RFC 4533 and loosely inspired by syncrepl code in [**slapd**(8)](/slapd/8.md). ## 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.