]> git.ozlabs.org Git - ccan/blob - ccan/talloc/_info
crypto/shachain: examples and some documentation.
[ccan] / ccan / talloc / _info
1 #include "config.h"
2 #include <stdio.h>
3 #include <string.h>
4
5 /**
6  * talloc - tree allocator routines
7  *
8  * Talloc is a hierarchical memory pool system with destructors: you keep your
9  * objects in heirarchies reflecting their lifetime.  Every pointer returned
10  * from talloc() is itself a valid talloc context, from which other talloc()s
11  * can be attached.  This means you can do this:
12  *
13  *  struct foo *X = talloc(mem_ctx, struct foo);
14  *  X->name = talloc_strdup(X, "foo");
15  *
16  * and the pointer X->name would be a "child" of the talloc context "X" which
17  * is itself a child of mem_ctx.  So if you do talloc_free(mem_ctx) then it is
18  * all destroyed, whereas if you do talloc_free(X) then just X and X->name are
19  * destroyed, and if you do talloc_free(X->name) then just the name element of
20  * X is destroyed.
21  *
22  * If you think about this, then what this effectively gives you is an n-ary
23  * tree, where you can free any part of the tree with talloc_free().
24  *
25  * Talloc has been measured with a time overhead of around 4% over glibc
26  * malloc, and 48/80 bytes per allocation (32/64 bit).
27  *
28  * This version is based on svn://svnanon.samba.org/samba/branches/SAMBA_4_0/source/lib/talloc revision 23158.
29  *
30  * Example:
31  *      #include <stdio.h>
32  *      #include <stdarg.h>
33  *      #include <err.h>
34  *      #include <ccan/talloc/talloc.h>
35  *
36  *      // A structure containing a popened command.
37  *      struct command
38  *      {
39  *              FILE *f;
40  *              const char *command;
41  *      };
42  *
43  *      // When struct command is freed, we also want to pclose pipe.
44  *      static int close_cmd(struct command *cmd)
45  *      {
46  *              pclose(cmd->f);
47  *              // 0 means "we succeeded, continue freeing"
48  *              return 0;
49  *      }
50  *
51  *      // This function opens a writable pipe to the given command.
52  *      static struct command *open_output_cmd(const void *ctx,
53  *                                             const char *fmt, ...)
54  *      {
55  *              va_list ap;
56  *              struct command *cmd = talloc(ctx, struct command);
57  *
58  *              if (!cmd)
59  *                      return NULL;
60  *
61  *              va_start(ap, fmt);
62  *              cmd->command = talloc_vasprintf(cmd, fmt, ap);
63  *              va_end(ap);
64  *              if (!cmd->command) {
65  *                      talloc_free(cmd);
66  *                      return NULL;
67  *              }
68  *
69  *              cmd->f = popen(cmd->command, "w");
70  *              if (!cmd->f) {
71  *                      talloc_free(cmd);
72  *                      return NULL;
73  *              }
74  *              talloc_set_destructor(cmd, close_cmd);
75  *              return cmd;
76  *      }
77  *
78  *      int main(int argc, char *argv[])
79  *      {
80  *              struct command *cmd;
81  *
82  *              if (argc != 2)
83  *                      errx(1, "Usage: %s <command>\n", argv[0]);
84  *
85  *              cmd = open_output_cmd(NULL, "%s hello", argv[1]);
86  *              if (!cmd)
87  *                      err(1, "Running '%s hello'", argv[1]);
88  *              fprintf(cmd->f, "This is a test\n");
89  *              talloc_free(cmd);
90  *              return 0;
91  *      }
92  *
93  * License: LGPL (v2.1 or any later version)
94  */
95 int main(int argc, char *argv[])
96 {
97         if (argc != 2)
98                 return 1;
99
100         if (strcmp(argv[1], "depends") == 0) {
101                 printf("ccan/compiler\n");
102                 printf("ccan/typesafe_cb\n");
103                 return 0;
104         }
105
106         if (strcmp(argv[1], "testdepends") == 0) {
107                 printf("ccan/failtest\n");
108                 return 0;
109         }
110
111         return 1;
112 }