usr/src/man/man3picl/libpicl.3picl

   1 '\" te
   2 .\" Copyright (c) 2000, 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 LIBPICL 3PICL "Mar 28, 2000"
   7 .SH NAME
   8 libpicl \- PICL interface library
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR \|.\|.\|. ] \fIfile\fR \|.\|.\|. \fB-lpicl\fR [ \fIlibrary\fR \|.\|.\|. ]
  13 #include <picl.h>
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The PICL interface is the platform-independent interface for clients to access
  20 the platform information. The set of functions and data structures of this
  21 interface are defined in the <\fBpicl.h\fR> header.
  22 .sp
  23 .LP
  24 The information published through PICL is organized in a tree, where each node
  25 is an instance of a well-defined PICL class. The functions in the PICL
  26 interface allow the clients to access the properties of the nodes.
  27 .sp
  28 .LP
  29 The name of the base PICL class is \fBpicl\fR, which defines a basic set of
  30 properties that all nodes in the tree must possess. The following table shows
  31 the property set of a \fBpicl\fR class node.
  32 .sp
  33
  34 .sp
  35 .TS
  36 box;
  37 c | c
  38 l | l .
  39 Property Name   Property Value
  40 _
  41 \fBname\fR      The name of the node
  42 _
  43 \fB_class\fR    The PICL class name of the node
  44 _
  45 \fB_parent\fR   Node handle of the parent node
  46 _
  47 \fB_child\fR    Node handle of the first child node
  48 _
  49 \fB_peer\fR     Node handle of the next peer node
  50 .TE
  51
  52 .sp
  53 .LP
  54 Property names with a a leading underscore ('_') are reserved for use by the
  55 PICL framework. The property names \fB_class\fR, \fB_parent\fR, \fB_child\fR,
  56 and \fB_peer\fR are reserved names of the PICL framework, and are used to refer
  57 to a node's parent, child, and peer nodes, respectively.  A client shall access
  58 a reserved property by their names only as they do not have an associated
  59 handle. The property \fBname\fR is not a reserved property, but a mandatory
  60 property for all nodes.
  61 .sp
  62 .LP
  63 Properties are classified into different types. Properties of type integer,
  64 unsigned-integer, and float have integer, unsigned integer, and floating-point
  65 values, respectively. A \fBtable\fR property type has the handle to a table as
  66 its value. A table is a matrix of properties. A \fBreference\fR property type
  67 has a handle to a node in the tree as its value. A \fBreference\fR property may
  68 be used to establish an association between any two nodes in the tree. A
  69 \fBtimestamp\fR property type has the value of time in seconds since Epoch. A
  70 \fBbytearray\fR property type has an array of bytes as its value. A
  71 \fBcharstring\fR property type has a nul ('\0') terminated sequence of ASCII
  72 characters. The size of a property specifies the size of its value in bytes. A
  73 \fBvoid\fR property type denotes a property that exists but has no value.
  74 .sp
  75 .LP
  76 The following table lists the different PICL property types enumerated in
  77 \fBpicl_prop_type_t\fR.
  78 .sp
  79
  80 .sp
  81 .TS
  82 box;
  83 c | c
  84 l | l .
  85 Property Type   Property Value
  86 _
  87 \fBPICL_PTYPE_VOID\fR   None
  88 _
  89 \fBPICL_PTYPE_INT\fR    Is an integer
  90 _
  91 \fBPICL_PTYPE_UNSIGNED_INT\fR   Is an unsigned integer
  92 _
  93 \fBPICL_PTYPE_FLOAT\fR  Is a floating-point number
  94 _
  95 \fBPICL_PTYPE_REFERENCE\fR      Is a PICL node handle
  96 .TE
  97
  98 .SS "Reference Property Naming Convention"
  99 .sp
 100 .LP
 101 Reference properties may be used by plug-ins to publish properties in nodes of
 102 different classes. To make these property names unique, their names must be
 103 prefixed by _\fIpicl_class_name\fR_, where \fIpicl_class_name\fR is the class
 104 name of the node referenced by the property. Valid PICL class names are
 105 combinations of uppercase and lowercase letters 'a' through 'z', digits '0'
 106 through '9', and '-' (minus) characters.  The string that follows
 107 the '_\fIpicl_class_name\fR_' portion of a reference property name may be used to
 108 indicate a specific property in the referenced class, when applicable.
 109 .SS "Property Information"
 110 .sp
 111 .LP
 112 The information about a node's property that can be accessed by PICL clients is
 113 defined by the \fBpicl_propinfo_t\fR structure.
 114 .sp
 115 .in +2
 116 .nf
 117 typedef struct {
 118     picl_prop_type_t  type;           /* property type */
 119     unsigned int      accessmode;     /* read, write */
 120     size_t            size;           /* item size or
 121                                          string size */
 122     char              name[PICL_PROPNAMELEN_MAX];
 123 } picl_propinfo_t;
 124 .fi
 125 .in -2
 126
 127 .sp
 128 .LP
 129 The \fBtype\fR member specifies the property value type and the
 130 \fBaccessmode\fR specifies the allowable access to the property. The plug-in
 131 module that adds the property to the PICL tree also sets the access mode of
 132 that property. The volatile nature of a property created by the plug-in is not
 133 visible to the PICL clients. The \fBsize\fR member specifies the number of
 134 bytes occupied by the property's value. The maximum allowable size of property
 135 value is \fBPICL_PROPSIZE_MAX\fR, which is set to 512KB.
 136 .SS "Property Access Modes"
 137 .sp
 138 .LP
 139 The plug-in module may publish a property granting a combination of the
 140 following access modes to the clients:
 141 .sp
 142 .in +2
 143 .nf
 144 #define   PICL_READ   0x1   /* read permission */
 145 #define   PICL_WRITE  0x2   /* write permission */
 146 .fi
 147 .in -2
 148
 149 .SS "Property Names"
 150 .sp
 151 .LP
 152 The maximum length of the name of any property is specified by
 153 \fBPICL_PROPNAMELEN_MAX\fR.
 154 .SS "Class Names"
 155 .sp
 156 .LP
 157 The maximum length of a PICL class name is specified by
 158 \fBPICL_CLASSNAMELEN_MAX\fR.
 159 .SH ATTRIBUTES
 160 .sp
 161 .LP
 162 See \fBattributes\fR(5)  for descriptions of the following attributes:
 163 .sp
 164
 165 .sp
 166 .TS
 167 box;
 168 c | c
 169 l | l .
 170 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 171 _
 172 MT-Level        MT-Safe
 173 .TE
 174
 175 .SH SEE ALSO
 176 .sp
 177 .LP
 178 \fBlibpicl\fR(3LIB), \fBattributes\fR(5)