c-api-03 minor nits

["Kurt D. Zeilenga" <Kurt@OpenLDAP.Org>]

This posting covers a few minor nits.  I'll post major nits
separately.

1) memory handling semantics (clarification)

The ber_bvfree() description includes: "Applications should not
use ber_bvfree with bervals which the aplication has allocated."
This applies, I believe to every *free* routine in the API.
However, many API calls do not include such in their descriptions.

I believe it would be wise to add a section describing, in
general, the API memory allocation semantics and than detailing
only exceptions in individual call descriptions.


2) struct berval

Other structure defined by the API have typedefs associated with
them.  I suggest adding:
	typedef struct berval { ... } BerVal;  /* or BerValue */

Purely for symmetry...


3) struct ldapmod

The union (mod_vals) should not be anonymous.  Suggest:
	union mod_vals_u {
		...
	} mod_vals


4) PLDAP namespace

PLDAP symbols are not used nor are they typedef'ed for all
LDAP structures (nor is there any PBer typedefs).   As these
symbols are not used by the specification, I suggest that
all PLDAP symbols be removed from the specification and the
namespace consumed by the specification.  (This still allows
implementations to provide PLDAP symbols if they choose to,
this change removes PLDAP symbols from the scope of this
specification).


5) Tag constants

The document includes numerous BER tags (in macros and in
examples).  These should all be declared with a 'U' suffix
(most are declared bare, some are declared L).

Ie:
#define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U

(note to editor, we sure to catch 0xn tags used in examples).


6) struct timeval

Not all systems timeval fields are of type 'long'.
Implementations must be allowed to declare struct
timeval as it is found in primary header files of
the current C translator.