94472 - ldap_search_ext semantics for timeout don't match documentation

Status: NEW

(Directory :: LDAP C SDK, defect)

Description

[Alan Stokes]

According to the SDK documentation:

For a given search, you can specify the maximum number of results to be returned
or the maximum amount of time to wait for a search. Use the timeoutp and
sizelimit arguments of the ldap_search_ext_s() or ldap_search_ext()
functions.
Note the following:
• To specify an infinite time limit (basically, no limit), create a timeval 
structure
with tv_sec = tv_usec = 0, and pass a pointer to this as the timeoutp
argument.
• To use the time limit specified by the LDAP_OPT_TIMELIMIT preference for this
connection, pass NULL as the timeoutp argument.

Note that this specifically allows a pointer to a 0 timeout to be passed.

However, the code for ldap_search_ext (in mozilla/directory/c-
sdk/ldap/libraries/libldap/search.c) checks for this case and returns a bad 
parameter error, with the comment "It is an error to pass in a zero'd timeval."

Clearly either the documentation or the implementation is wrong.

I would argue that it would be better to fix the implementation - especially 
since without it there is no way to specify an infinite timeout, which is 
useful and definitely allowed as part of the LDAP protocol.

(Passing NULL, or LDAP_NO_LIMIT, uses the default timeout for the connection.)

Comment 1

[Mark Smith [:mcs]]

The documentation is wrong, at least when compared to the LDAP C API Internet 
Draft, which says:

             For the ldap_search_ext() and ldap_search_ext_s() func-
             tions, the timeout parameter specifies both the local
             search timeout value and the operation time limit that is
             sent to the server within the search request.  Passing a
             NULL value for timeout causes the default timeout stored in
             the LDAP session handle (set by using ldap_set_option()
             with the LDAP_OPT_TIMELIMIT parameter) to be sent to the
             server with the request but an infinite local search
             timeout to be used.  If a zero timeout (where tv_sec and
             tv_usec are both zero) is passed in, API implementations
             SHOULD return LDAP_PARAM_ERROR.  If a zero value for tv_sec
             is used but tv_usec is non-zero, an operation time limit of
             1 SHOULD be passed to the LDAP server as the operation time
             limit.  For other values of tv_sec, the tv_sec value itself
             SHOULD be passed to the LDAP server.

Note that in the case of ldap_search_ext_s(), the LDAP search timelimit value 
that is passed to the LDAP server as well as a local (client side) timeout are 
both controlled by the timeout parameter.  I do not remember all of the detailed 
arguments that took place about this within the IETF LDAPEXT working group, but 
I believe the winning argument was that overloading a zero'd struct timeval to 
mean "infinite timeout" was confusing.  But as things stand today, you need to 
set the default timelimit (LDAP_OPT_TIMELIMIT) to zero and then pass NULL to 
ldap_search_ext_s() to get an infinite client timeout as well as no client 
requested LDAP search limit.

Comment 2

[Mark Smith [:mcs]]

TM = 5.14

Comment 3

[Jonathan]

rg ldap_search_ext returns no results