scf_tmpl_error_value(3scf)

1scf_tmpl_validatSee_rfvmircie(3CSoCnFf)iguration Facility Librasrcyf_Ftumnpclt_ivoanlsidate_fmri(3SCF)
2
3
4

NAME

6       scf_tmpl_validate_fmri,  scf_tmpl_errors_destroy,  scf_tmpl_next_error,
7       scf_tmpl_reset_errors,     scf_tmpl_strerror,      scf_tmpl_error_type,
8       scf_tmpl_error_source_fmri,  scf_tmpl_error_pg_tmpl, scf_tmpl_error_pg,
9       scf_tmpl_error_prop_tmpl, scf_tmpl_error_prop,  scf_tmpl_error_value  -
10       template validation functions
11

SYNOPSIS

13       cc [ flag... ] file... -lscf [ library... ]
14       #include <libscf.h>
15
16       int scf_tmpl_validate_fmri(scf_handle_t *h, const char *fmri,
17            const char *snapshot, scf_tmpl_errors_t **errs, int flags);
18
19
20       void scf_tmpl_errors_destroy(scf_tmpl_errors_t *errs);
21
22
23       scf_tmpl_error_t *scf_tmpl_next_error(scf_tmpl_errors_t *errs,
24            scf_tmpl_errors_t *err)
25
26
27       void scf_tmpl_reset_errors(scf_tmpl_errors_t *errs);
28
29
30       int scf_tmpl_strerror(scf_tmpl_error_t *err, char *s,
31            size_t n, int flags);
32
33
34       int scf_tmpl_error_type(const scf_tmpl_error_t *err,
35            scf_tmpl_error_type_t *type);
36
37
38       int scf_tmpl_error_source_fmri(const scf_tmpl_error_t *err,
39            char *fmri);
40
41
42       int scf_tmpl_error_pg_tmpl(const scf_tmpl_error_t *err, char *name,
43            char *type);
44
45
46       int scf_tmpl_error_pg(const scf_tmpl_error_t *err,
47            char **name, char **type);
48
49
50       int scf_tmpl_error_prop_tmpl(const scf_tmpl_error_t *err, char **name,
51            char **type);
52
53
54       int scf_tmpl_error_prop(const scf_tmpl_error_t *err, char **name,
55            char **type,);
56
57
58       int scf_tmpl_error_value(const scf_tmpl_error_t *err, char**val);
59
60

DESCRIPTION

62       The  template validation functions offer a way to validate the configu‐
63       ration data of an service instance  against  the  appropriate  template
64       data.  The  scf_tmpl_validate_fmri()  function  returns the full set of
65       errors for the specified instance, and those errors can be  printed  or
66       explored directly.
67
68
69       By  default,  the validation is performed on the composed data from the
70       running snapshot of an instance. A different snapshot can be explicitly
71       selected  by  specifying a valid snapshot name rather than NULL for the
72       snapshot argument. If  flags  includes  SCF_TMPL_VALIDATE_FLAG_CURRENT,
73       the snapshot argument is ignored and the current configuration is used.
74
75
76       By  default,  these functions also explore template data defined by the
77       service or instance itself, the service's restarter,  and  global  tem‐
78       plate  data. See smf_template(5) for more information about this compo‐
79       sition.
80
81
82       An instance FMRI is required, and FMRIs  that  specify  other  entities
83       (for example, services) are explicitly rejected.
84
85
86       The   scf_tmpl_validate_fmri()  function  validates  an  instance  FMRI
87       against the template data in the repository. As described  above,  when
88       the snapshot argument is NULL, the default running snapshot is used. If
89       scf_tmpl_errors_t **  is  non-null,  the  structure  is  allocated  and
90       returned to the caller for further perusal or printing of the errors.
91
92
93       The   scf_tmpl_errors_destroy()   function   destroys   and  frees  the
94       scf_tmpl_errors_t and all of the scf_tmpl_error_t structures  to  which
95       it refers.
96
97
98       The    scf_tmpl_next_error()    function   takes   a   pointer   to   a
99       scf_tmpl_errors_t  structure  previously  returned  by   scf_tmpl_vali‐
100       date_fmri().  On  the  first  call,  it  returns a pointer to the first
101       scf_tmpl_error_t found during validation. On subsequent calls, the next
102       error is returned. To resume processing from the first error, the call‐
103       er can use scf_tmpl_reset_errors().
104
105
106       The contents of an scf_tmpl_error_t are determined by its  type.  Types
107       added  as  additional  validation  checks  are introduced. Based on the
108       error type, a set of fields can be retrieved from the error.
109
110       SCF_TERR_TYPE_INVALID
111
112           reserved invalid type
113
114
115       SCF_TERR_MISSING_PG
116
117           required property group is missing
118             template source FMRI
119             property group template name and type
120
121
122       SCF_TERR_WRONG_PG_TYPE
123
124           property group type is incorrect
125             template source FMRI
126             property group template name and type
127             property group name and type
128
129
130       SCF_TERR_MISSING_PROP
131
132           required property is missing
133             template source FMRI
134             property group template name and type
135             property template name and type
136
137
138       SCF_TERR_WRONG_PROP_TYPE
139
140           property type is incorrect
141             template source FMRI
142             property group template name and type
143             property template name and type
144             property group name and type
145             property name and type
146
147
148       SCF_TERR_CARDINALITY_VIOLATION
149
150           number of values violates cardinality
151             template source FMRI
152             property group template name and type
153             property template name and type
154             property group name and type
155             property name and type
156             cardinality and cardinality limits
157
158
159       SCF_TERR_VALUE_CONSTRAINT_VIOLATED
160
161           constraint violated for value
162             template source FMRI
163             property group template name and type
164             property template name and type
165             property group name and type
166             property name and type
167             value
168
169
170       SCF_TERR_RANGE_VIOLATION
171
172           value violated specified range
173             template source FMRI
174             property group template name and type
175             property template name and type
176             property group name and type
177             property name and type
178             value
179
180
181       SCF_TERR_PROP_TYPE_MISMATCH
182
183           value type is different from property type
184             template source FMRI
185             property group template name and type
186             property template name and type
187
188
189       SCF_TERR_VALUE_OUT_OF_RANGE
190
191           value is out of template defined range
192             template source FMRI
193             property group template name and type
194             property template name and type
195             value
196
197
198       SCF_TERR_INVALID_VALUE
199
200           value violates template defined constraints
201             template source FMRI
202             property group template name and type
203             property template name and type
204             value
205
206
207
208       The   SCF_TERR_PROP_TYPE_MISMATCH,   SCF_TERR_VALUE_OUT_OF_RANGE    and
209       SCF_TERR_INVALID_VALUE    types    are   only   set   from   calls   to
210       scf_tmpl_value_in_constraint(3SCF).
211
212
213       The scf_tmpl_error_type() function retrieves the error type.
214
215
216       The scf_tmpl_error_source_fmri() function retrieves a string  with  the
217       FMRI  of  the  source of the template that was violated. This string is
218       freed by scf_tmpl_errors_destroy().
219
220
221       The scf_tmpl_error_pg_tmpl() function retrieves strings with  the  name
222       and type of the property group template that was violated. If the prop‐
223       erty group name or type was implicitly wildcarded (see smf_template(5))
224       in   the   template,   this   function   returns  a  string  containing
225       SCF_TMPL_WILDCARD    ("*").    These    strings    are     freed     by
226       scf_tmpl_errors_destroy().
227
228
229       The  scf_tmpl_error_pg()  function  retrieves strings with the name and
230       type of the property group that was violated. These strings  are  freed
231       by scf_tmpl_errors_destroy().
232
233
234       The scf_tmpl_error_prop_tmpl() function retrieves strings with the name
235       and type of the property template that was violated.  If  the  property
236       type  was  implicitly wildcarded (see smf_template(5)) in the template,
237       this function returns  a  string  containing  SCF_TMPL_WILDCARD  ("*").
238       These strings are freed by scf_tmpl_errors_destroy().
239
240
241       The  scf_tmpl_error_prop() function retrieves strings with the name and
242       type of the property that was violated.  These  strings  are  freed  by
243       scf_tmpl_errors_destroy().
244
245
246       The  scf_tmpl_error_value()  function retrieves a string with the value
247       containing   the   error   in   val.   This   string   are   freed   by
248       scf_tmpl_errors_destroy().
249
250
251       The  scf_tmpl_strerror()  function takes an scf_tmpl_error_t previously
252       returned by scf_tmpl_next_error() and returns in s. If  flags  includes
253       SCF_TMPL_STRERROR_HUMAN,  s  is a human-readable, localized description
254       of the error. Otherwise, s is a one-line string  suitable  for  logfile
255       output.
256

RETURN VALUES

258       The  scf_tmpl_validate_fmri()  function returns 0 on successful comple‐
259       tion with no validation failures. It returns 1 if there are  validation
260       failures. It returns -1 if there is an error validating the instance.
261
262
263       The  scf_tmpl_next_error()  function  returns  a  pointer  to  the next
264       scf_tmpl_error_t. When none remain, it returns NULL.
265
266
267       The        scf_tmpl_error_type(),         scf_tmpl_error_source_fmri(),
268       scf_tmpl_error_pg_tmpl(),                          scf_tmpl_error_pg(),
269       scf_tmpl_error_prop_tmpl(),         scf_tmpl_error_prop(),          and
270       scf_tmpl_error_value() functions return 0 on success and -1 on failure.
271
272
273       The scf_tmpl_strerror() function returns the number of bytes that would
274       have been written to s if n had been sufficiently large.
275

ERRORS

277       The scf_tmpl_validate_fmri() function will fail if:
278
279       SCF_ERROR_BACKEND_ACCESS
280
281           The storage mechanism that the repository server  (svc.configd(1M))
282           chose for the operation denied access.
283
284
285       SCF_ERROR_CONNECTION_BROKEN
286
287           The connection to the repository was lost.
288
289
290       SCF_ERROR_DELETED
291
292           The  instance  or  one  of  its  template  property group have been
293           deleted.
294
295
296       SCF_ERROR_HANDLE_DESTROYED
297
298           The handle passed in has been destroyed.
299
300
301       SCF_ERROR_INTERNAL
302
303           An internal error occurred.
304
305
306       SCF_ERROR_INVALID_ARGUMENT
307
308           The handle argument, FMRI argument, or snapshot name is invalid
309
310
311       SCF_ERROR_NO_MEMORY
312
313           There is not enough memory to validate the instance.
314
315
316       SCF_ERROR_NO_RESOURCES
317
318           The server  does  not  have  adequate  resources  to  complete  the
319           request.
320
321
322       SCF_ERROR_NOT_BOUND
323
324           The handle is not currently bound.
325
326
327       SCF_ERROR_NOT_FOUND
328
329           An  object  matching  FMRI does not exist in the repository, or the
330           snapshot does not exist.
331
332
333       SCF_ERROR_PERMISSION_DENIED
334
335           The instance or template could not be read due to  access  restric‐
336           tions.
337
338
339       SCF_ERROR_TEMPLATE_INVALID
340
341           The template data is invalid.
342
343
344
345       The             scf_tmpl_strerror(),             scf_tmpl_error_type(),
346       scf_tmpl_error_source_fmri(),                 scf_tmpl_error_pg_tmpl(),
347       scf_tmpl_error_pg(), scf_tmpl_error_prop_tmpl(), scf_tmpl_error_prop(),
348       and scf_tmpl_error_value() functions will fail if:
349
350       SCF_ERROR_INVALID_ARGUMENT    The   scf_tmpl_errors_t    argument    is
351                                     invalid.
352
353
354
355       The         scf_tmpl_error_type(),        scf_tmpl_error_source_fmri(),
356       scf_tmpl_error_pg_tmpl(),                          scf_tmpl_error_pg(),
357       scf_tmpl_error_prop_tmpl(),          scf_tmpl_error_prop(),         and
358       scf_tmpl_error_value() functions will fail if:
359
360       SCF_ERROR_NOT_FOUND    The data requested  is  not  available  for  the
361                              scf_tmpl_error_t argument supplied.
362
363

ATTRIBUTES

365       See attributes(5) for descriptions of the following attributes:
366
367
368
369
370       ┌─────────────────────────────┬─────────────────────────────┐
371       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
372       ├─────────────────────────────┼─────────────────────────────┤
373       │Interface Stability          │Committed                    │
374       ├─────────────────────────────┼─────────────────────────────┤
375       │MT-Level                     │Safe                         │
376       └─────────────────────────────┴─────────────────────────────┘
377

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO