From: Martin Willi <martin@revosec.ch>
Date: Tue, 6 May 2014 10:28:03 +0000 (+0200)
Subject: vici: Document errno values to expect from libvici API
X-Git-Tag: 5.2.0dr3~9^2~6
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e0a34ee4591b4b86ba536f01512a47d238f722dc;p=thirdparty%2Fstrongswan.git

vici: Document errno values to expect from libvici API
---

diff --git a/src/libcharon/plugins/vici/libvici.c b/src/libcharon/plugins/vici/libvici.c
index 211fefd57f..6e3b85a720 100644
--- a/src/libcharon/plugins/vici/libvici.c
+++ b/src/libcharon/plugins/vici/libvici.c
@@ -532,7 +532,7 @@ char* vici_parse_value_str(vici_res_t *res)
 		case VICI_KEY_VALUE:
 			if (!chunk_printable(res->value, NULL, 0))
 			{
-				errno = EINVAL;
+				errno = EBADMSG;
 				return NULL;
 			}
 			val = strndup(res->value.ptr, res->value.len);
diff --git a/src/libcharon/plugins/vici/libvici.h b/src/libcharon/plugins/vici/libvici.h
index 04d8f4a8e1..6957a00b65 100644
--- a/src/libcharon/plugins/vici/libvici.h
+++ b/src/libcharon/plugins/vici/libvici.h
@@ -247,8 +247,12 @@ void vici_end_list(vici_req_t *req);
 /**
  * Submit a request message, and wait for response.
  *
- * On error, NULL is returned an errno is set appropriately. The request
- * messages gets cleaned up by this call and gets invalid.
+ * The request messages gets cleaned up by this call and gets invalid.
+ * On error, NULL is returned an errno is set to:
+ * - EINVAL if the request is invalid/incomplete
+ * - ENOENT if the command is unknown
+ * - EBADMSG if the response is invalid
+ * - Any other IO related errno
  *
  * @param req		request message to send
  * @param conn		connection context to send message over
@@ -269,7 +273,8 @@ void vici_free_req(vici_req_t *req);
 /**
  * Dump a message text representation to a FILE stream.
  *
- * On error, errno is set appropriately.
+ * On error, errno is set to:
+ * - EBADMSG if the message is invalid
  *
  * @param res		response message to dump
  * @param label		a label to print for this message
@@ -294,7 +299,8 @@ vici_parse_t vici_parse(vici_res_t *res);
  *
  * The string is valid until vici_free_res() is called.
  *
- * On error, errno is set appropriately.
+ * On error, errno is set to:
+ *- EINVAL if not in valid parser state
  *
  * @param res		response message to parse
  * @return			name tag / key, NULL on error
@@ -321,7 +327,8 @@ int vici_parse_name_eq(vici_res_t *res, char *name);
  *
  * The string is valid until vici_free_res() is called.
  *
- * On error, errno is set appropriately.
+ * On error, errno is set to:
+ * - EINVAL if not in valid parser state
  *
  * @param len		pointer receiving value length
  * @return			pointer to value, NULL on error
@@ -337,7 +344,9 @@ void* vici_parse_value(vici_res_t *res, int *len);
  * This call is successful only if the value contains no non-printable
  * characters. The string is valid until vici_free_res() is called.
  *
- * On error, errno is set appropriately.
+ * On error, errno is set to:
+ * - EBADMSG if value is not a printable string
+ * - EINVAL if not in valid parser state
  *
  * @param res		response message to parse
  * @return			value as string, NULL on error
@@ -351,7 +360,9 @@ char* vici_parse_value_str(vici_res_t *res);
  * invoked for the current section level only. To descent into sections, call
  * vici_parse_cb() from within a section callback.
  *
- * On error, errno is set appropriately.
+ * On error, errno is set to:
+ * - EBADMSG if message encoding invalid
+ * - Any other errno set by the invoked callbacks
  *
  * @param res		message to parse
  * @param section	callback invoked for each section
@@ -417,7 +428,11 @@ void vici_free_res(vici_res_t *res);
  * (Un-)Register for events of a given kind.
  *
  * Events callbacks get invoked by a different thread from the libstrongswan
- * thread pool. On failure, errno is set appropriately.
+ * thread pool.
+ * On failure, errno is set to:
+ * - ENOENT if the event name is unknown
+ * - EBADMSG if the response is invalid
+ * - Any other IO related errno
  *
  * @param conn		connection context
  * @param name		name of event messages to register to