X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=generator%2Fgenerator_c.ml;h=b25d24b3855a67489ad3be5a309c87cfaa5ba717;hp=13040f0b010f95bf272ad65fc971ae7517d5a680;hb=6c6aa111795b20533a99a7e38b614b2aa1c0ccb7;hpb=19ea54b3f488755731ffc079519d6011dade9e5c diff --git a/generator/generator_c.ml b/generator/generator_c.ml index 13040f0..b25d24b 100644 --- a/generator/generator_c.ml +++ b/generator/generator_c.ml @@ -24,6 +24,7 @@ open Generator_types open Generator_utils open Generator_pr open Generator_docstrings +open Generator_api_versions open Generator_optgroups open Generator_actions open Generator_structs @@ -115,6 +116,9 @@ let rec generate_prototype ?(extern = true) ?(static = false) pr "const char *%s" n; next (); pr "size_t %s_size" n + | Pointer (t, n) -> + next (); + pr "%s %s" t n ) args; if is_RBufferOut then (next (); pr "size_t *size_r"); if optargs <> [] then ( @@ -225,8 +229,7 @@ I.\n\n" or NULL if there was an error. I after use>.\n\n" typ typ | RStructList (_, typ) -> - pr "This function returns a C -(see Eguestfs-structs.hE), + pr "This function returns a C, or NULL if there was an error. I after use>.\n\n" typ typ | RHashtable _ -> @@ -254,6 +257,10 @@ L for more information.\n\n"; | None -> () | Some txt -> pr "%s\n\n" txt ); + (match lookup_api_version name with + | Some version -> pr "(Added in %s)\n\n" version + | None -> () + ); (* Handling of optional argument variants. *) if optargs <> [] then ( @@ -329,22 +336,119 @@ and generate_availability_pod () = 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 +#include +#include + +/* 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. *) @@ -375,11 +479,12 @@ and generate_structs_h () = 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 = @@ -427,7 +532,27 @@ and generate_actions_h () = ~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 () = @@ -531,7 +656,8 @@ check_state (guestfs_h *g, const char *caller) | BufferIn n | StringList n | DeviceList n - | Key n -> + | Key n + | Pointer (_, n) -> pr " if (%s == NULL) {\n" n; pr " error (g, \"%%s: %%s: parameter cannot be NULL\",\n"; pr " \"%s\", \"%s\");\n" shortname n; @@ -586,7 +712,7 @@ check_state (guestfs_h *g, const char *caller) (* 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 @@ -607,10 +733,12 @@ check_state (guestfs_h *g, const char *caller) | Pathname n | Dev_or_Path n | FileIn n - | FileOut n - | Key n -> + | FileOut n -> (* guestfish doesn't support string escaping, so neither do we *) pr " fprintf (stderr, \" \\\"%%s\\\"\", %s);\n" n + | Key n -> + (* don't print keys *) + pr " fprintf (stderr, \" \\\"***\\\"\");\n" | OptString n -> (* string option *) pr " if (%s) fprintf (stderr, \" \\\"%%s\\\"\", %s);\n" n n; pr " else fprintf (stderr, \" null\");\n" @@ -632,6 +760,8 @@ check_state (guestfs_h *g, const char *caller) | BufferIn n -> (* RHBZ#646822 *) pr " fputc (' ', stderr);\n"; pr " guestfs___print_BufferIn (stderr, %s, %s_size);\n" n n + | Pointer (t, n) -> + pr " fprintf (stderr, \" (%s)%%p\", %s);\n" t n ) args; (* Optional arguments. *) @@ -662,7 +792,7 @@ check_state (guestfs_h *g, const char *caller) (* 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_" @@ -672,12 +802,31 @@ check_state (guestfs_h *g, const char *caller) ~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"; + pr " return r;\n"; pr "}\n"; pr "\n" ) non_daemon_functions; @@ -722,6 +871,23 @@ check_state (guestfs_h *g, const char *caller) 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; @@ -763,6 +929,7 @@ check_state (guestfs_h *g, const char *caller) pr " }\n"; pr " args.%s.%s_val = (char *) %s;\n" n n n; pr " args.%s.%s_len = %s_size;\n" n n n + | Pointer _ -> assert false ) args; pr " serial = guestfs___send (g, GUESTFS_PROC_%s,\n" (String.uppercase shortname); @@ -851,13 +1018,14 @@ check_state (guestfs_h *g, const char *caller) 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; @@ -865,13 +1033,13 @@ check_state (guestfs_h *g, const char *caller) 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"; @@ -880,15 +1048,15 @@ check_state (guestfs_h *g, const char *caller) 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"; ); - + pr " return ret_v;\n"; pr "}\n\n" ) daemon_functions;