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

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