I do agree that a sample in the docs would be nice for all of these calls.
I would just like to point out that the parameters to these library routines are clearly marked as either On Entry or On Exit where On Entry specifies the parameters that need to be set before the call.
For cbl_dir_scan_read it has:
On Entry:
handle
Set by CBL_DIR_SCAN_START. This field identifies the search operation. Search parameters cannot be changed for a given handle.
max-len
The length of the entry-name field.