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