libpicltree(3picltree)

1libpicltree(3PICLTREE)  PICL Plug-In Library Functions  libpicltree(3PICLTREE)
2
3
4

NAME

6       libpicltree - PTree and Plug-in Registration interface library
7

SYNOPSIS

9       cc [flag ...] file ... -lpicltree [library ...]
10       #include <picltree.h>
11
12

DESCRIPTION

14       The  PTree  interface  is  the  set of functions and data structures to
15       access and manipulate the PICL tree. The daemon and the plug-in modules
16       use the PTree interface.
17
18
19       The  Plug-in  Registration  interface is used by the plug-in modules to
20       register themselves with the daemon.
21
22
23       The plug-in modules create the nodes and properties of the tree. At the
24       time of creating a property, the plug-ins specify the property informa‐
25       tion in the ptree_propinfo_t structure defined as:
26
27         typedef struct {
28             int             version;    /* version */
29             picl_propinfo_t piclinfo;   /* info to clients */
30             int             (*read)(ptree_rarg_t *arg, void *buf);
31                                         /* read access function for */
32                                         /* volatile prop */
33             int             (*write)(ptree_warg_t *arg, const void *buf);
34                                         /* write access function for */
35                                         /* volatile prop */
36         } ptree_propinfo_t;
37
38
39
40       See libpicl(3PICL) for more information on PICL tree nodes and  proper‐
41       ties.
42
43
44       The  maximum  size of a property value cannot exceed PICL_PROPSIZE_MAX.
45       It is currently set to 512KB.
46
47   Volatile Properties
48       In addition to PICL_READ and  PICL_WRITE  property  access  modes,  the
49       plug-in  modules  specify whether a property is volatile or not by set‐
50       ting the bit PICL_VOLATILE.
51
52         #define   PICL_VOLATILE   0x4
53
54
55
56       For a volatile property, the plug-in module provides the  access  func‐
57       tions  to  read and/or write the property in the ptree_propinfo_t argu‐
58       ment passed when creating the property.
59
60
61       The daemon invokes the access functions  of  volatile  properties  when
62       clients  access  their  values.  Two  arguments  are passed to the read
63       access functions. The first argument  is  a  pointer  to  ptree_rarg_t,
64       which contains the handle of the node, the handle of the accessed prop‐
65       erty and the credentials of  the  caller.  The  second  argument  is  a
66       pointer to the  buffer where the value is to be copied.
67
68         typedef struct {
69                  picl_nodehdl_t nodeh;
70                  picl_prophdl_t proph;
71                  door_cred_t    cred;
72         } ptree_rarg_t;
73
74
75
76       The prototype of the read access function for volatile property is:
77
78         int read(ptree_rarg_t *rarg, void *buf);
79
80
81
82       The  read  function returns PICL_SUCCESS to indicate successful comple‐
83       tion.
84
85
86       Similarly, when a write access is performed on a volatile property, the
87       daemon  invokes  the  write access function provided by the plug-in for
88       that property and passes it two arguments.  The  first  argument  is  a
89       pointer  to  ptree_warg_t,  which  contains the handle to the node, the
90       handle of the accessed property and the credentials of the caller.  The
91       second  argument  is a pointer to the buffer containing the value to be
92       written.
93
94         typedef struct {
95                 picl_nodehdl_t  nodeh;
96                 picl_prophdl_t  proph;
97                 door_cred_t     cred;
98         } ptree_warg_t;
99
100
101
102       The prototype of the write access function for volatile property is:
103
104         int write(ptree_warg_t *warg, const void *buf);
105
106
107
108       The write function returns PICL_SUCCESS to indicate successful  comple‐
109       tion.
110
111
112       For  all volatile properties, the 'size' of the property must be speci‐
113       fied to be the maximum possible size of the value. The maximum size  of
114       the  value  cannot  exceed  PICL_PROPSIZE_MAX.  This allows a client to
115       allocate a sufficiently large buffer before retrieving a volatile prop‐
116       erty's value
117
118   Plug-in Modules
119       Plug-in  modules  are  shared  objects  that  are located in well-known
120       directories for the daemon to locate and load  them.  Plug-in  module's
121       are  located  in the one of the following plug-in directories depending
122       on the plaform-specific nature of the data they collect and publish.
123
124         /usr/platform/picl/plugins/`uname -i`/
125         /usr/platform/picl/plugins/`uname -m`/
126         /usr/lib/picl/plugins/
127
128
129
130       A plug-in module may specify its dependency on another  plug-in  module
131       using  the -l linker option. The plug-ins are loaded by the PICL daemon
132       using dlopen(3C) according to the specified dependencies. Each  plug-in
133       module  must define a .init section, which is executed when the plug-in
134       module  is  loaded,  to  register  themselves  with  the  daemon.   See
135       picld_plugin_register(3PICLTREE) for more information on plug-in regis‐
136       tration.
137
138
139       The plug-in modules may use the picld_log(3PICLTREE)  function  to  log
140       their messages to the system log file.
141

ATTRIBUTES

143       See attributes(5) for descriptions of the following attributes:
144
145
146
147
148       ┌─────────────────────────────┬─────────────────────────────┐
149       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
150       ├─────────────────────────────┼─────────────────────────────┤
151       │MT-Level                     │MT-Safe                      │
152       └─────────────────────────────┴─────────────────────────────┘
153

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

SEE ALSO