Initial version of man page for the schema routines

doc/man/man3/ldap_schema.3

+.TH LDAP_SCHEMA 3 "4 June 2000" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 2000 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
+.SH NAME
+ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free,
+ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name,
+ldap_matchingrule_free,
+ldap_str2attributetype, ldap_attributetype2str,
+ldap_attributetype2name, ldap_attributetype_free,
+ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name,
+ldap_objectclass_free,
+ldap_scherr2str \- Schema definition handling routines
+.SH SYNOPSIS
+.nf
+.ft B
+#include <ldap.h>
+.LP
+.ft B
+LDAP_SYNTAX * ldap_str2syntax(s, code, errp, flags)
+.ft
+const char * s;
+int * code;
+const char ** errp;
+const int flags;
+.LP
+.ft B
+char * ldap_syntax2str(syn)
+.ft
+const LDAP_SYNTAX * syn;
+.LP
+.ft B
+const char * ldap_syntax2name(syn)
+.ft
+LDAP_SYNTAX * syn;
+.LP
+.ft B
+ldap_syntax_free(syn)
+.ft
+LDAP_SYNTAX * syn;
+.LP
+.ft B
+LDAP_MATCHING_RULE * ldap_str2matchingrule(s, code, errp, flags)
+.ft
+const char * s;
+int * code;
+const char ** errp;
+const int flags;
+.LP
+.ft B
+char * ldap_matchingrule2str(mr);
+.ft
+const LDAP_MATCHING_RULE * mr;
+.LP
+.ft B
+const char * ldap_matchingrule2name(mr)
+.ft
+LDAP_MATCHING_RULE * mr;
+.LP
+.ft B
+ldap_matchingrule_free(mr)
+.ft
+LDAP_MATCHING_RULE * mr;
+.LP
+.ft B
+LDAP_ATTRIBUTE_TYPE * ldap_str2attributetype(s, code, errp, flags)
+.ft
+const char * s;
+int * code;
+const char ** errp;
+const int flags;
+.LP
+.ft B
+char * ldap_attributetype2str(at)
+.ft
+const LDAP_ATTRIBUTE_TYPE * at;
+.LP
+.ft B
+const char * ldap_attributetype2name(at)
+.ft
+LDAP_ATTRIBUTE_TYPE * at;
+.LP
+.ft B
+ldap_attributetype_free(at)
+.ft
+LDAP_ATTRIBUTE_TYPE * at;
+.LP
+.ft B
+LDAP_OBJECT_CLASS * ldap_str2objectclass(s, code, errp, flags)
+.ft
+const char * s;
+int * code;
+const char ** errp;
+const int flags;
+.LP
+.ft B
+char * ldap_objectclass2str(oc)
+.ft
+const LDAP_OBJECT_CLASS * oc;
+.LP
+.ft B
+const char * ldap_objectclass2name(oc)
+.ft
+LDAP_OBJECT_CLASS * oc;
+.LP
+.ft B
+ldap_objectclass_free(oc)
+.ft
+LDAP_OBJECT_CLASS * oc;
+.LP
+.ft B
+char * ldap_scherr2str(code)
+.ft
+int code;
+.SH DESCRIPTION
+These routines are used to parse schema definitions in the syntax
+defined in RFC2252 into structs and handle these structs.  These
+routines handle four kinds of definitions: syntaxes, matching rules,
+attribute types and objectclasses.  For each definition kind, four
+routines are provided.
+.LP
+.B ldap_str2xxx()
+takes a definition in RFC2252 format in argument
+.IR s
+as a NUL-terminated string and returns, if possible, a pointer to a
+newly allocated struct of the appropriate kind.  The caller is
+responsible for freeing the struct by calling
+.B ldap_xxx_free()
+when not needed any longer.  The routine returns NULL if some problem
+happened.  In this case, the integer pointed at by argument
+.IR code
+will receive an error code (see below the description of
+.B ldap_scherr2str()
+for an explanation of the values) and a pointer to a NUL-terminated
+string will be placed where requested by argument
+.IR errp
+, indicating where in argument
+.IR s
+the error happened, so it must not be freed by the caller.  Argument
+.IR flags
+is a bit mask of parsing options controlling the relaxation of the
+syntax recognized.  The following values are defined:
+.TP
+.B LDAP_SCHEMA_ALLOW_NONE
+strict parsing according to RFC2252.
+.TP
+.B LDAP_SCHEMA_ALLOW_NO_OID
+permit definitions that do not contain an initial OID.
+.TP
+.B LDAP_SCHEMA_ALLOW_QUOTED
+permit quotes around some items that should not have them.
+.TP
+.B LDAP_SCHEMA_ALLOW_DESCR
+permit a
+.B descr
+instead of a numeric OID in places where the syntax expect the latter.
+.TP
+.B LDAP_SCHEMA_ALLOW_DESCR_PREFIX
+permit that the initial numeric OID contains a prefix in
+.B descr
+format.
+.TP
+.B LDAP_SCHEMA_ALLOW_ALL
+be very liberal, include all options.
+.LP
+The structures returned are as follows:
+.sp
+.RS
+.nf
+.ne 7
+.ta 8n 16n 32 n
+typedef struct ldap_schema_extension_item {
+	char *lsei_name;	/* Extension name */
+	char **lsei_values;	/* Extension values */
+} LDAP_SCHEMA_EXTENSION_ITEM;
+
+typedef struct ldap_syntax {
+	char *syn_oid;		/* OID */
+	char **syn_names;	/* Names */
+	char *syn_desc;		/* Description */
+	LDAP_SCHEMA_EXTENSION_ITEM **syn_extensions; /* Extension */
+} LDAP_SYNTAX;
+
+typedef struct ldap_matchingrule {
+	char *mr_oid;		/* OID */
+	char **mr_names;	/* Names */
+	char *mr_desc;		/* Description */
+	int  mr_obsolete;	/* Is obsolete? */
+	char *mr_syntax_oid;	/* Syntax of asserted values */
+	LDAP_SCHEMA_EXTENSION_ITEM **mr_extensions; /* Extensions */
+} LDAP_MATCHING_RULE;
+
+typedef struct ldap_attributetype {
+	char *at_oid;		/* OID */
+	char **at_names;	/* Names */
+	char *at_desc;		/* Description */
+	int  at_obsolete;	/* Is obsolete? */
+	char *at_sup_oid;	/* OID of superior type */
+	char *at_equality_oid;	/* OID of equality matching rule */
+	char *at_ordering_oid;	/* OID of ordering matching rule */
+	char *at_substr_oid;	/* OID of substrings matching rule */
+	char *at_syntax_oid;	/* OID of syntax of values */
+	int  at_syntax_len;	/* Suggested minimum maximum length */
+	int  at_single_value;	/* Is single-valued?  */
+	int  at_collective;	/* Is collective? */
+	int  at_no_user_mod;	/* Are changes forbidden through LDAP? */
+	int  at_usage;		/* Usage, see below */
+	LDAP_SCHEMA_EXTENSION_ITEM **at_extensions; /* Extensions */
+} LDAP_ATTRIBUTE_TYPE;
+
+typedef struct ldap_objectclass {
+	char *oc_oid;		/* OID */
+	char **oc_names;	/* Names */
+	char *oc_desc;		/* Description */
+	int  oc_obsolete;	/* Is obsolete? */
+	char **oc_sup_oids;	/* OIDs of superior classes */
+	int  oc_kind;		/* Kind, see below */
+	char **oc_at_oids_must;	/* OIDs of required attribute types */
+	char **oc_at_oids_may;	/* OIDs of optional attribute types */
+	LDAP_SCHEMA_EXTENSION_ITEM **oc_extensions; /* Extensions */
+} LDAP_OBJECT_CLASS;
+.ta
+.fi
+.RE
+.PP
+Some integer fields (those described with a question mark) have a
+truth value, for these fields the possible values are:
+.TP
+.B LDAP_SCHEMA_NO
+The answer to the question is no.
+.TP
+.B LDAP_SCHEMA_YES
+The answer to the question is yes.
+.LP
+For attribute types, the following usages are possible:
+.TP
+.B LDAP_SCHEMA_USER_APPLICATIONS
+the attribute type is non-operational.
+.TP
+.B LDAP_SCHEMA_DIRECTORY_OPERATION
+the attribute type is operational and is pertinent to the directory
+itself, i.e. it has the same value on all servers that master the
+entry containing this attribute type.
+.TP
+.B LDAP_SCHEMA_DISTRIBUTED_OPERATION
+the attribute type is operational and is pertinent to replication,
+shadowing or other distributed directory aspect.  TBC.
+.TP
+.B LDAP_SCHEMA_DSA_OPERATION
+the attribute type is operational and is pertinent to the directory
+server itself, i.e. it may have different values for the same entry
+when retrieved from different servers that master the entry.
+.LP
+Object classes can be of three kinds:
+.TP
+.B LDAP_SCHEMA_ABSTRACT
+the object class is abstract, i.e. there cannot be entries of this
+class alone.
+.TP
+.B LDAP_SCHEMA_STRUCTURAL
+the object class is structural, i.e. it describes the main role of the
+entry.  On some servers, once the entry is created the set of
+structural object classes assigned cannot be changed: none of those
+present can be removed and none other can be added.
+.TP
+.B LDAP_SCHEMA_AUXILIARY
+the object class is auxiliary, i.e. it is intended to go with other,
+structural, object classes.  These can be added or removed at any time
+if attribute types are added or removed at the same time as needed by
+the set of object classes resulting from the operation.
+.LP
+Routines
+.B ldap_xxx2name()
+return a canonical name for the definition.
+.LP
+Routines
+.B ldap_xxx2str()
+return a string representation in the format described by RFC2252 of
+the struct passed in the argument.  The string is a newly allocated
+string that must be freed by the caller.  These routines may return
+NULL if no memory can be allocated for the string.
+.LP
+.B ldap_scherr2str()
+returns a NUL-terminated string with a text description of the error
+found.  This is a pointer to a static area, so it must not be freed by
+the caller.  The argument
+.IR code
+comes from one of the parsing routines and can adopt the following
+values:
+.TP
+.B LDAP_SCHERR_OUTOFMEM
+Out of memory.
+.TP
+.B LDAP_SCHERR_UNEXPTOKEN
+Unexpected token.
+.TP
+.B LDAP_SCHERR_NOLEFTPAREN
+Missing opening parenthesis.
+.TP
+.B LDAP_SCHERR_NORIGHTPAREN
+Missing closing parenthesis.
+.TP
+.B LDAP_SCHERR_NODIGIT
+Expecting digit.
+.TP
+.B LDAP_SCHERR_BADNAME
+Expecting a name.
+.TP
+.B LDAP_SCHERR_BADDESC
+Bad description.
+.TP
+.B LDAP_SCHERR_BADSUP
+Bad superiors.
+.TP
+.B LDAP_SCHERR_DUPOPT
+Duplicate option.
+.TP
+.B LDAP_SCHERR_EMPTY
+Unexpected end of data.
+
+.SH SEE ALSO
+.BR ldap (3),
+.SH ACKNOWLEDGEMENTS
+.B	OpenLDAP
+is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
+.B	OpenLDAP
+is derived from University of Michigan LDAP 3.3 Release.  
+

doc/man/man3/ldap_schema.3.links

+ldap_str2syntax.3
+ldap_syntax2str.3
+ldap_syntax2name.3
+ldap_syntax_free.3
+ldap_str2matchingrule.3
+ldap_matchingrule2str.3
+ldap_matchingrule2name.3
+ldap_matchingrule_free.3
+ldap_str2attributetype.3
+ldap_attributetype2str.3
+ldap_attributetype2name.3
+ldap_attributetype_free.3
+ldap_str2objectclass.3
+ldap_objectclass2str.3
+ldap_objectclass2name.3
+ldap_objectclass_free.3
+ldap_scherr2str.3