1scf_instance_creSaetrev(i3cSeCFC)onfiguration Facility LibrarysFcufn_citnisotnasnce_create(3SCF)
2
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
13 cc [ flag... ] file... -lscf [ library... ]
14 #include <libscf.h>
15 scf_instance_t *scf_instance_create(scf_handle_t *handle);
17 scf_handle_t *scf_instance_handle(scf_instance_t *inst);
20 void scf_instance_destroy(scf_instance_t *inst);
23 int scf_instance_get_parent(const scf_instance_t *inst,
26 scf_service_t *svc);
27 ssize_t scf_instance_get_name(const scf_instance_t *inst,
30 char *name, size_t size);
31 int scf_service_get_instance(const scf_service_t *svc,
34 const char *name, scf_instance_t *inst);
35 int scf_service_add_instance(const scf_service_t *svc,
38 const char *name, scf_instance_t *inst);
39 int scf_instance_delete(scf_instance_t *inst);
42
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 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 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 See smf(5) for information about instances.
63 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 The scf_instance_handle() function retrieves the handle to which inst
72 is bound.
73 The scf_inst_get_parent() function sets svc to the service that is the
76 parent of inst.
77 The scf_instance_get_name() function retrieves the name of the instance
80 to which inst is set.
81 The scf_service_get_instance() function sets inst to the child instance
84 of the service svc specified by name.
85 The scf_service_add_instance() function sets inst to a new child
88 instance of the service svc specified by name.
89 The scf_instance_delete() function deletes the instance to which inst
92 is set, as well all of the children of the instance.
93
95 Upon successful completion, scf_instance_create() returns a new
96 scf_instance_t. Otherwise it returns NULL.
97 Upon successful completion, scf_instance_handle() returns the handle to
100 which inst is bound. Otherwise, it returns NULL.
101 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 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
113 The scf_instance_create() function will fail if:
114 SCF_ERROR_HANDLE_DESTROYED
116 An object was bound to a destroyed handle.
118 SCF_ERROR_INTERNAL
121 An internal error occurred.
123 SCF_ERROR_INVALID_ARGUMENT
126 The handle argument is NULL.
128 SCF_ERROR_NO_MEMORY
131 There is not enough memory to allocate an scf_instance_t.
133 SCF_ERROR_NO_RESOURCES
136 The server does not have adequate resources for a new instance han‐
138 dle.
139 The scf_instance_handle() function will fail if:
143 SCF_ERROR_HANDLE_DESTROYED
145 The handle associated with inst has been destroyed.
147 The scf_instance_get_name(), scf_instance_get_parent(), and
151 scf_instance_delete() functions will fail if:
152 SCF_ERROR_DELETED
154 The instance has been deleted.
156 SCF_ERROR_NOT_SET
159 The instance is not set.
161 SCF_ERROR_NOT_BOUND
164 The repository handle is not bound.
166 SCF_ERROR_CONNECTION_BROKEN
169 The connection to the repository was lost.
171 The scf_service_add_instance() function will fail if:
175 SCF_ERROR_EXISTS
177 An instance named name already exists.
179 SCF_ERROR_INTERNAL
182 An internal error occurred.
184 SCF_ERROR_NO_RESOURCES
187 The server does not have the resources to complete the request.
189 SCF_ERROR_NOT_BOUND
192 The handle is not bound.
194 The scf_service_get_instance() function will fail if:
198 SCF_ERROR_BACKEND_ACCESS The storage mechanism that the repos‐
200 itory server (svc.configd(1M)) chose for
201 the operation denied access.
202 SCF_ERROR_INTERNAL An internal error occurred.
205 SCF_ERROR_NOT_BOUND The handle is not bound.
208 SCF_ERROR_NOT_FOUND No instance specified by name was found.
211 SCF_ERROR_NO_RESOURCES The repository server is out of resources.
214 The scf_service_add_instance() and scf_service_get_instance() functions
218 will fail if:
219 SCF_ERROR_NOT_SET
221 The service is not set.
223 SCF_ERROR_DELETED
226 The service has been deleted.
228 SCF_ERROR_INVALID_ARGUMENT
231 The name argument is not a valid instance name.
233 SCF_ERROR_HANDLE_MISMATCH
236 The service and instance are not derived from the same handle.
238 SCF_ERROR_CONNECTION_BROKEN
241 The connection to the repository was lost.
243 The scf_instance_get_parent() function will fail if:
247 SCF_ERROR_HANDLE_MISMATCH
249 The service and instance arguments are not derived from the same
251 handle.
252 The scf_service_add_instance() and scf_instance_delete() functions will
256 fail if:
257 SCF_ERROR_PERMISSION_DENIED
259 The user does not have sufficient privileges to create or delete an
261 instance.
262 SCF_ERROR_BACKEND_READONLY
265 The repository backend is read-only.
267 SCF_ERROR_BACKEND_ACCESS
270 The repository backend refused the modification.
272 The scf_instance_delete() function will fail if:
276 SCF_ERROR_NO_RESOURCES The server does not have adequate resources
278 for a new instance handle.
279
282 See attributes(5) for descriptions of the following attributes:
283 ┌─────────────────────────────┬─────────────────────────────┐
288 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
289 ├─────────────────────────────┼─────────────────────────────┤
290 │Interface Stability │Committed │
291 ├─────────────────────────────┼─────────────────────────────┤
292 │MT-Level │Safe │
293 └─────────────────────────────┴─────────────────────────────┘
294
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
301 Instance names are of the form:
302 [domain,]identifier
304 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.
312SunOS 5.11 24 Sep 2007 scf_instance_create(3SCF)