1 '\" te
2 .\" Copyright (c) 2004, 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 LIBPICLTREE 3PICLTREE "Mar 1, 2004"
7 .SH NAME
8 libpicltree \- PTree and Plug-in Registration interface library
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcc\fR [\fIflag \&.\|.\|.\fR] \fIfile \fR\&.\|.\|. \fB-lpicltree\fR [\fIlibrary \&.\|.\|.\fR]
13 #include <picltree.h>
14 .fi
15
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The PTree interface is the set of functions and data structures to access and
20 manipulate the PICL tree. The daemon and the plug-in modules use the PTree
21 interface.
22 .sp
23 .LP
24 The Plug-in Registration interface is used by the plug-in modules to register
25 themselves with the daemon.
26 .sp
27 .LP
28 The plug-in modules create the nodes and properties of the tree. At the time of
29 creating a property, the plug-ins specify the property information in the
30 \fBptree_propinfo_t\fR structure defined as:
31 .sp
32 .in +2
33 .nf
34 typedef struct {
35 int version; /* version */
36 picl_propinfo_t piclinfo; /* info to clients */
37 int (*read)(ptree_rarg_t *arg, void *buf);
38 /* read access function for */
39 /* volatile prop */
40 int (*write)(ptree_warg_t *arg, const void *buf);
41 /* write access function for */
42 /* volatile prop */
43 } ptree_propinfo_t;
44 .fi
45 .in -2
46
47 .sp
48 .LP
49 See \fBlibpicl\fR(3PICL) for more information on PICL tree nodes and
50 properties.
51 .sp
52 .LP
53 The maximum size of a property value cannot exceed \fBPICL_PROPSIZE_MAX\fR. It
54 is currently set to 512KB.
55 .SS "Volatile Properties"
56 .sp
57 .LP
58 In addition to \fBPICL_READ\fR and \fBPICL_WRITE\fR property access modes, the
59 plug-in modules specify whether a property is volatile or not by setting the
60 bit \fBPICL_VOLATILE\fR.
61 .sp
62 .in +2
63 .nf
64 #define PICL_VOLATILE 0x4
65 .fi
66 .in -2
67
68 .sp
69 .LP
70 For a volatile property, the plug-in module provides the access functions to
71 read and/or write the property in the \fBptree_propinfo_t\fR argument passed
72 when creating the property.
73 .sp
74 .LP
75 The daemon invokes the access functions of volatile properties when clients
76 access their values. Two arguments are passed to the read access functions. The
77 first argument is a pointer to \fBptree_rarg_t\fR, which contains the handle of
125 .LP
126 The prototype of the write access function for volatile property is:
127 .sp
128 .in +2
129 .nf
130 int write(ptree_warg_t *warg, const void *buf);
131 .fi
132 .in -2
133
134 .sp
135 .LP
136 The write function returns \fBPICL_SUCCESS\fR to indicate successful
137 completion.
138 .sp
139 .LP
140 For all volatile properties, the 'size' of the property must be specified to be
141 the maximum possible size of the value. The maximum size of the value cannot
142 exceed \fBPICL_PROPSIZE_MAX\fR. This allows a client to allocate a sufficiently
143 large buffer before retrieving a volatile property's value
144 .SS "Plug-in Modules"
145 .sp
146 .LP
147 Plug-in modules are shared objects that are located in well-known directories
148 for the daemon to locate and load them. Plug-in module's are located in the one
149 of the following plug-in directories depending on the plaform-specific nature
150 of the data they collect and publish.
151 .sp
152 .in +2
153 .nf
154 /usr/platform/picl/plugins/`uname -i`/
155 /usr/platform/picl/plugins/`uname -m`/
156 /usr/lib/picl/plugins/
157 .fi
158 .in -2
159
160 .sp
161 .LP
162 A plug-in module may specify its dependency on another plug-in module using the
163 \fB-l\fR linker option. The plug-ins are loaded by the PICL daemon using
164 \fBdlopen\fR(3C) according to the specified dependencies. Each plug-in module
165 must define a \fB\&.init\fR section, which is executed when the plug-in module
166 is loaded, to register themselves with the daemon. See
167 \fBpicld_plugin_register\fR(3PICLTREE) for more information on plug-in
168 registration.
169 .sp
170 .LP
171 The plug-in modules may use the \fBpicld_log\fR(3PICLTREE) function to log
172 their messages to the system log file.
173 .SH ATTRIBUTES
174 .sp
175 .LP
176 See \fBattributes\fR(5) for descriptions of the following attributes:
177 .sp
178
179 .sp
180 .TS
181 box;
182 c | c
183 l | l .
184 ATTRIBUTE TYPE ATTRIBUTE VALUE
185 _
186 MT-Level MT-Safe
187 .TE
188
189 .SH SEE ALSO
190 .sp
191 .LP
192 \fBlibpicl\fR(3PICL), \fBlibpicltree\fR(3LIB), \fBpicld_log\fR(3PICLTREE),
193 \fBpicld_plugin_register\fR(3PICLTREE), \fBattributes\fR(5)
|
1 '\" te
2 .\" Copyright (c) 2004, 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 LIBPICLTREE 3PICLTREE "May 16, 2020"
7 .SH NAME
8 libpicltree \- PTree and Plug-in Registration interface library
9 .SH SYNOPSIS
10 .nf
11 \fBcc\fR [\fIflag \&.\|.\|.\fR] \fIfile \fR\&.\|.\|. \fB-lpicltree\fR [\fIlibrary \&.\|.\|.\fR]
12 #include <picltree.h>
13 .fi
14
15 .SH DESCRIPTION
16 The PTree interface is the set of functions and data structures to access and
17 manipulate the PICL tree. The daemon and the plug-in modules use the PTree
18 interface.
19 .sp
20 .LP
21 The Plug-in Registration interface is used by the plug-in modules to register
22 themselves with the daemon.
23 .sp
24 .LP
25 The plug-in modules create the nodes and properties of the tree. At the time of
26 creating a property, the plug-ins specify the property information in the
27 \fBptree_propinfo_t\fR structure defined as:
28 .sp
29 .in +2
30 .nf
31 typedef struct {
32 int version; /* version */
33 picl_propinfo_t piclinfo; /* info to clients */
34 int (*read)(ptree_rarg_t *arg, void *buf);
35 /* read access function for */
36 /* volatile prop */
37 int (*write)(ptree_warg_t *arg, const void *buf);
38 /* write access function for */
39 /* volatile prop */
40 } ptree_propinfo_t;
41 .fi
42 .in -2
43
44 .sp
45 .LP
46 See \fBlibpicl\fR(3PICL) for more information on PICL tree nodes and
47 properties.
48 .sp
49 .LP
50 The maximum size of a property value cannot exceed \fBPICL_PROPSIZE_MAX\fR. It
51 is currently set to 512KB.
52 .SS "Volatile Properties"
53 In addition to \fBPICL_READ\fR and \fBPICL_WRITE\fR property access modes, the
54 plug-in modules specify whether a property is volatile or not by setting the
55 bit \fBPICL_VOLATILE\fR.
56 .sp
57 .in +2
58 .nf
59 #define PICL_VOLATILE 0x4
60 .fi
61 .in -2
62
63 .sp
64 .LP
65 For a volatile property, the plug-in module provides the access functions to
66 read and/or write the property in the \fBptree_propinfo_t\fR argument passed
67 when creating the property.
68 .sp
69 .LP
70 The daemon invokes the access functions of volatile properties when clients
71 access their values. Two arguments are passed to the read access functions. The
72 first argument is a pointer to \fBptree_rarg_t\fR, which contains the handle of
120 .LP
121 The prototype of the write access function for volatile property is:
122 .sp
123 .in +2
124 .nf
125 int write(ptree_warg_t *warg, const void *buf);
126 .fi
127 .in -2
128
129 .sp
130 .LP
131 The write function returns \fBPICL_SUCCESS\fR to indicate successful
132 completion.
133 .sp
134 .LP
135 For all volatile properties, the 'size' of the property must be specified to be
136 the maximum possible size of the value. The maximum size of the value cannot
137 exceed \fBPICL_PROPSIZE_MAX\fR. This allows a client to allocate a sufficiently
138 large buffer before retrieving a volatile property's value
139 .SS "Plug-in Modules"
140 Plug-in modules are shared objects that are located in well-known directories
141 for the daemon to locate and load them. Plug-in modules are located in the one
142 of the following plug-in directories depending on the platform-specific nature
143 of the data they collect and publish.
144 .sp
145 .in +2
146 .nf
147 /usr/platform/picl/plugins/`uname -i`/
148 /usr/platform/picl/plugins/`uname -m`/
149 /usr/lib/picl/plugins/
150 .fi
151 .in -2
152
153 .sp
154 .LP
155 A plug-in module may specify its dependency on another plug-in module using the
156 \fB-l\fR linker option. The plug-ins are loaded by the PICL daemon using
157 \fBdlopen\fR(3C) according to the specified dependencies. Each plug-in module
158 must define a \fB\&.init\fR section, which is executed when the plug-in module
159 is loaded, to register themselves with the daemon. See
160 \fBpicld_plugin_register\fR(3PICLTREE) for more information on plug-in
161 registration.
162 .sp
163 .LP
164 The plug-in modules may use the \fBpicld_log\fR(3PICLTREE) function to log
165 their messages to the system log file.
166 .SH ATTRIBUTES
167 See \fBattributes\fR(5) for descriptions of the following attributes:
168 .sp
169
170 .sp
171 .TS
172 box;
173 c | c
174 l | l .
175 ATTRIBUTE TYPE ATTRIBUTE VALUE
176 _
177 MT-Level MT-Safe
178 .TE
179
180 .SH SEE ALSO
181 \fBlibpicl\fR(3PICL), \fBlibpicltree\fR(3LIB), \fBpicld_log\fR(3PICLTREE),
182 \fBpicld_plugin_register\fR(3PICLTREE), \fBattributes\fR(5)
|