Add a few notes on the return value of uci_lookup_ptr().

[project/uci.git] / uci.h

diff --git a/uci.h b/uci.h
index b31d00795804bd1e443725eb83a328ffcde92042..abba660826c33fd64acc3e46a2d6f5f1510dfd04 100644 (file)
--- a/uci.h
+++ b/uci.h
@@ -154,6 +154,13 @@ extern int uci_unload(struct uci_context *ctx, struct uci_package *p);
  * Note: uci_lookup_ptr will automatically load a config package if necessary
  * @str must not be constant, as it will be modified and used for the strings inside @ptr,
  * thus it must also be available as long as @ptr is in use.
+ *
+ * This function returns UCI_ERR_NOTFOUND if the package specified in the tuple
+ * string cannot be found.  Otherwise it will return UCI_OK.
+ *
+ * Note that failures in looking up other parts, if they are also specfied,
+ * including section and option, will also have a return value UCI_OK but with
+ * ptr->flags * UCI_LOOKUP_COMPLETE not set.
  */
 extern int uci_lookup_ptr(struct uci_context *ctx, struct uci_ptr *ptr, char *str, bool extended);