Libelektra: improve the documentation of ksAppendKey

[raphi011]

Steps to Reproduce the Problem

1. Create a new key
2. increment the ref counter with keyIncRef
3. Add it to a keyset with ksAppendKey
4. call ksClose on the keyset
5. call keyDel on the key

Expected Result

The deletion of the key is successfull since the keyset should not have deleted it as described in the documentation of ksAppendKey:

 * Appends a Key to the end of @p ks.
 *
 * Hands the ownership of the key @p toAppend to the KeySet @p ks.
 * That means ksDel(ks) will remove the key unless
 * the key:
 * - got its refcount incremented by keyIncRef() before appending
 * - was also inserted into another keyset with ksAppendKey()
 ...

Actual Result

Crashes with invalid pointer because ksClose ignores the keys ref counter.

System Information

• Elektra Version: master

[markus2330]

Thank you for reporting this problem! As written in #3073 this testcase should also be part of the test suite (for regression tests).

[raphi011]

Going to add the test tomorrow

[raphi011]

What is the easiest way to a run a single test in the tests/ctests folder? @markus2330

[markus2330]

ctest -V -R ..., I added it in 69400481b699c068dba595ae334f353da9706f8c

[raphi011]

Seems like I was wrong - the logic of not deleting the key if it still has references is implemented in keyDel not ksDel, so everthing should be fine. Closing this

[markus2330]

Maybe you can update the docu so that the next person is not confused about the logic of keyClose/ksClose?

[raphi011]

Maybe you can update the docu so that the next person is not confused about the logic of keyClose/ksClose?

Done

[markus2330]

Can you reference to the commits/PRs where this happened? Ideally, you write "see/close #3072" within the commits, then the referencing happens automatically.

[raphi011]

Good question, I can remember changing the documentation but can't find the commit anymore. Will take another look tonight

[markus2330]

Implementation is in #3073