scf_handle_decorate(3scf)

1scf_handle_creatSee(r3vSiCcFe)Configuration Facility Library Fusnccft_ihoannsdle_create(3SCF)
2
3
4

NAME

6       scf_handle_create,  scf_handle_destroy,  scf_handle_decorate,  scf_han‐
7       dle_bind, scf_handle_unbind, scf_myname - Service Configuration  Facil‐
8       ity handle functions
9

SYNOPSIS

11       cc [ flag... ] file... -lscf [ library... ]
12       #include <libscf.h>
13
14       scf_handle_t *scf_handle_create(scf_version_t version);
15
16
17       void scf_handle_destroy(scf_handle_t *handle);
18
19
20       int scf_handle_decorate(scf_handle_t *handle, const char *param,
21            scf_value_t *value);
22
23
24       int scf_handle_bind(scf_handle_t *handle);
25
26
27       int scf_handle_unbind(scf_handle_t *handle);
28
29
30       ssize_t scf_myname(scf_handle_t *handle, char *out, size_t sz);
31
32

DESCRIPTION

34       The  scf_handle_create()  function  creates a new Service Configuration
35       Facility handle that is used as the base for all communication with the
36       configuration repository. The version argument must be SCF_VERSION.
37
38
39       The  scf_handle_decorate()  function  sets  a  single  connection-level
40       parameter,  param,  to  the  supplied  value.  If  value  is  SCF_DECO‐
41       RATE_CLEAR,  param  is  reset  to  its  default state. Values passed to
42       scf_handle_decorate() can be reset, reused, or  destroyed.  The  values
43       set  do  not take effect until scf_handle_bind() is called. Any invalid
44       values will not cause errors prior to the  call  to  scf_handle_bind().
45       The only available decorations is:
46
47       debug    (count) Set the debugging flags.
48
49
50
51       The  scf_handle_bind()  function binds the handle to a running svc.con‐
52       figd(1M) daemon, using the current decorations to  modify  the  connec‐
53       tion.  All states derived from the handle are reset immediately after a
54       successful binding.
55
56
57       The scf_handle_unbind() function severs an existing repository  connec‐
58       tion or clears the in-client state for a broken connection.
59
60
61       The  scf_handle_destroy() function destroys and frees an SCF handle. It
62       is illegal  to  use  the  handle  after  calling  scf_handle_destroy().
63       Actions on subordinate objects act as if the handle is unbound.
64
65
66       The  scf_myname()  function retrieves the FMRI for the service of which
67       the connecting process is a part. If the full FMRI does not fit in  the
68       provided buffer, it is truncated and, if sz > 0, zero-terminated.
69

RETURN VALUES

71       Upon successful completion, scf_handle_create() returns the new handle.
72       Otherwise, it returns NULL.
73
74
75       Upon successful completion,  scf_handle_decorate(),  scf_handle_bind(),
76       and scf_handle_unbind() return 0. Otherwise, they return -1.
77
78
79       The  scf_myname()  function returns the length of the full FMRI. Other‐
80       wise, it returns -1.
81

ERRORS

83       The scf_handle_create() function will fail if:
84
85       SCF_ERROR_NO_MEMORY           There is no memory available.
86
87
88       SCF_ERROR_VERSION_MISMATCH    The version is invalid, or  the  applica‐
89                                     tion  was  compiled  against a version of
90                                     the library that is more recent than  the
91                                     one on the system.
92
93
94
95       The scf_handle_decorate() function will fail if:
96
97       SCF_ERROR_INVALID_ARGUMENT    The  param  argument  is not a recognized
98                                     parameter.
99
100
101       SCF_ERROR_TYPE_MISMATCH       The value argument  does  not  match  the
102                                     expected type for param.
103
104
105       SCF_ERROR_NOT_SET             The value argument is not set.
106
107
108       SCF_ERROR_IN_USE              The handle is currently bound.
109
110
111       SCF_ERROR_HANDLE_MISMATCH     The  value  argument  is not derived from
112                                     handle.
113
114
115
116       The scf_handle_bind() function will fail if:
117
118       SCF_ERROR_INVALID_ARGUMENT    One of the decorations was invalid.
119
120
121       SCF_ERROR_NO_SERVER           The repository server is not running.
122
123
124       SCF_ERROR_NO_RESOURCES        The  server  does   not   have   adequate
125                                     resources for a new connection.
126
127
128       SCF_ERROR_IN_USE              The handle is already bound.
129
130
131
132       The scf_handle_unbind() function will fail if:
133
134       SCF_ERROR_NOT_BOUND    The handle is not bound.
135
136
137
138       The scf_handle_myname() function will fail if:
139
140       SCF_ERROR_CONNECTION_BROKEN
141
142           The connection to the repository was lost.
143
144
145       SCF_ERROR_NOT_BOUND
146
147           The handle is not bound.
148
149
150       SCF_ERROR_NOT_SET
151
152           This process is not marked as a SMF service.
153
154
155
156       The scf_error(3SCF) function can be used to retrieve the error value.
157

ATTRIBUTES

159       See attributes(5) for descriptions of the following attributes:
160
161
162
163
164       ┌─────────────────────────────┬─────────────────────────────┐
165       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
166       ├─────────────────────────────┼─────────────────────────────┤
167       │Interface Stability          │Committed                    │
168       ├─────────────────────────────┼─────────────────────────────┤
169       │MT-Level                     │See below.                   │
170       └─────────────────────────────┴─────────────────────────────┘
171
172
173       Operations  on a single handle (and the objects associated with it) are
174       Safe.  Operations on different handles are MT-Safe. Objects  associated
175       with  different  handles  cannot  be  mixed,  as  this  will lead to an
176       SCF_ERROR_HANDLE_MISMATCH error.
177

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

ERRORS

ATTRIBUTES

SEE ALSO