diff --git a/lib/src/clixon_datastore.c b/lib/src/clixon_datastore.c index 4202dbbb..93030499 100644 --- a/lib/src/clixon_datastore.c +++ b/lib/src/clixon_datastore.c @@ -82,6 +82,7 @@ /*! Translate from symbolic database name to actual filename in file-system + * * @param[in] th text handle handle * @param[in] db Symbolic database name, eg "candidate", "running" * @param[out] filename Filename. Unallocate after use with free() @@ -122,6 +123,7 @@ xmldb_db2file(clicon_handle h, } /*! Connect to a datastore plugin, allocate resources to be used in API calls + * * @param[in] h Clicon handle * @retval 0 OK * @retval -1 Error @@ -133,6 +135,7 @@ xmldb_connect(clicon_handle h) } /*! Disconnect from a datastore plugin and deallocate resources + * * @param[in] handle Disconect and deallocate from this handle * @retval 0 OK * @retval -1 Error @@ -163,11 +166,12 @@ xmldb_disconnect(clicon_handle h) } /*! Copy database from db1 to db2 + * * @param[in] h Clicon handle * @param[in] from Source database * @param[in] to Destination database - * @retval -1 Error - * @retval 0 OK + * @retval 0 OK + * @retval -1 Error */ int xmldb_copy(clicon_handle h, @@ -240,11 +244,12 @@ xmldb_copy(clicon_handle h, } /*! Lock database + * * @param[in] h Clicon handle * @param[in] db Database * @param[in] id Session id - * @retval -1 Error - * @retval 0 OK + * @retval 0 OK + * @retval -1 Error */ int xmldb_lock(clicon_handle h, @@ -264,10 +269,11 @@ xmldb_lock(clicon_handle h, } /*! Unlock database + * * @param[in] h Clicon handle * @param[in] db Database - * @retval -1 Error - * @retval 0 OK + * @retval 0 OK + * @retval -1 Error * Assume all sanity checks have been made */ int @@ -285,10 +291,11 @@ xmldb_unlock(clicon_handle h, } /*! Unlock all databases locked by session-id (eg process dies) - * @param[in] h Clicon handle - * @param[in] id Session id - * @retval -1 Error - * @retval 0 OK + * + * @param[in] h Clicon handle + * @param[in] id Session id + * @retval 0 OK + * @retval -1 Error */ int xmldb_unlock_all(clicon_handle h, @@ -320,12 +327,13 @@ xmldb_unlock_all(clicon_handle h, } /*! Check if database is locked + * * @param[in] h Clicon handle * @param[in] db Database - * @retval -1 Error - * @retval 0 Not locked * @retval >0 Session id of locker - */ + * @retval 0 Not locked + * @retval -1 Error + */ uint32_t xmldb_islocked(clicon_handle h, const char *db) @@ -338,11 +346,12 @@ xmldb_islocked(clicon_handle h, } /*! Get timestamp of when database was locked + * * @param[in] h Clicon handle * @param[in] db Database * @param[out] tv Timestamp - * @retval -1 No timestamp / not locked * @retval 0 OK + * @retval -1 No timestamp / not locked */ int xmldb_lock_timestamp(clicon_handle h, @@ -358,11 +367,12 @@ xmldb_lock_timestamp(clicon_handle h, } /*! Check if db exists or is empty + * * @param[in] h Clicon handle * @param[in] db Database - * @retval -1 Error - * @retval 0 No it does not exist - * @retval 1 Yes it exists + * @retval 1 Yes it exists + * @retval 0 No it does not exist + * @retval -1 Error * @note An empty datastore is treated as not existent so that a backend after dropping priviliges can re-create it */ int @@ -392,10 +402,11 @@ xmldb_exists(clicon_handle h, } /*! Clear database cache if any for mem/size optimization only, not file itself + * * @param[in] h Clicon handle * @param[in] db Database - * @retval -1 Error - * @retval 0 OK + * @retval 0 OK + * @retval -1 Error */ int xmldb_clear(clicon_handle h, @@ -414,10 +425,12 @@ xmldb_clear(clicon_handle h, } /*! Delete database, clear cache if any. Remove file + * * @param[in] h Clicon handle * @param[in] db Database - * @retval -1 Error - * @retval 0 OK + * @retval 0 OK + * @retval -1 Error + * @note Datastore is not actually deleted so that a backend after dropping priviliges can re-create it */ int @@ -446,10 +459,11 @@ xmldb_delete(clicon_handle h, } /*! Create a database. Open database for writing. + * * @param[in] h Clicon handle * @param[in] db Database - * @retval 0 OK - * @retval -1 Error + * @retval 0 OK + * @retval -1 Error */ int xmldb_create(clicon_handle h, @@ -484,6 +498,7 @@ xmldb_create(clicon_handle h, } /*! Create an XML database. If it exists already, delete it before creating + * * Utility function. * @param[in] h Clixon handle * @param[in] db Symbolic database name, eg "candidate", "running" @@ -504,6 +519,7 @@ xmldb_db_reset(clicon_handle h, } /*! Get datastore XML cache + * * @param[in] h Clicon handle * @param[in] db Database name * @retval xml XML cached tree or NULL @@ -520,11 +536,12 @@ xmldb_cache_get(clicon_handle h, } /*! Get modified flag from datastore + * * @param[in] h Clicon handle * @param[in] db Database name - * @retval -1 Error (datastore does not exist) - * @retval 0 Db is not modified * @retval 1 Db is modified + * @retval 0 Db is not modified + * @retval -1 Error (datastore does not exist) * @note This only makes sense for "candidate", see RFC 6241 Sec 7.5 * @note This only works if db cache is used,... */ @@ -542,11 +559,12 @@ xmldb_modified_get(clicon_handle h, } /*! Get empty flag from datastore (the datastore was empty ON LOAD) + * * @param[in] h Clicon handle * @param[in] db Database name - * @retval -1 Error (datastore does not exist) - * @retval 0 Db was not empty on load * @retval 1 Db was empty on load + * @retval 0 Db was not empty on load + * @retval -1 Error (datastore does not exist) */ int xmldb_empty_get(clicon_handle h, @@ -562,11 +580,12 @@ xmldb_empty_get(clicon_handle h, } /*! Set modified flag from datastore + * * @param[in] h Clicon handle * @param[in] db Database name * @param[in] value 0 or 1 - * @retval -1 Error (datastore does not exist) * @retval 0 OK + * @retval -1 Error (datastore does not exist) * @note This only makes sense for "candidate", see RFC 6241 Sec 7.5 * @note This only works if db cache is used,... */ @@ -615,12 +634,13 @@ xmldb_print(clicon_handle h, } /*! Rename an XML database + * * @param[in] h Clicon handle * @param[in] db Database name * @param[in] newdb New Database name; if NULL, then same as old * @param[in] suffix Suffix to append to new database name - * @retval -1 Error * @retval 0 OK + * @retval -1 Error * @note if newdb and suffix are null, OK is returned as it is a no-op */ int diff --git a/lib/src/clixon_datastore_read.c b/lib/src/clixon_datastore_read.c index 19cf890d..efdbf99a 100644 --- a/lib/src/clixon_datastore_read.c +++ b/lib/src/clixon_datastore_read.c @@ -87,9 +87,10 @@ #define handle(xh) (assert(text_handle_check(xh)==0),(struct text_handle *)(xh)) /*! Ensure that xt only has a single sub-element and that is "config" + * + * @retval 0 There exists a single "config" sub-element * @retval -1 Top element not "config" or "config" element not unique or * other error, check specific clicon_errno, clicon_suberrno - * @retval 0 There exists a single "config" sub-element */ static int singleconfigroot(cxobj *xt, @@ -128,8 +129,9 @@ singleconfigroot(cxobj *xt, } /*! Recurse up from x0 up to x0t then create objects from x1t down to new object x1 - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 OK + * + * @retval 0 OK + * @retval -1 General error, check specific clicon_errno, clicon_suberrno */ static int xml_copy_bottom_recurse(cxobj *x0t, @@ -206,8 +208,9 @@ xml_copy_bottom_recurse(cxobj *x0t, } /*! Copy an XML tree bottom-up - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 OK + * + * @retval 0 OK + * @retval -1 General error, check specific clicon_errno, clicon_suberrno */ static int xml_copy_from_bottom(cxobj *x0t, @@ -248,8 +251,8 @@ xml_copy_from_bottom(cxobj *x0t, * @param[in] yspec Top-level yang spec * @param[in] xt XML tree * @param[out] msdiff Modules-state differences - * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @retval 0 OK + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * * The modstate difference contains: * - if there is a modstate @@ -393,10 +396,11 @@ text_read_modstate(clicon_handle h, } /*! Check if nacm only contains default values, if so disable NACM + * * @param[in] xt Top-level XML * @param[in] yspec YANG spec - * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @retval 0 OK + * @retval -1 General error, check specific clicon_errno, clicon_suberrno */ static int disable_nacm_on_empty(cxobj *xt, @@ -439,6 +443,7 @@ disable_nacm_on_empty(cxobj *xt, } /*! Common read function that reads an XML tree from file + * * @param[in] th Datastore text handle * @param[in] db Symbolic database name, eg "candidate", "running" * @param[in] yb How to bind yang to XML top-level when parsing @@ -447,9 +452,9 @@ disable_nacm_on_empty(cxobj *xt, * @param[out] de If set, return db-element status (eg empty flag) * @param[out] msdiff If set, return modules-state differences * @param[out] xerr XML error if retval is 0 - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set * @retval 1 OK + * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @note Use of 1 for OK * @note retval 0 is NYI because calling functions cannot handle it yet * XXX if this code pass tests this code can be rewritten, esp the modstate stuff @@ -657,6 +662,7 @@ xmldb_readfile(clicon_handle h, } /*! Get content of database using xpath. return a set of matching sub-trees + * * The function returns a minimal tree that includes all sub-trees that match * xpath. * This is a clixon datastore plugin of the the xmldb api @@ -669,9 +675,9 @@ xmldb_readfile(clicon_handle h, * @param[out] xret Single return XML tree. Free with xml_free() * @param[out] msdiff If set, return modules-state differences * @param[out] xerr XML error if retval is 0 - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set * @retval 1 OK + * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @note Use of 1 for OK * @see xmldb_get the generic API function */ @@ -816,6 +822,7 @@ xmldb_get_nocache(clicon_handle h, } /*! Get content of database using xpath. return a set of matching sub-trees + * * The function returns a minimal tree that includes all sub-trees that match * xpath. * This is a clixon datastore plugin of the the xmldb api @@ -828,9 +835,9 @@ xmldb_get_nocache(clicon_handle h, * @param[out] xtop Single return XML tree. Free with xml_free() * @param[out] msdiff If set, return modules-state differences * @param[out] xerr XML error if retval is 0 - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set * @retval 1 OK + * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @note Use of 1 for OK * @see xmldb_get the generic API function */ @@ -1007,6 +1014,7 @@ xmldb_get_cache(clicon_handle h, } /*! Get the raw cache of whole tree + * * Useful for some higer level usecases for optimized access * This is a clixon datastore plugin of the the xmldb api * @param[in] h Clicon handle @@ -1018,9 +1026,9 @@ xmldb_get_cache(clicon_handle h, * @param[out] xret Single return XML tree. Free with xml_free() * @param[out] msdiff If set, return modules-state differences * @param[out] xerr XML error if retval is 0 - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set * @retval 1 OK + * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @note Use of 1 for OK */ static int @@ -1158,14 +1166,15 @@ xmldb_get_zerocopy(clicon_handle h, } /*! Get content of datastore and return a copy of the XML tree + * * @param[in] h Clicon handle * @param[in] db Name of database to search in, eg "running" * @param[in] nsc XML namespace context for XPATH * @param[in] xpath String with XPATH syntax. or NULL for all * @param[out] xret Single return XML tree. Free with xml_free() - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set * @retval 1 OK + * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @note Use of 1 for OK * @code * if (xmldb_get(xh, "running", NULL, "/interfaces/interface[name="eth"]", &xt) < 0) @@ -1202,9 +1211,9 @@ xmldb_get(clicon_handle h, * @param[out] xret Single return XML tree. Free with xml_free() * @param[out] msdiff If set, return modules-state differences (upgrade code) * @param[out] xerr XML error if retval is 0 - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set * @retval 1 OK + * @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @note Use of 1 for OK * @code * cxobj *xt; @@ -1287,8 +1296,8 @@ xmldb_get0(clicon_handle h, * * @param[in] h Clicon handle * @param[in] db Name of datastore - * @retval -1 General error, check specific clicon_errno, clicon_suberrno - * @retval 0 OK + * @retval 0 OK + * @retval -1 General error, check specific clicon_errno, clicon_suberrno * @note "Clear" an xml tree means removing default values and resetting all flags. * @see xmldb_get0 */ @@ -1316,6 +1325,7 @@ xmldb_get0_clear(clicon_handle h, } /*! Free xml tree obtained with xmldb_get0 + * * @param[in] h Clixon handle * @param[in,out] xp Pointer to XML cache. * @retval 0 Always. diff --git a/lib/src/clixon_datastore_write.c b/lib/src/clixon_datastore_write.c index 1dd90c6e..5bb1f9f9 100644 --- a/lib/src/clixon_datastore_write.c +++ b/lib/src/clixon_datastore_write.c @@ -95,9 +95,9 @@ * @param[in] ns (Expected) Namespace of attribute * @param[out] cbret Error message (if retval=0) * @param[out] valp Malloced value (if retval=1) - * @retval -1 Error - * @retval 0 Failed (cbret set) * @retval 1 OK + * @retval 0 Failed (cbret set) + * @retval -1 Error */ static int attr_ns_value(cxobj *x, @@ -153,9 +153,9 @@ attr_ns_value(cxobj *x, * @param[in] x1bstr Body string of x1 * @param[in] y Yang of x0 (and x1) * @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0. - * @retval -1 Error - * @retval 0 Failed (cbret set) * @retval 1 OK + * @retval 0 Failed (cbret set) + * @retval -1 Error */ static int check_body_namespace(cxobj *x0, @@ -273,9 +273,9 @@ check_body_namespace(cxobj *x0, * @param[in] x1 XML tree which modifies base * @param[in] y0 Yang spec corresponding to xml-node x0. NULL if x0 is NULL * @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0. - * @retval -1 Error - * @retval 0 Failed (cbret set) * @retval 1 OK + * @retval 0 Failed (cbret set) + * @retval -1 Error * @note There may be some combination cases (x0+x1) that are not covered in this function. */ static int @@ -331,8 +331,9 @@ check_when_condition(cxobj *x0p, } /*! Check if x0/y0 is part of other choice/case than y1 recursively , if so purge - * @retval 0 No, y0 it is not in other case than y1 + * * @retval 1 yes, y0 is in other case than y1 + * @retval 0 No, y0 it is not in other case than y1 */ static int choice_is_other(yang_stmt *y0c, @@ -428,6 +429,7 @@ choice_delete_other(cxobj *x0, } /*! Modify a base tree x0 with x1 with yang spec y according to operation op + * * @param[in] h Clicon handle * @param[in] x0 Base xml tree (can be NULL in add scenarios) * @param[in] x0p Parent of x0 @@ -440,9 +442,9 @@ choice_delete_other(cxobj *x0, * @param[in] xnacm NACM XML tree (only if !permit) * @param[in] permit If set, no NACM tests using xnacm required * @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0. - * @retval -1 Error - * @retval 0 Failed (cbret set) * @retval 1 OK + * @retval 0 Failed (cbret set) + * @retval -1 Error * Assume x0 and x1 are same on entry and that y is the spec * @see text_modify_top * RFC 7950 Sec 7.7.9(leaf-list), 7.8.6(lists) @@ -1007,6 +1009,7 @@ text_modify(clicon_handle h, } /* text_modify */ /*! Modify a top-level base tree x0 with modification tree x1 + * * @param[in] h Clicon handle * @param[in] x0t Base xml tree (can be NULL in add scenarios) * @param[in] x1t XML tree which modifies base @@ -1016,9 +1019,9 @@ text_modify(clicon_handle h, * @param[in] xnacm NACM XML tree (only if !permit) * @param[in] permit If set, no NACM tests using xnacm required * @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0. - * @retval -1 Error - * @retval 0 Failed (cbret set) * @retval 1 OK + * @retval 0 Failed (cbret set) + * @retval -1 Error * @see text_modify */ static int