modules: update documentation examples so they compile under ccanlint.
[ccan] / ccan / grab_file / grab_file.h
1 #ifndef CCAN_GRAB_FILE_H
2 #define CCAN_GRAB_FILE_H
3 #include <stdio.h> // For size_t
4
5 /**
6  * grab_fd - read all of a file descriptor into memory
7  * @ctx: the context to tallocate from (often NULL)
8  * @fd: the file descriptor to read from
9  * @size: the (optional) size of the file
10  *
11  * This function reads from the given file descriptor until no more
12  * input is available.  The content is talloced off @ctx, and the size
13  * of the file places in @size if it's non-NULL.  For convenience, the
14  * byte after the end of the content will always be NUL.
15  *
16  * Example:
17  *      #include <ccan/str_talloc/str_talloc.h>
18  *      #include <ccan/talloc/talloc.h>
19  *      ...
20  *      // Return all of standard input, as lines.
21  *      static char **read_stdin_as_lines(void)
22  *      {
23  *              char **lines, *all;
24  *
25  *              all = grab_fd(NULL, 0, NULL);
26  *              if (!all)
27  *                      return NULL;
28  *              lines = strsplit(NULL, all, "\n", NULL);
29  *              talloc_free(all);
30  *              return lines;
31  *      }
32  */
33 void *grab_fd(const void *ctx, int fd, size_t *size);
34
35 /**
36  * grab_file - read all of a file (or stdin) into memory
37  * @ctx: the context to tallocate from (often NULL)
38  * @filename: the file to read (NULL for stdin)
39  * @size: the (optional) size of the file
40  *
41  * This function reads from the given file until no more input is
42  * available.  The content is talloced off @ctx, and the size of the
43  * file places in @size if it's non-NULL.  For convenience, the byte
44  * after the end of the content will always be NUL.
45  *
46  * Example:
47  *      // Return all of a given file, as lines.
48  *      static char **read_file_as_lines(const char *filename)
49  *      {
50  *              char **lines, *all;
51  *
52  *              all = grab_file(NULL, filename, NULL);
53  *              if (!all)
54  *                      return NULL;
55  *              lines = strsplit(NULL, all, "\n", NULL);
56  *              talloc_free(all);
57  *              return lines;
58  *      }
59  */
60 void *grab_file(const void *ctx, const char *filename, size_t *size);
61 #endif /* CCAN_GRAB_FILE_H */