or NULL if there was an error.
I<The caller must call C<guestfs_free_%s> after use>.\n\n" typ typ
| RStructList (_, typ) ->
- pr "This function returns a C<struct guestfs_%s_list *>
-(see E<lt>guestfs-structs.hE<gt>),
+ pr "This function returns a C<struct guestfs_%s_list *>,
or NULL if there was an error.
I<The caller must call C<guestfs_free_%s_list> after use>.\n\n" typ typ
| RHashtable _ ->
pr "=back\n";
pr "\n"
-(* Generate the guestfs-structs.h file. *)
-and generate_structs_h () =
+(* Generate the guestfs.h file. *)
+and generate_guestfs_h () =
generate_header CStyle LGPLv2plus;
- (* This is a public exported header file containing various
- * structures. The structures are carefully written to have
- * exactly the same in-memory format as the XDR structures that
- * we use on the wire to the daemon. The reason for creating
- * copies of these structures here is just so we don't have to
- * export the whole of guestfs_protocol.h (which includes much
- * unrelated and XDR-dependent stuff that we don't want to be
- * public, or required by clients).
- *
- * To reiterate, we will pass these structures to and from the
- * client with a simple assignment or memcpy, so the format
- * must be identical to what rpcgen / the RFC defines.
+ pr "\
+/* ---------- IMPORTANT NOTE ----------
+ *
+ * All API documentation is in the manpage, 'guestfs(3)'.
+ * To read it, type: man 3 guestfs
+ * Or read it online here: http://libguestfs.org/guestfs.3.html
+ *
+ * Go and read it now, I'll be right here waiting for you
+ * when you come back.
+ *
+ * ------------------------------------
+ */
+
+#ifndef GUESTFS_H_
+#define GUESTFS_H_
+
+#ifdef __cplusplus
+extern \"C\" {
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdarg.h>
+
+/* The handle. */
+#ifndef GUESTFS_TYPEDEF_H
+#define GUESTFS_TYPEDEF_H 1
+typedef struct guestfs_h guestfs_h;
+#endif
+
+/* Connection management. */
+extern guestfs_h *guestfs_create (void);
+extern void guestfs_close (guestfs_h *g);
+
+/* Error handling. */
+extern const char *guestfs_last_error (guestfs_h *g);
+#define LIBGUESTFS_HAVE_LAST_ERRNO 1
+extern int guestfs_last_errno (guestfs_h *g);
+
+#ifndef GUESTFS_TYPEDEF_ERROR_HANDLER_CB
+#define GUESTFS_TYPEDEF_ERROR_HANDLER_CB 1
+typedef void (*guestfs_error_handler_cb) (guestfs_h *g, void *opaque, const char *msg);
+#endif
+
+#ifndef GUESTFS_TYPEDEF_ABORT_CB
+#define GUESTFS_TYPEDEF_ABORT_CB 1
+typedef void (*guestfs_abort_cb) (void) __attribute__((__noreturn__));
+#endif
+
+extern void guestfs_set_error_handler (guestfs_h *g, guestfs_error_handler_cb cb, void *opaque);
+extern guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g, void **opaque_rtn);
+
+extern void guestfs_set_out_of_memory_handler (guestfs_h *g, guestfs_abort_cb);
+extern guestfs_abort_cb guestfs_get_out_of_memory_handler (guestfs_h *g);
+
+/* Events. */
+#ifndef GUESTFS_TYPEDEF_LOG_MESSAGE_CB
+#define GUESTFS_TYPEDEF_LOG_MESSAGE_CB 1
+typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, char *buf, int len);
+#endif
+
+#ifndef GUESTFS_TYPEDEF_SUBPROCESS_QUIT_CB
+#define GUESTFS_TYPEDEF_SUBPROCESS_QUIT_CB 1
+typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque);
+#endif
+
+#ifndef GUESTFS_TYPEDEF_LAUNCH_DONE_CB
+#define GUESTFS_TYPEDEF_LAUNCH_DONE_CB 1
+typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque);
+#endif
+
+#ifndef GUESTFS_TYPEDEF_CLOSE_CB
+#define GUESTFS_TYPEDEF_CLOSE_CB 1
+typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque);
+#endif
+
+#ifndef GUESTFS_TYPEDEF_PROGRESS_CB
+#define GUESTFS_TYPEDEF_PROGRESS_CB 1
+typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque, int proc_nr, int serial, uint64_t position, uint64_t total);
+#endif
+
+extern void guestfs_set_log_message_callback (guestfs_h *g, guestfs_log_message_cb cb, void *opaque);
+extern void guestfs_set_subprocess_quit_callback (guestfs_h *g, guestfs_subprocess_quit_cb cb, void *opaque);
+extern void guestfs_set_launch_done_callback (guestfs_h *g, guestfs_launch_done_cb cb, void *opaque);
+#define LIBGUESTFS_HAVE_SET_CLOSE_CALLBACK 1
+extern void guestfs_set_close_callback (guestfs_h *g, guestfs_close_cb cb, void *opaque);
+#define LIBGUESTFS_HAVE_SET_PROGRESS_CALLBACK 1
+extern void guestfs_set_progress_callback (guestfs_h *g, guestfs_progress_cb cb, void *opaque);
+
+/* Private data area. */
+#define LIBGUESTFS_HAVE_SET_PRIVATE 1
+extern void guestfs_set_private (guestfs_h *g, const char *key, void *data);
+#define LIBGUESTFS_HAVE_GET_PRIVATE 1
+extern void *guestfs_get_private (guestfs_h *g, const char *key);
+
+/* Structures. */
+";
+
+ (* The structures are carefully written to have exactly the same
+ * in-memory format as the XDR structures that we use on the wire to
+ * the daemon. The reason for creating copies of these structures
+ * here is just so we don't have to export the whole of
+ * guestfs_protocol.h (which includes much unrelated and
+ * XDR-dependent stuff that we don't want to be public, or required
+ * by clients).
+ *
+ * To reiterate, we will pass these structures to and from the client
+ * with a simple assignment or memcpy, so the format must be
+ * identical to what rpcgen / the RFC defines.
*)
(* Public structures. *)
pr "extern void guestfs_free_%s (struct guestfs_%s *);\n" typ typ;
pr "extern void guestfs_free_%s_list (struct guestfs_%s_list *);\n" typ typ;
pr "\n"
- ) structs
+ ) structs;
+
+ pr "\
+/* Actions. */
+";
-(* Generate the guestfs-actions.h file. *)
-and generate_actions_h () =
- generate_header CStyle LGPLv2plus;
List.iter (
fun (shortname, (ret, args, optargs as style), _, flags, _, _, _) ->
let deprecated =
~prefix:"guestfs_" ~suffix:"_argv" ~optarg_proto:Argv
shortname style;
);
- ) all_functions_sorted
+ ) all_functions_sorted;
+
+ pr "\
+
+/* Private functions.
+ *
+ * These are NOT part of the public, stable API, and can change at any
+ * time! We export them because they are used by some of the language
+ * bindings.
+ */
+extern void *guestfs_safe_malloc (guestfs_h *g, size_t nbytes);
+extern void *guestfs_safe_calloc (guestfs_h *g, size_t n, size_t s);
+extern const char *guestfs_tmpdir (void);
+/* End of private functions. */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* GUESTFS_H_ */
+"
(* Generate the guestfs-internal-actions.h file. *)
and generate_internal_actions_h () =
(* Generate code to generate guestfish call traces. *)
let trace_call shortname (ret, args, optargs) =
- pr " if (guestfs__get_trace (g)) {\n";
+ pr " if (trace_flag) {\n";
let needs_i =
List.exists (function
);
) optargs;
- pr " fputc ('\\n', stderr);\n";
pr " }\n";
pr "\n";
in
+ let trace_return ?(indent = 2) (ret, _, _) rv =
+ let indent = spaces indent in
+
+ pr "%sif (trace_flag) {\n" indent;
+
+ let needs_i =
+ match ret with
+ | RStringList _ | RHashtable _ -> true
+ | _ -> false in
+ if needs_i then (
+ pr "%s size_t i;\n" indent;
+ pr "\n"
+ );
+
+ pr "%s fputs (\" = \", stderr);\n" indent;
+ (match ret with
+ | RErr | RInt _ | RBool _ ->
+ pr "%s fprintf (stderr, \"%%d\", %s);\n" indent rv
+ | RInt64 _ ->
+ pr "%s fprintf (stderr, \"%%\" PRIi64, %s);\n" indent rv
+ | RConstString _ | RString _ ->
+ pr "%s fprintf (stderr, \"\\\"%%s\\\"\", %s);\n" indent rv
+ | RConstOptString _ ->
+ pr "%s fprintf (stderr, \"\\\"%%s\\\"\", %s != NULL ? %s : \"NULL\");\n"
+ indent rv rv
+ | RBufferOut _ ->
+ pr "%s guestfs___print_BufferOut (stderr, %s, *size_r);\n" indent rv
+ | RStringList _ | RHashtable _ ->
+ pr "%s fputs (\"[\\\"\", stderr);\n" indent;
+ pr "%s for (i = 0; %s[i]; ++i) {\n" indent rv;
+ pr "%s if (i > 0) fputs (\"\\\", \\\"\", stderr);\n" indent;
+ pr "%s fputs (%s[i], stderr);\n" indent rv;
+ pr "%s }\n" indent;
+ pr "%s fputs (\"\\\"]\", stderr);\n" indent;
+ | RStruct (_, typ) ->
+ (* XXX There is code generated for guestfish for printing
+ * these structures. We need to make it generally available
+ * for all callers
+ *)
+ pr "%s fprintf (stderr, \"<struct guestfs_%s *>\");\n"
+ indent typ (* XXX *)
+ | RStructList (_, typ) ->
+ pr "%s fprintf (stderr, \"<struct guestfs_%s_list *>\");\n"
+ indent typ (* XXX *)
+ );
+ pr "%s fputc ('\\n', stderr);\n" indent;
+ pr "%s}\n" indent;
+ pr "\n";
+ in
+
+ let trace_return_error ?(indent = 2) (ret, _, _) =
+ let indent = spaces indent in
+
+ pr "%sif (trace_flag)\n" indent;
+
+ (match ret with
+ | RErr | RInt _ | RBool _
+ | RInt64 _ ->
+ pr "%s fputs (\" = -1 (error)\\n\", stderr);\n" indent
+ | RConstString _ | RString _
+ | RConstOptString _
+ | RBufferOut _
+ | RStringList _ | RHashtable _
+ | RStruct _
+ | RStructList _ ->
+ pr "%s fputs (\" = NULL (error)\\n\", stderr);\n" indent
+ );
+ in
+
(* For non-daemon functions, generate a wrapper around each function. *)
List.iter (
- fun (shortname, (_, _, optargs as style), _, _, _, _, _) ->
+ fun (shortname, (ret, _, optargs as style), _, _, _, _, _) ->
if optargs = [] then
generate_prototype ~extern:false ~semicolon:false ~newline:true
~handle:"g" ~prefix:"guestfs_"
~handle:"g" ~prefix:"guestfs_" ~suffix:"_argv" ~optarg_proto:Argv
shortname style;
pr "{\n";
+ pr " int trace_flag = g->trace;\n";
+ (match ret with
+ | RErr | RInt _ | RBool _ ->
+ pr " int r;\n"
+ | RInt64 _ ->
+ pr " int64_t r;\n"
+ | RConstString _ | RConstOptString _ ->
+ pr " const char *r;\n"
+ | RString _ | RBufferOut _ ->
+ pr " char *r;\n"
+ | RStringList _ | RHashtable _ ->
+ pr " char **r;\n"
+ | RStruct (_, typ) ->
+ pr " struct guestfs_%s *r;\n" typ
+ | RStructList (_, typ) ->
+ pr " struct guestfs_%s_list *r;\n" typ
+ );
+ pr "\n";
check_null_strings shortname style;
reject_unknown_optargs shortname style;
trace_call shortname style;
- pr " return guestfs__%s " shortname;
+ pr " r = guestfs__%s " shortname;
generate_c_call_args ~handle:"g" style;
pr ";\n";
+ trace_return style "r";
+ pr " return r;\n";
pr "}\n";
pr "\n"
) non_daemon_functions;
pr " int serial;\n";
pr " int r;\n";
+ pr " int trace_flag = g->trace;\n";
+ (match ret with
+ | RErr | RInt _ | RBool _ ->
+ pr " int ret_v;\n"
+ | RInt64 _ ->
+ pr " int64_t ret_v;\n"
+ | RConstString _ | RConstOptString _ ->
+ pr " const char *ret_v;\n"
+ | RString _ | RBufferOut _ ->
+ pr " char *ret_v;\n"
+ | RStringList _ | RHashtable _ ->
+ pr " char **ret_v;\n"
+ | RStruct (_, typ) ->
+ pr " struct guestfs_%s *ret_v;\n" typ
+ | RStructList (_, typ) ->
+ pr " struct guestfs_%s_list *ret_v;\n" typ
+ );
pr "\n";
check_null_strings shortname style;
reject_unknown_optargs shortname style;
trace_call shortname style;
- pr " if (check_state (g, \"%s\") == -1) return %s;\n"
- shortname error_code;
+ pr " if (check_state (g, \"%s\") == -1) {\n" shortname;
+ trace_return_error ~indent:4 style;
+ pr " return %s;\n" error_code;
+ pr " }\n";
pr " guestfs___set_busy (g);\n";
pr "\n";
| BufferIn n ->
pr " /* Just catch grossly large sizes. XDR encoding will make this precise. */\n";
pr " if (%s_size >= GUESTFS_MESSAGE_MAX) {\n" n;
+ trace_return_error ~indent:4 style;
pr " error (g, \"%%s: size of input buffer too large\", \"%s\");\n"
shortname;
pr " guestfs___end_busy (g);\n";
);
pr " if (serial == -1) {\n";
pr " guestfs___end_busy (g);\n";
+ trace_return_error ~indent:4 style;
pr " return %s;\n" error_code;
pr " }\n";
pr "\n";
pr " r = guestfs___send_file (g, %s);\n" n;
pr " if (r == -1) {\n";
pr " guestfs___end_busy (g);\n";
+ trace_return_error ~indent:4 style;
pr " return %s;\n" error_code;
pr " }\n";
pr " if (r == -2) /* daemon cancelled */\n";
pr " if (r == -1) {\n";
pr " guestfs___end_busy (g);\n";
+ trace_return_error ~indent:4 style;
pr " return %s;\n" error_code;
pr " }\n";
pr "\n";
pr " if (check_reply_header (g, &hdr, GUESTFS_PROC_%s, serial) == -1) {\n"
(String.uppercase shortname);
pr " guestfs___end_busy (g);\n";
+ trace_return_error ~indent:4 style;
pr " return %s;\n" error_code;
pr " }\n";
pr "\n";
pr " if (hdr.status == GUESTFS_STATUS_ERROR) {\n";
+ trace_return_error ~indent:4 style;
pr " int errnum = 0;\n";
pr " if (err.errno_string[0] != '\\0')\n";
pr " errnum = guestfs___string_to_errno (err.errno_string);\n";
| FileOut n ->
pr " if (guestfs___recv_file (g, %s) == -1) {\n" n;
pr " guestfs___end_busy (g);\n";
+ trace_return_error ~indent:4 style;
pr " return %s;\n" error_code;
pr " }\n";
pr "\n";
pr " guestfs___end_busy (g);\n";
(match ret with
- | RErr -> pr " return 0;\n"
+ | RErr ->
+ pr " ret_v = 0;\n"
| RInt n | RInt64 n | RBool n ->
- pr " return ret.%s;\n" n
+ pr " ret_v = ret.%s;\n" n
| RConstString _ | RConstOptString _ ->
failwithf "RConstString|RConstOptString cannot be used by daemon functions"
| RString n ->
- pr " return ret.%s; /* caller will free */\n" n
+ pr " ret_v = ret.%s; /* caller will free */\n" n
| RStringList n | RHashtable n ->
pr " /* caller will free this, but we need to add a NULL entry */\n";
pr " ret.%s.%s_val =\n" n n;
pr " sizeof (char *) * (ret.%s.%s_len + 1));\n"
n n;
pr " ret.%s.%s_val[ret.%s.%s_len] = NULL;\n" n n n n;
- pr " return ret.%s.%s_val;\n" n n
+ pr " ret_v = ret.%s.%s_val;\n" n n
| RStruct (n, _) ->
pr " /* caller will free this */\n";
- pr " return safe_memdup (g, &ret.%s, sizeof (ret.%s));\n" n n
+ pr " ret_v = safe_memdup (g, &ret.%s, sizeof (ret.%s));\n" n n
| RStructList (n, _) ->
pr " /* caller will free this */\n";
- pr " return safe_memdup (g, &ret.%s, sizeof (ret.%s));\n" n n
+ pr " ret_v = safe_memdup (g, &ret.%s, sizeof (ret.%s));\n" n n
| RBufferOut n ->
pr " /* RBufferOut is tricky: If the buffer is zero-length, then\n";
pr " * _val might be NULL here. To make the API saner for\n";
pr " */\n";
pr " if (ret.%s.%s_len > 0) {\n" n n;
pr " *size_r = ret.%s.%s_len;\n" n n;
- pr " return ret.%s.%s_val; /* caller will free */\n" n n;
+ pr " ret_v = ret.%s.%s_val; /* caller will free */\n" n n;
pr " } else {\n";
pr " free (ret.%s.%s_val);\n" n n;
pr " char *p = safe_malloc (g, 1);\n";
pr " *size_r = ret.%s.%s_len;\n" n n;
- pr " return p;\n";
+ pr " ret_v = p;\n";
pr " }\n";
);
-
+ trace_return style "ret_v";
+ pr " return ret_v;\n";
pr "}\n\n"
) daemon_functions;