Section Contents

 

 

LDIF files
[Handling LDIF files]


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.
DS_Status DS_LDIF_Close (DS_LDIF *ldif)
 Close the input/output LDIF files and release all associated resources.
DS_Status DS_LDIF_Get (DS_LDIF *ldif, DS_Entry **entry_p)
 Get the next entry from the input LDIF file.
DS_Status DS_LDIF_GetDN (DS_LDIF *ldif, DS_DN **dn_p)
 Get the DN of the next entry from the input LDIF file.
DS_Status DS_LDIF_GetPut (DS_LDIF *ldif1, DS_LDIF *ldif2)
 Copy an entry across from one LDIF file to another.
DS_Status DS_LDIF_Put (DS_LDIF *ldif, const DS_Entry *entry)
 Write an entry to the output LDIF file.
DS_Status DS_LDIF_TellOutput (DS_LDIF *ldif, off_t *offset_p)
 Return the current write-offset in the output file.
DS_Status DS_LDIF_Tell (DS_LDIF *ldif, off_t *offset_p)
 Return the current read-offset in the input file.
DS_Status DS_LDIF_Seek (DS_LDIF *ldif, off_t offset)
 Seek the input file to the given file-offset.
DS_Status DS_LDIF_ErrorString (DS_LDIF *ldif, char **errstr_p)
 Return a plain-text report of all errors encountered.
DS_Status DS_LDIF_PutComment (DS_LDIF *ldif, const char *str)
 Write a comment to the output LDIF file.
DS_Status DS_LDIF_Entry2LDIFString (const DS_Entry *entry, char **str_p)
 Convert an entry to an LDIF-encoded record in memory.
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.
DS_Status DS_LDIF_AllowUnknownAttrs (DS_LDIF *ldif, int allow_unknown)
 Turn on or off the flag that allows unknown attributes to be read.
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.

Function Documentation

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_fnam [in] Name of file to read as input, or NULL for no input
out_fnam [in] Name of file to write as output, or NULL for no output
ldif_p [out] 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_Status DS_LDIF_Close ( DS_LDIF *  ldif  ) 

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

Parameters:
ldif [in] LDIF stream handle
Return values:
DS_E_NOERROR Resources were released without problem
Since:
DSAPI_VERSION 2004

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

Get the next entry from the input LDIF file.

Parameters:
ldif [in] LDIF stream handle
entry_p [out] 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_Status DS_LDIF_GetDN ( DS_LDIF *  ldif,
DS_DN **  dn_p 
)

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

Parameters:
ldif [in] LDIF stream handle
dn_p [out] 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_Status DS_LDIF_GetPut ( DS_LDIF *  ldif1,
DS_LDIF *  ldif2 
)

Copy an entry across from one LDIF file to another.

Parameters:
ldif1 [in] LDIF stream handle for Get operation
ldif2 [in] 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_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:
ldif [in] LDIF stream handle
entry [in] 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_Status DS_LDIF_TellOutput ( DS_LDIF *  ldif,
off_t *  offset_p 
)

Return the current write-offset in the output file.

Parameters:
ldif [in] LDIF stream handle
offset_p [out] 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_Status DS_LDIF_Tell ( DS_LDIF *  ldif,
off_t *  offset_p 
)

Return the current read-offset in the input file.

Parameters:
ldif [in] LDIF stream handle
offset_p [out] 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_Status DS_LDIF_Seek ( DS_LDIF *  ldif,
off_t  offset 
)

Seek the input file to the given file-offset.

Parameters:
ldif [in] LDIF stream handle
offset [out] 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_Status DS_LDIF_ErrorString ( DS_LDIF *  ldif,
char **  errstr_p 
)

Return a plain-text report of all errors encountered.

Parameters:
ldif [in] LDIF stream handle
errstr_p [out] 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_Status DS_LDIF_PutComment ( DS_LDIF *  ldif,
const char *  str 
)

Write a comment to the output LDIF file.

Parameters:
ldif [in] LDIF stream handle
str [in] 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_Status DS_LDIF_Entry2LDIFString ( const DS_Entry *  entry,
char **  str_p 
)

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

Parameters:
entry [in] DS_Entry to convert
str_p [out] 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_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
entry_p [out] Output DS_Entry
allow_unknown [in] 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_Status DS_LDIF_AllowUnknownAttrs ( DS_LDIF *  ldif,
int  allow_unknown 
)

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

Parameters:
ldif [in] DS_LDIF stream to modify
allow_unknown [in] 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_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:
ldif [in] DS_LDIF stream to modify
allow_unknown_p [out] 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.

Copyright © 2008 Isode privacy   feedback Subscribe to our rss newsfeed