share/man/man3picltree/libpicltree.3picltree

   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
  78 the node, the handle of the accessed property and the credentials of the
  79 caller. The second argument is a pointer to the  buffer where the value is to
  80 be copied.
  81 .sp
  82 .in +2
  83 .nf
  84 typedef struct {
  85          picl_nodehdl_t nodeh;
  86          picl_prophdl_t proph;
  87          door_cred_t    cred;
  88 } ptree_rarg_t;
  89 .fi
  90 .in -2
  91
  92 .sp
  93 .LP
  94 The prototype of the read access function for volatile property is:
  95 .sp
  96 .in +2
  97 .nf
  98 int read(ptree_rarg_t *rarg, void *buf);
  99 .fi
 100 .in -2
 101
 102 .sp
 103 .LP
 104 The read function returns \fBPICL_SUCCESS\fR to indicate successful completion.
 105 .sp
 106 .LP
 107 Similarly, when a write access is performed on a volatile property, the daemon
 108 invokes the write access function provided by the plug-in for that property and
 109 passes it two arguments. The first argument is a pointer to \fBptree_warg_t\fR,
 110 which contains the handle to the node, the handle of the accessed property and
 111 the credentials of the caller. The second argument is a pointer to the buffer
 112 containing the value to be written.
 113 .sp
 114 .in +2
 115 .nf
 116 typedef struct {
 117         picl_nodehdl_t  nodeh;
 118         picl_prophdl_t  proph;
 119         door_cred_t     cred;
 120 } ptree_warg_t;
 121 .fi
 122 .in -2
 123
 124 .sp
 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)