git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_schema.3

   1 .TH LDAP_SCHEMA 3 "4 June 2000" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 2000-2002 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free,
   7 ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name,
   8 ldap_matchingrule_free,
   9 ldap_str2attributetype, ldap_attributetype2str,
  10 ldap_attributetype2name, ldap_attributetype_free,
  11 ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name,
  12 ldap_objectclass_free,
  13 ldap_scherr2str \- Schema definition handling routines
  14 .SH SYNOPSIS
  15 .nf
  16 .ft B
  17 #include <ldap.h>
  18 #include <ldap_schema.h>
  19 .LP
  20 .ft B
  21 LDAPSyntax * ldap_str2syntax(s, code, errp, flags)
  22 .ft
  23 const char * s;
  24 int * code;
  25 const char ** errp;
  26 const int flags;
  27 .LP
  28 .ft B
  29 char * ldap_syntax2str(syn)
  30 .ft
  31 const LDAPSyntax * syn;
  32 .LP
  33 .ft B
  34 const char * ldap_syntax2name(syn)
  35 .ft
  36 LDAPSyntax * syn;
  37 .LP
  38 .ft B
  39 ldap_syntax_free(syn)
  40 .ft
  41 LDAPSyntax * syn;
  42 .LP
  43 .ft B
  44 LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags)
  45 .ft
  46 const char * s;
  47 int * code;
  48 const char ** errp;
  49 const int flags;
  50 .LP
  51 .ft B
  52 char * ldap_matchingrule2str(mr);
  53 .ft
  54 const LDAPMatchingRule * mr;
  55 .LP
  56 .ft B
  57 const char * ldap_matchingrule2name(mr)
  58 .ft
  59 LDAPMatchingRule * mr;
  60 .LP
  61 .ft B
  62 ldap_matchingrule_free(mr)
  63 .ft
  64 LDAPMatchingRule * mr;
  65 .LP
  66 .ft B
  67 LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags)
  68 .ft
  69 const char * s;
  70 int * code;
  71 const char ** errp;
  72 const int flags;
  73 .LP
  74 .ft B
  75 char * ldap_attributetype2str(at)
  76 .ft
  77 const LDAPAttributeType * at;
  78 .LP
  79 .ft B
  80 const char * ldap_attributetype2name(at)
  81 .ft
  82 LDAPAttributeType * at;
  83 .LP
  84 .ft B
  85 ldap_attributetype_free(at)
  86 .ft
  87 LDAPAttributeType * at;
  88 .LP
  89 .ft B
  90 LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags)
  91 .ft
  92 const char * s;
  93 int * code;
  94 const char ** errp;
  95 const int flags;
  96 .LP
  97 .ft B
  98 char * ldap_objectclass2str(oc)
  99 .ft
 100 const LDAPObjectClass * oc;
 101 .LP
 102 .ft B
 103 const char * ldap_objectclass2name(oc)
 104 .ft
 105 LDAPObjectClass * oc;
 106 .LP
 107 .ft B
 108 ldap_objectclass_free(oc)
 109 .ft
 110 LDAPObjectClass * oc;
 111 .LP
 112 .ft B
 113 char * ldap_scherr2str(code)
 114 .ft
 115 int code;
 116 .SH DESCRIPTION
 117 These routines are used to parse schema definitions in the syntax
 118 defined in RFC 2252 into structs and handle these structs.  These
 119 routines handle four kinds of definitions: syntaxes, matching rules,
 120 attribute types and objectclasses.  For each definition kind, four
 121 routines are provided.
 122 .LP
 123 .B ldap_str2xxx()
 124 takes a definition in RFC 2252 format in argument
 125 .IR s
 126 as a NUL-terminated string and returns, if possible, a pointer to a
 127 newly allocated struct of the appropriate kind.  The caller is
 128 responsible for freeing the struct by calling
 129 .B ldap_xxx_free()
 130 when not needed any longer.  The routine returns NULL if some problem
 131 happened.  In this case, the integer pointed at by argument
 132 .IR code
 133 will receive an error code (see below the description of
 134 .B ldap_scherr2str()
 135 for an explanation of the values) and a pointer to a NUL-terminated
 136 string will be placed where requested by argument
 137 .IR errp
 138 , indicating where in argument
 139 .IR s
 140 the error happened, so it must not be freed by the caller.  Argument
 141 .IR flags
 142 is a bit mask of parsing options controlling the relaxation of the
 143 syntax recognized.  The following values are defined:
 144 .TP
 145 .B LDAP_SCHEMA_ALLOW_NONE
 146 strict parsing according to RFC 2252.
 147 .TP
 148 .B LDAP_SCHEMA_ALLOW_NO_OID
 149 permit definitions that do not contain an initial OID.
 150 .TP
 151 .B LDAP_SCHEMA_ALLOW_QUOTED
 152 permit quotes around some items that should not have them.
 153 .TP
 154 .B LDAP_SCHEMA_ALLOW_DESCR
 155 permit a
 156 .B descr
 157 instead of a numeric OID in places where the syntax expect the latter.
 158 .TP
 159 .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX
 160 permit that the initial numeric OID contains a prefix in
 161 .B descr
 162 format.
 163 .TP
 164 .B LDAP_SCHEMA_ALLOW_ALL
 165 be very liberal, include all options.
 166 .LP
 167 The structures returned are as follows:
 168 .sp
 169 .RS
 170 .nf
 171 .ne 7
 172 .ta 8n 16n 32n
 173 typedef struct ldap_schema_extension_item {
 174         char *lsei_name;        /* Extension name */
 175         char **lsei_values;     /* Extension values */
 176 } LDAPSchemaExtensionItem;
 177
 178 typedef struct ldap_syntax {
 179         char *syn_oid;          /* OID */
 180         char **syn_names;       /* Names */
 181         char *syn_desc;         /* Description */
 182         LDAPSchemaExtensionItem **syn_extensions; /* Extension */
 183 } LDAPSyntax;
 184
 185 typedef struct ldap_matchingrule {
 186         char *mr_oid;           /* OID */
 187         char **mr_names;        /* Names */
 188         char *mr_desc;          /* Description */
 189         int  mr_obsolete;       /* Is obsolete? */
 190         char *mr_syntax_oid;    /* Syntax of asserted values */
 191         LDAPSchemaExtensionItem **mr_extensions; /* Extensions */
 192 } LDAPMatchingRule;
 193
 194 typedef struct ldap_attributetype {
 195         char *at_oid;           /* OID */
 196         char **at_names;        /* Names */
 197         char *at_desc;          /* Description */
 198         int  at_obsolete;       /* Is obsolete? */
 199         char *at_sup_oid;       /* OID of superior type */
 200         char *at_equality_oid;  /* OID of equality matching rule */
 201         char *at_ordering_oid;  /* OID of ordering matching rule */
 202         char *at_substr_oid;    /* OID of substrings matching rule */
 203         char *at_syntax_oid;    /* OID of syntax of values */
 204         int  at_syntax_len;     /* Suggested minimum maximum length */
 205         int  at_single_value;   /* Is single-valued?  */
 206         int  at_collective;     /* Is collective? */
 207         int  at_no_user_mod;    /* Are changes forbidden through LDAP? */
 208         int  at_usage;          /* Usage, see below */
 209         LDAPSchemaExtensionItem **at_extensions; /* Extensions */
 210 } LDAPAttributeType;
 211
 212 typedef struct ldap_objectclass {
 213         char *oc_oid;           /* OID */
 214         char **oc_names;        /* Names */
 215         char *oc_desc;          /* Description */
 216         int  oc_obsolete;       /* Is obsolete? */
 217         char **oc_sup_oids;     /* OIDs of superior classes */
 218         int  oc_kind;           /* Kind, see below */
 219         char **oc_at_oids_must; /* OIDs of required attribute types */
 220         char **oc_at_oids_may;  /* OIDs of optional attribute types */
 221         LDAPSchemaExtensionItem **oc_extensions; /* Extensions */
 222 } LDAPObjectClass;
 223 .ta
 224 .fi
 225 .RE
 226 .PP
 227 Some integer fields (those described with a question mark) have a
 228 truth value, for these fields the possible values are:
 229 .TP
 230 .B LDAP_SCHEMA_NO
 231 The answer to the question is no.
 232 .TP
 233 .B LDAP_SCHEMA_YES
 234 The answer to the question is yes.
 235 .LP
 236 For attribute types, the following usages are possible:
 237 .TP
 238 .B LDAP_SCHEMA_USER_APPLICATIONS
 239 the attribute type is non-operational.
 240 .TP
 241 .B LDAP_SCHEMA_DIRECTORY_OPERATION
 242 the attribute type is operational and is pertinent to the directory
 243 itself, i.e. it has the same value on all servers that master the
 244 entry containing this attribute type.
 245 .TP
 246 .B LDAP_SCHEMA_DISTRIBUTED_OPERATION
 247 the attribute type is operational and is pertinent to replication,
 248 shadowing or other distributed directory aspect.  TBC.
 249 .TP
 250 .B LDAP_SCHEMA_DSA_OPERATION
 251 the attribute type is operational and is pertinent to the directory
 252 server itself, i.e. it may have different values for the same entry
 253 when retrieved from different servers that master the entry.
 254 .LP
 255 Object classes can be of three kinds:
 256 .TP
 257 .B LDAP_SCHEMA_ABSTRACT
 258 the object class is abstract, i.e. there cannot be entries of this
 259 class alone.
 260 .TP
 261 .B LDAP_SCHEMA_STRUCTURAL
 262 the object class is structural, i.e. it describes the main role of the
 263 entry.  On some servers, once the entry is created the set of
 264 structural object classes assigned cannot be changed: none of those
 265 present can be removed and none other can be added.
 266 .TP
 267 .B LDAP_SCHEMA_AUXILIARY
 268 the object class is auxiliary, i.e. it is intended to go with other,
 269 structural, object classes.  These can be added or removed at any time
 270 if attribute types are added or removed at the same time as needed by
 271 the set of object classes resulting from the operation.
 272 .LP
 273 Routines
 274 .B ldap_xxx2name()
 275 return a canonical name for the definition.
 276 .LP
 277 Routines
 278 .B ldap_xxx2str()
 279 return a string representation in the format described by RFC 2252 of
 280 the struct passed in the argument.  The string is a newly allocated
 281 string that must be freed by the caller.  These routines may return
 282 NULL if no memory can be allocated for the string.
 283 .LP
 284 .B ldap_scherr2str()
 285 returns a NUL-terminated string with a text description of the error
 286 found.  This is a pointer to a static area, so it must not be freed by
 287 the caller.  The argument
 288 .IR code
 289 comes from one of the parsing routines and can adopt the following
 290 values:
 291 .TP
 292 .B LDAP_SCHERR_OUTOFMEM
 293 Out of memory.
 294 .TP
 295 .B LDAP_SCHERR_UNEXPTOKEN
 296 Unexpected token.
 297 .TP
 298 .B LDAP_SCHERR_NOLEFTPAREN
 299 Missing opening parenthesis.
 300 .TP
 301 .B LDAP_SCHERR_NORIGHTPAREN
 302 Missing closing parenthesis.
 303 .TP
 304 .B LDAP_SCHERR_NODIGIT
 305 Expecting digit.
 306 .TP
 307 .B LDAP_SCHERR_BADNAME
 308 Expecting a name.
 309 .TP
 310 .B LDAP_SCHERR_BADDESC
 311 Bad description.
 312 .TP
 313 .B LDAP_SCHERR_BADSUP
 314 Bad superiors.
 315 .TP
 316 .B LDAP_SCHERR_DUPOPT
 317 Duplicate option.
 318 .TP
 319 .B LDAP_SCHERR_EMPTY
 320 Unexpected end of data.
 321
 322 .SH SEE ALSO
 323 .BR ldap (3),
 324 .SH ACKNOWLEDGEMENTS
 325 .B      OpenLDAP
 326 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 327 .B      OpenLDAP
 328 is derived from University of Michigan LDAP 3.3 Release.
 329