X-Git-Url: http://git.ozlabs.org/?a=blobdiff_plain;f=ccan%2Ftal%2F_info;h=853c69851ad5b9d7af8cdf3fd91d77304fc40248;hb=dfaf896adb74ddf7271c9eee7330f2e3e009345b;hp=2417de1c20af90df8bdff9ad114ccaefa789d6f4;hpb=0e34459a02e2615f50bac2767c7dce6632470946;p=ccan

diff --git a/ccan/tal/_info b/ccan/tal/_info
index 2417de1c..853c6985 100644
--- a/ccan/tal/_info
+++ b/ccan/tal/_info
@@ -12,27 +12,29 @@
  * This allows you to build complex objects based on their lifetimes, eg:
  *
  *  struct foo *X = tal(NULL, struct foo);
- *  X->name = tal_strdup(X, "foo");
+ *  X->val = tal(X, int);
  *
- * and the pointer X->name would be a "child" of the tal context "X";
- * tal_free(X->name) would free X->name as expected, by tal_free(X) would
- * free X and X->name.
+ * and the pointer X->val would be a "child" of the tal context "X";
+ * tal_free(X->val) would free X->val as expected, by tal_free(X) would
+ * free X and X->val.
  *
- * With an overhead of approximately 2.1 pointers per object (vs. talloc's
- * 12 pointers), it's a little slower in freeing single objects, though
- * comparable for allocation and freeing whole object trees).  It does not
- * support talloc's references or failing destructors.
+ * With an overhead of approximately 4 pointers per object
+ * (vs. talloc's 12 pointers), it uses dynamic allocation for
+ * destructors and child lists, so those operations can fail.  It does
+ * not support talloc's references or failing destructors.
+ *
+ * See Also:
+ *	ccan/tal/str (useful string helpers)
  *
  * Example:
  *	#include <stdio.h>
- *	#include <stdarg.h>
  *	#include <err.h>
  *	#include <ccan/talloc/talloc.h>
  *
  *	// A structure containing a popened command.
  *	struct command {
  *		FILE *f;
- *		const char *command;
+ *		char *command;
  *	};
  *
  *	// When struct command is freed, we also want to pclose pipe.
@@ -43,21 +45,22 @@
  *
  *	// This function opens a writable pipe to the given command.
  *	static struct command *open_output_cmd(const tal_t *ctx,
- *					       const char *fmt, ...)
+ *					       const char *a0, const char *a1)
  *	{
- *		va_list ap;
  *		struct command *cmd = tal(ctx, struct command);
  *
  *		if (!cmd)
  *			return NULL;
  *
- *		va_start(ap, fmt);
- *		cmd->command = tal_vasprintf(cmd, fmt, ap);
- *		va_end(ap);
+ *		// Note that tal/str has helpers to make this much easier!
+ *		cmd->command = tal_arrz(cmd, char, strlen(a0) + strlen(a1) + 2);
  *		if (!cmd->command) {
  *			tal_free(cmd);
  *			return NULL;
  *		}
+ *		strcat(cmd->command, a0);
+ *		strcat(cmd->command, " ");
+ *		strcat(cmd->command, a1);
  *
  *		cmd->f = popen(cmd->command, "w");
  *		if (!cmd->f) {
@@ -75,7 +78,7 @@
  *		if (argc != 2)
  *			errx(1, "Usage: %s <command>\n", argv[0]);
  *
- *		cmd = open_output_cmd(NULL, "%s hello", argv[1]);
+ *		cmd = open_output_cmd(NULL, argv[1], "hello");
  *		if (!cmd)
  *			err(1, "Running '%s hello'", argv[1]);
  *		fprintf(cmd->f, "This is a test\n");
@@ -92,9 +95,10 @@ int main(int argc, char *argv[])
 
 	if (strcmp(argv[1], "depends") == 0) {
 		printf("ccan/compiler\n");
-		printf("ccan/hash\n");
 		printf("ccan/likely\n");
 		printf("ccan/list\n");
+		printf("ccan/str\n");
+		printf("ccan/take\n");
 		printf("ccan/typesafe_cb\n");
 		return 0;
 	}