Subject: ldap_err2string format

From: "Dave Steck" <[email-masked]>
Date: Fri, 16 Jun 2000 15:54:28 -0600

According to <draft-ietf-ldapext-ldap-c-api-04.txt>, the output of ldap_err2string(err) is:
  "an informative zero-terminated character string message describing the error."

It doesn't specify whether the string is encoded in UTF-8 or may be local, such as DBCS.

The draft says:
  All DN and string attribute values passed into or produced by this C LDAP API are represented using the character set of the underlying LDAP protocol version in use.  When this API is used with LDAPv3, DN and string values are represented as UTF-8[6] characters.

But this is neither a DN or string attribute value.  I've heard arguments both ways.  
So what do you think?  Does the spec nail this down to UTF-8 (in LDAPv3)?

If so, the common coding practice of:
   printf(".... %s\n", ldap_err2string(err));
is ill advised since it's not internationalized.

---

From: "Kurt D. Zeilenga" <[email-masked]>
Date: Sat, 17 Jun 2000 20:04:49 -0700

>It doesn't specify whether the string is encoded in UTF-8 or may be local, such as DBCS.

I believe ldap_err2string(err) is intended to behave much
like strerror(err).  I would suggest using language similar
to that found in the Standard C Library specification.

Synopsis
   char *ldap_err2string(err);

Description
   The ldap_err2string function maps the LDAP result code in
   err to an message string.  The implementation behaves as if no
   library calls the ldap_err2string function.

Returns
   The ldap_err2string function returns a pointer to the string,
   the contents of which are implementation-defined.  The array
   pointed to shall not be modified by the program, but may be
   overwritten by a subsequent call to the ldap_err2string
   function.

Of course, like strerror(), ldap_err2string is not thread safe.
This may be cause to alter the last sentence,
  s/, but may/and must not/

>So what do you think?

I believe the UTF-8/T.61 requirement should only apply to
strings which are to carried over LDAP.  Other strings,
such as host names and error texts, should be C strings.

> Does the spec nail this down to UTF-8 (in LDAPv3)?

No, and it shouldn't.

 char *s = ldap_err2string( ldap_get_option( NULL, -1, NULL ) );

Is the returned string UTF-8, T.61, or a C string?
It cannot depend on the protocol in use as a protocol version
has yet to specified.  The encoding should not be protocol
dependent, it should be language dependent.

>If [UTF-8], the common coding practice of:

Exactly.  Note that this practice is assumed valid given
the I-D examples.

Kurt

---

From: Mark Smith <[email-masked]>
Date: Mon, 19 Jun 2000 13:24:35 -0400

I generally agree with your comments, and this should be clarified when
we revise the C API I-D.

But ldap_err2string() may or may not be thread safe, depending on how it
is implemented.  If an implementation returns a pointer to static,
readonly data or to thread specific data, ldap_err2string() should be
thread safe).

Also, I don't understand what this sentence from your suggested text is
intended to convey:

>    The implementation behaves as if no

?

-- 
Mark Smith
Directory Product Development / iPlanet E-Commerce Solutions
My words are my own, not my employer's.            Got LDAP?

---

From: "Kurt D. Zeilenga" <[email-masked]>
Date: Mon, 19 Jun 2000 10:46:30 -0700

At 01:24 PM 6/19/00 -0400, Mark Smith wrote:
>is implemented.

Which means that applications must assume that it is not thread
safe unless they have specific knowledge regarding the current
implementation.

>If an implementation returns a pointer to static,

strerror() is not thread safe because it allows the implementation
to dynamically create the string in the static, readonly (to caller)
space, e.g: "unknown error (666)".  Same would follow for
ldap_err2string().

>>    library calls the ldap_err2string function.

That's straight from Standard C Library spec for strerror().
It implies that if the caller makes a call to strerror() followed
by some other library call (such as printf or strcpy) that the
string will not change until the caller makes a subsequent
strerror() call.  Without this requirement:

	char *s = strerror(errno);
	printf("%s\n", s);

might not print the value of s at the time of the strerror
call.  That is, printf is not allowed to call strerror itself
and trash the string before printing the string.

Kurt

---

From: John Haxby <[email-masked]>
Date: Wed, 21 Jun 2000 12:26:44 +0100

> space, e.g: "unknown error (666)".  Same would follow for

A thread-safe strerror() (or ldap_err2string()) would require that the
"static" string is store in thread-specific storage.

For strerror(), some platforms provide a strerror_r() that takes a buffer as
parameter, other platforms -- like HP/UX 11 -- use thread-specific storage.

I would have thought that the nature of the LDAP API would make using
thread-specific storage for ldap_err2string() somewhat attractive.  On the
other hand, I recently discovered that pthread_key_create() (which is what
is used to create this stuff) fails on AIX 4.2 and earlier... so perhaps
ldap_err2string() should simply take a buffer as an extra parameter.

jch