| blob | eb02188581fbe151dea3f09c5cd82eca340cd3c3 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SCF_TMPL_VALIDATE_FMRI 3SCF "Oct 28, 2008"
7 .SH NAME
8 scf_tmpl_validate_fmri, scf_tmpl_errors_destroy, scf_tmpl_next_error,
9 scf_tmpl_reset_errors, scf_tmpl_strerror, scf_tmpl_error_type,
10 scf_tmpl_error_source_fmri, scf_tmpl_error_pg_tmpl, scf_tmpl_error_pg,
11 scf_tmpl_error_prop_tmpl, scf_tmpl_error_prop, scf_tmpl_error_value \- template
12 validation functions
13 .SH SYNOPSIS
14 .LP
15 .nf
16 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
17 #include <libscf.h>
19 \fBint\fR \fBscf_tmpl_validate_fmri\fR(\fBscf_handle_t *\fR\fIh\fR, \fBconst char *\fR\fIfmri\fR,
20 \fBconst char *\fR\fIsnapshot\fR, \fBscf_tmpl_errors_t **\fR\fIerrs\fR, \fBint\fR \fIflags\fR);
21 .fi
23 .LP
24 .nf
25 \fBvoid\fR \fBscf_tmpl_errors_destroy\fR(\fBscf_tmpl_errors_t *\fR\fIerrs\fR);
26 .fi
28 .LP
29 .nf
30 \fBscf_tmpl_error_t *\fR\fBscf_tmpl_next_error\fR(\fBscf_tmpl_errors_t *\fR\fIerrs\fR,
31 \fBscf_tmpl_errors_t *\fR\fIerr\fR)
32 .fi
34 .LP
35 .nf
36 \fBvoid\fR \fBscf_tmpl_reset_errors\fR(\fBscf_tmpl_errors_t *\fR\fIerrs\fR);
37 .fi
39 .LP
40 .nf
41 \fBint\fR \fBscf_tmpl_strerror\fR(\fBscf_tmpl_error_t *\fR\fIerr\fR, \fBchar *\fR\fIs\fR,
42 \fBsize_t\fR \fIn\fR, \fBint\fR \fIflags\fR);
43 .fi
45 .LP
46 .nf
47 \fBint\fR \fBscf_tmpl_error_type\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR,
48 \fBscf_tmpl_error_type_t *\fR\fItype\fR);
49 .fi
51 .LP
52 .nf
53 \fBint\fR \fBscf_tmpl_error_source_fmri\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR,
54 \fBchar *\fR\fIfmri\fR);
55 .fi
57 .LP
58 .nf
59 \fBint\fR \fBscf_tmpl_error_pg_tmpl\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar *\fR\fIname\fR,
60 \fBchar *\fR\fItype\fR);
61 .fi
63 .LP
64 .nf
65 \fBint\fR \fBscf_tmpl_error_pg\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR,
66 \fBchar **\fR\fIname\fR, \fBchar **\fR\fItype\fR);
67 .fi
69 .LP
70 .nf
71 \fBint\fR \fBscf_tmpl_error_prop_tmpl\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar **\fR\fIname\fR,
72 \fBchar **\fR\fItype\fR);
73 .fi
75 .LP
76 .nf
77 \fBint\fR \fBscf_tmpl_error_prop\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar **\fR\fIname\fR,
78 \fBchar **\fR\fItype\fR,);
79 .fi
81 .LP
82 .nf
83 \fBint\fR \fBscf_tmpl_error_value\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar**\fR\fIval\fR);
84 .fi
86 .SH DESCRIPTION
87 .sp
88 .LP
89 The template validation functions offer a way to validate the configuration
90 data of an service instance against the appropriate template data. The
91 \fBscf_tmpl_validate_fmri()\fR function returns the full set of errors for the
92 specified instance, and those errors can be printed or explored directly.
93 .sp
94 .LP
95 By default, the validation is performed on the composed data from the running
96 snapshot of an instance. A different snapshot can be explicitly selected by
97 specifying a valid snapshot name rather than \fINULL\fR for the \fIsnapshot\fR
98 argument. If \fIflags\fR includes \fBSCF_TMPL_VALIDATE_FLAG_CURRENT\fR, the
99 \fIsnapshot\fR argument is ignored and the current configuration is used.
100 .sp
101 .LP
102 By default, these functions also explore template data defined by the service
103 or instance itself, the service's restarter, and global template data. See
104 \fBsmf_template\fR(5) for more information about this composition.
105 .sp
106 .LP
107 An instance FMRI is required, and FMRIs that specify other entities (for
108 example, services) are explicitly rejected.
109 .sp
110 .LP
111 The \fBscf_tmpl_validate_fmri()\fR function validates an instance FMRI against
112 the template data in the repository. As described above, when the
113 \fIsnapshot\fR argument is \fINULL\fR, the default running snapshot is used. If
114 \fBscf_tmpl_errors_t **\fR is non-null, the structure is allocated and returned
115 to the caller for further perusal or printing of the errors.
116 .sp
117 .LP
118 The \fBscf_tmpl_errors_destroy()\fR function destroys and frees the
119 \fBscf_tmpl_errors_t\fR and all of the \fBscf_tmpl_error_t\fR structures to
120 which it refers.
121 .sp
122 .LP
123 The \fBscf_tmpl_next_error()\fR function takes a pointer to a
124 \fBscf_tmpl_errors_t\fR structure previously returned by
125 \fBscf_tmpl_validate_fmri()\fR. On the first call, it returns a pointer to the
126 first \fBscf_tmpl_error_t\fR found during validation. On subsequent calls, the
127 next error is returned. To resume processing from the first error, the caller
128 can use \fBscf_tmpl_reset_errors()\fR.
129 .sp
130 .LP
131 The contents of an \fBscf_tmpl_error_t\fR are determined by its type. Types
132 added as additional validation checks are introduced. Based on the error type,
133 a set of fields can be retrieved from the error.
134 .sp
135 .ne 2
136 .na
137 \fB\fBSCF_TERR_TYPE_INVALID\fR\fR
138 .ad
139 .sp .6
140 .RS 4n
141 reserved invalid type
142 .RE
144 .sp
145 .ne 2
146 .na
147 \fB\fBSCF_TERR_MISSING_PG\fR\fR
148 .ad
149 .sp .6
150 .RS 4n
151 required property group is missing
152 .br
153 .in +2
154 template source FMRI
155 .in -2
156 .br
157 .in +2
158 property group template name and type
159 .in -2
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fB\fBSCF_TERR_WRONG_PG_TYPE\fR\fR
166 .ad
167 .sp .6
168 .RS 4n
169 property group type is incorrect
170 .br
171 .in +2
172 template source FMRI
173 .in -2
174 .br
175 .in +2
176 property group template name and type
177 .in -2
178 .br
179 .in +2
180 property group name and type
181 .in -2
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBSCF_TERR_MISSING_PROP\fR\fR
188 .ad
189 .sp .6
190 .RS 4n
191 required property is missing
192 .br
193 .in +2
194 template source FMRI
195 .in -2
196 .br
197 .in +2
198 property group template name and type
199 .in -2
200 .br
201 .in +2
202 property template name and type
203 .in -2
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fBSCF_TERR_WRONG_PROP_TYPE\fR\fR
210 .ad
211 .sp .6
212 .RS 4n
213 property type is incorrect
214 .br
215 .in +2
216 template source FMRI
217 .in -2
218 .br
219 .in +2
220 property group template name and type
221 .in -2
222 .br
223 .in +2
224 property template name and type
225 .in -2
226 .br
227 .in +2
228 property group name and type
229 .in -2
230 .br
231 .in +2
232 property name and type
233 .in -2
234 .RE
236 .sp
237 .ne 2
238 .na
239 \fB\fBSCF_TERR_CARDINALITY_VIOLATION\fR\fR
240 .ad
241 .sp .6
242 .RS 4n
243 number of values violates cardinality
244 .br
245 .in +2
246 template source FMRI
247 .in -2
248 .br
249 .in +2
250 property group template name and type
251 .in -2
252 .br
253 .in +2
254 property template name and type
255 .in -2
256 .br
257 .in +2
258 property group name and type
259 .in -2
260 .br
261 .in +2
262 property name and type
263 .in -2
264 .br
265 .in +2
266 cardinality and cardinality limits
267 .in -2
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBSCF_TERR_VALUE_CONSTRAINT_VIOLATED\fR\fR
274 .ad
275 .sp .6
276 .RS 4n
277 constraint violated for value
278 .br
279 .in +2
280 template source FMRI
281 .in -2
282 .br
283 .in +2
284 property group template name and type
285 .in -2
286 .br
287 .in +2
288 property template name and type
289 .in -2
290 .br
291 .in +2
292 property group name and type
293 .in -2
294 .br
295 .in +2
296 property name and type
297 .in -2
298 .br
299 .in +2
300 value
301 .in -2
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fBSCF_TERR_RANGE_VIOLATION\fR\fR
308 .ad
309 .sp .6
310 .RS 4n
311 value violated specified range
312 .br
313 .in +2
314 template source FMRI
315 .in -2
316 .br
317 .in +2
318 property group template name and type
319 .in -2
320 .br
321 .in +2
322 property template name and type
323 .in -2
324 .br
325 .in +2
326 property group name and type
327 .in -2
328 .br
329 .in +2
330 property name and type
331 .in -2
332 .br
333 .in +2
334 value
335 .in -2
336 .RE
338 .sp
339 .ne 2
340 .na
341 \fB\fBSCF_TERR_PROP_TYPE_MISMATCH\fR\fR
342 .ad
343 .sp .6
344 .RS 4n
345 value type is different from property type
346 .br
347 .in +2
348 template source FMRI
349 .in -2
350 .br
351 .in +2
352 property group template name and type
353 .in -2
354 .br
355 .in +2
356 property template name and type
357 .in -2
358 .RE
360 .sp
361 .ne 2
362 .na
363 \fB\fBSCF_TERR_VALUE_OUT_OF_RANGE\fR\fR
364 .ad
365 .sp .6
366 .RS 4n
367 value is out of template defined range
368 .br
369 .in +2
370 template source FMRI
371 .in -2
372 .br
373 .in +2
374 property group template name and type
375 .in -2
376 .br
377 .in +2
378 property template name and type
379 .in -2
380 .br
381 .in +2
382 value
383 .in -2
384 .RE
386 .sp
387 .ne 2
388 .na
389 \fB\fBSCF_TERR_INVALID_VALUE\fR\fR
390 .ad
391 .sp .6
392 .RS 4n
393 value violates template defined constraints
394 .br
395 .in +2
396 template source FMRI
397 .in -2
398 .br
399 .in +2
400 property group template name and type
401 .in -2
402 .br
403 .in +2
404 property template name and type
405 .in -2
406 .br
407 .in +2
408 value
409 .in -2
410 .RE
412 .sp
413 .LP
414 The \fBSCF_TERR_PROP_TYPE_MISMATCH\fR, \fBSCF_TERR_VALUE_OUT_OF_RANGE\fR and
415 \fBSCF_TERR_INVALID_VALUE\fR types are only set from calls to
416 \fBscf_tmpl_value_in_constraint\fR(3SCF).
417 .sp
418 .LP
419 The \fBscf_tmpl_error_type()\fR function retrieves the error type.
420 .sp
421 .LP
422 The \fBscf_tmpl_error_source_fmri()\fR function retrieves a string with the
423 FMRI of the source of the template that was violated. This string is freed by
424 \fBscf_tmpl_errors_destroy()\fR.
425 .sp
426 .LP
427 The \fBscf_tmpl_error_pg_tmpl()\fR function retrieves strings with the name and
428 type of the property group template that was violated. If the property group
429 name or type was implicitly wildcarded (see \fBsmf_template\fR(5)) in the
430 template, this function returns a string containing \fBSCF_TMPL_WILDCARD\fR
431 ("*"). These strings are freed by \fBscf_tmpl_errors_destroy()\fR.
432 .sp
433 .LP
434 The \fBscf_tmpl_error_pg()\fR function retrieves strings with the name and type
435 of the property group that was violated. These strings are freed by
436 \fBscf_tmpl_errors_destroy()\fR.
437 .sp
438 .LP
439 The \fBscf_tmpl_error_prop_tmpl()\fR function retrieves strings with the name
440 and type of the property template that was violated. If the property type was
441 implicitly wildcarded (see \fBsmf_template\fR(5)) in the template, this
442 function returns a string containing \fBSCF_TMPL_WILDCARD\fR ("*"). These
443 strings are freed by \fBscf_tmpl_errors_destroy()\fR.
444 .sp
445 .LP
446 The \fBscf_tmpl_error_prop()\fR function retrieves strings with the name and
447 type of the property that was violated. These strings are freed by
448 \fBscf_tmpl_errors_destroy()\fR.
449 .sp
450 .LP
451 The \fBscf_tmpl_error_value()\fR function retrieves a string with the value
452 containing the error in \fIval\fR. This string are freed by
453 \fBscf_tmpl_errors_destroy()\fR.
454 .sp
455 .LP
456 The \fBscf_tmpl_strerror()\fR function takes an \fBscf_tmpl_error_t\fR
457 previously returned by \fBscf_tmpl_next_error()\fR and returns in \fIs\fR. If
458 flags includes \fBSCF_TMPL_STRERROR_HUMAN\fR, \fIs\fR is a human-readable,
459 localized description of the error. Otherwise, \fIs\fR is a one-line string
460 suitable for logfile output.
461 .SH RETURN VALUES
462 .sp
463 .LP
464 The \fBscf_tmpl_validate_fmri()\fR function returns 0 on successful completion
465 with no validation failures. It returns 1 if there are validation failures. It
466 returns -1 if there is an error validating the instance.
467 .sp
468 .LP
469 The \fBscf_tmpl_next_error()\fR function returns a pointer to the next
470 \fBscf_tmpl_error_t\fR. When none remain, it returns \fINULL\fR.
471 .sp
472 .LP
473 The \fBscf_tmpl_error_type()\fR, \fBscf_tmpl_error_source_fmri()\fR,
474 \fBscf_tmpl_error_pg_tmpl()\fR, \fBscf_tmpl_error_pg()\fR,
475 \fBscf_tmpl_error_prop_tmpl()\fR, \fBscf_tmpl_error_prop()\fR, and
476 \fBscf_tmpl_error_value()\fR functions return 0 on success and -1 on failure.
477 .sp
478 .LP
479 The \fBscf_tmpl_strerror()\fR function returns the number of bytes that would
480 have been written to s if n had been sufficiently large.
481 .SH ERRORS
482 .sp
483 .LP
484 The \fBscf_tmpl_validate_fmri()\fR function will fail if:
485 .sp
486 .ne 2
487 .na
488 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
489 .ad
490 .sp .6
491 .RS 4n
492 The storage mechanism that the repository server (\fBsvc.configd\fR(1M)) chose
493 for the operation denied access.
494 .RE
496 .sp
497 .ne 2
498 .na
499 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
500 .ad
501 .sp .6
502 .RS 4n
503 The connection to the repository was lost.
504 .RE
506 .sp
507 .ne 2
508 .na
509 \fB\fBSCF_ERROR_DELETED\fR\fR
510 .ad
511 .sp .6
512 .RS 4n
513 The instance or one of its template property group have been deleted.
514 .RE
516 .sp
517 .ne 2
518 .na
519 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
520 .ad
521 .sp .6
522 .RS 4n
523 The handle passed in has been destroyed.
524 .RE
526 .sp
527 .ne 2
528 .na
529 \fB\fBSCF_ERROR_INTERNAL\fR\fR
530 .ad
531 .sp .6
532 .RS 4n
533 An internal error occurred.
534 .RE
536 .sp
537 .ne 2
538 .na
539 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
540 .ad
541 .sp .6
542 .RS 4n
543 The handle argument, FMRI argument, or snapshot name is invalid
544 .RE
546 .sp
547 .ne 2
548 .na
549 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
550 .ad
551 .sp .6
552 .RS 4n
553 There is not enough memory to validate the instance.
554 .RE
556 .sp
557 .ne 2
558 .na
559 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
560 .ad
561 .sp .6
562 .RS 4n
563 The server does not have adequate resources to complete the request.
564 .RE
566 .sp
567 .ne 2
568 .na
569 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
570 .ad
571 .sp .6
572 .RS 4n
573 The handle is not currently bound.
574 .RE
576 .sp
577 .ne 2
578 .na
579 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
580 .ad
581 .sp .6
582 .RS 4n
583 An object matching FMRI does not exist in the repository, or the snapshot does
584 not exist.
585 .RE
587 .sp
588 .ne 2
589 .na
590 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
591 .ad
592 .sp .6
593 .RS 4n
594 The instance or template could not be read due to access restrictions.
595 .RE
597 .sp
598 .ne 2
599 .na
600 \fB\fBSCF_ERROR_TEMPLATE_INVALID\fR\fR
601 .ad
602 .sp .6
603 .RS 4n
604 The template data is invalid.
605 .RE
607 .sp
608 .LP
609 The \fBscf_tmpl_strerror()\fR, \fBscf_tmpl_error_type()\fR,
610 \fBscf_tmpl_error_source_fmri()\fR, \fBscf_tmpl_error_pg_tmpl()\fR,
611 \fBscf_tmpl_error_pg()\fR, \fBscf_tmpl_error_prop_tmpl()\fR,
612 \fBscf_tmpl_error_prop()\fR, and \fBscf_tmpl_error_value()\fR functions will
613 fail if:
614 .sp
615 .ne 2
616 .na
617 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
618 .ad
619 .RS 30n
620 The \fBscf_tmpl_errors_t\fR argument is invalid.
621 .RE
623 .sp
624 .LP
625 The \fBscf_tmpl_error_type()\fR, \fBscf_tmpl_error_source_fmri()\fR,
626 \fBscf_tmpl_error_pg_tmpl()\fR, \fBscf_tmpl_error_pg()\fR,
627 \fBscf_tmpl_error_prop_tmpl()\fR, \fBscf_tmpl_error_prop()\fR, and
628 \fBscf_tmpl_error_value()\fR functions will fail if:
629 .sp
630 .ne 2
631 .na
632 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
633 .ad
634 .RS 23n
635 The data requested is not available for the \fBscf_tmpl_error_t\fR argument
636 supplied.
637 .RE
639 .SH ATTRIBUTES
640 .sp
641 .LP
642 See \fBattributes\fR(5) for descriptions of the following attributes:
643 .sp
645 .sp
646 .TS
647 box;
648 c | c
649 l | l .
650 ATTRIBUTE TYPE ATTRIBUTE VALUE
651 _
652 Interface Stability Committed
653 _
654 MT-Level Safe
655 .TE
657 .SH SEE ALSO
658 .sp
659 .LP
660 \fBsvc.configd\fR(1M), \fBscf_tmpl_value_in_constraint\fR(3SCF),
661 \fBattributes\fR(5), \fBsmf_template\fR(5)