NAME¶

Modules¶

Enumerations¶

Functions¶

Detailed Description¶

Enumeration Type Documentation¶

enum keyswitch_t¶

KEY_NAME

Flag for the key name

KEY_VALUE

Flag for the key data

KEY_OWNER

Flag for the key user domain

KEY_COMMENT

Flag for the key comment

KEY_BINARY

Flag if the key is binary

KEY_UID

Flag for the key UID

KEY_GID

Flag for the key GID

KEY_MODE

Flag for the key permissions

KEY_ATIME

Flag for the key access time

KEY_MTIME

Flag for the key change time

KEY_CTIME

Flag for the key status change time

KEY_SIZE

Flag for maximum size to limit value

KEY_DIR

Flag for the key directories

KEY_END

Used as a parameter terminator to keyNew()

Function Documentation¶

int keyClear (Key *key)¶

int f (Key *k)
{
        keyClear (k);
        // you have a fresh key k here
        keySetString (k, "value");
        // the caller will get an empty key k with an value
}

int keyCopy (Key *dest, const Key *source)¶

void h (Key *k)
{
        // receive key c
        keyCopy (k, c);
        // the caller will see the changed key k
}

void g (Key *k)
{
        keyCopy (k, 0);
        // k is now an empty and fresh key
}

void j (Key *k)
{
        size_t size = keyGetValueSize (k);
        char *value = malloc (size);
        int bstring = keyIsString (k);

        // receive key c
        memcpy (value, keyValue(k), size);
        keyCopy (k, c);
        if (bstring) keySetString (k, value);
        else keySetBinary (k, value, size);
        free (value);
        // the caller will see the changed key k
        // with the metadata from c
}

ssize_t keyDecRef (Key *key)¶

int keyDel (Key *key)¶

Key* keyDup (const Key *source)¶

int f (const Key * source)
{
        Key * dup = keyDup (source);
        // work with duplicate
        keyDel (dup);
        // everything related to dup is freed
        // and source is unchanged
}

int g (const Key * source, KeySet * ks)
{
        Key * dup = keyDup (source);
        // work with duplicate
        ksAppendKey (ks, dup);
        // ksDel(ks) will also free the duplicate
        // source remains unchanged.
}

ssize_t keyGetRef (const Key *key)¶

ssize_t keyIncRef (Key *key)¶

Key *k;
keyInc (k);
function_that_keyDec(k);
// work with k
keyDel (k); // now really free it

Key* keyNew (const char *name, ...)¶

Key *k = keyNew(0);
// work with it
keyDel (k);

Key *nullKey,*emptyNamedKey;

// Create a key that has no name, is completely empty, but is initialized
nullKey=keyNew(0);
keyDel (nullKey);

// Is the same as above
nullKey=keyNew("", KEY_END);
keyDel (nullKey);

// Create and initialize a key with a name and nothing else
emptyNamedKey=keyNew("user/some/example",KEY_END);
keyDel (emptyNamedKey);

•

keyswitch_t::KEY_TYPE

 

Next parameter is a type of the value. Default assumed is KEY_TYPE_UNDEFINED. Set this attribute so that a subsequent KEY_VALUE can toggle to keySetString() or keySetBinary() regarding to keyIsString() or keyIsBinary(). If you don't use KEY_TYPE but a KEY_VALUE follows afterwards, KEY_TYPE_STRING will be used.

•

keyswitch_t::KEY_SIZE

 

Define a maximum length of the value. This is especially useful for setting a binary key. So make sure you use that before you KEY_VALUE for binary keys.

•

keyswitch_t::KEY_VALUE

 

Next parameter is a pointer to the value that will be set to the key If no keyswitch_t::KEY_TYPE was used before, keyswitch_t::KEY_TYPE_STRING is assumed. If KEY_TYPE was previously passed with a KEY_TYPE_BINARY, you should have passed KEY_SIZE before! Otherwise it will be cut of with first \0 in string!

•

keyswitch_t::KEY_UID, keyswitch_t::KEY_GID

 

Next parameter is taken as the UID (uid_t) or GID (gid_t) that will be defined on the key. See keySetUID() and keySetGID().

•

keyswitch_t::KEY_MODE

 

Next parameter is taken as mode permissions (int) to the key. See keySetMode().

•

keyswitch_t::KEY_DIR

 

Define that the key is a directory rather than a ordinary key. This means its executable bits in its mode are set. This option allows the key to have subkeys. See keySetDir().

•

keyswitch_t::KEY_OWNER

 

Next parameter is the owner. See keySetOwner().

•

keyswitch_t::KEY_COMMENT

 

Next parameter is a comment. See keySetComment().

•

keyswitch_t::KEY_END

 

Must be the last parameter passed to keyNew(). It is always required, unless the keyName is 0.

KeySet *ks=ksNew(0);

ksAppendKey(ks,keyNew(0));       // an empty key

ksAppendKey(ks,keyNew("user/sw",              // the name of the key
        KEY_END));                      // no more args

ksAppendKey(ks,keyNew("user/tmp/ex1",
        KEY_VALUE,"some data",          // set a string value
        KEY_END));                      // end of args

ksAppendKey(ks,keyNew("user/tmp/ex2",
        KEY_VALUE,"some data",          // with a simple value
        KEY_MODE,0777,                  // permissions
        KEY_END));                      // end of args

ksAppendKey(ks,keyNew("user/tmp/ex4",
        KEY_TYPE,KEY_TYPE_BINARY,       // key type
        KEY_SIZE,7,                     // assume binary length 7
        KEY_VALUE,"some data",          // value that will be truncated in 7 bytes
        KEY_COMMENT,"value is truncated",
        KEY_OWNER,"root",               // owner (not uid) is root
        KEY_UID,0,                      // root uid
        KEY_END));                      // end of args

ksAppendKey(ks,keyNew("user/tmp/ex5",
        KEY_TYPE,
                KEY_TYPE_DIR | KEY_TYPE_BINARY,// dir key with a binary value
        KEY_SIZE,7,
        KEY_VALUE,"some data",          // value that will be truncated in 7 bytes
        KEY_COMMENT,"value is truncated",
        KEY_OWNER,"root",               // owner (not uid) is root
        KEY_UID,0,                      // root uid
        KEY_END));                      // end of args

ksDel(ks);

Key *k = keyNew(0); // ref counter 0
ksAppendKey(ks, k); // ref counter of key 1
ksDel(ks); // key will be deleted with keyset

Key *k = keyNew(0); // ref counter 0
keyIncRef(k); // ref counter of key 1
keyDel(k);    // has no effect
keyDecRef(k); // ref counter back to 0
keyDel(k);    // key is now deleted

Key *k = keyNew(0); // ref counter 0
ksAppendKey(ks1, k); // ref counter of key 1
ksAppendKey(ks2, k); // ref counter of key 2
ksDel(ks1); // ref counter of key 1
ksDel(ks2); // k is now deleted

Key *k = keyNew(0); // ref counter 0
keyIncRef(k); // ref counter of key 1
keyDel (k);   // has no effect
keyIncRef(k); // ref counter of key 2
keyDel (k);   // has no effect
keyDecRef(k); // ref counter of key 1
keyDel (k);   // has no effect
keyDecRef(k); // ref counter is now 0
keyDel (k); // k is now deleted

Key *k = keyNew(0);
// keyNeedSync() will be false

Author¶