scf_snaplevel_create(3scf)

1scf_snaplevel_crSeeartvei(c3eSCCFo)nfiguration Facility LibraryscFfu_nscntaipolnesvel_create(3SCF)
2
3
4

NAME

6       scf_snaplevel_create,    scf_snaplevel_handle,   scf_snaplevel_destroy,
7       scf_snaplevel_get_parent,                 scf_snaplevel_get_scope_name,
8       scf_snaplevel_get_service_name,        scf_snaplevel_get_instance_name,
9       scf_snapshot_get_base_snaplevel,   scf_snaplevel_get_next_snaplevel   -
10       create  and  manipulate  snaplevel handles in the Service Configuration
11       Facility
12

SYNOPSIS

14       cc [ flag... ] file... -lscf [ library... ]
15       #include <libscf.h>
16
17       scf_snaplevel_t *scf_snaplevel_create(scf_handle_t *handle);
18
19
20       scf_handle_t *scf_snaplevel_handle(scf_snaplevel_t *level);
21
22
23       void scf_snaplevel_destroy(scf_snaplevel_t *level);
24
25
26       int scf_snaplevel_get_parent(const scf_snaplevel_t *level,
27            const scf_snapshot_t *snap);
28
29
30       ssize_t scf_snaplevel_get_scope_name(const scf_snaplevel_t *level,
31            char *buf, size_t size);
32
33
34       ssize_t scf_snaplevel_get_service_name(const scf_snaplevel_t *level,
35            char *buf, size_t size);
36
37
38       ssize_t scf_snaplevel_get_instance_name(const scf_snaplevel_t *level,
39            char *buf, size_t size);
40
41
42       int scf_snapshot_get_base_snaplevel(const scf_snapshot_t *snap,
43            scf_snaplevel_t *level);
44
45
46       int scf_snaplevel_get_next_snaplevel(scf_snaplevel_t *in,
47            scf_snaplevel_t *out);
48
49

DESCRIPTION

51       A snaplevel holds all of the property groups associated with  either  a
52       service   or  an  instance.  Each  snapshot  has  an  ordered  list  of
53       snaplevels. Snaplevels contain the names of  the  instance  or  service
54       from which they are derived.
55
56
57       An  scf_snaplevel_t  is  an  opaque  handle that can be set to a single
58       snaplevel at any given time. When set, the scf_snaplevel_t inherits the
59       point in time from the scf_snapshot_t from which it comes.
60
61
62       The  scf_snaplevel_create()  function  allocates  and initializes a new
63       scf_snaplevel_t bound to handle. The  scf_snaplevel_destroy()  function
64       destroys and frees level.
65
66
67       The scf_snaplevel_handle() function retrieves the handle to which level
68       is bound.
69
70
71       The scf_snaplevel_get_parent() function sets snap to the  parent  snap‐
72       shot of the snaplevel to which level is set.  The snapshot specified by
73       snap is attached to the same point in time as level.
74
75
76       The  scf_snaplevel_get_scope_name(),  scf_snaplevel_get_service_name(),
77       and  scf_snaplevel_get_instance_name()  functions  retrieve the name of
78       the scope, service, and instance for the snapshot to which snap is set.
79       If  the  snaplevel  is  from  an  instance,  all  three succeed. If the
80       snaplevel is from a service, scf_snaplevel_get_instance_name() fails.
81
82
83       The scf_snapshot_get_base_snaplevel() function sets level to the  first
84       snaplevel    in    the   snapshot   to   which   snap   is   set.   The
85       scf_snaplevel_get_next_snaplevel()  function  sets  out  to  the   next
86       snaplevel  after  the snaplevel to which in is set. Both the in and out
87       arguments can point to the same scf_snaplevel_t.
88
89
90       To retrieve the  property  groups  associated  with  a  snaplevel,  see
91       scf_iter_snaplevel_pgs(3SCF),  scf_iter_snaplevel_pgs_typed(3SCF),  and
92       scf_snaplevel_get_pg(3SCF).
93

RETURN VALUES

95       Upon  successful  completion,  scf_snaplevel_create()  returns  a   new
96       scf_snaplevel_t. Otherwise, it returns NULL.
97
98
99       Upon     successful     completion,     scf_snaplevel_get_scope_name(),
100       scf_snaplevel_get_service_name(), and scf_snaplevel_get_instance_name()
101       return  the length of the string written, not including the terminating
102       null byte. Otherwise, they return -1.
103
104
105       Upon  successful  completion,   scf_snaplevel_get_parent(),   scf_snap‐
106       shot_get_base_snaplevel(),    and    scf_snaplevel_get_next_snaplevel()
107       return. Otherwise, they return -1.
108

ERRORS

110       The scf_snaplevel_create() function will fail if:
111
112       SCF_ERROR_INVALID_ARGUMENT    The handle argument is NULL.
113
114
115       SCF_ERROR_NO_MEMORY           There is not enough memory to allocate an
116                                     scf_snaplevel_t.
117
118
119       SCF_ERROR_NO_RESOURCES        The   server   does   not  have  adequate
120                                     resources for a new snapshot handle.
121
122
123
124       The  scf_snaplevel_get_scope_name(),  scf_snaplevel_get_service_name(),
125       scf_snaplevel_get_instance_name(), and scf_snaplevel_get_parent() func‐
126       tions will fail if:
127
128       SCF_ERROR_DELETED
129
130           The object referred to by level has been deleted.
131
132
133       SCF_ERROR_NOT_SET
134
135           The snaplevel is not set.
136
137
138       SCF_ERROR_NOT_BOUND
139
140           The handle is not bound.
141
142
143       SCF_ERROR_CONNECTION_BROKEN
144
145           The connection to the repository was lost.
146
147
148
149       The scf_snaplevel_get_instance_name() function will fail if:
150
151       SCF_ERROR_CONSTRAINT_VIOLATED
152
153           The snaplevel is derived from a service.
154
155
156
157       The scf_snapshot_get_base_snaplevel() function will fail if:
158
159       SCF_ERROR_CONNECTION_BROKEN
160
161           The connection to the repository was lost.
162
163
164       SCF_ERROR_DELETED
165
166           The snapshot has been deleted.
167
168
169       SCF_ERROR_HANDLE_MISMATCH
170
171           The snapshot and snaplevel are not derived from the same handle.
172
173
174       SCF_ERROR_NO_RESOURCES
175
176           The server does not have the resources to complete the request.
177
178
179       SCF_ERROR_NOT_BOUND
180
181           The handle is not bound.
182
183
184       SCF_ERROR_NOT_FOUND
185
186           There are no snaplevels in this snapshot.
187
188
189       SCF_ERROR_NOT_SET
190
191           The snapshot is not set.
192
193
194
195       The scf_snaplevel_get_next_snaplevel() function will fail if:
196
197       SCF_ERROR_DELETED
198
199           The snaplevel has been deleted.
200
201
202       SCF_ERROR_NOT_SET
203
204           The snaplevel is not set.
205
206
207       SCF_ERROR_HANDLE_MISMATCH
208
209           The in and out arguments are not derived from the same handle.
210
211
212       SCF_ERROR_NOT_BOUND
213
214           The handle is not bound.
215
216
217       SCF_ERROR_CONNECTION_BROKEN
218
219           The connection to the repository was lost.
220
221
222       SCF_ERROR_NOT_FOUND
223
224           There are no more snaplevels in this snapshot.
225
226
227
228       The scf_error(3SCF) function can be used to retrieve the error value.
229

ATTRIBUTES

231       See attributes(5) for descriptions of the following attributes:
232
233
234
235
236       ┌─────────────────────────────┬─────────────────────────────┐
237       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
238       ├─────────────────────────────┼─────────────────────────────┤
239       │Interface Stability          │Committed                    │
240       ├─────────────────────────────┼─────────────────────────────┤
241       │MT-Level                     │Safe                         │
242       └─────────────────────────────┴─────────────────────────────┘
243

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO