1scf_instance_creSaetrev(i3cSeCFC)onfiguration Facility LibrarysFcufn_citnisotnasnce_create(3SCF)
2
3
4

NAME

6       scf_instance_create,     scf_instance_handle,     scf_instance_destroy,
7       scf_instance_get_parent,        scf_instance_get_name,         scf_ser‐
8       vice_get_instance, scf_service_add_instance, scf_instance_delete - cre‐
9       ate and manipulate instance handles and instances in the  Service  Con‐
10       figuration Facility
11

SYNOPSIS

13       cc [ flag... ] file... -lscf [ library... ]
14       #include <libscf.h>
15
16       scf_instance_t *scf_instance_create(scf_handle_t *handle);
17
18
19       scf_handle_t *scf_instance_handle(scf_instance_t *inst);
20
21
22       void scf_instance_destroy(scf_instance_t *inst);
23
24
25       int scf_instance_get_parent(const scf_instance_t *inst,
26            scf_service_t *svc);
27
28
29       ssize_t scf_instance_get_name(const scf_instance_t *inst,
30            char *name, size_t size);
31
32
33       int scf_service_get_instance(const scf_service_t *svc,
34            const char *name, scf_instance_t *inst);
35
36
37       int scf_service_add_instance(const scf_service_t *svc,
38            const char *name, scf_instance_t *inst);
39
40
41       int scf_instance_delete(scf_instance_t *inst);
42
43

DESCRIPTION

45       Instances  form  the bottom layer of the Service Configuration Facility
46       repository tree. An instance is the child of a service and has two sets
47       of children:
48
49       Property Groups    These  hold  configuration  information  specific to
50                          this     instance.     See      scf_pg_create(3SCF),
51                          scf_iter_instance_pgs(3SCF),                     and
52                          scf_iter_instance_pgs_typed(3SCF).
53
54
55       Snapshots          These are complete configuration snapshots that hold
56                          unchanging copies of all of the property groups nec‐
57                          essary to run the  instance.  See  scf_snapshot_cre‐
58                          ate(3SCF) and scf_iter_instance_snapshots(3SCF).
59
60
61
62       See smf(5) for information about instances.
63
64
65       An  scf_instance_t  is  an  opaque  handle  that can be set to a single
66       instance at any given time. The  scf_instance_create()  function  allo‐
67       cates  and  initializes  a  new  scf_instance_t  bound  to  handle. The
68       scf_instance_destroy() function destroys and frees inst.
69
70
71       The scf_instance_handle() function retrieves the handle to  which  inst
72       is bound.
73
74
75       The  scf_inst_get_parent() function sets svc to the service that is the
76       parent of inst.
77
78
79       The scf_instance_get_name() function retrieves the name of the instance
80       to which inst is set.
81
82
83       The scf_service_get_instance() function sets inst to the child instance
84       of the service svc specified by name.
85
86
87       The scf_service_add_instance()  function  sets  inst  to  a  new  child
88       instance of the service svc specified by name.
89
90
91       The  scf_instance_delete()  function deletes the instance to which inst
92       is set, as well all of the children of the instance.
93

RETURN VALUES

95       Upon  successful  completion,  scf_instance_create()  returns   a   new
96       scf_instance_t. Otherwise it returns NULL.
97
98
99       Upon successful completion, scf_instance_handle() returns the handle to
100       which inst is bound. Otherwise, it returns NULL.
101
102
103       Upon successful completion, scf_instance_get_name() returns the  length
104       of  the  string  written, not including the terminating null character.
105       Otherwise it returns -1.
106
107
108       Upon   successful   completion,   scf_instance_get_parent(),   scf_ser‐
109       vice_get_instance(),           scf_service_add_instance(),          and
110       scf_instance_delete() functions return 0. Otherwise, they return -1.
111

ERRORS

113       The scf_instance_create() function will fail if:
114
115       SCF_ERROR_HANDLE_DESTROYED
116
117           An object was bound to a destroyed handle.
118
119
120       SCF_ERROR_INTERNAL
121
122           An internal error occurred.
123
124
125       SCF_ERROR_INVALID_ARGUMENT
126
127           The handle argument is NULL.
128
129
130       SCF_ERROR_NO_MEMORY
131
132           There is not enough memory to allocate an scf_instance_t.
133
134
135       SCF_ERROR_NO_RESOURCES
136
137           The server does not have adequate resources for a new instance han‐
138           dle.
139
140
141
142       The scf_instance_handle() function will fail if:
143
144       SCF_ERROR_HANDLE_DESTROYED
145
146           The handle associated with inst has been destroyed.
147
148
149
150       The     scf_instance_get_name(),     scf_instance_get_parent(),     and
151       scf_instance_delete() functions will fail if:
152
153       SCF_ERROR_DELETED
154
155           The instance has been deleted.
156
157
158       SCF_ERROR_NOT_SET
159
160           The instance is not set.
161
162
163       SCF_ERROR_NOT_BOUND
164
165           The repository handle is not bound.
166
167
168       SCF_ERROR_CONNECTION_BROKEN
169
170           The connection to the repository was lost.
171
172
173
174       The scf_service_add_instance() function will fail if:
175
176       SCF_ERROR_EXISTS
177
178           An instance named name already exists.
179
180
181       SCF_ERROR_INTERNAL
182
183           An internal error occurred.
184
185
186       SCF_ERROR_NO_RESOURCES
187
188           The server does not have the resources to complete the request.
189
190
191       SCF_ERROR_NOT_BOUND
192
193           The handle is not bound.
194
195
196
197       The scf_service_get_instance() function will fail if:
198
199       SCF_ERROR_BACKEND_ACCESS    The  storage  mechanism  that  the   repos‐
200                                   itory  server  (svc.configd(1M))  chose for
201                                   the operation denied access.
202
203
204       SCF_ERROR_INTERNAL          An internal error occurred.
205
206
207       SCF_ERROR_NOT_BOUND         The handle is not bound.
208
209
210       SCF_ERROR_NOT_FOUND         No instance specified by name was found.
211
212
213       SCF_ERROR_NO_RESOURCES      The repository server is out of resources.
214
215
216
217       The scf_service_add_instance() and scf_service_get_instance() functions
218       will fail if:
219
220       SCF_ERROR_NOT_SET
221
222           The service is not set.
223
224
225       SCF_ERROR_DELETED
226
227           The service has been deleted.
228
229
230       SCF_ERROR_INVALID_ARGUMENT
231
232           The name argument is not a valid instance name.
233
234
235       SCF_ERROR_HANDLE_MISMATCH
236
237           The service and instance are not derived from the same handle.
238
239
240       SCF_ERROR_CONNECTION_BROKEN
241
242           The connection to the repository was lost.
243
244
245
246       The scf_instance_get_parent() function will fail if:
247
248       SCF_ERROR_HANDLE_MISMATCH
249
250           The  service  and  instance arguments are not derived from the same
251           handle.
252
253
254
255       The scf_service_add_instance() and scf_instance_delete() functions will
256       fail if:
257
258       SCF_ERROR_PERMISSION_DENIED
259
260           The user does not have sufficient privileges to create or delete an
261           instance.
262
263
264       SCF_ERROR_BACKEND_READONLY
265
266           The repository backend is read-only.
267
268
269       SCF_ERROR_BACKEND_ACCESS
270
271           The repository backend refused the modification.
272
273
274
275       The scf_instance_delete() function will fail if:
276
277       SCF_ERROR_NO_RESOURCES    The server does not have  adequate  resources
278                                 for a new instance handle.
279
280

ATTRIBUTES

282       See attributes(5) for descriptions of the following attributes:
283
284
285
286
287       ┌─────────────────────────────┬─────────────────────────────┐
288       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
289       ├─────────────────────────────┼─────────────────────────────┤
290       │Interface Stability          │Committed                    │
291       ├─────────────────────────────┼─────────────────────────────┤
292       │MT-Level                     │Safe                         │
293       └─────────────────────────────┴─────────────────────────────┘
294

SEE ALSO

296       libscf(3LIB),       scf_error(3SCF),       scf_iter_instance_pgs(3SCF),
297       scf_iter_instance_pgs_typed(3SCF),   scf_iter_instance_snapshots(3SCF),
298       scf_pg_create(3SCF), scf_snapshot_create(3SCF), attributes(5), smf(5)
299

NOTES

301       Instance names are of the form:
302
303         [domain,]identifier
304
305
306
307
308       where  domain  is  either a stock ticker symbol such as SUNW or a Java-
309       style reversed domain name such as com.sun. Identifiers  begin  with  a
310       letter or underscore and contain only letters, digits, underscores, and
311       dashes.
312
313
314
315SunOS 5.11                        24 Sep 2007        scf_instance_create(3SCF)
Impressum