external/bsd/openldap/man/ldap_schema.3

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