Functions
DS_Status	DS_LDIF_Open (const char in_fnam, const char out_fnam, DS_LDIF **ldif_p)
	Open an LDIF stream handle with input and/or output LDIF files. More...

DS_Status	DS_LDIF_Close (DS_LDIF *ldif)
	Close the input/output LDIF files and release all associated resources. More...

DS_Status	DS_LDIF_Get (DS_LDIF ldif, DS_Entry *entry_p)
	Get the next entry from the input LDIF file. More...

DS_Status	DS_LDIF_GetDN (DS_LDIF ldif, DS_DN *dn_p)
	Get the DN of the next entry from the input LDIF file. More...

DS_Status	DS_LDIF_GetPut (DS_LDIF ldif1, DS_LDIF ldif2)
	Copy an entry across from one LDIF file to another. More...

DS_Status	DS_LDIF_Put (DS_LDIF ldif, const DS_Entry entry)
	Write an entry to the output LDIF file. More...

DS_Status	DS_LDIF_TellOutput (DS_LDIF ldif, off_t offset_p)
	Return the current write-offset in the output file. More...

DS_Status	DS_LDIF_Tell (DS_LDIF ldif, off_t offset_p)
	Return the current read-offset in the input file. More...

DS_Status	DS_LDIF_Seek (DS_LDIF *ldif, off_t offset)
	Seek the input file to the given file-offset. More...

DS_Status	DS_LDIF_ErrorString (DS_LDIF ldif, char *errstr_p)
	Return a plain-text report of all errors encountered. More...

DS_Status	DS_LDIF_PutComment (DS_LDIF ldif, const char str)
	Write a comment to the output LDIF file. More...

DS_Status	DS_LDIF_Entry2LDIFString (const DS_Entry entry, char *str_p)
	Convert an entry to an LDIF-encoded record in memory. More...

DS_Status	DS_LDIF_LDIFString2Entry (const char str_p, DS_Entry entry_p, int allow_unknown)
	Convert an LDIF-encoded record in memory into a DS_Entry. More...

DS_Status	DS_LDIF_AllowUnknownAttrs (DS_LDIF *ldif, int allow_unknown)
	Turn on or off the flag that allows unknown attributes to be read. More...

DS_Status	DS_LDIF_GetAllowUnknownAttrs (DS_LDIF ldif, int allow_unknown_p)
	Get the state of the flag that allows unknown attributes to be read. More...

Detailed Description

Function Documentation

◆ DS_LDIF_Open()

DS_Status DS_LDIF_Open	(	const char *	in_fnam,
		const char *	out_fnam,
		DS_LDIF **	ldif_p
	)

Open an LDIF stream handle with input and/or output LDIF files.

Parameters

[in]	in_fnam	Name of file to read as input, or NULL for no input
[in]	out_fnam	Name of file to write as output, or NULL for no output
[out]	ldif_p	Returned handle to be used in other DS_LDIF_* calls, or NULL on error

Return values

DS_E_NOMEMORY	Out of memory
DS_E_OPFAILED	If either the input or output file could not be opened
DS_E_BADPARAM	If both in_fnam and out_fnam parameters are NULL, or if ldif_p is NULL
DS_E_NOERROR	A valid handle was returned

Since: DSAPI_VERSION 2004

It is possible to set up a single DS_LDIF handle with both input and output files, or with just one or the other. Output files are always recreated blank – there is no append mode.

If the input filename has the same string value as the output filename, then a blank file is created for writing, and the input stream is also attached to the new file, allowing it to read back entries already written to the output stream. Note that the seek position is moved to the end of the file every time a new entry is added with DS_LDIF_Put(), so normally DS_LDIF_Seek() would be called before calling DS_LDIF_Get() one or more times, using file-offsets previously obtained with DS_LDIF_TellOutput().

◆ DS_LDIF_Close()

DS_Status DS_LDIF_Close ( DS_LDIF * ldif )

Close the input/output LDIF files and release all associated resources.

Parameters

[in] ldif LDIF stream handle

Return values

DS_E_NOERROR Resources were released without problem

Since: DSAPI_VERSION 2004

◆ DS_LDIF_Get()

DS_Status DS_LDIF_Get	(	DS_LDIF *	ldif,
		DS_Entry **	entry_p
	)

Get the next entry from the input LDIF file.

Parameters

[in]	ldif	LDIF stream handle
[out]	entry_p	Newly-read entry, or NULL on error or EOF

Return values

DS_E_NOMEMORY	Out of memory
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_OPFAILED	The stream was not opened for reading
DS_E_BADDN	The DN could not be converted
DS_E_BADENTRY	Badly-formed data was found in the LDIF file
DS_E_BADATTRTYPE	An attribute could not be converted
DS_E_BADATTRVALUE	An attribute could not be converted
DS_E_BADATTRSYNTAX	An attribute could not be converted
DS_E_NOTFOUND	End-of-file was reached
DS_E_NOERROR	An entry was read without problem

Since: DSAPI_VERSION 2004

The caller must release the returned entry using DS_Entry_Delete(), and check its type using DS_Entry_IsNormal() and so on before using the data. If DS_E_BADENTRY is returned, then the next call will attempt to pick up after the damage or bad data. Fatal errors reading the input stream will result in a return of DS_E_BADENTRY followed by a return of DS_E_NOTFOUND on the following call.

◆ DS_LDIF_GetDN()

DS_Status DS_LDIF_GetDN	(	DS_LDIF *	ldif,
		DS_DN **	dn_p
	)

Get the DN of the next entry from the input LDIF file.

Parameters

[in]	ldif	LDIF stream handle
[out]	dn_p	Newly-read DN, or NULL on error or EOF

Return values

DS_E_NOMEMORY	Out of memory
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_OPFAILED	The stream was not opened for reading
DS_E_BADDN	The DN could not be converted
DS_E_BADENTRY	Badly-formed data was found in the LDIF file
DS_E_NOTFOUND	End-of-file was reached
DS_E_NOERROR	An entry was read without problem

Since: DSAPI_VERSION 2025

This call returns just the DN of the entry without converting all the attributes or checking their validity. It moves the file position onto the next entry just the same as the DS_LDIF_Get() call. The caller must release the returned DN using DS_DN_Delete(). If DS_E_BADENTRY is returned, then the next call will attempt to pick up after the damage or bad data. Fatal errors reading the input stream will result in a return of DS_E_BADENTRY followed by a return of DS_E_NOTFOUND on the following call.

◆ DS_LDIF_GetPut()

DS_Status DS_LDIF_GetPut	(	DS_LDIF *	ldif1,
		DS_LDIF *	ldif2
	)

Copy an entry across from one LDIF file to another.

Parameters

[in]	ldif1	LDIF stream handle for Get operation
[in]	ldif2	LDIF stream handle for Put operation

Return values

DS_E_NOMEMORY	Out of memory
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_OPFAILED	The first stream was not opened for reading or the second wasn't open for writing, or there was a problem writing the entry.
DS_E_BADENTRY	Badly-formed data was found in the source LDIF file
DS_E_NOTFOUND	End-of-file was reached
DS_E_NOERROR	An entry was read without problem

Since: DSAPI_VERSION 2025

This call quickly copies an entry from one LDIF stream to another, similar to doing a DS_LDIF_Get() on one stream followed by a DS_LDIF_Put() on the other, but with less validity-checking and greater efficiency. The two arguments may point to the same stream or to different streams. The attributes aren't decoded/re-encoded, so the validity of the attributes' types and values is not checked. If the 'Get' part fails, then that is the status returned, as for DS_LDIF_GetDN(). If it is successful, the entry data goes on to the 'Put' operation, which may give its own failure status.

◆ DS_LDIF_Put()

DS_Status DS_LDIF_Put	(	DS_LDIF *	ldif,
		const DS_Entry *	entry
	)

Write an entry to the output LDIF file.

Both normal entries and the four types of change-entries are handled. However, a single LDIF stream can handle only all normal-records or all change-records, selected by the first entry read from or written to the stream. Attempting to write a record of the other type will result in DS_E_BADENTRY.

Parameters

[in]	ldif	LDIF stream handle
[in]	entry	Entry to write

Since: DSAPI_VERSION 2004

Return values

DS_E_NOMEMORY	Out of memory
DS_E_OPFAILED	There was an error writing the data to the file, or the stream was not set up for writing
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_BADENTRY	The entry could not be converted to LDIF
DS_E_BADATTRTYPE	An attribute could not be converted
DS_E_BADATTRVALUE	An attribute could not be converted
DS_E_BADATTRSYNTAX	An attribute could not be converted
DS_E_BADDN	Some part of the DN could not be converted
DS_E_NOERROR	Entry was written without problem

◆ DS_LDIF_TellOutput()

DS_Status DS_LDIF_TellOutput	(	DS_LDIF *	ldif,
		off_t *	offset_p
	)

Return the current write-offset in the output file.

Parameters

[in]	ldif	LDIF stream handle
[out]	offset_p	Current write-offset

Return values

DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_OPFAILED	The stream was not opened for writing
DS_E_NOERROR	Offset was read without problem

Since: DSAPI_VERSION 2023

This returns the offset in the output file at which the next entry will be written. This offset may be passed to DS_LDIF_Seek() to read back the next entry in a future DS_LDIF_Get() operation. Note that the read-offset for the next DS_LDIF_Get() operation is lost by this call (it is moved to the end-of-file).

◆ DS_LDIF_Tell()

DS_Status DS_LDIF_Tell	(	DS_LDIF *	ldif,
		off_t *	offset_p
	)

Return the current read-offset in the input file.

Parameters

[in]	ldif	LDIF stream handle
[out]	offset_p	Current read-offset

Return values

DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_OPFAILED	The stream was not opened for reading
DS_E_NOERROR	Offset was read without problem

Since: DSAPI_VERSION 2004

◆ DS_LDIF_Seek()

DS_Status DS_LDIF_Seek	(	DS_LDIF *	ldif,
		off_t	offset
	)

Seek the input file to the given file-offset.

Parameters

[in]	ldif	LDIF stream handle
[out]	offset	Offset to seek to

Return values

DS_E_OPFAILED	Error seeking to the given offset, or the stream was not opened for reading
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_NOERROR	Seek completed without problem

Since: DSAPI_VERSION 2004

The offset value must be a value previously returned by DS_LDIF_Tell() for this file.

◆ DS_LDIF_ErrorString()

DS_Status DS_LDIF_ErrorString	(	DS_LDIF *	ldif,
		char **	errstr_p
	)

Return a plain-text report of all errors encountered.

Parameters

[in]	ldif	LDIF stream handle
[out]	errstr_p	Error string, or NULL for no new errors

Return values

DS_E_NOMEMORY	Out of memory
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_NOERROR	An error string or NULL has been returned

Since: DSAPI_VERSION 2004

Returns a string containing a plain-text explanation of all the errors that have occurred during reading/writing the LDIF files since the last call to this function, or NULL if there are no new errors to report. The returned string should be free'd. The string consists of lines terminated by linefeeds.

◆ DS_LDIF_PutComment()

DS_Status DS_LDIF_PutComment	(	DS_LDIF *	ldif,
		const char *	str
	)

Write a comment to the output LDIF file.

Parameters

[in]	ldif	LDIF stream handle
[in]	str	String to write

Return values

DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_NOERROR	Success

Since: DSAPI_VERSION 2014

The string is written with "# " before, and a newline after. If there are newlines embedded in the string, then extra "# " characters are inserted to make sure that the text is correctly recognised as a comment.

◆ DS_LDIF_Entry2LDIFString()

DS_Status DS_LDIF_Entry2LDIFString	(	const DS_Entry *	entry,
		char **	str_p
	)

Convert an entry to an LDIF-encoded record in memory.

Parameters

[in]	entry	DS_Entry to convert
[out]	str_p	Output string

Return values

DS_E_NOMEMORY	Out of memory
DS_E_OPFAILED	There was an error writing the data
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_BADENTRY	The entry could not be converted to LDIF
DS_E_BADATTRTYPE	An attribute could not be converted
DS_E_BADATTRVALUE	An attribute could not be converted
DS_E_BADATTRSYNTAX	An attribute could not be converted
DS_E_BADDN	Some part of the DN could not be converted
DS_E_NOERROR	Entry was written without problem

Since: DSAPI_VERSION 2017

The entry is converted into LDIF format and returned in as a strdup'd string, which the caller must free.

◆ DS_LDIF_LDIFString2Entry()

DS_Status DS_LDIF_LDIFString2Entry	(	const char **	str_p,
		DS_Entry **	entry_p,
		int	allow_unknown
	)

Convert an LDIF-encoded record in memory into a DS_Entry.

Parameters

	str_p	[in/out] Variable pointing to string to convert
[out]	entry_p	Output DS_Entry
[in]	allow_unknown	Allow unknown attributes to be converted? (1 yes, 0 no)

Return values

DS_E_NOMEMORY	Out of memory
DS_E_BADPARAM	A NULL argument was passed to the function
DS_E_BADDN	The DN could not be converted
DS_E_BADENTRY	Badly-formed data was found in the LDIF file
DS_E_BADATTRTYPE	An attribute could not be converted
DS_E_BADATTRVALUE	An attribute could not be converted
DS_E_BADATTRSYNTAX	An attribute could not be converted
DS_E_NOTFOUND	End-of-file was reached
DS_E_NOERROR	An entry was read without problem

Since: DSAPI_VERSION 2017

The LDIF record in the given string is converted into a DS_Entry. The string pointer is updated to point after the data read (or skipped in the case of a DS_E_BADENTRY return). The caller must release the returned entry using DS_Entry_Delete(), and check its type using DS_Entry_IsNormal() and so on before using the data.

◆ DS_LDIF_AllowUnknownAttrs()

DS_Status DS_LDIF_AllowUnknownAttrs	(	DS_LDIF *	ldif,
		int	allow_unknown
	)

Turn on or off the flag that allows unknown attributes to be read.

Parameters

[in]	ldif	DS_LDIF stream to modify
[in]	allow_unknown	Allow unknown attributes? (1 yes, 0 no)

Return values

DS_E_NOERROR	Success
DS_E_BADPARAM	If ldif is NULL or allow_unknown is something other than 0 or 1

Since: DSAPI_VERSION 2018

By default a stream is set up to return DS_E_BADATTRTYPE if any unknown attribute-types are encountered in the LDIF file. However, if the 'allow_unknown' flag is set on the stream, then these will be returned successfully as "unknown attributes", with a syntax of 'octetstring'. Unknown attributes may be output to LDIF or sent over LDAP, but not sent over DAP.

◆ DS_LDIF_GetAllowUnknownAttrs()

DS_Status DS_LDIF_GetAllowUnknownAttrs	(	DS_LDIF *	ldif,
		int *	allow_unknown_p
	)

Get the state of the flag that allows unknown attributes to be read.

Parameters

[in]	ldif	DS_LDIF stream to modify
[out]	allow_unknown_p	Variable to place result

Return values

DS_E_NOERROR	Success
DS_E_BADPARAM	If ldif or allow_unknown_p is NULL

Since: DSAPI_VERSION 2018

The current state of the 'allow unknown attributes' flag (1 to allow, 0 to disallow) is returned in the given variable.

Functions

Detailed Description

Function Documentation

◆ DS_LDIF_Open()

◆ DS_LDIF_Close()

◆ DS_LDIF_Get()

◆ DS_LDIF_GetDN()

◆ DS_LDIF_GetPut()

◆ DS_LDIF_Put()

◆ DS_LDIF_TellOutput()

◆ DS_LDIF_Tell()

◆ DS_LDIF_Seek()

◆ DS_LDIF_ErrorString()

◆ DS_LDIF_PutComment()

◆ DS_LDIF_Entry2LDIFString()

◆ DS_LDIF_LDIFString2Entry()

◆ DS_LDIF_AllowUnknownAttrs()

◆ DS_LDIF_GetAllowUnknownAttrs()