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 ta-
       ble 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 (' ') 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  allow-
       able 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

       See attributes(5)  for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       libpicl(3LIB), attributes(5)

SunOS 5.11							    28 Mar 2000 						    libpicl(3PICL)