[lttng-dev] [PATCH] lttng-tools lttng commands calibrate.c : Return values of the cmd_calibrate() chain of functions

[Thibault, Daniel]

Improve lttng/commands/calibrate.c usage() printout.
Document and enforce the expected return values for the cmd_calibrate() chain of functions.
This includes a couple of documentation lines in lib/lttng-ctl/lttng-ctl.c.
------------------------------
>From 4c9089ec185d72c9e457dc6656323ae0e2939ae3 Thu, 26 Jan 2012 16:05:04 -0500
From: Daniel U. Thibault <daniel.thibault at drdc-rddc.gc.ca>
Date: Thu, 26 Jan 2012 16:04:41 -0500
Subject: [PATCH] lttng-tools lttng commands calibrate.c : Return values of the cmd_calibrate() chain of functions

diff --git a/src/bin/lttng/commands/calibrate.c b/src/bin/lttng/commands/calibrate.c
index 81eadbf..1af1807 100644
--- a/src/bin/lttng/commands/calibrate.c
+++ b/src/bin/lttng/commands/calibrate.c
@@ -89,14 +89,14 @@
 	fprintf(ofp, "\n");
 	fprintf(ofp, "  -h, --help               Show this help\n");
 	fprintf(ofp, "      --list-options       Simple listing of options\n");
-	fprintf(ofp, "  -k, --kernel             Apply for the kernel tracer\n");
+	fprintf(ofp, "  -k, --kernel             Apply to the kernel tracer\n");
 #if 0
-	fprintf(ofp, "  -u, --userspace [CMD]    Apply for the user-space tracer\n");
-	fprintf(ofp, "                           If no CMD, the domain used is UST global\n");
-	fprintf(ofp, "                           or else the domain is UST EXEC_NAME\n");
+	fprintf(ofp, "  -u, --userspace [CMD]    Apply to the user-space tracer (domain: UST\n");
+	fprintf(ofp, "                           EXEC_NAME). If no CMD, the domain is UST globa.\n");
+	fprintf(ofp, "                           (-k preempts -u)\n");
 	fprintf(ofp, "  -p, --pid PID            If -u, apply to specific PID (domain: UST PID)\n");
 #else
-	fprintf(ofp, "  -u, --userspace          Apply for the user-space tracer\n");
+	fprintf(ofp, "  -u, --userspace          Apply to the user-space tracer\n");
 #endif
 	fprintf(ofp, "\n");
 	fprintf(ofp, "Calibrate options:\n");
@@ -120,6 +120,7 @@
  *  calibrate_lttng
  *
  *  Calibrate LTTng.
+ *  Returns one of the CMD_* result constants.
  */
 static int calibrate_lttng(void)
 {
@@ -140,7 +141,7 @@
 
 	handle = lttng_create_handle(NULL, &dom);
 	if (handle == NULL) {
-		ret = -1;
+		ret = CMD_ERROR;
 		goto error;
 	}
 
@@ -154,9 +155,17 @@
 	case LTTNG_EVENT_FUNCTION:
 		DBG("Calibrating kernel functions");
 		calibrate.type = LTTNG_CALIBRATE_FUNCTION;
+		/*
+		 * lttng_calibrate() returns the size of
+		 * the returned session payload data
+		 * or a negative error code.
+		 */
 		ret = lttng_calibrate(handle, &calibrate);
 		if (ret < 0) {
+			ret = CMD_ERROR;
 			goto error;
+		} else {
+			ret = CMD_SUCCESS;
 		}
 		MSG("%s calibration done", opt_kernel ? "Kernel" : "UST");
 		break;
@@ -181,6 +190,7 @@
  *  cmd_calibrate
  *
  *  Calibrate LTTng tracer.
+ *  Returns one of the CMD_* result constants.
  */
 int cmd_calibrate(int argc, const char **argv)
 {
@@ -196,7 +206,7 @@
 	while ((opt = poptGetNextOpt(pc)) != -1) {
 		switch (opt) {
 		case OPT_HELP:
-			usage(stderr);
+			usage(stdout);
 			ret = CMD_SUCCESS;
 			goto end;
 		case OPT_TRACEPOINT:
diff --git a/src/lib/lttng-ctl/lttng-ctl.c b/src/lib/lttng-ctl/lttng-ctl.c
index b7fc781..e7ebab5 100644
--- a/src/lib/lttng-ctl/lttng-ctl.c
+++ b/src/lib/lttng-ctl/lttng-ctl.c
@@ -302,7 +302,7 @@
 /*
  * Ask the session daemon a specific command and put the data into buf.
  *
- * Return size of data (only payload, not header).
+ * Return size of data (only payload, not header) or a negative error code.
  */
 static int ask_sessiond(struct lttcomm_session_msg *lsm, void **buf)
 {
@@ -808,6 +808,7 @@
 
 /*
  *  lttng_calibrate
+ *  Returns size of returned session payload data or a negative error code.
  */
 int lttng_calibrate(struct lttng_handle *handle,
 		struct lttng_calibrate *calibrate)
------------------------------

Daniel U. Thibault
R & D pour la défense Canada - Valcartier (RDDC Valcartier) / Defence R&D Canada - Valcartier (DRDC Valcartier)
Système de systèmes (SdS) / System of Systems (SoS)
Solutions informatiques et expérimentations (SIE) / Computing Solutions and Experimentations (CSE)
2459 Boul. Pie XI Nord
Québec, QC  G3J 1X5
CANADA
Vox : (418) 844-4000 x4245
Fax : (418) 844-4538
NAC: 918V QSDJ
Gouvernement du Canada / Government of Canada
<http://www.valcartier.drdc-rddc.gc.ca/>