March 2017 - Libguestfs - libguestfs List Archives

[PATCH 0/6] Various Coverity fixes #2
by Pino Toscano 06 Mar '17

06 Mar '17

Hi, this patch series fixes few more issues discovered by Coverity. Thanks, Pino Toscano (6): tail: check the return value pf guestfs_set_pgroup daemon: btrfs: check end_stringsbuf return values everywhere java: use cleanup handlers for structs (lists) as return values lib: qemu: improve handling of FILE* p2v: check more return values p2v: fix possible close(-1) issue cat/tail.c | 5 ++- daemon/btrfs.c | 3 +- generator/java.ml | 8 ++--- lib/qemu.c | 104 +++++++++++++++++++++++++++--------------------------- p2v/nbd.c | 19 +++++++--- 5 files changed, 77 insertions(+), 62 deletions(-) -- 2.9.3

2 7

[PATCH] v2v, p2v: rename rhvm network to ovirtmgmt (RHBZ#1429491)
by Pino Toscano 06 Mar '17

06 Mar '17

Since RHV 3.6.10, the default network name is 'ovirtmgmt' instead of 'rhvm'. This is just a documentation change. --- p2v/virt-p2v.pod | 10 +++++----- v2v/cmdline.ml | 2 +- v2v/virt-v2v.pod | 12 ++++++------ 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/p2v/virt-p2v.pod b/p2v/virt-p2v.pod index ea685be..4a5f587 100644 --- a/p2v/virt-p2v.pod +++ b/p2v/virt-p2v.pod @@ -393,14 +393,14 @@ interfaces to the target C<default> network. You give a comma-separated list of C<interface:target> pairs, plus optionally a default target. For example: - p2v.network=em1:rhvm + p2v.network=em1:ovirtmgmt -maps interface C<em1> to target network C<rhvm>. +maps interface C<em1> to target network C<ovirtmgmt>. - p2v.network=em1:rhvm,em2:management,other + p2v.network=em1:ovirtmgmt,em2:management,other -maps interface C<em1> to C<rhvm>, and C<em2> to C<management>, and -any other interface that is found to C<other>. +maps interface C<em1> to C<ovirtmgmt>, and C<em2> to C<management>, +and any other interface that is found to C<other>. =item B<p2v.o=[libvirt|local|...]> diff --git a/v2v/cmdline.ml b/v2v/cmdline.ml index 7135cfe..f417dea 100644 --- a/v2v/cmdline.ml +++ b/v2v/cmdline.ml @@ -220,7 +220,7 @@ let parse_cmdline () = virt-v2v -ic vpx://vcenter.example.com/Datacenter/esxi -os imported esx_guest virt-v2v -ic vpx://vcenter.example.com/Datacenter/esxi esx_guest \ - -o rhv -os rhv.nfs:/export_domain --network rhvm + -o rhv -os rhv.nfs:/export_domain --network ovirtmgmt virt-v2v -i libvirtxml guest-domain.xml -o local -os /var/tmp diff --git a/v2v/virt-v2v.pod b/v2v/virt-v2v.pod index 3d0eada..fb1560f 100644 --- a/v2v/virt-v2v.pod +++ b/v2v/virt-v2v.pod @@ -7,7 +7,7 @@ virt-v2v - Convert a guest to use KVM virt-v2v -ic vpx://vcenter.example.com/Datacenter/esxi vmware_guest virt-v2v -ic vpx://vcenter.example.com/Datacenter/esxi vmware_guest \ - -o rhv -os rhv.nfs:/export_domain --network rhvm + -o rhv -os rhv.nfs:/export_domain --network ovirtmgmt virt-v2v -i libvirtxml guest-domain.xml -o local -os /var/tmp @@ -104,10 +104,10 @@ guest to a RHV-M Export Storage Domain which is located remotely (over NFS) at C<rhv.nfs:/export_domain>. If you are unclear about the location of the Export Storage Domain you should check the settings on your RHV-M management console. Guest network -interface(s) are connected to the target network called C<rhvm>. +interface(s) are connected to the target network called C<ovirtmgmt>. virt-v2v -ic vpx://vcenter.example.com/Datacenter/esxi vmware_guest \ - -o rhv -os rhv.nfs:/export_domain --network rhvm + -o rhv -os rhv.nfs:/export_domain --network ovirtmgmt In this case the host running virt-v2v acts as a B<conversion server>. @@ -974,13 +974,13 @@ This is typical of a libvirt guest: It has a single network interface connected to a network called C<default>. To map a specific network to a target network, for example C<default> -on the source to C<rhvm> on the target, use: +on the source to C<ovirtmgmt> on the target, use: - virt-v2v [...] --network default:rhvm + virt-v2v [...] --network default:ovirtmgmt To map every network to a target network, use: - virt-v2v [...] --network rhvm + virt-v2v [...] --network ovirtmgmt Bridges are handled in the same way, but you have to use the I<--bridge> option instead. For example: -- 2.9.3

2 1

[PATCH] v2v: Fix invalid regexp in file_contexts file (RHBZ#1374232).
by Richard W.M. Jones 06 Mar '17

06 Mar '17

Instead of just documenting this bug, fix it in the file_contexts file. Replaces commit ad3c8fe7f49c4991e1aa536856a1a408f55d5409. --- customize/SELinux_relabel.ml | 19 +++++++++++++++++++ v2v/virt-v2v.pod | 11 ----------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/customize/SELinux_relabel.ml b/customize/SELinux_relabel.ml index fa9603c..69a4779 100644 --- a/customize/SELinux_relabel.ml +++ b/customize/SELinux_relabel.ml @@ -44,6 +44,25 @@ let relabel (g : G.guestfs) = let specfile = sprintf "/etc/selinux/%s/contexts/files/file_contexts" policy in + (* RHEL 6.2 - 6.5 had a malformed specfile that contained the + * invalid regular expression "/var/run/spice-vdagentd.\pid" + * (instead of "\.p"). This stops setfiles from working on + * the guest. + * + * Because an SELinux relabel writes all over the filesystem, + * it seems reasonable to fix this problem in the specfile + * at the same time. (RHBZ#1374232) + *) + if g#grep ~fixed:true ".\\p" specfile <> [||] then ( + debug "fixing invalid regular expression in %s" specfile; + let old_specfile = specfile ^ "~" in + g#mv specfile old_specfile; + let content = g#read_file old_specfile in + let content = String.replace content ".\\p" "\\.p" in + g#write specfile content; + g#copy_attributes ~all:true old_specfile specfile + ); + (* Relabel everything. *) g#selinux_relabel ~force:true specfile "/"; diff --git a/v2v/virt-v2v.pod b/v2v/virt-v2v.pod index 3d0eada..a5b8e88 100644 --- a/v2v/virt-v2v.pod +++ b/v2v/virt-v2v.pod @@ -789,17 +789,6 @@ can install policycoreutils E<ge> 1.18.1-4.13 before starting the v2v conversion. See also L<https://bugzilla.redhat.com/show_bug.cgi?id=244636> -=head1 RHEL 6 - -=head2 RHEL 6.2 fails with "libguestfs error: selinux_relabel: : Success" - -Conversion of a RHEL 6.2 (exactly) guest will fail because the -C</etc/selinux/targeted/contexts/files> file within the guest contains -a corrupt regular expression. This was fixed in later versions of -RHEL 6, so you will need to update to any version E<ge> 6.3 before -performing the conversion. See also -L<https://bugzilla.redhat.com/show_bug.cgi?id=1374232> - =head1 DEBIAN AND UBUNTU =head2 "warning: could not determine a way to update the configuration of Grub2" -- 2.10.2

2 2

[PATCH 1/2] Use gnulib set_nonblocking_flag function instead of fcntl.
by Richard W.M. Jones 06 Mar '17

06 Mar '17

The previous code: fcntl (fd, F_SETFL, O_NONBLOCK) was technically incorrect, because it would have reset any other flags on the file descriptor. Thanks: Eric Blake --- bootstrap | 1 + daemon/inotify.c | 6 ++++-- lib/conn-socket.c | 21 +++++++++++---------- m4/.gitignore | 9 +++++++++ 4 files changed, 25 insertions(+), 12 deletions(-) diff --git a/bootstrap b/bootstrap index faa10a3..77a95a2 100755 --- a/bootstrap +++ b/bootstrap @@ -75,6 +75,7 @@ mkdtemp mkstemps netdb netinet_in +nonblocking openat perror pipe2 diff --git a/daemon/inotify.c b/daemon/inotify.c index 4360866..93722d0 100644 --- a/daemon/inotify.c +++ b/daemon/inotify.c @@ -29,6 +29,8 @@ #include <sys/inotify.h> #endif +#include "nonblocking.h" + #include "guestfs_protocol.h" #include "daemon.h" #include "actions.h" @@ -112,8 +114,8 @@ do_inotify_init (int max_events) reply_with_perror ("inotify_init"); return -1; } - if (fcntl (inotify_fd, F_SETFL, O_NONBLOCK) == -1) { - reply_with_perror ("fcntl: O_NONBLOCK"); + if (set_nonblocking_flag (inotify_fd, 1) == -1) { + reply_with_perror ("set_nonblocking_flag"); close (inotify_fd); inotify_fd = -1; return -1; diff --git a/lib/conn-socket.c b/lib/conn-socket.c index 4e1f781..2cd261a 100644 --- a/lib/conn-socket.c +++ b/lib/conn-socket.c @@ -37,6 +37,7 @@ #include <libintl.h> #include "ignore-value.h" +#include "nonblocking.h" #include "guestfs.h" #include "guestfs-internal.h" @@ -129,8 +130,8 @@ accept_connection (guestfs_h *g, struct connection *connv) conn->daemon_sock = sock; /* Make sure the new socket is non-blocking. */ - if (fcntl (conn->daemon_sock, F_SETFL, O_NONBLOCK) == -1) { - perrorf (g, "accept_connection: fcntl"); + if (set_nonblocking_flag (conn->daemon_sock, 1) == -1) { + perrorf (g, "accept_connection: set_nonblocking_flag"); return -1; } @@ -438,14 +439,14 @@ guestfs_int_new_conn_socket_listening (guestfs_h *g, assert (daemon_accept_sock >= 0); - if (fcntl (daemon_accept_sock, F_SETFL, O_NONBLOCK) == -1) { - perrorf (g, "new_conn_socket_listening: fcntl"); + if (set_nonblocking_flag (daemon_accept_sock, 1) == -1) { + perrorf (g, "new_conn_socket_listening: set_nonblocking_flag"); return NULL; } if (console_sock >= 0) { - if (fcntl (console_sock, F_SETFL, O_NONBLOCK) == -1) { - perrorf (g, "new_conn_socket_listening: fcntl"); + if (set_nonblocking_flag (console_sock, 1) == -1) { + perrorf (g, "new_conn_socket_listening: set_nonblocking_flag"); return NULL; } } @@ -478,14 +479,14 @@ guestfs_int_new_conn_socket_connected (guestfs_h *g, assert (daemon_sock >= 0); - if (fcntl (daemon_sock, F_SETFL, O_NONBLOCK) == -1) { - perrorf (g, "new_conn_socket_connected: fcntl"); + if (set_nonblocking_flag (daemon_sock, 1) == -1) { + perrorf (g, "new_conn_socket_connected: set_nonblocking_flag"); return NULL; } if (console_sock >= 0) { - if (fcntl (console_sock, F_SETFL, O_NONBLOCK) == -1) { - perrorf (g, "new_conn_socket_connected: fcntl"); + if (set_nonblocking_flag (console_sock, 1) == -1) { + perrorf (g, "new_conn_socket_connected: set_nonblocking_flag"); return NULL; } } diff --git a/m4/.gitignore b/m4/.gitignore index bbe7a9d..009cd5b 100644 --- a/m4/.gitignore +++ b/m4/.gitignore @@ -41,6 +41,7 @@ /exponentd.m4 /extensions.m4 /extern-inline.m4 +/fatal-signal.m4 /fchdir.m4 /fclose.m4 /fcntl_h.m4 @@ -156,6 +157,7 @@ /netdb_h.m4 /netinet_in_h.m4 /nocrash.m4 +/nonblocking.m4 /off_t.m4 /onceonly.m4 /openat.m4 @@ -165,6 +167,7 @@ /perror.m4 /pipe2.m4 /pipe.m4 +/posix_spawn.m4 /pread.m4 /printf.m4 /priv-set.m4 @@ -186,12 +189,14 @@ /safe-read.m4 /safe-write.m4 /save-cwd.m4 +/sched_h.m4 /secure_getenv.m4 /select.m4 /servent.m4 /setenv.m4 /setlocale.m4 /sigaction.m4 +/sig_atomic_t.m4 /signalblocking.m4 /signal_h.m4 /signed.m4 @@ -202,6 +207,7 @@ /sockets.m4 /socklen.m4 /sockpfaf.m4 +/spawn_h.m4 /ssize_t.m4 /stat.m4 /stat-time.m4 @@ -256,6 +262,9 @@ /utimes.m4 /vasnprintf.m4 /vasprintf.m4 +/vsnprintf.m4 +/waitpid.m4 +/wait-process.m4 /warnings.m4 /warn-on-use.m4 /wchar_h.m4 -- 2.9.3

2 2

[PATCH v3] Fix virt-rescue.
by Richard W.M. Jones 04 Mar '17

04 Mar '17

Version 3: - Tidies up the code further. - Implements correct handling of SIGTSTP and SIGCONT. - Adds: ^] s - sync filesystems - Adds: ^] z - suspend virt-rescue Rich.

1 7

[PATCH] rescue: Implement escape sequences.
by Richard W.M. Jones 04 Mar '17

04 Mar '17

This implements a few useful escape sequences: ><rescue> ^]? virt-rescue escape sequences: ^]? - print this message ^]h - print this message ^]i - print inspection data ^]q - quit virt-rescue ^]u - unmount filesystems ^]x - quit virt-rescue to send the escape key to the rescue shell, type it twice ^]i root device: /dev/sda3 product name: Fedora 25 (Twenty Five) type: linux distro: fedora ^]u unmounting filesystems ... [ 21.158558] XFS (sda3): Unmounting Filesystem --- rescue/rescue.c | 145 ++++++++++++++++++++++++++++++++++++++++++++++++- rescue/virt-rescue.pod | 65 ++++++++++++++++++++++ 2 files changed, 209 insertions(+), 1 deletion(-) diff --git a/rescue/rescue.c b/rescue/rescue.c index fb747df..06920c2 100644 --- a/rescue/rescue.c +++ b/rescue/rescue.c @@ -20,6 +20,7 @@ #include <stdio.h> #include <stdlib.h> +#include <stdbool.h> #include <string.h> #include <inttypes.h> #include <unistd.h> @@ -32,6 +33,7 @@ #include <assert.h> #include <libintl.h> +#include "c-ctype.h" #include "full-write.h" #include "getprogname.h" #include "ignore-value.h" @@ -61,6 +63,7 @@ const char *libvirt_uri = NULL; int inspector = 0; int in_guestfish = 0; int in_virt_rescue = 1; +int escape_key = '\x1d'; /* ^] */ /* Old terminal settings. */ static struct termios old_termios; @@ -115,7 +118,7 @@ main (int argc, char *argv[]) enum { HELP_OPTION = CHAR_MAX + 1 }; - static const char options[] = "a:c:d:im:rvVwx"; + static const char options[] = "a:c:d:e:im:rvVwx"; static const struct option long_options[] = { { "add", 1, 0, 'a' }, { "append", 1, 0, 0 }, @@ -223,6 +226,24 @@ main (int argc, char *argv[]) OPTION_d; break; + case 'e': + if (STREQ (optarg, "none")) + escape_key = 0; + else if (STRPREFIX (optarg, "^")) { + if (strlen (optarg) == 2 && + ((optarg[1] >= 'a' && optarg[1] <= 'z') || + (optarg[1] >= 'A' && optarg[1] <= '_'))) { + escape_key = c_toupper (optarg[1]) - '@'; + } + else + error (EXIT_FAILURE, 0, + _("unrecognized ^-escape in -e option: %s"), optarg); + } + else + error (EXIT_FAILURE, 0, + _("unrecognized escape key: %s"), optarg); + break; + case 'i': OPTION_i; break; @@ -463,6 +484,9 @@ log_message_callback (guestfs_h *g, void *opaque, uint64_t event, static char rbuf[BUFSIZE]; /* appliance -> local tty */ static char wbuf[BUFSIZE]; /* local tty -> appliance */ +static bool process_escapes (char *buf, size_t *len); +static void print_escape_key (void); + static void do_rescue (int sock) { @@ -524,6 +548,13 @@ do_rescue (int sock) } if (n > 0) wlen += n; + + /* Process escape sequences in the tty input. If the function + * returns true, then we exit the loop causing virt-rescue to + * exit. + */ + if (escape_key > 0 && process_escapes (wbuf, &wlen)) + return; } /* Log message from appliance. */ @@ -576,6 +607,118 @@ do_rescue (int sock) } } +/* Process escapes in the tty input buffer. + * + * This function has internal state so that we can handle an escape + * sequence split over the end of the buffer. Escape sequences are + * removed from the buffer. + * + * Returns true iff virt-rescue should exit. + */ +static bool +process_escapes (char *buf, size_t *len) +{ + size_t i; + static bool in_escape = false; + + for (i = 0; i < *len; ++i) { + if (!in_escape) { + if (buf[i] == escape_key) { + /* Drop the escape key from the buffer and go to escape mode. */ + memmove (&buf[i], &buf[i+1], --(*len)); + in_escape = 1; + } + } + else /* in escape sequence */ { + if (buf[i] == escape_key) /* ^] ^] means send ^] to rescue shell */ + in_escape = 0; + else { + switch (buf[i]) { + case '?': case 'h': + printf ("\r\n"); + printf (_("virt-rescue escape sequences:\r\n")); + print_escape_key (); printf (_("? - print this message\r\n")); + print_escape_key (); printf (_("h - print this message\r\n")); + if (inspector) { + print_escape_key (); printf (_("i - print inspection data\r\n")); + } + print_escape_key (); printf (_("q - quit virt-rescue\r\n")); + print_escape_key (); printf (_("u - unmount filesystems\r\n")); + print_escape_key (); printf (_("x - quit virt-rescue\r\n")); + printf (_("to send the escape key to the rescue shell, type it twice\r\n")); + break; + + case 'i': + if (inspector) { + CLEANUP_FREE_STRING_LIST char **roots; + size_t i; + + roots = guestfs_inspect_get_roots (g); + if (roots) { + printf ("\r\n"); + for (i = 0; roots[i] != NULL; ++i) { + const char *root = roots[i]; + char *str; + + printf (_("root device: %s\r\n"), root); + str = guestfs_inspect_get_product_name (g, root); + if (str) + printf (_(" product name: %s\r\n"), str); + free (str); + str = guestfs_inspect_get_type (g, root); + if (str) + printf (_(" type: %s\r\n"), str); + free (str); + str = guestfs_inspect_get_distro (g, root); + if (str) + printf (_(" distro: %s\r\n"), str); + free (str); + } + } + } + break; + + case 'q': case 'x': + return true /* exit virt-rescue at once */; + + case 'u': + printf ("\r\n"); + printf (_("unmounting filesystems ...\r\n")); + guestfs_umount_all (g); + break; + + default: + /* Any unrecognized escape sequence will be dropped. We could + * be obnoxious and ring the bell. XXX + */ + break; + } + /* Drop the escape key and return to non-escape mode. */ + memmove (&buf[i], &buf[i+1], --(*len)); + in_escape = 0; + } + } + } + + return false /* don't exit */; +} + +static void +print_escape_key (void) +{ + switch (escape_key) { + case 0: + printf ("none"); + break; + case '\x1'...'\x1f': + putchar ('^'); + putchar (escape_key + '@'); + break; + default: + abort (); + } +} + static void restore_tty (void) { diff --git a/rescue/virt-rescue.pod b/rescue/virt-rescue.pod index b651f84..6439b98 100644 --- a/rescue/virt-rescue.pod +++ b/rescue/virt-rescue.pod @@ -128,6 +128,29 @@ not used at all. Add all the disks from the named libvirt guest. Domain UUIDs can be used instead of names. +=item B<-e none> + +Disable the escape key. + +=item B<-e> KEY + +Set the escape key to the given key sequence. The default is C<^]>. +To specify the escape key you can use: + +=over 4 + +=item C<^x> + +Control key + C<x> key. + +=item C<none> + +I<-e none> means there is no escape key, escapes are disabled. + +=back + +See L</ESCAPE KEY> below for further information. + =item B<--format=raw|qcow2|..> =item B<--format> @@ -321,6 +344,48 @@ See L<bash(1)> for more details. =back +=head1 ESCAPE KEY + +Virt-rescue supports various keyboard escape sequences which are +entered by pressing C<^]> (Control key + C<]> key). + +You can change the escape key using the I<-e> option on the command +line (see above), and you can disable escapes completely using +I<-e none>. The rest of this section assumes the default escape key. + +The following escapes can be used: + +=over 4 + +=item C<^] ?> + +=item C<^] h> + +Prints a brief help text about escape sequences. + +=item C<^] i> + +Prints brief libguestfs inspection information for the guest. This +only works if you used I<-i> on the virt-rescue command line. + +=item C<^] q> + +=item C<^] x> + +Quits virt-rescue immediately. + +=item C<^] u> + +Unmounts all the filesystems, except for the root (appliance) +filesystems. + +=item C<^] ^]> + +Sends the literal character C<^]> (ASCII 0x1d) through to the rescue +shell. + +=back + =head1 CAPTURING CORE DUMPS If you are testing a tool inside virt-rescue and the tool (B<not> -- 2.9.3

1 0

[PATCH v2 0/6] Fix virt-rescue.
by Richard W.M. Jones 03 Mar '17

03 Mar '17

This supersedes the two previous patch series: https://www.redhat.com/archives/libguestfs/2017-March/msg00017.html https://www.redhat.com/archives/libguestfs/2017-March/msg00046.html Rich.

1 6

[PATCH v2 0/4] Avoid 0-bytes malloc in bindings
by Pino Toscano 03 Mar '17

03 Mar '17

Hi, some of the bindings may try to malloc with 0 bytes as size when closing an handle, because there were no event handlers registered. Since this can have different behaviours in POSIX, avoid that situation altogether by just skipping allocating anything when there were no event handlers. Thanks, Pino Toscano (4): ocaml: do not try to malloc 0 elements in get_all_event_callbacks python: do not try to malloc 0 elements in get_all_event_callbacks ruby: do not try to malloc 0 elements in get_all_event_callbacks java: do not try to malloc 0 elements in get_all_event_callbacks java/handle.c | 17 ++++++++++++----- ocaml/guestfs-c.c | 17 ++++++++++++----- python/handle.c | 22 +++++++++++++++++----- ruby/ext/guestfs/handle.c | 17 ++++++++++++----- 4 files changed, 53 insertions(+), 20 deletions(-) -- 2.9.3

2 5

[PATCH] generator: java: Don't link to undocumented methods.
by Richard W.M. Jones 03 Mar '17

03 Mar '17

We aren't generating Java bindings for internal and other undocumented methods, and therefore providing {@link #...} for deprecated methods replaced by internal methods doesn't work. The easiest way is just to check for this and turn such links into plain text. --- generator/java.ml | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/generator/java.ml b/generator/java.ml index 83f2e65..732cbe6 100644 --- a/generator/java.ml +++ b/generator/java.ml @@ -299,7 +299,15 @@ public class GuestFS { (match f with | { deprecated_by = Not_deprecated } -> () | { deprecated_by = Replaced_by alt } -> - pr " * @deprecated In new code, use {@link #%s} instead\n" alt + (* Don't link to an undocumented function as javadoc will + * give a hard error. + *) + let f_alt = try List.find (fun { name = n } -> n = alt) actions + with Not_found -> assert false in + if is_documented f_alt then + pr " * @deprecated In new code, use {@link #%s} instead\n" alt + else + pr " * @deprecated In new code, use method %s instead\n" alt | { deprecated_by = Deprecated_no_replacement } -> pr " * @deprecated\n" ); -- 2.9.3

2 2

[PATCH] generator: Allow actions to be deprecated with no replacement.
by Richard W.M. Jones 03 Mar '17

03 Mar '17

There is precisely one such function at the moment (guestfs_wait_ready). --- generator/GObject.ml | 6 +- generator/OCaml.ml | 7 +- generator/actions_core_deprecated.ml | 102 ++++++++++++++--------------- generator/actions_inspection_deprecated.ml | 2 +- generator/actions_properties_deprecated.ml | 12 ++-- generator/c.ml | 27 +++++--- generator/checks.ml | 4 +- generator/docstrings.ml | 14 +++- generator/java.ml | 11 ++-- generator/ruby.ml | 9 ++- generator/types.ml | 9 ++- 11 files changed, 118 insertions(+), 85 deletions(-) diff --git a/generator/GObject.ml b/generator/GObject.ml index eada33c..fd2c07c 100644 --- a/generator/GObject.ml +++ b/generator/GObject.ml @@ -1118,9 +1118,11 @@ guestfs_session_close (GuestfsSession *session, GError **err) ); pr "\n"; (match deprecated_by with - | None -> () - | Some alt -> + | Not_deprecated -> () + | Replaced_by alt -> pr " * Deprecated: In new code, use guestfs_session_%s() instead\n" alt + | Deprecated_no_replacement -> + pr " * Deprecated\n" ); (match version_added f with | None -> () diff --git a/generator/OCaml.ml b/generator/OCaml.ml index 083e505..38b254d 100644 --- a/generator/OCaml.ml +++ b/generator/OCaml.ml @@ -186,10 +186,13 @@ end opt ); (match f.deprecated_by with - | None -> () - | Some replacement -> + | Not_deprecated -> () + | Replaced_by replacement -> has_tags := true; pr "\n\n @deprecated Use {!%s} instead" replacement + | Deprecated_no_replacement -> + has_tags := true; + pr "\n\n @deprecated" ); (match version_added f with | None -> () diff --git a/generator/actions_core_deprecated.ml b/generator/actions_core_deprecated.ml index b8cca79..ae93f29 100644 --- a/generator/actions_core_deprecated.ml +++ b/generator/actions_core_deprecated.ml @@ -28,7 +28,7 @@ let non_daemon_functions = [ name = "wait_ready"; added = (0, 0, 3); style = RErr, [], []; visibility = VStateTest; - deprecated_by = Some "launch"; + deprecated_by = Deprecated_no_replacement; blocking = false; shortdesc = "wait until the hypervisor launches (no op)"; longdesc = "\ @@ -46,7 +46,7 @@ versions of the API." }; { defaults with name = "kill_subprocess"; added = (0, 0, 3); style = RErr, [], []; - deprecated_by = Some "shutdown"; + deprecated_by = Replaced_by "shutdown"; shortdesc = "kill the hypervisor"; longdesc = "\ This kills the hypervisor. @@ -56,7 +56,7 @@ Do not call this. See: C<guestfs_shutdown> instead." }; { defaults with name = "add_cdrom"; added = (0, 0, 3); style = RErr, [String "filename"], []; - deprecated_by = Some "add_drive_ro"; config_only = true; + deprecated_by = Replaced_by "add_drive_ro"; config_only = true; blocking = false; shortdesc = "add a CD-ROM disk image to examine"; longdesc = "\ @@ -68,7 +68,7 @@ of C<guestfs_add_drive_ro>." }; { defaults with name = "add_drive_with_if"; added = (1, 0, 84); style = RErr, [String "filename"; String "iface"], []; - deprecated_by = Some "add_drive"; config_only = true; + deprecated_by = Replaced_by "add_drive"; config_only = true; blocking = false; shortdesc = "add a drive specifying the QEMU block emulation to use"; longdesc = "\ @@ -79,7 +79,7 @@ to specify the QEMU interface emulation to use at run time." }; name = "add_drive_ro_with_if"; added = (1, 0, 84); style = RErr, [String "filename"; String "iface"], []; blocking = false; - deprecated_by = Some "add_drive"; config_only = true; + deprecated_by = Replaced_by "add_drive"; config_only = true; shortdesc = "add a drive read-only specifying the QEMU block emulation to use"; longdesc = "\ This is the same as C<guestfs_add_drive_ro> but it allows you @@ -88,7 +88,7 @@ to specify the QEMU interface emulation to use at run time." }; { defaults with name = "lstatlist"; added = (1, 0, 77); style = RStructList ("statbufs", "stat"), [Pathname "path"; FilenameList "names"], []; - deprecated_by = Some "lstatnslist"; + deprecated_by = Replaced_by "lstatnslist"; shortdesc = "lstat on multiple files"; longdesc = "\ This call allows you to perform the C<guestfs_lstat> operation @@ -108,7 +108,7 @@ for getting extended attributes." }; { defaults with name = "stat"; added = (1, 9, 2); style = RStruct ("statbuf", "stat"), [Pathname "path"], []; - deprecated_by = Some "statns"; + deprecated_by = Replaced_by "statns"; tests = [ InitISOFS, Always, TestResult ( [["stat"; "/empty"]], "ret->size == 0"), [] @@ -122,7 +122,7 @@ This is the same as the L<stat(2)> system call." }; { defaults with name = "lstat"; added = (1, 9, 2); style = RStruct ("statbuf", "stat"), [Pathname "path"], []; - deprecated_by = Some "lstatns"; + deprecated_by = Replaced_by "lstatns"; tests = [ InitISOFS, Always, TestResult ( [["lstat"; "/empty"]], "ret->size == 0"), [] @@ -145,7 +145,7 @@ let daemon_functions = [ style = RErr, [Device "device"; Int "cyls"; Int "heads"; Int "sectors"; StringList "lines"], []; - deprecated_by = Some "part_add"; + deprecated_by = Replaced_by "part_add"; shortdesc = "create partitions on a block device"; longdesc = "\ This is a direct interface to the L<sfdisk(8)> program for creating @@ -174,7 +174,7 @@ C<guestfs_part_init>" }; { defaults with name = "blockdev_setbsz"; added = (1, 9, 3); style = RErr, [Device "device"; Int "blocksize"], []; - deprecated_by = Some "mkfs"; + deprecated_by = Replaced_by "mkfs"; shortdesc = "set blocksize of block device"; longdesc = "\ This call does nothing and has never done anything @@ -186,7 +186,7 @@ C<blocksize> option of C<guestfs_mkfs>." }; { defaults with name = "tgz_in"; added = (1, 0, 3); style = RErr, [FileIn "tarball"; Pathname "directory"], []; - deprecated_by = Some "tar_in"; + deprecated_by = Replaced_by "tar_in"; cancellable = true; tests = [ InitScratchFS, Always, TestResultString ( @@ -202,7 +202,7 @@ I<gzip compressed> tar file) into F<directory>." }; { defaults with name = "tgz_out"; added = (1, 0, 3); style = RErr, [Pathname "directory"; FileOut "tarball"], []; - deprecated_by = Some "tar_out"; + deprecated_by = Replaced_by "tar_out"; cancellable = true; shortdesc = "pack directory into compressed tarball"; longdesc = "\ @@ -212,7 +212,7 @@ it to local file C<tarball>." }; { defaults with name = "set_e2label"; added = (1, 0, 15); style = RErr, [Device "device"; String "label"], []; - deprecated_by = Some "set_label"; + deprecated_by = Replaced_by "set_label"; tests = [ InitBasicFS, Always, TestResultString ( [["set_e2label"; "/dev/sda1"; "testlabel"]; @@ -230,7 +230,7 @@ to return the existing label on a filesystem." }; { defaults with name = "get_e2label"; added = (1, 0, 15); style = RString "label", [Device "device"], []; - deprecated_by = Some "vfs_label"; + deprecated_by = Replaced_by "vfs_label"; shortdesc = "get the ext2/3/4 filesystem label"; longdesc = "\ This returns the ext2/3/4 filesystem label of the filesystem on @@ -239,7 +239,7 @@ C<device>." }; { defaults with name = "set_e2uuid"; added = (1, 0, 15); style = RErr, [Device "device"; String "uuid"], []; - deprecated_by = Some "set_uuid"; + deprecated_by = Replaced_by "set_uuid"; tests = [ InitBasicFS, Always, TestResultString ( [["set_e2uuid"; "/dev/sda1"; stable_uuid]; @@ -267,7 +267,7 @@ of a filesystem." }; { defaults with name = "get_e2uuid"; added = (1, 0, 15); style = RString "uuid", [Device "device"], []; - deprecated_by = Some "vfs_uuid"; + deprecated_by = Replaced_by "vfs_uuid"; tests = [ (* We can't predict what UUID will be, so just check the command run; regression test for RHBZ#597112. *) @@ -285,7 +285,7 @@ C<device>." }; style = RErr, [Device "device"; Int "partnum"; Int "cyls"; Int "heads"; Int "sectors"; String "line"], []; - deprecated_by = Some "part_add"; + deprecated_by = Replaced_by "part_add"; shortdesc = "modify a single partition on a block device"; longdesc = "\ This runs L<sfdisk(8)> option to modify just the single @@ -299,7 +299,7 @@ See also: C<guestfs_part_add>" }; { defaults with name = "sfdisk_l"; added = (1, 0, 26); style = RString "partitions", [Device "device"], []; - deprecated_by = Some "part_list"; + deprecated_by = Replaced_by "part_list"; shortdesc = "display the partition table"; longdesc = "\ This displays the partition table on C<device>, in the @@ -311,7 +311,7 @@ See also: C<guestfs_part_list>" }; { defaults with name = "e2fsck_f"; added = (1, 0, 29); style = RErr, [Device "device"], []; - deprecated_by = Some "e2fsck"; + deprecated_by = Replaced_by "e2fsck"; shortdesc = "check an ext2/ext3 filesystem"; longdesc = "\ This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3 @@ -321,7 +321,7 @@ even if the filesystem appears to be clean (I<-f>)." }; { defaults with name = "mkswap_L"; added = (1, 0, 55); style = RErr, [String "label"; Device "device"], []; - deprecated_by = Some "mkswap"; + deprecated_by = Replaced_by "mkswap"; tests = [ InitEmpty, Always, TestRun ( [["part_disk"; "/dev/sda"; "mbr"]; @@ -338,7 +338,7 @@ a limitation of the kernel or swap tools." }; { defaults with name = "mkswap_U"; added = (1, 0, 55); style = RErr, [String "uuid"; Device "device"], []; - deprecated_by = Some "mkswap"; + deprecated_by = Replaced_by "mkswap"; optional = Some "linuxfsuuid"; tests = [ InitEmpty, Always, TestRun ( @@ -352,7 +352,7 @@ Create a swap partition on C<device> with UUID C<uuid>." }; { defaults with name = "sfdiskM"; added = (1, 0, 55); style = RErr, [Device "device"; StringList "lines"], []; - deprecated_by = Some "part_add"; + deprecated_by = Replaced_by "part_add"; shortdesc = "create partitions on a block device"; longdesc = "\ This is a simplified interface to the C<guestfs_sfdisk> @@ -367,7 +367,7 @@ and C<guestfs_part_disk>" }; { defaults with name = "zfile"; added = (1, 0, 59); style = RString "description", [String "meth"; Pathname "path"], []; - deprecated_by = Some "file"; + deprecated_by = Replaced_by "file"; shortdesc = "determine file type inside a compressed file"; longdesc = "\ This command runs F<file> after first decompressing C<path> @@ -382,7 +382,7 @@ process compressed files." }; name = "egrep"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["egrep"; "abc"; "/test-grep.txt"]], @@ -397,7 +397,7 @@ matching lines." }; name = "fgrep"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["fgrep"; "abc"; "/test-grep.txt"]], @@ -412,7 +412,7 @@ matching lines." }; name = "grepi"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["grepi"; "abc"; "/test-grep.txt"]], @@ -427,7 +427,7 @@ matching lines." }; name = "egrepi"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["egrepi"; "abc"; "/test-grep.txt"]], @@ -442,7 +442,7 @@ matching lines." }; name = "fgrepi"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["fgrepi"; "abc"; "/test-grep.txt"]], @@ -457,7 +457,7 @@ matching lines." }; name = "zgrep"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zgrep"; "abc"; "/test-grep.txt.gz"]], @@ -472,7 +472,7 @@ matching lines." }; name = "zegrep"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zegrep"; "abc"; "/test-grep.txt.gz"]], @@ -487,7 +487,7 @@ matching lines." }; name = "zfgrep"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zfgrep"; "abc"; "/test-grep.txt.gz"]], @@ -503,7 +503,7 @@ matching lines." }; style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zgrepi"; "abc"; "/test-grep.txt.gz"]], @@ -518,7 +518,7 @@ matching lines." }; name = "zegrepi"; added = (1, 0, 66); style = RStringList "lines", [String "regex"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zegrepi"; "abc"; "/test-grep.txt.gz"]], @@ -533,7 +533,7 @@ matching lines." }; name = "zfgrepi"; added = (1, 0, 66); style = RStringList "lines", [String "pattern"; Pathname "path"], []; protocol_limit_warning = true; - deprecated_by = Some "grep"; + deprecated_by = Replaced_by "grep"; tests = [ InitISOFS, Always, TestResult ( [["zfgrepi"; "abc"; "/test-grep.txt.gz"]], @@ -547,7 +547,7 @@ matching lines." }; { defaults with name = "fallocate"; added = (1, 0, 66); style = RErr, [Pathname "path"; Int "len"], []; - deprecated_by = Some "fallocate64"; + deprecated_by = Replaced_by "fallocate64"; tests = [ InitScratchFS, Always, TestResult ( [["fallocate"; "/fallocate"; "1000000"]; @@ -567,7 +567,7 @@ attaches it as a device." }; name = "setcon"; added = (1, 0, 67); style = RErr, [String "context"], []; optional = Some "selinux"; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "set SELinux security context"; longdesc = "\ This sets the SELinux security context of the daemon @@ -579,7 +579,7 @@ See the documentation about SELINUX in L<guestfs(3)>." }; name = "getcon"; added = (1, 0, 67); style = RString "context", [], []; optional = Some "selinux"; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "get SELinux security context"; longdesc = "\ This gets the SELinux security context of the daemon. @@ -590,7 +590,7 @@ and C<guestfs_setcon>" }; { defaults with name = "mkfs_b"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"], []; - deprecated_by = Some "mkfs"; + deprecated_by = Replaced_by "mkfs"; tests = [ InitEmpty, Always, TestResultString ( [["part_disk"; "/dev/sda"; "mbr"]; @@ -627,7 +627,7 @@ the requested cluster size." }; { defaults with name = "mke2journal"; added = (1, 0, 68); style = RErr, [Int "blocksize"; Device "device"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; tests = [ InitEmpty, Always, TestResultString ( [["part_init"; "/dev/sda"; "mbr"]; @@ -649,7 +649,7 @@ to the command: { defaults with name = "mke2journal_L"; added = (1, 0, 68); style = RErr, [Int "blocksize"; String "label"; Device "device"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; tests = [ InitEmpty, Always, TestResultString ( [["part_init"; "/dev/sda"; "mbr"]; @@ -668,7 +668,7 @@ This creates an ext2 external journal on C<device> with label C<label>." }; { defaults with name = "mke2journal_U"; added = (1, 0, 68); style = RErr, [Int "blocksize"; String "uuid"; Device "device"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; optional = Some "linuxfsuuid"; tests = [ InitEmpty, Always, TestResultString ( @@ -688,7 +688,7 @@ This creates an ext2 external journal on C<device> with UUID C<uuid>." }; { defaults with name = "mke2fs_J"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; shortdesc = "make ext2/3/4 filesystem with external journal"; longdesc = "\ This creates an ext2/3/4 filesystem on C<device> with @@ -702,7 +702,7 @@ See also C<guestfs_mke2journal>." }; { defaults with name = "mke2fs_JL"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; shortdesc = "make ext2/3/4 filesystem with external journal"; longdesc = "\ This creates an ext2/3/4 filesystem on C<device> with @@ -713,7 +713,7 @@ See also C<guestfs_mke2journal_L>." }; { defaults with name = "mke2fs_JU"; added = (1, 0, 68); style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"], []; - deprecated_by = Some "mke2fs"; + deprecated_by = Replaced_by "mke2fs"; optional = Some "linuxfsuuid"; shortdesc = "make ext2/3/4 filesystem with external journal"; longdesc = "\ @@ -725,7 +725,7 @@ See also C<guestfs_mke2journal_U>." }; { defaults with name = "dd"; added = (1, 0, 80); style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], []; - deprecated_by = Some "copy_device_to_device"; + deprecated_by = Replaced_by "copy_device_to_device"; tests = [ InitScratchFS, Always, TestResult ( [["mkdir"; "/dd"]; @@ -749,7 +749,7 @@ This command cannot do partial copies { defaults with name = "txz_in"; added = (1, 3, 2); style = RErr, [FileIn "tarball"; Pathname "directory"], []; - deprecated_by = Some "tar_in"; + deprecated_by = Replaced_by "tar_in"; optional = Some "xz"; cancellable = true; tests = [ InitScratchFS, Always, TestResultString ( @@ -765,7 +765,7 @@ I<xz compressed> tar file) into F<directory>." }; { defaults with name = "txz_out"; added = (1, 3, 2); style = RErr, [Pathname "directory"; FileOut "tarball"], []; - deprecated_by = Some "tar_out"; + deprecated_by = Replaced_by "tar_out"; optional = Some "xz"; cancellable = true; shortdesc = "pack directory into compressed tarball"; longdesc = "\ @@ -775,7 +775,7 @@ it to local file C<tarball> (as an xz compressed tar archive)." }; { defaults with name = "llz"; added = (1, 17, 6); style = RString "listing", [Pathname "directory"], []; - deprecated_by = Some "lgetxattrs"; + deprecated_by = Replaced_by "lgetxattrs"; shortdesc = "list the files in a directory (long format with SELinux contexts)"; longdesc = "\ List the files in F<directory> in the format of 'ls -laZ'. @@ -786,7 +786,7 @@ is I<not> intended that you try to parse the output string." }; { defaults with name = "write_file"; added = (0, 0, 8); style = RErr, [Pathname "path"; String "content"; Int "size"], []; - protocol_limit_warning = true; deprecated_by = Some "write"; + protocol_limit_warning = true; deprecated_by = Replaced_by "write"; (* Regression test for RHBZ#597135. *) tests = [ InitScratchFS, Always, TestLastFail @@ -808,7 +808,7 @@ characters does I<not> work, even if the length is specified." }; { defaults with name = "copy_size"; added = (1, 0, 87); style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], []; - progress = true; deprecated_by = Some "copy_device_to_device"; + progress = true; deprecated_by = Replaced_by "copy_device_to_device"; tests = [ InitScratchFS, Always, TestResult ( [["mkdir"; "/copy_size"]; @@ -828,7 +828,7 @@ is not large enough." }; { defaults with name = "ntfsresize_size"; added = (1, 3, 14); style = RErr, [Device "device"; Int64 "size"], []; - optional = Some "ntfsprogs"; deprecated_by = Some "ntfsresize"; + optional = Some "ntfsprogs"; deprecated_by = Replaced_by "ntfsresize"; shortdesc = "resize an NTFS filesystem (with size)"; longdesc = "\ This command is the same as C<guestfs_ntfsresize> except that it diff --git a/generator/actions_inspection_deprecated.ml b/generator/actions_inspection_deprecated.ml index 04fb143..5ca062c 100644 --- a/generator/actions_inspection_deprecated.ml +++ b/generator/actions_inspection_deprecated.ml @@ -26,7 +26,7 @@ let non_daemon_functions = [ { defaults with name = "inspect_list_applications"; added = (1, 7, 8); style = RStructList ("applications", "application"), [Mountable "root"], []; - deprecated_by = Some "inspect_list_applications2"; + deprecated_by = Replaced_by "inspect_list_applications2"; shortdesc = "get list of applications installed in the operating system"; longdesc = "\ Return the list of applications installed in the operating system. diff --git a/generator/actions_properties_deprecated.ml b/generator/actions_properties_deprecated.ml index 3fe8fef..def17b9 100644 --- a/generator/actions_properties_deprecated.ml +++ b/generator/actions_properties_deprecated.ml @@ -30,7 +30,7 @@ let non_daemon_functions = [ style = RErr, [OptString "hv"], []; fish_alias = ["qemu"]; config_only = true; blocking = false; - deprecated_by = Some "set_hv"; + deprecated_by = Replaced_by "set_hv"; shortdesc = "set the hypervisor binary (usually qemu)"; longdesc = "\ Set the hypervisor binary (usually qemu) that we will use. @@ -55,7 +55,7 @@ the qemu binary at the same time as the handle is created." }; name = "get_qemu"; added = (1, 0, 6); style = RConstString "hv", [], []; blocking = false; - deprecated_by = Some "get_hv"; + deprecated_by = Replaced_by "get_hv"; tests = [ InitNone, Always, TestRun ( [["get_qemu"]]), [] @@ -72,7 +72,7 @@ return the default qemu binary name." }; style = RErr, [Bool "selinux"], []; fish_alias = ["selinux"]; config_only = true; blocking = false; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "set SELinux enabled or disabled at appliance boot"; longdesc = "\ This sets the selinux flag that is passed to the appliance @@ -88,7 +88,7 @@ see L<guestfs(3)>." }; name = "get_selinux"; added = (1, 0, 67); style = RBool "selinux", [], []; blocking = false; - deprecated_by = Some "selinux_relabel"; + deprecated_by = Replaced_by "selinux_relabel"; shortdesc = "get SELinux enabled flag"; longdesc = "\ This returns the current setting of the selinux flag which @@ -102,7 +102,7 @@ see L<guestfs(3)>." }; style = RErr, [String "backend"], []; fish_alias = ["attach-method"]; config_only = true; blocking = false; - deprecated_by = Some "set_backend"; + deprecated_by = Replaced_by "set_backend"; shortdesc = "set the backend"; longdesc = "\ Set the method that libguestfs uses to connect to the backend @@ -114,7 +114,7 @@ See L<guestfs(3)/BACKEND>." }; name = "get_attach_method"; added = (1, 9, 8); style = RString "backend", [], []; blocking = false; - deprecated_by = Some "get_backend"; + deprecated_by = Replaced_by "get_backend"; tests = [ InitNone, Always, TestRun ( [["get_attach_method"]]), [] diff --git a/generator/c.ml b/generator/c.ml index 1cb0880..606c898 100644 --- a/generator/c.ml +++ b/generator/c.ml @@ -445,11 +445,14 @@ extern \"C\" { #endif /* Define GUESTFS_WARN_DEPRECATED=1 to warn about deprecated API functions. */ -#define GUESTFS_DEPRECATED_BY(s) +#define GUESTFS_DEPRECATED_NO_REPLACEMENT +#define GUESTFS_DEPRECATED_REPLACED_BY(s) #if GUESTFS_WARN_DEPRECATED # if defined(__GNUC__) && GUESTFS_GCC_VERSION >= 40500 /* gcc >= 4.5 */ -# undef GUESTFS_DEPRECATED_BY -# define GUESTFS_DEPRECATED_BY(s) __attribute__((__deprecated__(\"change the program to use guestfs_\" s \" instead of this deprecated function\"))) +# undef GUESTFS_DEPRECATED_NO_REPLACEMENT +# undef GUESTFS_DEPRECATED_REPLACED_BY +# define GUESTFS_DEPRECATED_NO_REPLACEMENT __attribute__((__deprecated__)) +# define GUESTFS_DEPRECATED_REPLACED_BY(s) __attribute__((__deprecated__(\"change the program to use guestfs_\" s \" instead of this deprecated function\"))) # endif #endif /* GUESTFS_WARN_DEPRECATED */ @@ -562,17 +565,17 @@ typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque, int proc_nr, in #endif extern GUESTFS_DLL_PUBLIC void guestfs_set_log_message_callback (guestfs_h *g, guestfs_log_message_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); extern GUESTFS_DLL_PUBLIC void guestfs_set_subprocess_quit_callback (guestfs_h *g, guestfs_subprocess_quit_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); extern GUESTFS_DLL_PUBLIC void guestfs_set_launch_done_callback (guestfs_h *g, guestfs_launch_done_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); #define GUESTFS_HAVE_SET_CLOSE_CALLBACK 1 extern GUESTFS_DLL_PUBLIC void guestfs_set_close_callback (guestfs_h *g, guestfs_close_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); #define GUESTFS_HAVE_SET_PROGRESS_CALLBACK 1 extern GUESTFS_DLL_PUBLIC void guestfs_set_progress_callback (guestfs_h *g, guestfs_progress_cb cb, void *opaque) - GUESTFS_DEPRECATED_BY(\"set_event_callback\"); + GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\"); /* Private data area. */ #define GUESTFS_HAVE_SET_PRIVATE 1 @@ -662,8 +665,12 @@ extern GUESTFS_DLL_PUBLIC void *guestfs_next_private (guestfs_h *g, const char * generate_prototype ~single_line:true ~semicolon:false ~dll_public:true ~handle:"g" ~prefix:"guestfs_" shortname style; (match deprecated_by with - | Some fn -> pr "\n GUESTFS_DEPRECATED_BY (%S);\n" fn - | None -> pr ";\n" + | Not_deprecated -> + pr ";\n" + | Replaced_by fn -> + pr "\n GUESTFS_DEPRECATED_REPLACED_BY (%S);\n" fn + | Deprecated_no_replacement -> + pr "\n GUESTFS_DEPRECATED_NO_REPLACEMENT;\n" ); if optargs <> [] then ( diff --git a/generator/checks.ml b/generator/checks.ml index 63536e5..788a116 100644 --- a/generator/checks.ml +++ b/generator/checks.ml @@ -184,7 +184,7 @@ let () = failwithf "%s: guestfish alias %s should not contain '_'" name n ) f.fish_alias; (match f.deprecated_by with - | Some n -> + | Replaced_by n -> (* 'n' must be a cross-ref to the name of another action. *) if not (List.exists ( function @@ -192,7 +192,7 @@ let () = | _ -> false ) actions) then failwithf "%s: deprecated_by flag must be cross-reference to another action" name - | None -> () + | Not_deprecated | Deprecated_no_replacement -> () ); (match f.optional with | Some n -> diff --git a/generator/docstrings.ml b/generator/docstrings.ml index acfdb53..2ce595d 100644 --- a/generator/docstrings.ml +++ b/generator/docstrings.ml @@ -39,8 +39,9 @@ of somewhere between 2MB and 4MB. See L<guestfs(3)/PROTOCOL LIMITS>." let deprecation_notice ?(prefix = "") ?(replace_underscores = false) = function - | { deprecated_by = None } -> None - | { deprecated_by = Some alt } -> + | { deprecated_by = Not_deprecated } -> None + + | { deprecated_by = Replaced_by alt } -> let alt = if replace_underscores then String.replace_char alt '_' '-' else alt in let txt = @@ -52,6 +53,15 @@ fact that they are deprecated indicates that there are problems with correct use of these functions." prefix alt in Some txt + | { deprecated_by = Deprecated_no_replacement } -> + Some "I<This function is deprecated.> +There is no replacement. Consult the API documentation in +L<guestfs(3)> for further information. + +Deprecated functions will not be removed from the API, but the +fact that they are deprecated indicates that there are problems +with correct use of these functions." + let version_added = function | { added = (0, 0, release) } -> Some (sprintf "0.%d" release) | { added = ((0|1) as major, minor, release) } -> diff --git a/generator/java.ml b/generator/java.ml index 8f71feb..83f2e65 100644 --- a/generator/java.ml +++ b/generator/java.ml @@ -297,9 +297,11 @@ public class GuestFS { | Some version -> pr " * @since %s\n" version ); (match f with - | { deprecated_by = None } -> () - | { deprecated_by = Some alt } -> + | { deprecated_by = Not_deprecated } -> () + | { deprecated_by = Replaced_by alt } -> pr " * @deprecated In new code, use {@link #%s} instead\n" alt + | { deprecated_by = Deprecated_no_replacement } -> + pr " * @deprecated\n" ); pr " * @throws LibGuestFSException If there is a libguestfs error.\n"; pr " */\n"; @@ -307,8 +309,9 @@ public class GuestFS { pr " "; let deprecated = match f with - | { deprecated_by = None } -> false - | { deprecated_by = Some _ } -> true in + | { deprecated_by = Not_deprecated } -> false + | { deprecated_by = Replaced_by _ | Deprecated_no_replacement } -> + true in generate_java_prototype ~public:true ~semicolon:false ~deprecated f.name f.style; pr "\n"; pr " {\n"; diff --git a/generator/ruby.ml b/generator/ruby.ml index c938bc9..594036d 100644 --- a/generator/ruby.ml +++ b/generator/ruby.ml @@ -146,9 +146,12 @@ and generate_ruby_c actions () = | Some version -> doc ^ (sprintf "\n *\n * [Since] Added in version %s." version) in let doc = match f with - | { deprecated_by = None } -> doc - | { deprecated_by = Some alt } -> - doc ^ (sprintf "\n *\n * [Deprecated] In new code, use rdoc-ref:%s instead." alt) in + | { deprecated_by = Not_deprecated } -> doc + | { deprecated_by = Replaced_by alt } -> + doc ^ + sprintf "\n *\n * [Deprecated] In new code, use rdoc-ref:%s instead." alt + | { deprecated_by = Deprecated_no_replacement } -> + doc ^ "\n *\n * [Deprecated]" in let doc = match f.optional with | None -> doc diff --git a/generator/types.ml b/generator/types.ml index fd9f215..3fa96fd 100644 --- a/generator/types.ml +++ b/generator/types.ml @@ -342,6 +342,11 @@ type visibility = type version = int * int * int +type deprecated_by = + | Not_deprecated (* function not deprecated *) + | Replaced_by of string (* replaced by another function *) + | Deprecated_no_replacement (* deprecated with no replacement *) + (* Type of an action as declared in Actions module. *) type action = { name : string; (* name, not including "guestfs_" *) @@ -358,7 +363,7 @@ type action = { fish_alias : string list; (* alias(es) for this cmd in guestfish *) fish_output : fish_output_t option; (* how to display output in guestfish *) visibility: visibility; (* The visbility of function *) - deprecated_by : string option; (* function is deprecated, use .. instead *) + deprecated_by : deprecated_by; (* function is deprecated *) optional : string option; (* function is part of an optional group *) progress : bool; (* function can generate progress messages *) camel_name : string; (* Pretty camel case name of @@ -407,7 +412,7 @@ let defaults = { name = ""; shortdesc = ""; longdesc = ""; protocol_limit_warning = false; fish_alias = []; fish_output = None; visibility = VPublic; - deprecated_by = None; optional = None; + deprecated_by = Not_deprecated; optional = None; progress = false; camel_name = ""; cancellable = false; config_only = false; once_had_no_optargs = false; blocking = true; wrapper = true; -- 2.9.3

2 2