| blob | 9776694f760a227102e9f1a8103c5e1787f51c6f |
1 '\" te
2 .\" Copyright (c) 2007, 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_SERVICE_CREATE 3SCF "Aug 27, 2007"
7 .SH NAME
8 scf_service_create, scf_service_handle, scf_service_destroy,
9 scf_service_get_parent, scf_service_get_name, scf_scope_get_service,
10 scf_scope_add_service, scf_service_delete \- create and manipulate service
11 handles and services in the Service Configuration Facility
12 .SH SYNOPSIS
13 .LP
14 .nf
15 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
16 #include <libscf.h>
18 \fBscf_service_t *\fR\fBscf_service_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
19 .fi
21 .LP
22 .nf
23 \fBscf_handle_t *\fR\fBscf_service_handle\fR(\fBscf_service_t *\fR\fIsvc\fR);
24 .fi
26 .LP
27 .nf
28 \fBvoid\fR \fBscf_service_destroy\fR(\fBscf_service_t *\fR\fIsvc\fR);
29 .fi
31 .LP
32 .nf
33 \fBint\fR \fBscf_service_get_parent\fR(\fBscf_service_t *\fR\fIsvc\fR, \fBscf_scope_t *\fR\fIsc\fR);
34 .fi
36 .LP
37 .nf
38 \fBssize_t\fR \fBscf_service_get_name\fR(\fBconst scf_service_t *\fR\fIsvc\fR, \fBchar *\fR\fIbuf\fR,
39 \fBsize_t\fR \fIsize\fR);
40 .fi
42 .LP
43 .nf
44 \fBint\fR \fBscf_scope_get_service\fR(\fBconst scf_scope_t *\fR\fIsc\fR, \fBconst char *\fR\fIname\fR,
45 \fBscf_service_t *\fR\fIsvc\fR);
46 .fi
48 .LP
49 .nf
50 \fBint\fR \fBscf_scope_add_service\fR(\fBconst scf_scope_t *\fR\fIsc\fR, \fBconst char *\fR\fIname\fR,
51 \fBscf_service_t *\fR\fIsvc\fR);
52 .fi
54 .LP
55 .nf
56 \fBint\fR \fBscf_service_delete\fR(\fBscf_service_t *\fR\fIsvc\fR);
57 .fi
59 .SH DESCRIPTION
60 .sp
61 .LP
62 Services form the middle layer of the Service Configuration Facility repository
63 tree. Services are children of a scope (see \fBscf_scope_create\fR(3SCF)) and
64 have three sets of children:
65 .sp
66 .ne 2
67 .na
68 \fBProperty groups\fR
69 .ad
70 .RS 19n
71 These hold configuration information shared by all of the instances of the
72 service. See \fBscf_pg_create\fR(3SCF), \fBscf_iter_service_pgs\fR(3SCF), and
73 \fBscf_iter_service_pgs_typed\fR(3SCF).
74 .RE
76 .sp
77 .ne 2
78 .na
79 \fBInstances\fR
80 .ad
81 .RS 19n
82 A particular instantiation of the service. See \fBscf_instance_create\fR(3SCF).
83 .RE
85 .sp
86 .LP
87 A service groups one or more related instances and provides a shared
88 configuration for them.
89 .sp
90 .LP
91 An \fBscf_service_t\fR is an opaque handle that can be set to a single service
92 at any given time. The \fBscf_service_create()\fR function allocates and
93 initializes a new \fBscf_service_t\fR bound to \fIhandle\fR. The
94 \fBscf_service_destroy()\fR function destroys and frees svc.
95 .sp
96 .LP
97 The \fBscf_service_handle()\fR function retrieves the handle to which \fIsvc\fR
98 is bound.
99 .sp
100 .LP
101 The \fBscf_service_get_parent()\fR function sets \fIsc\fR to the scope that is
102 the parent of \fIsvc\fR.
103 .sp
104 .LP
105 The \fBscf_service_get_name()\fR function retrieves the name of the service to
106 which \fIsvc\fR is set.
107 .sp
108 .LP
109 The \fBscf_scope_get_service()\fR function sets \fIsvc\fR to the service
110 specified by \fIname\fR in the scope specified by \fIsc\fR.
111 .sp
112 .LP
113 The \fBscf_scope_add_service()\fR function sets \fIsvc\fR to a new service
114 specified by \fIname\fR in the scope specified by \fIsc\fR.
115 .sp
116 .LP
117 The \fBscf_service_delete()\fR function deletes the service to which \fIsvc\fR
118 is set, as well as all of its children.
119 .SH RETURN VALUES
120 .sp
121 .LP
122 Upon successful completion, \fBscf_service_create()\fR returns a new
123 \fBscf_service_t\fR. Otherwise, it returns \fINULL\fR.
124 .sp
125 .LP
126 Upon successful completion, \fBscf_service_handle()\fR returns the handle to
127 which svc is bound. Otherwise, it returns \fINULL\fR.
128 .sp
129 .LP
130 Upon successful completion, \fBscf_service_get_name()\fR returns the length of
131 the string written, not including the terminating null byte. Otherwise, it
132 returns -1.
133 .sp
134 .LP
135 Upon successful completion, \fBscf_service_get_parent()\fR,
136 \fBscf_scope_get_service()\fR, \fBscf_scope_add_service()\fR, and
137 \fBscf_service_delete()\fR return 0. Otherwise, it returns -1.
138 .SH ERRORS
139 .sp
140 .LP
141 The \fBscf_service_create()\fR function will fail if:
142 .sp
143 .ne 2
144 .na
145 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
146 .ad
147 .RS 30n
148 The value of the \fIhandle\fR argument is \fINULL\fR.
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
155 .ad
156 .RS 30n
157 There is not enough memory to allocate an \fBscf_service_t\fR.
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
164 .ad
165 .RS 30n
166 The server does not have adequate resources for a new scope handle.
167 .RE
169 .sp
170 .LP
171 The \fBscf_service_handle()\fR function will fail if:
172 .sp
173 .ne 2
174 .na
175 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
176 .ad
177 .RS 30n
178 The handle associated with \fIsvc\fR has been destroyed.
179 .RE
181 .sp
182 .LP
183 The \fBscf_service_get_name()\fR, \fBscf_service_get_parent()\fR, and
184 \fBscf_service_delete()\fR functions will fail if:
185 .sp
186 .ne 2
187 .na
188 \fB\fBSCF_ERROR_DELETED\fR\fR
189 .ad
190 .sp .6
191 .RS 4n
192 The service has been deleted by someone else.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fBSCF_ERROR_NOT_SET\fR\fR
199 .ad
200 .sp .6
201 .RS 4n
202 The service is not set.
203 .RE
205 .sp
206 .ne 2
207 .na
208 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
209 .ad
210 .sp .6
211 .RS 4n
212 The handle is not bound.
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
219 .ad
220 .sp .6
221 .RS 4n
222 The connection to the repository was lost.
223 .RE
225 .sp
226 .LP
227 The \fBscf_service_delete()\fR function will fail if:
228 .sp
229 .ne 2
230 .na
231 \fB\fBSCF_ERROR_EXISTS\fR\fR
232 .ad
233 .RS 26n
234 The service contains instances.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
241 .ad
242 .RS 26n
243 The server does not have adequate resources for a new scope handle.
244 .RE
246 .sp
247 .LP
248 The \fBscf_scope_add_service()\fR function will fail if:
249 .sp
250 .ne 2
251 .na
252 \fB\fBSCF_ERROR_EXISTS\fR\fR
253 .ad
254 .RS 20n
255 A {service,instance,property group} named \fIname\fR already exists.
256 .RE
258 .sp
259 .LP
260 The \fBscf_scope_get_service()\fR function will fail if:
261 .sp
262 .ne 2
263 .na
264 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
265 .ad
266 .RS 28n
267 The storage mechanism that the repository server (\fBsvc.configd\fR(1M))
268 chose for the operation denied access.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fBSCF_ERROR_INTERNAL\fR\fR
275 .ad
276 .RS 28n
277 An internal error occurred.
278 .RE
280 .sp
281 .LP
282 The \fBscf_scope_add_service()\fR and \fBscf_scope_get_service()\fR functions
283 will fail if:
284 .sp
285 .ne 2
286 .na
287 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
288 .ad
289 .sp .6
290 .RS 4n
291 The connection to the repository was lost.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fBSCF_ERROR_DELETED\fR\fR
298 .ad
299 .sp .6
300 .RS 4n
301 The parent entity has been deleted.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
308 .ad
309 .sp .6
310 .RS 4n
311 The scope and service are not derived from the same handle.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
318 .ad
319 .sp .6
320 .RS 4n
321 The value of the \fIname\fR argument is not a valid service name.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
328 .ad
329 .sp .6
330 .RS 4n
331 The server does not have the resources to complete the request.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
338 .ad
339 .sp .6
340 .RS 4n
341 The handle is not bound.
342 .RE
344 .sp
345 .ne 2
346 .na
347 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
348 .ad
349 .sp .6
350 .RS 4n
351 The service specified by \fIname\fR was not found.
352 .RE
354 .sp
355 .ne 2
356 .na
357 \fB\fBSCF_ERROR_NOT_SET\fR\fR
358 .ad
359 .sp .6
360 .RS 4n
361 The scope is not set.
362 .RE
364 .sp
365 .LP
366 The \fBscf_scope_add_service()\fR and \fBscf_service_delete()\fR functions will
367 fail if:
368 .sp
369 .ne 2
370 .na
371 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
372 .ad
373 .sp .6
374 .RS 4n
375 The user does not have sufficient privileges to create or delete a service.
376 .RE
378 .sp
379 .ne 2
380 .na
381 \fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
382 .ad
383 .sp .6
384 .RS 4n
385 The repository backend is read-only.
386 .RE
388 .sp
389 .ne 2
390 .na
391 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
392 .ad
393 .sp .6
394 .RS 4n
395 The repository backend refused the modification.
396 .RE
398 .sp
399 .LP
400 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
401 .SH ATTRIBUTES
402 .sp
403 .LP
404 See \fBattributes\fR(5) for descriptions of the following attributes:
405 .sp
407 .sp
408 .TS
409 box;
410 c | c
411 l | l .
412 ATTRIBUTE TYPE ATTRIBUTE VALUE
413 _
414 Interface Stability Committed
415 _
416 MT-Level Safe
417 .TE
419 .SH SEE ALSO
420 .sp
421 .LP
422 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_handle_decode_fmri\fR(3SCF),
423 \fBscf_iter_service_pgs\fR(3SCF), \fBscf_iter_service_pgs_typed\fR(3SCF),
424 \fBscf_instance_create\fR(3SCF), \fBscf_pg_create\fR(3SCF),
425 \fBscf_scope_create\fR(3SCF), \fBscf_service_to_fmri\fR(3SCF),
426 \fBattributes\fR(5), \fBsmf\fR(5)