The visibility field in action replaces in_fish, in_docs and internal.
The defined types are:
VPublic:
A public API. This is exported and documented in all language
bindings, and in guestfish.
VStateTest:
A public API which queries the library state machine. It is exported
and documented in all language bindings, but not guestfish.
VBindTest:
An internal API used only for testing language bindings. It is
guarded by GUESTFS_PRIVATE in the C api, but exported by all other
language bindings as it is required for testing. If language
bindings offer any way to guard use of these apis, that mechanism
should be used. It is not documented anywhere.
VDebug:
A debugging API. It is exported by all language bindings, and in
guestfish, but is not documented anywhere.
VInternal:
An internal-only API. It is guarded by GUESTFS_PRIVATE in the C api,
and not exported at all in any other language binding. It is not
documented anywhere.
This commit rearranges the internal header files.
"src/guestfs-internal.h" is just for the library, as before.
"src/guestfs-internal-frontend.h" is for use by all library, bindings,
tools C code, but NOT the daemon.
"src/guestfs-internal-all.h" is for use by all C code including the
daemon.
This is just code motion, but it has some important consequences:
(1) We can use the CLEANUP_* macros in bindings and tools code.
(2) We can get rid of TMP_TEMPLATE_ON_STACK.
(3) We will (in future) be able to stop bindings and tools code from
using the safe_* allocation functions (which are NOT safe to use
outside the library alone).
Rename guestfs_safe_malloc et al to guestfs___safe_malloc etc.
To use the private functions, code now has to define
-DGUESTFS_PRIVATE_FUNCTIONS=1. This will make it easier for us in
future to work out which programs are using these functions and to
minimize both the number of programs and the functions they are
calling.
Note that the Perl, Python, OCaml, Ruby and Java bindings use
guestfs_safe_* calls. None of the other bindings do. This is a bug
(in the bindings using those functions): these functions will call the
out of memory callback on failure. This function defaults to abort(),
and since this happens from a language binding, there is no way to
change this default.
guestfs_parse_environment_list.
Add a new function for creating a handle:
guestfs_h *guestfs_create_flags (unsigned flags [, ...]);
This variant lets you supply flags and extra arguments, although extra
arguments are not used at the moment.
Of particular interest is the ability to separate the creation of the
handle from the parsing of environment variables like
LIBGUESTFS_DEBUG. guestfs_create does both together, which prevents
us from propagating errors from parsing environment variables back to
the caller (guestfs_create has always printed any errors on stderr and
then just ignored them).
If you are interested in these errors, you can now write:
g = guestfs_create_flags (GUESTFS_CREATE_NO_ENVIRONMENT);
if (!g)
exit (EXIT_FAILURE);
r = guestfs_parse_environment (g);
if (!r)
exit (EXIT_FAILURE);
Also you can *omit* the call to guestfs_parse_environment, which
creates a handle unaffected by the environment (which was not possible
before).
This commit also includes new (backwards compatible) changes to the
OCaml, Perl, Python, Ruby and Java constructors that let you use the
flags.
This is a simple renaming of the files/modules.
Note that in OCaml, module names are derived from filenames by
capitalizing the first letter. Thus the old module names had the form
"Generator_api_versions". The new modules names have the form
"Api_versions".
