X-Git-Url: https://git.ozlabs.org/?a=blobdiff_plain;f=ccan%2Fstring%2Fstring.h;h=3bc7adfd006f034b037e9beea06b200bc51be392;hb=8d43fa7458b0102d440f242f1a3a1b45fbb41827;hp=14a9c2c8fdba86eedbb4c0845c5cd24d69035b34;hpb=16b7eb13fbcb1a04a71622e6310020baccc3c39c;p=ccan

diff --git a/ccan/string/string.h b/ccan/string/string.h
index 14a9c2c8..3bc7adfd 100644
--- a/ccan/string/string.h
+++ b/ccan/string/string.h
@@ -103,7 +103,57 @@ char **strsplit(const void *ctx, const char *string, const char *delims,
  */
 char *strjoin(const void *ctx, char *strings[], const char *delim);
 
-void *grab_fd(const void *ctx, int fd);
+/**
+ * grab_fd - read all of a file descriptor into memory
+ * @ctx: the context to tallocate from (often NULL)
+ * @fd: the file descriptor to read from
+ * @size: the (optional) size of the file
+ *
+ * This function reads from the given file descriptor until no more
+ * input is available.  The content is talloced off @ctx, and the size
+ * of the file places in @size if it's non-NULL.  For convenience, the
+ * byte after the end of the content will always be NUL.
+ *
+ * Example:
+ *	// Return all of standard input, as lines.
+ *	char **read_as_lines(void)
+ *	{
+ *		char **lines, *all;
+ *
+ *		all = grab_fd(NULL, 0, NULL);
+ *		if (!all)
+ *			return NULL;
+ *		lines = strsplit(NULL, all, "\n", NULL);
+ *		talloc_free(all);
+ *		return lines;
+ *	}
+ */
+void *grab_fd(const void *ctx, int fd, size_t *size);
 
-void *grab_file(const void *ctx, const char *filename);
+/**
+ * grab_file - read all of a file (or stdin) into memory
+ * @ctx: the context to tallocate from (often NULL)
+ * @filename: the file to read (NULL for stdin)
+ * @size: the (optional) size of the file
+ *
+ * This function reads from the given file until no more input is
+ * available.  The content is talloced off @ctx, and the size of the
+ * file places in @size if it's non-NULL.  For convenience, the byte
+ * after the end of the content will always be NUL.
+ *
+ * Example:
+ *	// Return all of a given file, as lines.
+ *	char **read_as_lines(const char *filename)
+ *	{
+ *		char **lines, *all;
+ *
+ *		all = grab_file(NULL, filename, NULL);
+ *		if (!all)
+ *			return NULL;
+ *		lines = strsplit(NULL, all, "\n", NULL);
+ *		talloc_free(all);
+ *		return lines;
+ *	}
+ */
+void *grab_file(const void *ctx, const char *filename, size_t *size);
 #endif /* CCAN_STRING_H */