Tribblix: manual page: libpicl.3picl

LIBPICL(3PICL) PICL Library Functions LIBPICL(3PICL)

NAME

libpicl - PICL interface library

SYNOPSIS

cc [ flag ... ] file ... -lpicl [ library ... ]
#include <picl.h>

DESCRIPTION

The PICL interface is the platform-independent interface for clients
to access the platform information. The set of functions and data
structures of this interface are defined in the <picl.h> header.

The information published through PICL is organized in a tree, where
each node is an instance of a well-defined PICL class. The functions
in the PICL interface allow the clients to access the properties of
the nodes.

The name of the base PICL class is picl, which defines a basic set of
properties that all nodes in the tree must possess. The following
table shows the property set of a picl class node.

+--------------+-------------------------------------+
|Property Name | Property Value |
+--------------+-------------------------------------+
|name | The name of the node |
+--------------+-------------------------------------+
|_class | The PICL class name of the node |
+--------------+-------------------------------------+
|_parent | Node handle of the parent node |
+--------------+-------------------------------------+
|_child | Node handle of the first child node |
+--------------+-------------------------------------+
|_peer | Node handle of the next peer node |
+--------------+-------------------------------------+

Property names with a a leading underscore ('_') are reserved for use
by the PICL framework. The property names _class, _parent, _child,
and _peer are reserved names of the PICL framework, and are used to
refer to a node's parent, child, and peer nodes, respectively. A
client shall access a reserved property by their names only as they
do not have an associated handle. The property name is not a reserved
property, but a mandatory property for all nodes.

Properties are classified into different types. Properties of type
integer, unsigned-integer, and float have integer, unsigned integer,
and floating-point values, respectively. A table property type has
the handle to a table as its value. A table is a matrix of
properties. A reference property type has a handle to a node in the
tree as its value. A reference property may be used to establish an
association between any two nodes in the tree. A timestamp property
type has the value of time in seconds since Epoch. A bytearray
property type has an array of bytes as its value. A charstring
property type has a nul ('\0') terminated sequence of ASCII
characters. The size of a property specifies the size of its value in
bytes. A void property type denotes a property that exists but has no
value.

The following table lists the different PICL property types
enumerated in picl_prop_type_t.

+------------------------+----------------------------+
| Property Type | Property Value |
+------------------------+----------------------------+
|PICL_PTYPE_VOID | None |
+------------------------+----------------------------+
|PICL_PTYPE_INT | Is an integer |
+------------------------+----------------------------+
|PICL_PTYPE_UNSIGNED_INT | Is an unsigned integer |
+------------------------+----------------------------+
|PICL_PTYPE_FLOAT | Is a floating-point number |
+------------------------+----------------------------+
|PICL_PTYPE_REFERENCE | Is a PICL node handle |
+------------------------+----------------------------+

Reference Property Naming Convention

Reference properties may be used by plug-ins to publish properties in
nodes of different classes. To make these property names unique,
their names must be prefixed by _picl_class_name_, where
picl_class_name is the class name of the node referenced by the
property. Valid PICL class names are combinations of uppercase and
lowercase letters 'a' through 'z', digits '0' through '9', and '-'
(minus) characters. The string that follows the '_picl_class_name_'
portion of a reference property name may be used to indicate a
specific property in the referenced class, when applicable.

Property Information

The information about a node's property that can be accessed by PICL
clients is defined by the picl_propinfo_t structure.

typedef struct {
picl_prop_type_t type; /* property type */
unsigned int accessmode; /* read, write */
size_t size; /* item size or
string size */
char name[PICL_PROPNAMELEN_MAX];
} picl_propinfo_t;

The type member specifies the property value type and the accessmode
specifies the allowable access to the property. The plug-in module
that adds the property to the PICL tree also sets the access mode of
that property. The volatile nature of a property created by the plug-
in is not visible to the PICL clients. The size member specifies the
number of bytes occupied by the property's value. The maximum
allowable size of property value is PICL_PROPSIZE_MAX, which is set
to 512KB.

Property Access Modes

The plug-in module may publish a property granting a combination of
the following access modes to the clients:

#define PICL_READ 0x1 /* read permission */
#define PICL_WRITE 0x2 /* write permission */

Property Names

The maximum length of the name of any property is specified by
PICL_PROPNAMELEN_MAX.

Class Names

The maximum length of a PICL class name is specified by
PICL_CLASSNAMELEN_MAX.

ATTRIBUTES