alchemist.h -


SYNOPSIS

       #include <sys/types.h>

   Compounds
       struct adm_bb_cap_t

   Defines
       #define ALCHEMIST_ABI_MAJOR_VER   0
       #define ALCHEMIST_ABI_MINOR_VER   0
       #define ADM_EDEADNODE   1
       #define ADM_EBADTYPE   2
       #define ADM_EBADNAME   3
       #define ADM_EBADDATA   4
       #define ADM_ECONSTRAINT   5
       #define ADM_ENOINDEX   51
       #define ADM_ENONAME   52
       #define ADM_ENOPATH   53
       #define ADM_EACCESSFAILED   101
       #define ADM_ENONAMESPACE   102
       #define ADM_ENOSUBSPACE   103
       #define ADM_ENOWRITE   201
       #define ADM_ENOREAD   202
       #define ADM_ENOLISTSERIAL   203
       #define ADM_ENOREADSERIAL   204
       #define ADM_ENOCACHE   205
       #define ADM_ENOBOXTYPE   251
       #define ADM_EPARSE   301
       #define AdmRefStr_str(REFSTR)
       #define AdmContext_getIdentityRoot_b(CONTEXT, ERROR)
       #define AdmIdentity_getParentA_b(ID, ERROR)
       #define AdmIdentity_getParentB_b(ID, ERROR)
       #define AdmIdentity_getContext_b(ID, ERROR)
       #define AdmContext_getDataRoot_b(CONTEXT, ERROR)
       #define AdmData_getContainer_b(DATA, ERROR)
       #define AdmData_getPrev_b(DATA, WRAP, ERROR)
       #define AdmData_getNext_b(DATA, WRAP, ERROR)
       #define AdmData_getContext_b(DATA, ERROR)
       #define AdmContext_getDataByPath_b(CONTEXT, PATH, ERROR)
       #define AdmList_getDataByIndex_b(LIST, INDEX, ERROR)
       #define AdmList_getDataByName_b(LIST, NAME, ERROR)
       #define AdmList_getDataByPath_b(LIST, PATH, ERROR)
       #define AdmList_addData_b(LIST, TYPE, NAME, ERROR)
       #define AdmList_copyData_b(LIST, DATA, ERROR)
       #define ADM_BBCAP_SUP_WRITE(CAP)   ((CAP).array[0] & (1 <<
           0))
       #define ADM_BBCAP_SUP_READ(CAP)   ((CAP).array[0] & (1 <<
           1))
       #define ADM_BBCAP_SUP_LISTSERIAL(CAP)   ((CAP).array[0] &
           (1 << 2))
       #define ADM_BBCAP_SUP_READSERIAL(CAP)   ((CAP).array[0] &
           (1 << 3))

           4))
       #define AdmSwitchboard_getNspCfg_b(CTX, NAMESPACE, ERROR)
       #define AdmSwitchboard_getSubspCfg_b(CTX, SUBSPACE, ERROR)

   Typedefs
       typedef struct AdmError AdmError
       typedef struct AdmRefStr AdmRefStr
       typedef struct AdmData AdmData
       typedef struct AdmList AdmList
       typedef struct AdmInt AdmInt
       typedef struct AdmBool AdmBool
       typedef struct AdmFloat AdmFloat
       typedef struct AdmString AdmString
       typedef struct AdmString AdmBase64
       typedef struct AdmString AdmCopy
       typedef struct AdmIdentity AdmIdentity
       typedef struct AdmContext AdmContext
       typedef struct AdmBlackBox AdmBlackBox

   Enumerations
       enum AdmDataType { ADM_TYPE_UNKNOWN =  0, ADM_TYPE_LIST =
           1, ADM_TYPE_COPY =  2, ADM_TYPE_INT =  3,
           ADM_TYPE_FLOAT =  4, ADM_TYPE_BOOL =  5,
           ADM_TYPE_STRING =  6, ADM_TYPE_BASE64 =  7 }

   Functions
       void AdmError_create (AdmError **error, int num, const
           char *format,...)
           Allocate new AdmError structure.
       void AdmError_ref (AdmError *error)
           Increment the ref count of an AdmError structure.
       void AdmError_unref (AdmError *error)
           Decrement the ref count of an AdmError structure.
       const char* AdmError_strerr (AdmError *error)
           String description of error.
       int AdmError_errno (AdmError *error)
           Integer error code of error.
       AdmRefStr* AdmRefStr_ref (AdmRefStr *refstr)
       void AdmRefStr_unref (AdmRefStr *refstr)
       size_t AdmRefStr_len (AdmRefStr *refstr)
       AdmRefStr* AdmRefStr_get (const char *str, int force)
           Get an AdmRefStr.
       AdmRefStr* AdmRefStr_nget (const char *str, size_t len,
           int force)
           Get an AdmRefStr, by length.
       AdmContext* AdmContext_new (const char *name, unsigned int
           serial, AdmError **error)
           AdmContext constructor.
       AdmContext* AdmContext_ref (AdmContext *context, AdmError
           **error)
           AdmContext reference increment.
       void AdmContext_unref (AdmContext *context, AdmError
           **error)

       AdmContext* AdmContext_copy (AdmContext *context, AdmError
           **error)
           AdmContext copy operator.
       AdmContext* AdmContext_merge (const char *name, unsigned
           int serial, AdmContext *contextA, AdmContext
           *contextB, AdmError **error)
           AdmContext merge operator.
       void AdmContext_flatten (AdmContext *context, AdmError
           **error)
           AdmContext flatten operator.
       void AdmContext_strip (AdmContext *context, AdmError
           **error)
           AdmContext strip function.
       char* AdmContext_toXML (AdmContext *context, AdmError
           **error)
       AdmContext* AdmContext_fromXML (const char *xml, AdmError
           **error)
       int AdmContext_readFromFile (AdmContext **context, const
           char *path, AdmError **error)
       int AdmContext_writeToFile (AdmContext *context, const
           char *path, int mode, uid_t uid, gid_t gid, AdmError
           **error)
       AdmRefStr* AdmContext_getMask (AdmContext *context,
           unsigned int index, AdmError **error)
           AdmContext mask set accessor.
       int AdmContext_setMask (AdmContext *context, const char
           *path, AdmError **error)
           AdmContext mask set mutator.
       int AdmContext_clearMaskByIndex (AdmContext *context,
           unsigned int index, AdmError **error)
           AdmContext mask set element index remove.
       int AdmContext_clearMaskByPath (AdmContext *context, const
           char *path, AdmError **error)
           AdmContext mask set element data path remove.
       unsigned int AdmContext_getNumMasks (AdmContext *context,
           AdmError **error)
           AdmContext mask set length aggregator.
       AdmIdentity* AdmContext_getIdentityRoot (AdmContext
           *context, AdmError **error)
           AdmContext identity root accessor.
       AdmIdentity* AdmIdentity_getParentA (AdmIdentity
           *identity, AdmError **error)
           AdmIdentity parentA accessor.
       AdmIdentity* AdmIdentity_getParentB (AdmIdentity
           *identity, AdmError **error)
           AdmIdentity parentB accessor.
       AdmRefStr* AdmIdentity_getName (AdmIdentity *identity,
           AdmError **error)
           AdmIdentity name accessor.
       int AdmIdentity_setName (AdmIdentity *identity, const char
           *name, AdmError **error)
           AdmIdentity name mutator.
       unsigned int AdmIdentity_getSerial (AdmIdentity *identity,

           AdmIdentity serial number accessor.
       int AdmIdentity_setSerial (AdmIdentity *identity, unsigned
           int serial, AdmError **error)
           AdmIdentity serial number mutator.
       AdmIdentity* AdmIdentity_ref (AdmIdentity *identity,
           AdmError **error)
           AdmIdentity reference increment.
       void AdmIdentity_unref (AdmIdentity *identity, AdmError
           **error)
           AdmIdentity reference decrement.
       AdmContext* AdmIdentity_getContext (AdmIdentity *identity,
           AdmError **error)
           AdmIdentity context accessor.
       int AdmIdentity_isAlive (AdmIdentity *identity, AdmError
           **error)
           AdmIdentity reference check.
       AdmData* AdmContext_getDataRoot (AdmContext *context,
           AdmError **error)
           AdmContext data root accessor.
       AdmData* AdmData_getContainer (AdmData *data, AdmError
           **error)
           AdmData container accessor.
       AdmData* AdmData_getPrev (AdmData *data, int wrap,
           AdmError **error)
           get the previous sibling of an AdmData element.
       AdmData* AdmData_getNext (AdmData *data, int wrap,
           AdmError **error)
           get the next sibling of an AdmData element.
       AdmContext* AdmData_getContext (AdmData *data, AdmError
           **error)
           AdmData context accessor.
       AdmData* AdmContext_getDataByPath (AdmContext *context,
           const char *path, AdmError **error)
           AdmData path lookup.
       AdmDataType AdmData_getType (AdmData *data, AdmError
           **error)
           AdmData type accessor.
       AdmData* AdmData_ref (AdmData *data, AdmError **error)
           AdmData reference increment.
       void AdmData_unref (AdmData *data, AdmError **error)
           AdmData reference decrement.
       int AdmData_isAlive (AdmData *data, AdmError **error)
           AdmData reference check.
       int AdmData_unlink (AdmData *data, AdmError **error)
           AdmData unlink operator.
       int AdmData_validName (const char *name)
           Checks a string for name validity.
       AdmRefStr* AdmData_getName (AdmData *data, AdmError
           **error)
           AdmData name accessor.
       int AdmData_setName (AdmData *data, const char *name,
           AdmError **error)
           AdmData name mutator.

           **error)
           AdmData source accessor.
       int AdmData_setSource (AdmData *data, const char *source,
           AdmError **error)
           AdmData source mutator.
       int AdmData_isProtected (AdmData *data, AdmError **error)
           AdmData protected verification.
       int AdmData_setProtected (AdmData *data, int state,
           AdmError **error)
           AdmData protected mutator.
       int AdmList_isAnonymous (AdmList *list, AdmError **error)
           AdmList anonymous verification.
       int AdmList_setAnonymous (AdmList *list, int state,
           AdmError **error)
           AdmList anonymous mutator.
       int AdmList_isAtomic (AdmList *list, AdmError **error)
           AdmList atomic verification.
       int AdmList_setAtomic (AdmList *list, int state, AdmError
           **error)
           AdmList atomic mutator.
       int AdmList_isPrepend (AdmList *list, AdmError **error)
           AdmList prepend verification.
       int AdmList_setPrepend (AdmList *list, int state, AdmError
           **error)
           AdmList prepend mutator.
       unsigned int AdmList_getNumData (AdmList *list, AdmError
           **error)
           AdmList length aggregator.
       AdmData* AdmList_getDataByIndex (AdmList *list, unsigned
           int index, AdmError **error)
           AdmList child index accessor.
       AdmData* AdmList_getDataByName (AdmList *list, const char
           *name, AdmError **error)
           AdmList child name accessor.
       AdmData* AdmList_getDataByPath (AdmList *list, const char
           *path, AdmError **error)
           AdmList child data path accessor.
       AdmData* AdmList_addData (AdmList *list, AdmDataType type,
           const char *name, AdmError **error)
           AdmList add child operator.
       int AdmList_moveData (AdmList *list, AdmData *data,
           unsigned int index, AdmError **error)
           AdmList child move operator.
       int AdmList_reparentData (AdmList *list, AdmData *data,
           const char *name, unsigned int index, AdmError
           **error)
           AdmList child move operator.
       AdmData* AdmList_copyData (AdmList *list, AdmData *data,
           AdmError **error)
           AdmList copy data operator.
       unsigned int AdmData_getPos (AdmData *data, AdmError
           **error)
           AdmList child position operator.

           get an AdmInt's value.
       int AdmInt_setValue (AdmInt *int_scalar, int value,
           AdmError **error)
           set an AdmInt's value.
       double AdmFloat_getValue (AdmFloat *float_scalar, AdmError
           **error)
           get an AdmFloat's value.
       int AdmFloat_setValue (AdmFloat *float_scalar, double
           value, AdmError **error)
           set an AdmFloat's value.
       int AdmBool_getValue (AdmBool *bool_scalar, AdmError
           **error)
           get an AdmBool's value.
       int AdmBool_setValue (AdmBool *bool_scalar, int value,
           AdmError **error)
           set an AdmBool's value.
       AdmRefStr* AdmString_getValue (AdmString *string_scalar,
           AdmError **error)
           get an AdmString's value.
       int AdmString_setValue (AdmString *string_scalar, const
           char *value, AdmError **error)
       AdmRefStr* AdmBase64_getValue (AdmBase64 *base64_scalar,
           AdmError **error)
       int AdmBase64_setValue (AdmBase64 *base64_scalar, const
           char *value, AdmError **error)
           Set the value of an AdmBase64 element.
       size_t AdmBase64_getBinValue (AdmBase64 *base64_scalar,
           void **value, AdmError **error)
           Get the binary value of an AdmBase64 element.
       int AdmBase64_setBinValue (AdmBase64 *base64_scalar, const
           void *value, size_t size, AdmError **error)
           Set the value of an AdmBase64 element.
       AdmRefStr* AdmCopy_getValue (AdmCopy *copy_scalar,
           AdmError **error)
           Get the value of an AdmCopy element.
       int AdmCopy_setValue (AdmCopy *copy_scalar, const char
           *value, AdmError **error)
           Set the value of an AdmCopy element.
       AdmRefStr* AdmBlackBox_getCacheDir (AdmError **error)
       int AdmBlackBox_setCacheDir (const char *path, AdmError
           **error)
       AdmBlackBox* AdmBlackBox_getBox (AdmList *box_cfg,
           AdmError **error)
       adm_bb_cap_t AdmBlackBox_caps (AdmBlackBox *box, AdmError
           **error)
           AdmBlackBox capability querry.
       void AdmBlackBox_ref (AdmBlackBox *box, AdmError **error)
           AdmBlackbox reference increment.
       void AdmBlackBox_unref (AdmBlackBox *box, AdmError
           **error)
           AdmBlackbox reference decrement.
       AdmContext* AdmBlackBox_read (AdmBlackBox *box, AdmError
           **error)

       int AdmBlackBox_listSerial (AdmBlackBox *box, unsigned int
           *array, unsigned int array_len, unsigned int
           top_serial, AdmError **error)
           AdmBlackbox serial list request.
       AdmContext* AdmBlackBox_readSerial (AdmBlackBox *box,
           unsigned int serial, AdmError **error)
           AdmBlackbox serial list request.
       int AdmBlackBox_write (AdmBlackBox *box, AdmContext
           *context, AdmError **error)
           AdmBlackbox write operator.
       unsigned int AdmBlackBox_getMark (AdmBlackBox *box, const
           char *mark, AdmError **error)
           AdmBlackBox mark accessor.
       int AdmBlackBox_setMark (AdmBlackBox *box, const char
           *mark, AdmError **error)
           AdmBlackBox mark mutator.
       int AdmBlackBox_clearMark (AdmBlackBox *box, const char
           *mark, AdmError **error)
           AdmBlackbox mark destructor.
       AdmRefStr* AdmSwitchboard_getSwbDir (AdmError **error)
       int AdmSwitchboard_setSwbDir (const char *path, AdmError
           **error)
       int AdmSwitchboard_markNsp (const char *namespace, const
           char *subspace, const char *mark, AdmError **error)
       int AdmSwitchboard_markNspWithConfig (AdmList
           *namespace_cfg, const char *subspace, const char
           *mark, AdmError **error)
       int AdmSwitchboard_checkNspMark (const char *namespace,
           const char *subspace, const char *mark, AdmError
           **error)
       int AdmSwitchboard_checkNspMarkWithConfig (AdmList
           *namespace_cfg, const char *subspace, const char
           *mark, AdmError **error)
       AdmContext* AdmSwitchboard_readNsp (const char *namespace,
           const char *subspace, unsigned int depth, AdmError
           **error)
       AdmContext* AdmSwitchboard_readNspWithConfig (AdmList
           *namespace_cfg, const char *subspace, unsigned int
           depth, AdmError **error)
       int AdmSwitchboard_writeNsp (const char *namespace, const
           char *subspace, AdmContext *context, AdmError **error)
       int AdmSwitchboard_writeNspWithConfig (AdmList
           *namespace_cfg, const char *subspace, AdmContext
           *context, AdmError **error)
       AdmContext* AdmSwitchboard_readNspCtx (const char
           *namespace, AdmError **error)
           read a switchboard namespace configuration from the
           system.
       int AdmSwitchboard_writeNspCtx (const char *namespace,
           AdmContext *namespace_ctx, int mode, uid_t uid, gid_t
           gid, AdmError **error)
           writes a switchboard namespace configuration to the
           system.

           *namespace_ctx, const char *namespace, AdmError
           **error)
       AdmList* AdmSwitchboard_getSubspCfg (AdmList
           *namespace_cfg, const char *subspace, AdmError
           **error)
       AdmBlackBox* AdmSwitchboard_getBox (AdmList *subspace_cfg,
           const char *box_name, AdmError **error)


DEFINE DOCUMENTATION

   #define ALCHEMIST_ABI_MAJOR_VER   0
   #define ALCHEMIST_ABI_MINOR_VER   0
   #define ADM_EDEADNODE   1
   #define ADM_EBADTYPE   2
   #define ADM_EBADNAME   3
   #define ADM_EBADDATA   4
   #define ADM_ECONSTRAINT   5
   #define ADM_ENOINDEX   51
   #define ADM_ENONAME   52
   #define ADM_ENOPATH   53
   #define ADM_EACCESSFAILED   101
   #define ADM_ENONAMESPACE   102
   #define ADM_ENOSUBSPACE   103
   #define ADM_ENOWRITE   201
   #define ADM_ENOREAD   202
   #define ADM_ENOLISTSERIAL   203
   #define ADM_ENOREADSERIAL   204
   #define ADM_ENOCACHE   205
   #define ADM_ENOBOXTYPE   251
   #define ADM_EPARSE   301
   #define AdmRefStr_str(REFSTR)
       Value:

       ({         AdmRefStr *__tok = (REFSTR);         (const char *) __tok; })

   #define AdmContext_getIdentityRoot_b(CONTEXT, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmIdentity *__id;         __id = AdmContext_getIdentityRoot((CONTEXT), __err);         if (__id != NULL)                 AdmIdentity_unref(__id, __err);         __id; })

   #define AdmIdentity_getParentA_b(ID, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmIdentity *__id;         __id = AdmIdentity_getParentA((ID), __err);         if (__id != NULL)                 AdmIdentity_unref(__id, __err);         __id; })

   #define AdmIdentity_getParentB_b(ID, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmIdentity *__id;         __id = AdmIdentity_getParentB((ID), __err);         if (__id != NULL)                 AdmIdentity_unref(__id, __err);         __id; })

   #define AdmIdentity_getContext_b(ID, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmContext *__ctx;         __ctx = AdmIdentity_getContext((ID), __err);         if (__ctx != NULL)                 AdmContext_unref(__ctx, __err);         __ctx; })

       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmContext_getDataRoot((CONTEXT), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmData_getContainer_b(DATA, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmData_getContainer((DATA), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmData_getPrev_b(DATA, WRAP, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmData_getPrev((DATA), (WRAP), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmData_getNext_b(DATA, WRAP, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmData_getNext((DATA), (WRAP), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmData_getContext_b(DATA, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmContext *__ctx;         __ctx = AdmData_getContext((DATA), __err);         if (__ctx != NULL)                 AdmContext_unref(__ctx, __err);         __ctx; })

   #define AdmContext_getDataByPath_b(CONTEXT, PATH, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmContext_getDataByPath((CONTEXT), (PATH), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmList_getDataByIndex_b(LIST, INDEX, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmList_getDataByIndex((LIST), (INDEX), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmList_getDataByName_b(LIST, NAME, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmList_getDataByName((LIST), (NAME), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmList_getDataByPath_b(LIST, PATH, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmList_getDataByPath((LIST), (PATH), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmList_addData_b(LIST, TYPE, NAME, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmList_addData((LIST), (TYPE), (NAME), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define AdmList_copyData_b(LIST, DATA, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmData *__data;         __data = AdmList_copyData((LIST), (DATA), __err);         if (__data != NULL)                 AdmData_unref(__data, __err);         __data; })

   #define ADM_BBCAP_SUP_READ(CAP)   ((CAP).array[0] & (1 << 1))
   #define ADM_BBCAP_SUP_LISTSERIAL(CAP)   ((CAP).array[0] & (1
       << 2))
   #define ADM_BBCAP_SUP_READSERIAL(CAP)   ((CAP).array[0] & (1
       << 3))
   #define ADM_BBCAP_CACHED(CAP)   ((CAP).array[0] & (1 << 4))
   #define AdmSwitchboard_getNspCfg_b(CTX, NAMESPACE, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmList *__list;         __list = AdmSwitchboard_getNspCfg((CTX), (NAMESPACE), __err);         if (__list != NULL)                 AdmData_unref((AdmData *) __list, __err);         __list; })

   #define AdmSwitchboard_getSubspCfg_b(CTX, SUBSPACE, ERROR)
       Value:

       ({         AdmError **__err = (ERROR);         AdmList *__list;         __list = AdmSwitchboard_getSubspCfg((CTX), (SUBSPACE), __err);         if (__list != NULL)                 AdmData_unref((AdmData *) __list, __err);         __list; })


TYPEDEF DOCUMENTATION

   typedef struct AdmError AdmError
   typedef struct AdmRefStr AdmRefStr
   typedef struct AdmData AdmData
   typedef struct AdmList AdmList
   typedef struct AdmInt AdmInt
   typedef struct AdmBool AdmBool
   typedef struct AdmFloat AdmFloat
   typedef struct AdmString AdmString
   typedef struct AdmString AdmBase64
   typedef struct AdmString AdmCopy
   typedef struct AdmIdentity AdmIdentity
   typedef struct AdmContext AdmContext
   typedef struct AdmBlackBox AdmBlackBox

ENUMERATION TYPE DOCUMENTATION

   enum AdmDataType
       Enumeration values:

       ADM_TYPE_UNKNOWN

       ADM_TYPE_LIST

       ADM_TYPE_COPY

       ADM_TYPE_INT

       ADM_TYPE_FLOAT

       ADM_TYPE_BOOL

       ADM_TYPE_STRING

       ADM_TYPE_BASE64


FUNCTION DOCUMENTATION


       format, ...)
       Constructor/allocator for our AdmError structure. Fails
       safely and silently if error is NULL.

       Parameters:

       error  The pointer to the AdmError pointer in which the
              newly allocated AdmError structure will be
              returned.

       num    The integer error code of the new AdmError
              structure.

       format The output format in printf(3) format.

       The variable arguments for the printf(3) format.

   void AdmError_ref (AdmError * error)
       Parameters:

       error  The pointer to the AdmError structure to be
              deallocated.

   void AdmError_unref (AdmError * error)
       Decrements the reference count of the given AdmError
       function, and deallocates it when the count reaches 0.
       This function must only be called by reference holders.

       Parameters:

       error  The pointer to the AdmError structure to be
              deallocated.

   const char * AdmError_strerr (AdmError * error)
       Returns the error string of the given AdmError structure.
       The error string returned is guaranteed for only as long
       as the AdmError is refed. Users that want a copy, should
       make one.

       Parameters:

       error  The pointer to the AdmError structure.

       Returns:
           The character string that contains the description of
           the error of the given AdmError structure.

       Note:
           Based on the strerror(3) *NIX C library.

   int AdmError_errno (AdmError * error)
       Returns the error code of the given AdmError structure.


       error  The pointer to the AdmError structure.

       Returns:
           The int error code of the given AdmError structure.
           See admerror.h for a list of valid error code.

       Note:
           Based on errno(3) *NIX C library.

       See also:
           AdmError

   AdmRefStr * AdmRefStr_ref (AdmRefStr * refstr)
   void AdmRefStr_unref (AdmRefStr * refstr)
   size_t AdmRefStr_len (AdmRefStr * refstr)
   AdmRefStr * AdmRefStr_get (const char * str, int force)
       Parameters:

       str    the string to match the AdmRefStr to

       force  if we should create a matching AdmRefStr if one
              does not already exist

       Returns:
           the unique matching AdmRefStr, or NULL if there is no
           match

   AdmRefStr * AdmRefStr_nget (const char * str, size_t len, int
       force)
       Parameters:

       str    the string to match the AdmRefStr to

       len    the lenght of the string, as strlen would report it

       force  if we should create a matching AdmRefStr if one
              does not already exist

       Returns:
           the unique matching AdmRefStr, or NULL if there is no
           match

   AdmContext * AdmContext_new (const char * name, unsigned int
       serial, AdmError ** error)
       AdmContext_new: create a new AdmContext element.

       This function creates a new AdmContext element. Its root
       id node will be initialized using the passed name and
       serial. The returned AdmContext will be given a ref for
       the caller.

       Parameters:


       serial The serial number of the new AdmContext.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the new AdmContext element or NULL on
           failure.

   AdmContext * AdmContext_ref (AdmContext * context, AdmError **
       error)
       AdmContext_ref: ref an AdmContext element.

       Increases the refcount of an AdmContext element

       Parameters:

       context
              The AdmContext to increase the reference to.

       error  Optional pointer to AdmError pointer.

       Returns:
           The AdmContext

   void AdmContext_unref (AdmContext * context, AdmError **
       error)
       AdmContext_unref: unref an AdmContext element.

       Unrefs an AdmContext. This will free the context, and all
       its children, when the ref count reaches 0. It is an error
       for an entity which does not own a ref to a context to
       call AdmContext_unref. AdmContext refs can be acquired
       only by calls to AdmContext_new, AdmContext_copy,
       AdmContext_merge, AdmContext_fromXML, and AdmContext_ref.

       Parameters:

       context
              The AdmContext to decrease the reference to.

       error  Optional pointer to AdmError pointer.

   AdmContext * AdmContext_copy (AdmContext * context, AdmError
       ** error)
       This function creates a full depth copy of an AdmContext
       element. It is one of the AdmContext refing functions.

       Parameters:

       context
              The pointer to the AdmContext element to be copied.


       Returns:
           The pointer to the copied AdmContext element.

   AdmContext * AdmContext_merge (const char * name, unsigned int
       serial, AdmContext * contextA, AdmContext * contextB,
       AdmError ** error)
       AdmContext_merge: merge two AdmContext elements into a
       third.

       This is the heart function of the Alchemist. It performs
       the context merge algorithm upon two contexts, and returns
       the result. It is also one of the refing functions, as the
       returned child is refed for the caller.

       Parameters:

       name   The name of the new AdmContext.

       serial The serial number of the new AdmContext.

       contextA
              The pointer to the first AdmContext element.

       contextB
              The pointer to the second AdmContext element.

       error  Optional pointer to an AdmError pointer.

       Returns:
           The pointer to the new AdmContext element which
           contains the result of the merge operation of contextA
           and contextB or NULL on failure.

   void AdmContext_flatten (AdmContext * context, AdmError **
       error)
       AdmContext_flatten: flatten an AdmContext element.

       This function strips all masks and AdmCopy elements from
       an AdmContext element.

       Parameters:

       context
              The pointer to the AdmContext element.

       error  Optional pointer to AdmError pointer.

   void AdmContext_strip (AdmContext * context, AdmError **
       error)
       AdmContext_strip: strip an AdmContext's id tree.

       This function strips all ids except for the root id from


       Parameters:

       context
              The pointer to the AdmContext element.

       error  Optional pointer to AdmError pointer.

   char * AdmContext_toXML (AdmContext * context, AdmError **
       error)
   AdmContext * AdmContext_fromXML (const char * xml, AdmError **
       error)
   int AdmContext_readFromFile (AdmContext ** context, const char
       * path, AdmError ** error)
   int AdmContext_writeToFile (AdmContext * context, const char *
       path, int mode, uid_t uid, gid_t gid, AdmError ** error)
   AdmRefStr * AdmContext_getMask (AdmContext * context, unsigned
       int index, AdmError ** error)
       AdmContext_getMask: Gets a mask element from an AdmContext
       by index.

       This function is used to request the index'th mask of an
       AdmContext element's mask set. The string returned must be
       considered const and volatile, and if it is needed for
       long periods of time, the programmer should copy it.

       Specifically, it is guranteed for only so long as the
       AdmContext element is refed, and the mask is not cleared.

       Parameters:

       context
              The AdmContext to use.

       index  The index of the mask set element to get.

       error  Optional pointer to AdmError pointer.

       Returns:
           The mask set element AdmRefStr.

   int AdmContext_setMask (AdmContext * context, const char *
       path, AdmError ** error)
       AdmContext_setMask: set a mask in an AdmContext element's
       mask set.

       This function adds a mask path to an AdmContext element's
       mask set. It will quietly handle duplicate paths. Blank
       paths will not be added.

       Parameters:

              The AdmContext to use.

       path   The string of the mask set element to be added.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

       Note:
           This could be made much faster, if we searched the set
           only once.

   int AdmContext_clearMaskByIndex (AdmContext * context,
       unsigned int index, AdmError ** error)
       AdmContext_clearMaskByIndex: remove a mask entry from an
       AdmContext by index.

       This function removes a mask entry from an AdmContext
       element by searching against the passed index. It is an
       error to index past the end of the mask set.

       Parameters:

       context
              The AdmContext to use.

       index  The index of the mask set element to remove.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   int AdmContext_clearMaskByPath (AdmContext * context, const
       char * path, AdmError ** error)
       AdmContext_clearMaskByPath: remove a mask entry from an
       AdmContext by string.

       This function removes a mask entry from an AdmContext
       element by searching against the passed string.

       Parameters:

       context
              The AdmContext to use.

       path   The data path of the mask set element to remove.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

       AdmError ** error)
       AdmContext_getNumMasks: Gets the number of masks in an
       AdmContext's mask set.

       This function returns the number of masks in an
       AdmContext's mask set.

       Parameters:

       context
              The AdmContext to use.

       error  Optional pointer to AdmError pointer.

       Returns:
           The number of mask set element of the given
           AdmContext.

   AdmIdentity * AdmContext_getIdentityRoot (AdmContext *
       context, AdmError ** error)
       AdmContext_getIdentityRoot: Get the root AdmIdentity
       element of an AdmContext's id tree.

       This function gets the root node AdmIdentity element of an
       AdmContext element's id tree.

       Parameters:

       context
              The AdmContext of which we want to get the root
              AdmIdentity.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the root AdmIdentity element.

   AdmIdentity * AdmIdentity_getParentA (AdmIdentity * identity,
       AdmError ** error)
       AdmIdentity_getParentA: Get the A parent of an AdmIdentity
       element.

       This function returns the A parent of an AdmIdentity
       element, if it exists. Otherwise, it returns NULL.

       Parameters:

       identity
              The AdmIdentity of which to get the first parent.

       error  Optional pointer to AdmError pointer.

       Returns:


   AdmIdentity * AdmIdentity_getParentB (AdmIdentity * identity,
       AdmError ** error)
       AdmIdentity_getParentB: Get the B parent of an AdmIdentity
       element.

       This function returns the B parent of an AdmIdentity
       element, if it exists. Otherwise, it returns NULL.

       Parameters:

       identity
              The AdmIdentity of which to get the second parent.

       error  Optional pointer to AdmError pointer.

       Returns:
           The AdmIdentity pointer to the first parent.

   AdmRefStr * AdmIdentity_getName (AdmIdentity * identity,
       AdmError ** error)
       AdmIdentity_getName: Get the name of an AdmIdentity
       element.

       This function is used to request the name of an
       AdmIdentity element. The string returned must be
       considered const and volatile, and if it is needed for
       long periods of time, the programmer should copy it.

       Specifically, it is guranteed for only so long as the
       AdmCopy element is refed, and its value is not changed.

       Parameters:

       identity
              The AdmIdentity of which to get the name.

       error  Optional pointer to AdmError pointer.

       Returns:
           The name of the given AdmIdentity in an AdmRefStr.

   int AdmIdentity_setName (AdmIdentity * identity, const char *
       name, AdmError ** error)
       AdmIdentity_setName: Set the name of an AdmIdentity
       element.

       This function sets the name of an AdmIdentity element.

       Parameters:

       identity
              The AdmIdentity of which to set the name.


       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   unsigned int AdmIdentity_getSerial (AdmIdentity * identity,
       AdmError ** error)
       AdmIdentity_getSerial: Get the serial number of an
       AdmIdentity element.

       This function gets the serial number of an AdmIdentity
       element.

       Parameters:

       identity
              The AdmIdentity of which to get the serial number.

       error  Optional pointer to AdmError pointer.

       Returns:
           The serial number of the given AdmIdentity.

   int AdmIdentity_setSerial (AdmIdentity * identity, unsigned
       int serial, AdmError ** error)
       AdmIdentity_setSerial: Set the serial number of an
       AdmIdentity element.

       This function sets the serial number of an AdmIdentity
       element.

       Parameters:

       identity
              The AdmIdentity of which to set the serial number.

       name   The new serial number of the AdmIdentity.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   AdmIdentity * AdmIdentity_ref (AdmIdentity * identity,
       AdmError ** error)
       AdmIdentity_ref: ref an AdmIdentity element.

       This function refs an AdmIdentity element. It is the only
       way to acquire a ref to an AdmIdentity element.

       Parameters:

              The AdmIdentity to increase the reference to.

       error  Optional pointer to AdmError pointer.

       Returns:
           The AdmIdentity (for convienience).

   void AdmIdentity_unref (AdmIdentity * identity, AdmError **
       error)
       AdmIdentity_unref: unref an AdmIdentity element.

       This function unrefs an AdmIdentity element, and frees it
       if the refcount reaches 0. It must only be called by
       entities which own a ref to the AdmIdentity element.
       AdmIdentity refs can only be aquired by calling
       AdmIdentity_ref.

       Parameters:

       identity
              The AdmIdentity to decrease the reference to.

       error  Optional pointer to AdmError pointer.

   AdmContext * AdmIdentity_getContext (AdmIdentity * identity,
       AdmError ** error)
       AdmIdentity_getContext: Get the context of an AdmIdentity
       element.

       This function returns a pointer to the AdmContext in which
       this AdmIdentity element exists.

       Parameters:

       id     The pointer to the AdmIdentity element.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the AdmContext of the given
           AdmIdentity.

   int AdmIdentity_isAlive (AdmIdentity * identity, AdmError **
       error)
       AdmIdentity_isAlive: check the lifecycle status of an
       AdmIdentity element.

       This function checks the lifecycle status of an
       AdmIdentity element. It is used to tell if an element is
       still linked against an AdmContext, and is 'alive'; or if
       it is not, and is 'dead'.

       A dead element must have a reference held against it that


       Parameters:

       identity
              The AdmIdentity to check.

       error  Optional pointer to AdmError pointer.

       Returns:
           TRUE if Identity is still referenced, FALSE otherwise.

   AdmData * AdmContext_getDataRoot (AdmContext * context,
       AdmError ** error)
       AdmContext_getDataRoot: Get the root AdmData element of an
       AdmContext's data tree.

       This function gets the root AdmData element of an
       AdmContext's data tree.

       Parameters:

       context
              The AdmContext of which we want to get the AdmData
              root.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the root AdmData element.

   AdmData * AdmData_getContainer (AdmData * data, AdmError **
       error)
       AdmData_getContainer: Get the container of an AdmData
       element.

       This function returns a pointer to the AdmData element
       which  contains this AdmData element. For the root node,
       it will return a pointer to the AdmData element it was
       passed.

       Parameters:

       data   The AdmData of which we want to get the container
              (parent).

       error  Optional pointer to AdmError pointer.

       Returns:
           The container/parent of the given AdmData element.

   AdmData * AdmData_getPrev (AdmData * data, int wrap, AdmError
       ** error)
       Parameters:


       wrap   specify if we should wrap round the begining of the
              list

       error  Optional pointer to AdmError pointer.

       Returns:
           the previous AdmData element

   AdmData * AdmData_getNext (AdmData * data, int wrap, AdmError
       ** error)
       Parameters:

       data   The AdmData element

       wrap   specify if we should wrap round the end of the list

       error  Optional pointer to AdmError pointer.

       Returns:
           the next AdmData element

   AdmContext * AdmData_getContext (AdmData * data, AdmError **
       error)
       AdmData_getContext: Get the context of an AdmData element.

       This function returns a pointer to the AdmContext in which
       this AdmData element exists.

       Parameters:

       data   The AdmData of which we want to get the context.

       error  Optional pointer to AdmError pointer.

       Returns:
           The context of the given AdmData element.

   AdmData * AdmContext_getDataByPath (AdmContext * context,
       const char * path, AdmError ** error)
       AdmContext_getDataByPath: Gets an AdmData element from an
       AdmContext by path.

       This function does path lookups against AdmContext
       element's data trees. It will give an error if no matching
       AdmData element is found.

       Parameters:

       context
              The AdmContext we want to search.

       path   The data path of the AdmData element to look up.


       Returns:
           The pointer to the found AdmData element or NULL on
           failure.

   AdmDataType AdmData_getType (AdmData * data, AdmError **
       error)
       AdmData_getType: Get the type of an AdmData element.

       This function gets the type of an AdmData element

       Parameters:

       data   The AdmData of which we want to get the data type.

       error  Optional pointer to AdmError pointer.

       Returns:
           The data type of the given AdmData element.

   AdmData * AdmData_ref (AdmData * data, AdmError ** error)
       AdmData_ref: ref an AdmData element.

       This function refs an AdmData element. It is the only way
       to aquire a ref to an AdmData element.

       Parameters:

       data   The AdmData to increase the reference to.

       error  Optional pointer to AdmError pointer.

       Returns:
           The AdmData element

   void AdmData_unref (AdmData * data, AdmError ** error)
       AdmData_unref: unref an AdmData element.

       This function unrefs an AdmData element, and frees it if
       the refcount reaches 0. It must only be called by entities
       which own a ref to the AdmData element. AdmData refs can
       only be aquired by calling AdmData_ref.

       Parameters:

       data   The AdmData to decrease the reference to.

       error  Optional pointer to AdmError pointer.

   int AdmData_isAlive (AdmData * data, AdmError ** error)
       AdmData_isAlive: check the lifecycle status of an AdmData
       element.

       element. It is used to tell if an element is still linked
       against an AdmContext, and is 'alive'; or if it is not,
       and is 'dead'.

       A dead element must have a reference held against it that
       is not its container's reference.

       Parameters:

       data   The AdmData to check.

       error  Optional pointer to AdmError pointer.

       Returns:
           TRUE if Data is still referenced, FALSE otherwise.

   int AdmData_unlink (AdmData * data, AdmError ** error)
       AdmData_unlink: Unlink an AdmData element from its
       container.

       This function recursively unlinks an AdmData element from
       its containing AdmData element. It unrefs each element
       which it unlinks, as they loose their parents reference.
       It is an error to unlink the root node, and will fail.

       Parameters:

       data   The AdmData to unlink.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   int AdmData_validName (const char * name)
       Checks a string to determine if it is a valid AdmData
       name. A valid name is of the form: Name = (Letter | '_')
       (Letter | Digit | '_' | '-' | '.'){0,254} Letter = ['a' -
       'z'] | ['A' - 'Z']  Digit = ['0' - '9']

       Parameters:

       name   The string to check.

       Returns:
           1 if the name is valid, 0 if the name is not.

   AdmRefStr * AdmData_getName (AdmData * data, AdmError **
       error)
       AdmData_getName: Get the name of an AdmData element.

       This function is used to request the name of an AdmData
       element. The string returned must be considered const and

       the programmer should copy it.

       Specifically, it is guranteed for only so long as the
       AdmData element is refed, and its name is not changed.

       Parameters:

       data   The AdmData of which we want to get the name.

       error  Optional pointer to AdmError pointer.

       Returns:
           The name of the given AdmData element.

   int AdmData_setName (AdmData * data, const char * name,
       AdmError ** error)
       AdmData_setName: Set the name of an AdmData element.

       This function sets the name of an AdmData element to a
       copy of the passed string.

       It will not alter the root node, and it is an error to
       attempt it.

       Parameters:

       data   The AdmData of which we want to set the name.

       name   The new name of the AdmData element.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   AdmRefStr * AdmData_getSource (AdmData * data, AdmError **
       error)
       AdmData_getSource: Get the source of an AdmData element.

       This function is used to request the source of an AdmData
       element. The string returned must be considered const and
       volatile, and if it is needed for long periods of time,
       the programmer should copy it.

       Specifically, it is guranteed for only so long as the
       AdmData element is refed, and its source is not changed.
       The source of the root data node changes every time the
       name of the root id node changes.

       Parameters:

       data   The AdmData of which we want to get the source.


       Returns:
           The source of the given AdmData element.

   int AdmData_setSource (AdmData * data, const char * source,
       AdmError ** error)
       AdmData_setSource: Set the source of an AdmData element.

       This function sets the source of an AdmData element to a
       copy of the passed string.

       It will not alter the root node, and it is an error to
       attempt it.

       Parameters:

       data   The AdmData of which we want to set the source.

       name   The new source of the AdmData element.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   int AdmData_isProtected (AdmData * data, AdmError ** error)
       AdmData_isProtected: Get the state of an AdmData's
       protected flag.

       This function gets the state of an AdmData's protected
       flag.

       Parameters:

       data   The AdmData which we want to check for the
              protected flag.

       error  Optional pointer to AdmError pointer.

       Returns:
           TRUE if the given AdmData element is protected, FALSE
           otherwise.

   int AdmData_setProtected (AdmData * data, int state, AdmError
       ** error)
       AdmData_setProtected: Set an AdmData's protected flag.

       This function sets the protected flag of an AdmData
       element to the value passed.

       It will not set the flag of the root node, and is an error
       to attempt it.


       data   The AdmData of which we want to set the protected
              flag.

       state  The new protection state of the AdmData element.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   int AdmList_isAnonymous (AdmList * list, AdmError ** error)
       AdmList_isAnonymous: Get the state of an AdmList's
       anonymous flag.

       This function gets the state of an AdmList's anonymous
       flag.

       Parameters:

       list   The AdmList which we want to check for the
              anonymous flag.

       error  Optional pointer to AdmError pointer.

       Returns:
           TRUE if the given AdmList element is anonymous, FALSE
           otherwise.

   int AdmList_setAnonymous (AdmList * list, int state, AdmError
       ** error)
       AdmList_setAnonymous: Set an AdmList's anonymous flag.

       This function sets the anonymous flag of an AdmList
       element to the value passed. It will not allow the flag to
       be cleared if it will cause a name collide, and will raise
       an error.

       It will not set the flag of the root node, and is an error
       to attempt it.

       Parameters:

       list   The AdmList of which we want to set the anonymous
              flag.

       state  The new anonymous state of the AdmList element.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

       AdmList_isAtomic: Get the state of an AdmList's atomic
       flag.

       This function gets the state of an AdmList's atomic flag.

       Parameters:

       list   The AdmList which we want to check for the atomic
              flag.

       error  Optional pointer to AdmError pointer.

       Returns:
           TRUE if the given AdmList element is atomic, FALSE
           otherwise.

   int AdmList_setAtomic (AdmList * list, int state, AdmError **
       error)
       AdmList_setAtomic: Set an AdmList's atomic flag.

       This function sets the atomic flag of an AdmList element
       to the value passed.

       It will not set the flag of the root node, and is an error
       to attempt it.

       Parameters:

       list   The AdmList of which we want to set the atomic
              flag.

       state  The new atomic state of the AdmList element.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   int AdmList_isPrepend (AdmList * list, AdmError ** error)
       AdmList_isPrepend: Get the state of an AdmList's prepend
       flag.

       This function gets the state of an AdmList's prepend flag.

       Parameters:

       list   The AdmList which we want to check for the prepend
              flag.

       error  Optional pointer to AdmError pointer.

       Returns:
           TRUE if the given AdmList element is prepend, FALSE


   int AdmList_setPrepend (AdmList * list, int state, AdmError **
       error)
       AdmList_setPrepend: Set an AdmList's prepend flag.

       This function sets the prepend flag of an AdmList element
       to the value passed.

       It will not set the flag of the root node, and is an error
       to attempt it.

       Parameters:

       list   The AdmList of which we want to set the prepend
              flag.

       state  The new prepend state of the AdmList element.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   unsigned int AdmList_getNumData (AdmList * list, AdmError **
       error)
       AdmList_getNumData: Get the size of an AdmList's child
       set.

       This function gets the number of children held in an
       AdmList's child set.

       Parameters:

       list   The AdmList which we want to count.

       error  Optional pointer to AdmError pointer.

       Returns:
           The number of children inside the given list.

   AdmData * AdmList_getDataByIndex (AdmList * list, unsigned int
       index, AdmError ** error)
       AdmList_getDataByIndex: Get a child of an AdmList element
       by its index.

       This function seeks on an AdmList's child set, and returns
       its index'th child. It is an error to seek on an index
       greater >= the list length, since the first element is
       stored at index 0.

       Parameters:

       list   The AdmList which we want to access.


       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to requested AdmData element of the list.

   AdmData * AdmList_getDataByName (AdmList * list, const char *
       name, AdmError ** error)
       AdmList_getDataByName: Get a child od an AdmList element
       by its name.

       This function seeks againts an AdmList's child set, and
       returns the first child whose name matches the search
       name. It raises a AdmError if no name is found.

       Parameters:

       list   The AdmList which we want to access.

       name   The name of the child we want to get.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to requested AdmData element of the list.

   AdmData * AdmList_getDataByPath (AdmList * list, const char *
       path, AdmError ** error)
       AdmList_getDataByPath: Get a child od an AdmList element
       by its path.

       This function seeks againts an AdmList's child set, and
       returns the first child whose path matches the search
       path. It raises a AdmError if no path is found.

       Parameters:

       list   The AdmList which we want to access.

       path   The data path of the child we want to get.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to requested AdmData element of the list.

   AdmData * AdmList_addData (AdmList * list, AdmDataType type,
       const char * name, AdmError ** error)
       AdmList_addData: add a new child to an AdmList element.

       This function appends a new child of the given type and
       name to the end of the AdmList. It returns a pointer to
       the new AdmData element. Name collides in non-anonymous


       Note that new AdmCopy elements will have the invalid
       reference '' as their initial value, and must be changed.

       The new child is refed, but the ref is owned by its
       AdmList element, and no ref is implied to the accessor.

       Parameters:

       list   The AdmList to which we want to add a new child.

       type   The AdmData type of the new child to be added.

       name   The name of the new child to be added.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the newly added AdmData element.

   int AdmList_moveData (AdmList * list, AdmData * data, unsigned
       int index, AdmError ** error)
       AdmList_moveData: reposition an AdmData element in its
       containing AdmList.

       This function extracts an AdmData element from its
       containing list, and then reinserts it at the index value
       passed. It is an error to give it an illegal index value.

       Parameters:

       list   The AdmList which we want to move in.

       data   The AdmData pointer of the child we want to move.

       index  The index to where we want to move the child.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   int AdmList_reparentData (AdmList * list, AdmData * data,
       const char * name, unsigned int index, AdmError ** error)
       AdmList_reparentData: reparent an AdmData element to a
       different AdmList.

       This function extracts an AdmData element from its
       containing list, and then appends it to the list given.

       Parameters:

       list   The AdmList which we want to reparent to.


       name   The name to reparent the data with.

       index  The index to where we want to reparent the data.

       error  Optional pointer to AdmError pointer.

       Returns:
           -1 on error, 0 on success

   AdmData * AdmList_copyData (AdmList * list, AdmData * data,
       AdmError ** error)
       AdmList_copyData: copy a AdmData element into an AdmList
       element.

       This function recursively copies an AdmData tree from the
       passed data node, and inserts the result onto the end of
       the passed AdmList. It checks for name collides in Non-
       anonymous lists, and will not copy a root node; both are
       errors.

       Parameters:

       list   The AdmList to append the data to.

       data   The AdmData element to recursively copy and append
              to the list.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the newly copied and appended AdmData
           element.

   unsigned int AdmData_getPos (AdmData * data, AdmError **
       error)
       AdmData_getPos: Get the position of an AdmData node in its
       containing list.

       This function returns the position that an AdmData node
       holds in its containing list. The position of the root
       node is defined to be 0.

       Parameters:

       data   The AdmData of which we want to know the index.

       error  Optional pointer to AdmError pointer.

       Returns:
           The index of the data element in it's parent list.

       Gets the integer value stored in an AdmInt node.

       Parameters:

       int_scalar
              a pointer to an AdmInt node

       error  an optional pointer to an AdmError pointer

       Returns:
           the value of the node

       See also:
           AdmInt , AdmError

   int AdmInt_setValue (AdmInt * int_scalar, int value, AdmError
       ** error)
       Sets the integer value stored in an AdmInt node.

       Parameters:

       int_scalar
              a pointer to an AdmInt node

       value  the integer value to set the node to

       error  an optional pointer to an AdmError pointer

       Returns:
           -1 on error, 0 on success

       See also:
           AdmInt , AdmError

   double AdmFloat_getValue (AdmFloat * float_scalar, AdmError **
       error)
       Gets the double value stored in an AdmFloat node.

       Parameters:

       float_scalar
              a pointer to an AdmFloat node

       error  an optional pointer to an AdmError pointer

       Returns:
           the double value of the node

       See also:
           AdmFloat , AdmError

   int AdmFloat_setValue (AdmFloat * float_scalar, double value,
       AdmError ** error)


       Parameters:

       float_scalar
              a pointer to an AdmFloat element

       value  the double value to set the node with

       error  an optional pointer to an AdmError pointer

       Returns:
           -1 on error, 0 on success

       See also:
           AdmFloat , AdmError

   int AdmBool_getValue (AdmBool * bool_scalar, AdmError **
       error)
       Gets the boolean value stored in an AdmBool node.

       Parameters:

       bool_scalar
              a pointer to an AdmBool node

       error  an optional pointer to an AdmError pointer

       Returns:
           the value of the node as an int

       See also:
           AdmBool , AdmError

   int AdmBool_setValue (AdmBool * bool_scalar, int value,
       AdmError ** error)
       Sets the boolean value stored in an AdmBool node.

       Parameters:

       bool_scalar
              a pointer to an AdmBool node

       value  the value to set the node to as an int

       error  an optional pointer to an AdmError pointer

       Returns:
           -1 on error, 0 on success

       See also:
           AdmBool , AdmError

       AdmError ** error)
       Get the value of an AdmString element.

       This function is used to request the string stored in an
       AdmString element. The string returned must be considered
       const and volatile, and if it is needed for long periods
       of time, the programmer should copy it.

       Specifically, it is guaranteed for only so long as the
       AdmString element remains refed, and its value is not
       changed.

       Parameters:

       string_scalar
              The pointer to the AdmString element

       error  optional pointer to an AdmError pointer

       Returns:
           An AdmRefStr with the AdmString element's value
           string.

   int AdmString_setValue (AdmString * string_scalar, const char
       * value, AdmError ** error)
       Set the value of an AdmString element.

       This function is used to set the value of an AdmString
       element. It stores a copy of the value string it is
       passed.

       Parameters:

       string_scalar
              The pointer to the AdmString element.

       value  The pointer to the string.

       error  optional pointer to an AdmError pointer

       Returns:
           -1 on error, 0 on success

   AdmRefStr * AdmBase64_getValue (AdmBase64 * base64_scalar,
       AdmError ** error)
       AdmBase64_getValue: Get the value of an AdmBase64 element
       @base64_scalar: a pointer to an AdmBase64 element @error:
       an optional AdmError

       This function is used to request the string stored in an
       AdmBase64 string element. The string returned must be
       considered const and volatile, and if it is needed for
       long periods of time, the programmer should copy it.

       string.

   int AdmBase64_setValue (AdmBase64 * base64_scalar, const char
       * value, AdmError ** error)
       This function is used to set the value of an AdmBase64
       string element. It stores a copy of the value string it is
       passed.

       Parameters:

       base64_scalar
              a pointer to an AdmBase64 element

       value  a pointer to a base64 encoded binary string

       error  an optional AdmError

       Returns:
           -1 on error, 0 on success

   size_t AdmBase64_getBinValue (AdmBase64 * base64_scalar, void
       ** value, AdmError ** error)
       Parameters:

       base64_scalar
              a pointer to an AdmBase64 element

       value  a pointer to a void pointer to return the address
              of the new buffer.

       error  an optional AdmError

       Returns:
           the size of the new buffer.

       This function will decode and return a copy of the binary
       string stored in a AdmBase64 element. You must free the
       returned buffer.

       Return value: a pointer to the AdmBase64 element's value
       string.

   int AdmBase64_setBinValue (AdmBase64 * base64_scalar, const
       void * value, size_t size, AdmError ** error)
       This function is used to set the binary value of an
       AdmBase64 string element. It stores an encoded copy of the
       value string it is passed.

       Parameters:

       base64_scalar
              a pointer to an AdmBase64 element


       size   the size of the binary string

       error  an optional AdmError

       Returns:
           -1 on error, 0 on success

   AdmRefStr * AdmCopy_getValue (AdmCopy * copy_scalar, AdmError
       ** error)
       This function is used to request the path of an AdmCopy
       element. The string returned must be considered const and
       volatile, and if it is needed for long periods of time,
       the programmer should copy it.

       Specifically, it is guranteed for only so long as the
       AdmCopy element is refed, and its value is not changed.

       Parameters:

       copy_scalar
              a pointer to an AdmCopy element

       error  an optional GError

       Returns:
           An AdmRefStr containing the AdmCopy's path

   int AdmCopy_setValue (AdmCopy * copy_scalar, const char *
       value, AdmError ** error)
       This function is used to set the path of an AdmCopy
       element. It stores a copy of the string passed to it,
       after checking its path validity.

       Parameters:

       copy_scalar
              a pointer to an AdmCopy element

       value  a pointer to a valid path string

       error  an optional GError

       Returns:
           -1 on error, 0 on success

   AdmRefStr * AdmBlackBox_getCacheDir (AdmError ** error)
       Gets the cache directory the alchemist is currently using.

       Parameters:

       error  an optional pointer to an AdmError pointer

           the cache dir

       Note:
           you do not own the return stritg, and must not free it

   int AdmBlackBox_setCacheDir (const char * path, AdmError **
       error)
       Sets the cache directory the alchemist is currently using.

       Parameters:

       path   the cache directory you want to use

       error  an optional pointer to an AdmError pointer

       Returns:
           -1 on failure, 0 on succes

       Note:
           passing NULL as the path resets the path to the
           default

   AdmBlackBox * AdmBlackBox_getBox (AdmList * box_cfg, AdmError
       ** error)
   adm_bb_cap_t AdmBlackBox_caps (AdmBlackBox * box, AdmError **
       error)
       Returns a capability vector listing the capabilities of an
       AdmBlackBox.

       Parameters:

       box    The AdmBlackBox to check

       error  Optional pointer to AdmError pointer.

       Returns:
           an adm_bb_cap_t structure

   void AdmBlackBox_ref (AdmBlackBox * box, AdmError ** error)
       Increase reference to given AdmBlackBox element.

       Parameters:

       box    The AdmBlackBox to increase the reference to.

       error  Optional pointer to AdmError pointer.

   void AdmBlackBox_unref (AdmBlackBox * box, AdmError ** error)
       Decrease reference to given AdmBlackBox element.

       Parameters:

       box    The AdmBlackBox to decrease the reference to.


   AdmContext * AdmBlackBox_read (AdmBlackBox * box, AdmError **
       error)
       Tries to read the most current context from the given
       AdmBlackBox and return it. The BlackBox may not be able to
       be readable in which case NULL will be returned. Also it
       may allow caching and do so transparently.

       Parameters:

       box    The AdmBlackBox to read from.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the AdmContext retrived through the
           given box.

   int AdmBlackBox_listSerial (AdmBlackBox * box, unsigned int *
       array, unsigned int array_len, unsigned int top_serial,
       AdmError ** error)
       Creates a list of serial numbers of the given AdmBlackBox
       subject to the constraints.

       Parameters:

       box    The AdmBlackBox to get the list of serial numbers
              from.

       array  The pointer to the preallocated array of int values
              to be filled with the serial numbers.

       array_len
              The size of the perallocated array.

       top_serial
              The highest serial number that we request. Only
              serial numbers below that will be returned. Use 0
              to request the newest (highest) serial numbers.

       error  Optional pointer to AdmError pointer.

       Returns:
           The amount of serial numbers filled in. Always less or
           equal to the array length.

       Note:
           The list of serial numbers can partially come from the
           local cached BlackBoxes as well.

   AdmContext * AdmBlackBox_readSerial (AdmBlackBox * box,
       unsigned int serial, AdmError ** error)
       Reads a context from the given AdmBlackBox with the


       Parameters:

       box    The AdmBlackBox to read the context from.

       serial The serial number of the context we request.

       error  Optional pointer to AdmError pointer.

       Returns:
           The pointer to the AdmContext retrived through the
           given box or NULL if no context with that serial
           number exists.

   int AdmBlackBox_write (AdmBlackBox * box, AdmContext *
       context, AdmError ** error)
       Write the given AdmContext to the given AdmBlackBox. Does
       automatic caching if the given AdmBlackBox supports it.

       Parameters:

       box    The AdmBlackBox to write to.

       context
              The AdmContext to be written to the box.

       error  Optional pointer to AdmError pointer.

       Returns:
           0 on success, all other values indicate an error.

   unsigned int AdmBlackBox_getMark (AdmBlackBox * box, const
       char * mark, AdmError ** error)
       Get the serial number of the given AdmBlackBox for the
       given mark. The whole business with marks allows us to
       'tag' cached boxes and to identify if they are dirty or
       not.

       Parameters:

       box    The AdmBlackBox from which to get the marked
              serial.

       mark   The mark string.

       error  Optional pointer to AdmError pointer.

       Returns:
           The serial number of the marked cached box or 0 if no
           marked cached box exists.

   int AdmBlackBox_setMark (AdmBlackBox * box, const char * mark,
       AdmError ** error)

       from the given AdmBlackBox automatically. Any existing
       mark will be overwritten. If an AdmBlackBox is cached,
       then it is possible to mark it. This provides a mechanism
       for marking the top serial number in the cache down at a
       given mark, which is a string; allowing various
       applications to check to see if an interface has changed
       since the last time the accessed by doing something along
       the lines of:

        AdmBlackBox_setMark(box_p, 'app1_mark_string', error);
        ...
        int i;
        if ((AdmBlackBok_listSerial(box_p, &i, 1, 0, NULL) &&
               (i != AdmBlackBox_getMark(box_p, 'app1_mark_string', NULL)) {
               ...
        }
       Parameters:

       box    The AdmBlackBox which we want to mark.

       mark   The mark string.

       error  Optional pointer to AdmError pointer.

       Returns:
           0 on success, all other values indicate an error.

   int AdmBlackBox_clearMark (AdmBlackBox * box, const char *
       mark, AdmError ** error)
       Clear the mark for the given AdmBlackBox.

       Parameters:

       box    The AdmBlackBox where we want to clear its mark.

       mark   The mark string.

       error  Optional pointer to AdmError pointer.

       Returns:
           0 on success, all other values indicate an error.

   AdmRefStr * AdmSwitchboard_getSwbDir (AdmError ** error)
       Gets the swb directory the alchemist is currently using.

       Parameters:

       error  an optional pointer to an AdmError pointer

       Returns:
           the swb dir

       Note:


   int AdmSwitchboard_setSwbDir (const char * path, AdmError **
       error)
       Sets the swb directory the alchemist is currently using.

       Parameters:

       path   the swb directory you want to use

       error  an optional pointer to an AdmError pointer

       Returns:
           -1 on failure, 0 on succes

       Note:
           passing NULL as the path resets the path to the
           default

   int AdmSwitchboard_markNsp (const char * namespace, const char
       * subspace, const char * mark, AdmError ** error)
   int AdmSwitchboard_markNspWithConfig (AdmList * namespace_cfg,
       const char * subspace, const char * mark, AdmError **
       error)
   int AdmSwitchboard_checkNspMark (const char * namespace, const
       char * subspace, const char * mark, AdmError ** error)
   int AdmSwitchboard_checkNspMarkWithConfig (AdmList *
       namespace_cfg, const char * subspace, const char * mark,
       AdmError ** error)
   AdmContext * AdmSwitchboard_readNsp (const char * namespace,
       const char * subspace, unsigned int depth, AdmError **
       error)
       read the given subspace from the given namespace

       Parameters:

       namespace
              the namespace to read

       subspace
              the box set to extract, NULL uses the default
              'config' set

       depth  the number of boxes in the namespace to read, 0
              means all.

       error  an optional pointer to an AdmError pointer

   AdmContext * AdmSwitchboard_readNspWithConfig (AdmList *
       namespace_cfg, const char * subspace, unsigned int depth,
       AdmError ** error)
   int AdmSwitchboard_writeNsp (const char * namespace, const
       char * subspace, AdmContext * context, AdmError ** error)
       writes the given subspace in the given namespace


       namespace
              the namespace to write

       subspace
              the box set to extract, NULL uses the default
              'config' set

       context
              the context to write

       error  an optional pointer to an AdmError pointer

   int AdmSwitchboard_writeNspWithConfig (AdmList *
       namespace_cfg, const char * subspace, AdmContext *
       context, AdmError ** error)
   AdmContext * AdmSwitchboard_readNspCtx (const char *
       namespace, AdmError ** error)
       Parameters:

       namespace
              the name of the namespace to read

       error  an optional pointer to an AdmError pointer

       Returns:
           an AdmContext that is the namespace configuration

   int AdmSwitchboard_writeNspCtx (const char * namespace,
       AdmContext * namespace_ctx, int mode, uid_t uid, gid_t
       gid, AdmError ** error)
       Parameters:

       namespace
              the name of the namespace to read

       context
              the configuration context to write

       mode   the file mode to write the context out with

       uid    the uid to write the file with, -1 for dont care

       gid    the gid to write the file with, -1 for dont care

       error  an optional pointer to an AdmError pointer

       Returns:
           -1 on failure, 0 on succes

   AdmList * AdmSwitchboard_getNspCfg (AdmContext *
       namespace_ctx, const char * namespace, AdmError ** error)
       extract a namespace config from a namespace context


       namespace
              the namespace to extract

       config the namespace config context

   AdmList * AdmSwitchboard_getSubspCfg (AdmList * namespace_cfg,
       const char * subspace, AdmError ** error)
       extract a box set from a namespace config

       Parameters:

       subspace
              the box set to extract, NULL uses the default
              'config' set

       namespace
              the namespace used

       config the namespace config context

   AdmBlackBox * AdmSwitchboard_getBox (AdmList * subspace_cfg,
       const char * box_name, AdmError ** error)
       extract a box_config set from a namespace config

       Parameters:

       box_name
              the box to extract

       subspace_cfg
              the subspace config no use


AUTHOR

       Generated automatically by Doxygen for Alchemist from the
       source code.


Man(1) output converted with man2html