1scf_handle_decodSee_rfvmircie(3CSoCnFf)iguration Facility Librasrcyf_Fhuanncdtlieo_ndsecode_fmri(3SCF)
2
3
4

NAME

6       scf_handle_decode_fmri,     scf_scope_to_fmri,     scf_service_to_fmri,
7       scf_instance_to_fmri, scf_pg_to_fmri,  scf_property_to_fmri  -  convert
8       between objects and FMRIs in the Service Configuration Facility
9

SYNOPSIS

11       cc [ flag... ] file... -lscf [ library... ]
12       #include <libscf.h>
13
14       int scf_handle_decode_fmri(scf_handle_t *handle, const char *fmri,
15            scf_scope_t *scope, scf_service_t *service,
16            scf_instance_t *instance, scf_propertygroup_t *pg,
17            scf_property_t *property, int flag);
18
19
20       ssize_t scf_scope_to_fmri(const scf_scope_t *object,
21            char *buffer, size_t sz);
22
23
24       ssize_t scf_service_to_fmri(const scf_scope_t *object,
25            char *buffer, size_t sz);
26
27
28       ssize_t scf_instance_to_fmri(const scf_instance_t *inst,
29            char *buffer, size_t sz);
30
31
32       ssize_t scf_pg_to_fmri(const scf_propertygroup_t *pg, char *out,
33            size_t sz);
34
35
36       ssize_t scf_property_to_fmri(const scf_scope_t *object,
37            char *buffer, size_t sz);
38
39

DESCRIPTION

41       The scf_handle_decode_fmri() function decodes an FMRI string into a set
42       of repository entries. Any number of the entity handles  can  be  NULL.
43       The  validation  and  decoding  of the FMRI are determined by the flags
44       argument and by those arguments that are NULL.
45
46
47       If flags == 0, any FMRI is accepted as long as it  is  well-formed  and
48       exists in the repository.
49
50
51       If  SCF_DECODE_FMRI_EXACT  is  set  in flags, the last part of the FMRI
52       must match the last non-null entity handle. For example, if property is
53       NULL and pg is non-null, the FMRI must be a property group FMRI.
54
55
56       If  SCF_DECODE_FMRI_TRUNCATE is set in flags, there is no check for the
57       existence of any objects specified in the FMRI  that  follow  the  last
58       non-null  entity  handle.  For example, if property is NULL, pg is non-
59       null, and a property FMRI is passed in,  scf_handle_decode_fmri()  suc‐
60       ceeds  as  long  as  the  property group exists, even if the referenced
61       property does not exist.
62
63
64       If SCF_DECODE_FMRI_REQUIRE_INSTANCE  (or  SCF_FMRI_REQUIRE_NO_INSTANCE)
65       is set in flags, then the FMRI must (or must not) specify an instance.
66
67
68       If  an  error occurs, all of the entity handles that were passed to the
69       function are reset.
70
71
72       The scf_scope_to_fmri(), scf_service_to_fmri(), scf_instance_to_fmri(),
73       scf_pg_to_fmri(),   and  scf_property_to_fmri()  functions  convert  an
74       entity handle to an FMRI.
75

RETURN VALUES

77       Upon successful completion, scf_handle_decode_fmri() returns 0.  Other‐
78       wise, it returns -1.
79
80
81       Upon successful completion, scf_scope_to_fmri(), scf_service_to_fmri(),
82       scf_instance_to_fmri(),  scf_pg_to_fmri(),  and  scf_property_to_fmri()
83       return the length of the FMRI. The buffer will be null-terminated if sz
84       > 0, similar to  strlcpy(3C). Otherwise, they return -1  and  the  con‐
85       tents of buffer are undefined.
86

ERRORS

88       The scf_handle_decode_fmri() function will fail if:
89
90       SCF_ERROR_BACKEND_ACCESS
91
92           The   storage   mechanism   that  the   repository server (svc.con‐
93           figd(1M)) chose for the operation denied access.
94
95
96       SCF_ERROR_CONNECTION_BROKEN
97
98           The connection to the repository was lost.
99
100
101       SCF_ERROR_CONSTRAINT_VIOLATED
102
103           The FMRI does not meet the restrictions requested in the flag argu‐
104           ment.
105
106
107       SCF_ERROR_DELETED
108
109           The object argument refers to an object that has been deleted.
110
111
112       SCF_ERROR_HANDLE_MISMATCH
113
114           One or more of the entity handles was not derived from handle.
115
116
117       SCF_ERROR_INTERNAL
118
119           An internal error occurred.
120
121
122       SCF_ERROR_INVALID_ARGUMENT
123
124           The fmri argument is not a valid FMRI.
125
126
127       SCF_ERROR_NO_RESOURCES
128
129           The  server  does  not  have  adequate  resources  to  complete the
130           request.
131
132
133       SCF_ERROR_NOT_BOUND
134
135           The handle is not currently bound.
136
137
138       SCF_ERROR_NOT_FOUND
139
140           The FMRI is well-formed but there is no object  in  the  repository
141           matching it.
142
143
144       SCF_ERROR_NOT_SET
145
146           Cannot use unset value.
147
148
149
150       The scf_scope_to_fmri(), scf_service_to_fmri(), scf_instance_to_fmri(),
151       scf_pg_to_fmri(), and scf_property_to_fmri() functions will fail if:
152
153       SCF_ERROR_NOT_SET
154
155           The object argument is not currently set.
156
157
158       SCF_ERROR_DELETED
159
160           The object argument refers to an object that has been deleted.
161
162
163       SCF_ERROR_NOT_BOUND
164
165           The handle is not currently bound.
166
167
168       SCF_ERROR_CONNECTION_BROKEN
169
170           The connection to the repository was lost.
171
172
173
174       The scf_error(3SCF) function can be used to retrieve the error value.
175

ATTRIBUTES

177       See attributes(5) for descriptions of the following attributes:
178
179
180
181
182       ┌─────────────────────────────┬─────────────────────────────┐
183       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
184       ├─────────────────────────────┼─────────────────────────────┤
185       │Interface Stability          │Committed                    │
186       ├─────────────────────────────┼─────────────────────────────┤
187       │MT-Level                     │Safe                         │
188       └─────────────────────────────┴─────────────────────────────┘
189

SEE ALSO

191       libscf(3LIB), scf_error(3SCF), attributes(5)
192
193
194
195SunOS 5.11                        4 Jun 2009      scf_handle_decode_fmri(3SCF)
Impressum